menu_book User Documentation

How to Use PolyDrobe

This guide covers the fastest way to set up your workspace, manage assets and variants, collaborate with your team, and solve common issues.

rocket_launch Quick Start

Up and running in four steps

From zero to a fully organized asset catalog in minutes.

folder_open

Create a project

Create your first project and set a clear project slug.

tune

Configure taxonomy

Configure core settings: categories, rarities, tags, currencies, statuses, and releases.

add_photo_alternate

Add assets & variants

Add assets, then create variants with images, price data, and optional metadata.

group_add

Invite your team

Invite teammates and assign Owner, Editor, or Viewer roles based on responsibility.

account_tree Core Workflows

Everything you can do

Click a workflow to see the details.

Create project details and icon.
Define reusable taxonomy in Project Settings.

Add asset-level metadata and assign category/rarity.
Attach variant textures, images, and pricing.

Use filtering, status, and tags to find work quickly.
Use activity history to review changes.

Export project data to JSON or Excel for reporting.
Import datasets with validation and error review.

Create a native Google Spreadsheet (not an uploaded .xlsx) with one worksheet per entity type: Categories, Tags, Rarities, Currencies, Releases, Assets, Variants.
Add exact column headers as the first row of each worksheet (case-sensitive). For example, the Variants sheet needs: slug, name, asset_slug, rarity, release, currency, price, description, tags.
Entities are imported in dependency order: Categories first, then Tags, Rarities, Currencies, Releases, Assets, and finally Variants. Earlier entities must exist before later ones can reference them.
In your project, go to the Data Exchange page, select Google Sheet, and connect your Google account.
Create a Sync Profile by entering the spreadsheet URL and optionally customizing worksheet names.
Always run a dry run (Generate Preview) first to check for validation errors before applying the import.
For tags on Assets or Variants, use semicolon-separated values: starter;seasonal=winter;limited-edition.
Prices accept both dot and comma decimal separators (9.99 or 9,99). Rarity is matched by name, currency by code, and release by version string.

integration_instructions Developer Guides

Connect your tools, agents, and pipelines to PolyDrobe

Step-by-step setup with code snippets. Requires Professional plan.

1. Generate an access token

Go to Settings > API Tokens and create a new personal access token. Give it a descriptive name (e.g. 'CI Pipeline' or 'Local Script'), select read and write scopes, and choose an expiration period. Copy the token immediately — it is shown only once.

# Your token will look like this:
pdtk_a8f3b2c1d4e5f6a7b8c9d0e1f2a3b4c5...

# Keep it safe — you cannot retrieve it later.
# If lost, revoke it and create a new one.

2. Authenticate requests

Include the token as a Bearer token in the Authorization header on every request.

curl -H "Authorization: Bearer pdtk_abc123..." \
     https://polydrobe.app/api/v1/projects/

3. List your projects

Returns all projects where you are a member. Response uses the standard envelope format with data and meta keys.

GET /api/v1/projects/

# Response:
{
  "data": [
    {
      "id": "...",
      "name": "Cyber Skins",
      "slug": "cyber-skins",
      "asset_count": 42,
      "my_role": "owner"
    }
  ],
  "meta": { "total": 1, "page": 1, "page_size": 25 }
}

4. Create an asset

Create an asset inside a project. Requires editor or owner role. The slug is auto-generated from the name.

curl -X POST \
  -H "Authorization: Bearer pdtk_abc123..." \
  -H "Content-Type: application/json" \
  -d '{"name": "Plasma Rifle", "description": "Sci-fi weapon", "category_slug": "weapons"}' \
  https://polydrobe.app/api/v1/projects/cyber-skins/assets/

5. Create a variant

Add a variant to an asset with pricing, rarity, and status. All foreign key references use slugs.

curl -X POST \
  -H "Authorization: Bearer pdtk_abc123..." \
  -H "Content-Type: application/json" \
  -d '{"name": "Gold Edition", "rarity_slug": "legendary", "price": "29.99", "currency_code": "USD"}' \
  https://polydrobe.app/api/v1/projects/cyber-skins/assets/plasma-rifle/variants/

6. Search assets

Full-text search across assets and variants using PostgreSQL search. Supports phrases, OR, and negation.

GET /api/v1/projects/cyber-skins/search/?q=gold+legendary&type=variant&limit=10

7. Bulk operations

