Automating Asset Import/Export with ShotGrid’s REST API – Authentication, Payloads, and Error Handling

Why Use the REST API for Asset Automation?

ShotGrid’s REST API lets you create, update, and query assets programmatically. For studios that need to sync external pipelines (e.g., Houdini, Maya, or asset databases) with ShotGrid, the API is the single source of truth. The key takeaway: authenticate once, then embed the bearer token in every subsequent request, and keep payloads small and well‑structured to avoid validation errors.

Step 1: Get an OAuth2 Bearer Token

The API uses OAuth2 client‑credentials flow. First, create an API key in Admin > API Keys and note the Client ID and Client Secret. Then request a token:

curl -X POST \
  https://YOUR_SHOTGRID_DOMAIN/api/v1/oauth/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials&client_id=YOUR_CLIENT_ID&client_secret=YOUR_CLIENT_SECRET"

Response (JSON):

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "expires_in": 3600,
  "token_type": "Bearer"
}

Store access_token safely; it must be included in the Authorization header for every API call:

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

Step 2: Create an Asset

ShotGrid expects JSON with case‑sensitive field names. Required fields for a new asset are type and code. Optional fields include tags and entity_description.

Example payload (save as create_asset.json):

{
  "type": "Model",
  "code": "Hero_01",
  "tags": ["ready", "review"],
  "entity_description": "Hero character model for Act 1"
}

Send the POST request:

curl -X POST \
  https://YOUR_SHOTGRID_DOMAIN/api/v1/entity/Asset \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d @create_asset.json

Success returns HTTP 201 with the new asset’s id. If you omit code or use an incorrect case (e.g., Code), ShotGrid will reply with a 400 Bad Request and a JSON body like:

{"code": "validation_error", "message": "'code' field is required."}

Step 3: Query Assets with Pagination

Large studios often have thousands of assets. Use the page and page_size query parameters to retrieve results in chunks. Example: fetch the first 50 assets of type "Model".

curl -X GET \
  "https://YOUR_SHOTGRID_DOMAIN/api/v1/entity/Asset?filter=[[\"type\",\"is\",\"Model\"]]&page=1&page_size=50" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Response includes total_count and page metadata. Loop until page * page_size >= total_count.

Step 4: Handle Rate Limiting and Retries

ShotGrid enforces per‑user rate limits. When you exceed them, the API returns HTTP 429 with a Retry-After header. Implement exponential backoff:

def request_with_retry(url, headers, payload=None):
    for attempt in range(5):
        resp = requests.request("POST", url, headers=headers, json=payload)
        if resp.status_code != 429:
            return resp
        wait = int(resp.headers.get("Retry-After", 1)) * (2 ** attempt)
        time.sleep(wait)
    raise Exception("Rate limit exceeded after retries")

Check the Retry-After header; if absent, default to 1 second.

Step 5: Upload Large Files (e.g., Thumbnails)

ShotGrid’s multipart upload endpoint (/api/v1/entity/Asset/{id}/upload) must be used for files > 5 MB. Base64 payloads are not accepted. Example using curl:

curl -X POST \
  https://YOUR_SHOTGRID_DOMAIN/api/v1/entity/Asset/12345/upload \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -F "file=@/path/to/thumbnail.png"

After upload, the asset’s thumbnail field will reference the file.

Common Pitfalls and Limits

• Case‑sensitivity: Field names like code must be lowercase. Using Code triggers a 400 error.
• Missing required fields: Always validate your JSON before sending. A 400 response will list the missing keys.
• Rate limits: Different user tiers have different caps. Monitor 429 responses and back off accordingly.
• Large payloads: Keep JSON payloads under 2 MB. For bulk imports, use the bulk endpoint if available.
• Token expiration: Tokens last 1 hour by default. Refresh before expiry to avoid 401 errors.

Verifying Success

After creating or updating an asset, query it back to confirm the changes:

curl -X GET \
  "https://YOUR_SHOTGRID_DOMAIN/api/v1/entity/Asset?filter=[[\"code\",\"is\",\"Hero_01\"]]" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Inspect the returned JSON for the expected fields. For automated pipelines, log the id and any error messages to a monitoring system.

Conclusion

With a single bearer token and well‑structured JSON, you can reliably automate asset import and export in ShotGrid. Follow the best practices above to avoid common errors, respect rate limits, and keep your pipeline robust.