Shotgrid REST API: Create Custom Fields for Assets and Shots

Want to extend Shotgrid with new data points? This guide walks you through creating custom fields for assets and shots with the REST API, showing payloads, batch updates, and how to avoid common pitfalls.

Concrete Problem: Manual UI Workflows Are a Bottleneck

Production teams often need to capture new data points on assets or shots—think “Lead Actor”, “Location Code”, or “Color Grade Version”. The Shotgrid UI lets you add a field, but doing this for dozens of entities, or doing it programmatically as part of a pipeline, is tedious and error‑prone. Moreover, once a field exists in the UI it is invisible to automated tools that rely on the API, forcing a manual sync.

In short: you want a repeatable, scriptable way to create, update, and remove custom fields across any entity type, and you want to do it without constantly logging into Shotgrid.

Thesis: Shotgrid’s REST API Gives Full Control Over Custom Fields

Shotgrid’s /custom_fields endpoint is the single point of truth for field definitions. By combining it with the bulk /batch endpoint you can:

Create new fields in a single request.
Attach them to the desired entity type (assets, shots, tasks, etc.).
Set visibility and permission rules per role.
Perform multiple changes atomically.

The following sections walk through the exact payloads, commands, and checks you need to make this work reliably.

1. Custom Field Types and Payload Structure

Shotgrid supports primitive types (text, number, date) and complex types (entity reference, enum). Each type requires a specific data_type value and optional data_type_options.

Type	data_type	data_type_options (example)
Text	text	—
Number	number	—
Date	date	—
Entity Reference	entity_reference	{"entity_type":"assets"}
Enum	enum	{"choices":["Red","Green","Blue"]}

Payload Skeleton

{
  "name": "",
  "data_type": "",
  "data_type_options": { /* optional */ },
  "entity_type": "",
  "entity_schema": {
    "default_value": "",
    "required": false,
    "display_name": ""
  }
}

Key points:

name must be unique per entity type. Duplicate names return a 400 error.
Changing data_type after data exists can corrupt records; plan migrations carefully.
Always include entity_type so Shotgrid knows where to register the field.

2. Creating a Custom Field for Shots

Example: Add a text field called “Lead Actor” to the shots entity.

curl -X POST \
  "${SHOTGRID_BASE_URL}/api/v1/custom_fields" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ${YOUR_API_KEY}" \
  -d '{
    "name": "lead_actor",
    "data_type": "text",
    "entity_type": "shots",
    "entity_schema": {
      "default_value": "",
      "required": false,
      "display_name": "Lead Actor"
    }
  }'

Run this in a terminal on the machine that has network access to Shotgrid. You need ADMIN or a role that can manage fields. Expect a 201 Created response. If you get a 400 check that no field named lead_actor already exists for shots.

3. Registering the Field in the Entity Schema

Shotgrid automatically registers the new field on the entity when the POST succeeds. To verify:

curl -X GET \
  "${SHOTGRID_BASE_URL}/api/v1/entities/shots/fields" \
  -H "Authorization: Bearer ${YOUR_API_KEY}"

Look for an entry with name: lead_actor in the JSON array. If it’s missing, the creation failed or you’re querying the wrong entity type.

4. Batch Operations: Adding Multiple Fields at Once

When you need to add several fields—say, “Location Code” (text) and “Color Grade Version” (enum)—use the /batch endpoint to reduce round‑trips.

curl -X POST \
  "${SHOTGRID_BASE_URL}/api/v1/batch" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ${YOUR_API_KEY}" \
  -d '{
    "operations": [
      {
        "method": "POST",
        "path": "/custom_fields",
        "body": {
          "name": "location_code",
          "data_type": "text",
          "entity_type": "shots",
          "entity_schema": {
            "default_value": "",
            "required": false,
            "display_name": "Location Code"
          }
        }
      },
      {
        "method": "POST",
        "path": "/custom_fields",
        "body": {
          "name": "grade_version",
          "data_type": "enum",
          "data_type_options": {"choices": ["A", "B", "C"]},
          "entity_type": "shots",
          "entity_schema": {
            "default_value": "A",
            "required": true,
            "display_name": "Color Grade Version"
          }
        }
      }
    ]
  }'

The batch response will contain a results array with status codes for each operation. A 201 for each indicates success. If any operation fails, the others still succeed; you’ll need to handle partial failures in your script.

5. Field Visibility and Permissions

Custom fields can be hidden from certain roles. After creation, update the field’s entity_schema to include a permissions object:

{
  "entity_schema": {
    "required": false,
    "display_name": "Lead Actor",
    "permissions": {
      "read": ["Studio Admin", "Producer"],
      "write": ["Studio Admin"]
    }
  }
}

Send a PATCH to /custom_fields/{id} with the updated schema. Users without the listed roles will see the field as read‑only or hidden in the UI.

Trade‑Offs and Limitations

Data Type Changes: Once data exists, changing data_type can corrupt records. Use a migration script that copies data to a new field, then deletes the old one.
Rate Limits: Shotgrid enforces per‑minute request limits. Bulk operations mitigate this, but avoid hammering the API with individual field creations in a tight loop.
Unique Names: Field names are unique per entity. Plan naming conventions to avoid clashes across projects.

Actionable Checklist

Define the field schema and test the payload in API Explorer or Postman.
Use curl or your preferred HTTP client to POST to /custom_fields (or /batch).
Verify creation with GET /entities/{entity_type}/fields.
Assign values to the field in a shot record via the UI or by PATCHing /shots/{id} with the field key.
Check persistence by retrieving the shot again and confirming the field value appears.
Document the field definition in your pipeline repo so future developers know the expected schema.

By following this workflow you can keep your Shotgrid data model in sync with automated processes, reduce manual UI work, and enforce consistent permissions across your team.

Adding and Managing Custom Fields in Shotgrid via the REST API: A Practical Guide