Update or delete multiple variants at once. Requires the Bulk Operations capability (Professional plan).

curl -X POST \
  -H "Authorization: Bearer pdtk_abc123..." \
  -H "Content-Type: application/json" \
  -d '{"slugs": ["v1", "v2", "v3"], "updates": {"status_slug": "released"}}' \
  https://polydrobe.app/api/v1/projects/cyber-skins/bulk/variants/update/

Available endpoints

The REST API covers all project operations. Every resource uses slug-based URLs.

Projects:     GET|POST /v1/projects/
              GET|PATCH|DELETE /v1/projects/{slug}/

Assets:       GET|POST /v1/projects/{slug}/assets/
              GET|PATCH|DELETE /v1/projects/{slug}/assets/{slug}/

Variants:     GET|POST /v1/projects/{slug}/assets/{slug}/variants/
              GET|PATCH|DELETE /v1/projects/{slug}/assets/{slug}/variants/{slug}/
              GET /v1/projects/{slug}/variants/  (flat list)

Classification: GET|POST /v1/projects/{slug}/{categories|tags|rarities|releases|currencies|statuses}/
                PATCH|DELETE /v1/projects/{slug}/{entity}/{slug}/

Team:         GET|POST /v1/projects/{slug}/members/
              PATCH|DELETE /v1/projects/{slug}/members/{user_id}/

Search:       GET /v1/projects/{slug}/search/?q=term&type=all
Activity:     GET /v1/projects/{slug}/activity/
Export:       GET /v1/projects/{slug}/export/?format=json
Webhooks:     GET|POST /v1/projects/{slug}/webhooks/

1. Generate a personal access token

Go to Settings > API Tokens and create a new token. Name it after your AI client (e.g. 'Claude Desktop' or 'Claude Code'). Select read and write scopes, and choose a long expiration (1 year or no expiration). Copy the token immediately — it is shown only once.

# Your token will look like this:
pdtk_a8f3b2c1d4e5f6a7b8c9d0e1f2a3b4c5...

# Use this token in the configuration steps below.
# The same token works for both REST API and MCP server.

2. Connect Claude Desktop

Add the PolyDrobe MCP server to your Claude Desktop configuration. Open claude_desktop_config.json and add this entry.

{
  "mcpServers": {
    "polydrobe": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://polydrobe.app/mcp"],
      "env": {
        "MCP_HEADERS": "Authorization: Bearer pdtk_abc123..."
      }
    }
  }
}

3. Connect Claude Code

Add the MCP server from the terminal using the Claude Code CLI.

claude mcp add polydrobe \
  --transport http \
  --url https://polydrobe.app/mcp \
  --header "Authorization: Bearer pdtk_abc123..."

4. Local development (stdio mode)

For local development, run the MCP server directly over stdio without HTTP. This pre-authenticates as the specified user.

python manage.py mcp_stdio --user=your-username

# Claude Desktop config for local stdio:
{
  "mcpServers": {
    "polydrobe-local": {
      "command": "python",
      "args": ["manage.py", "mcp_stdio", "--user=your-username"],
      "cwd": "/path/to/polydrobe"
    }
  }
}

5. Try it out

Once connected, ask your AI assistant natural-language questions about your project data.

# Example prompts for your AI assistant:

"List all my projects"
"Show me the assets in project 'cyber-skins'"
"Create a new asset called 'Neon Jacket' in the 'outerwear' category"
"Search for legendary variants with price above 20"
"Set up categories: Headwear, Outerwear, Footwear, Accessories"
"Tag all sword assets with 'melee' and 'weapon'"
"Export the project data as JSON"
"Give me a project overview with sample thumbnails"

Available MCP tools (51)

The MCP server exposes 51 tools organized by category. AI assistants can discover and use these automatically.

Projects:       list_projects, get_project, create_project,
                update_project, delete_project

Assets:         list_assets, get_asset, create_asset,
                update_asset, delete_asset

Variants:       list_variants, create_variant,
                update_variant, delete_variant

Classification: list_categories, create_category, update_category,
                delete_category, list_tags, create_tag, delete_tag,
                list_rarities, create_rarity, list_releases,
                create_release, list_currencies, create_currency,
                list_statuses, create_status

Tags:           add_asset_tags, remove_asset_tags,
                add_variant_tags, remove_variant_tags

Team:           list_members, update_member_role, remove_member

Search:         search (full-text across assets & variants)
Activity:       get_activity_log

Images:         fetch_variant_thumbnail, fetch_variant_image,
                fetch_variant_texture, set_variant_thumbnail

Bulk:           bulk_create_variants, bulk_update_variants,
                bulk_delete_variants

Data:           export_project, import_project_data

OAuth 2.1 for production (advanced)

For CI/CD pipelines and server-to-server integrations, you can use OAuth 2.1 client credentials flow instead of personal tokens. Contact support for OAuth application setup.

# Exchange client credentials for an access token:
curl -X POST https://polydrobe.app/o/token/ \
  -d "grant_type=client_credentials" \
  -d "client_id=your-client-id" \
  -d "client_secret=your-client-secret" \
  -d "scope=read write"

# For most use cases, personal access tokens from
# Settings > API Tokens are simpler and sufficient.

shield_person Role Guidance

Who can do what

Three roles with clear boundaries. Viewers are always free.

admin_panel_settings

Owner

Manages project settings, billing-plan limits, and team access.

check_circle Project settings & configuration
check_circle Billing & subscription management
check_circle Team member management
check_circle Full asset CRUD
check_circle Import & Export
check_circle Delete project

Billable seat

edit_note

Editor

Creates and updates assets, variants, and operational data.

remove Project settings
remove Billing
remove Team management
check_circle Full asset CRUD
check_circle Import & Export
remove Delete project

Billable seat

visibility

Viewer

Reads project data for review, QA, or stakeholder visibility.

remove Project settings
remove Billing
remove Team management
remove Create or edit assets
remove Import & Export
check_circle Read-only browsing

Free seat

help FAQ

Frequently asked questions

What is PolyDrobe? expand_more

PolyDrobe is a game asset management platform for documenting, versioning, and collaborating on apparel assets — skins, cosmetics, and accessories — across a game project. It replaces spreadsheets with a structured, searchable database built for game asset pipelines.

What types of assets does PolyDrobe manage? expand_more

PolyDrobe is designed for game apparel and cosmetic items: character skins, outfits, accessories, weapons, and any item that has multiple visual variants. Each asset can have multiple variants representing different colorways, quality tiers, or seasonal versions.

Does PolyDrobe support 3D model preview? expand_more

Yes. PolyDrobe includes a built-in 3D model viewer that renders .glb and .gltf files directly in the browser. You can attach mesh files to assets and texture files to variants and preview them without leaving the app.

How does PolyDrobe compare to Google Sheets for game asset tracking? expand_more

Google Sheets lacks structured data types, version tracking, team role controls, and media management. PolyDrobe provides dedicated fields for rarity, status, price, release version, and tags; stores thumbnails and 3D models; and enforces role-based access. It is built specifically for game asset catalogues rather than general spreadsheet use.

How is PolyDrobe different from Notion or Airtable? expand_more

Notion and Airtable are generic database tools that require significant setup to track game assets. PolyDrobe is purpose-built with a fixed schema optimised for game apparel: asset-variant hierarchy, 3D model viewer, texture management, pipeline statuses, rarity levels, and release versioning — all ready to use out of the box.

What game engines is PolyDrobe compatible with? expand_more

PolyDrobe is engine-agnostic. It acts as a documentation and collaboration hub, not a runtime tool. Teams using Unity, Unreal Engine, Godot, or custom engines can use PolyDrobe to catalogue and manage their asset library. The JSON/Excel export and MCP server integration allow data to flow into any pipeline.

Can AI agents interact with PolyDrobe? expand_more

Yes. PolyDrobe has a Model Context Protocol (MCP) server at https://polydrobe.app/mcp with 51 tools. AI assistants such as Claude and ChatGPT can connect using a Bearer token, then list projects, manage assets and variants, configure classifications, assign tags, bulk-update entries, and search the database using natural language. See the Developer Guides section for setup instructions.

What is the difference between the REST API and the MCP server? expand_more

Both access the same data through the same shared service layer. The REST API uses standard HTTP methods (GET, POST, PATCH, DELETE) with JSON request/response envelopes — ideal for scripts, CI/CD pipelines, and custom integrations. The MCP server uses the Model Context Protocol — designed for AI assistants like Claude and ChatGPT to interact with your data using natural language. Both require a Professional plan and OAuth2 authentication.

How do I get an API access token? expand_more

Go to Settings > API Tokens and click Create Token. Give it a name, select scopes (read, write), and choose an expiration period. The token is shown once — copy it immediately. It works for both the REST API and the MCP server. Requires a Professional plan.

Does PolyDrobe support team collaboration? expand_more

Yes. Projects support multiple team members with three roles: Owner (full control including settings and billing), Editor (can create and update assets and variants), and Viewer (read-only access for QA or stakeholder review). Invite teammates by email from Project Settings.

Should I model each skin as an asset or variant? expand_more

Use one asset for the core item and variants for each skin or version. For example, a Hoodie asset might have variants named Hoodie Blue, Hoodie Red, and Hoodie Gold. The asset holds shared properties like mesh file and category; variants hold per-version properties like texture, price, and rarity.

How do I keep naming consistent? expand_more

Use clear naming conventions and rely on slug-based URLs for stable references. PolyDrobe auto-generates URL slugs from names, so a consistent naming convention produces consistent, human-readable URLs that remain stable even if the display name changes.

Can I share project data externally? expand_more

Yes, on plans that include Data Exchange. Use the Data Exchange page to export the full project to JSON or Excel and share with downstream tools, publishers, or external contractors.

What does the Free plan include? expand_more

The Free plan includes 1 owned project, up to 3 members, 1 GB of workspace storage, unlimited assets, 100 variants per project, and 30 days of activity retention.

Do Viewer seats count toward billing? expand_more

No. Only Owner and Editor roles are billable seats. Viewers stay free regardless of how many you add.

Is PolyDrobe a SaaS product? expand_more

Yes. PolyDrobe is a web-based SaaS application hosted at polydrobe.app. There is no software to install. Sign up, create a project, and start adding assets immediately.

Can I import existing asset data into PolyDrobe? expand_more

Yes. PolyDrobe supports JSON, Excel, and Google Sheets import. You can export your existing spreadsheet in the expected format and import it using the Data Exchange page. The importer validates data and shows errors before committing changes.

What columns does the Google Sheets import template need? expand_more

Each worksheet uses specific columns. Categories need: slug, name, description, parent_slug. Tags need: slug, name, value. Rarities need: name, color (#RRGGBB hex), priority. Currencies need: code, name, symbol. Releases need: version, name, description, release_date (YYYY-MM-DD). Assets need: slug, name, description, category_slug, tags. Variants need: slug, name, asset_slug, rarity, release, currency, price, description, tags. Column headers are case-sensitive and must appear in the first row.

Why does my Google Sheets import say 'Spreadsheet metadata could not be loaded'? expand_more

This usually means the file is an uploaded .xlsx opened in Google Sheets rather than a native Google Spreadsheet. URLs with 'rtpof=true' parameters indicate an uploaded file. Fix: open the file in Google Sheets, go to File > Save as Google Sheets, and use the new URL. Also verify the spreadsheet is shared with (or owned by) the connected Google account.

Do I need to connect Google separately for each project? expand_more

Yes. Each project requires its own Google connection for multi-tenancy isolation. Different projects may have different owners and access controls. The same Google account can be used across all projects.

build Troubleshooting

Common issues

Quick fixes for the most frequent problems.

lock

Missing permissions

If an action is unavailable, check your project role and ask an Owner for access updates.

error

Import validation errors

Review required fields, category slugs, and enum values before retrying import.

cloud_upload

Media upload issues

Verify file type, file size, and current storage usage against your active plan limits.

link_off

Google Sheets: 'Spreadsheet metadata could not be loaded'

The file is likely an uploaded .xlsx, not a native Google Spreadsheet. Open the file, go to File > Save as Google Sheets, and use the new URL. Also check that the connected Google account has access to the spreadsheet.

sell

Google Sheets: Assets or Variants fail with 'Tag not found' or 'Category not found'

Referenced entities must exist before they can be used. Import processes worksheets in order (Categories > Tags > Rarities > Currencies > Releases > Assets > Variants). If a referenced entity failed to import, dependent entities will also fail. Check the dry run preview for errors in earlier entity types first.

attach_money

Google Sheets: Variant price shows 'invalid price'

Both dot (9.99) and comma (9,99) decimal separators are supported. If you still get this error, check for stray characters, currency symbols, or spaces in the price cell.

Still have questions?

We're here to help. Reach out and we'll get back to you quickly.

mail Contact us