diff --git a/docs/openapi/spec.yaml b/docs/openapi/spec.yaml new file mode 100644 index 00000000..ea2d376d --- /dev/null +++ b/docs/openapi/spec.yaml @@ -0,0 +1,2103 @@ +openapi: "3.0.3" + +info: + title: "Flow Production Tracking Python API" + version: "3.10.0" + description: | + OpenAPI 3.0.3 description of the [Flow Production Tracking Python API](https://developers.shotgridsoftware.com/python-api/reference.html) (`shotgun_api3` v3.10.0). + + ## Shotgun Client + + The main entry point is the `Shotgun` class: + + ```python + import shotgun_api3 + sg = shotgun_api3.Shotgun( + "https://yoursite.shotgrid.autodesk.com", + script_name="my_script", + api_key="abc123" + ) + ``` + + **Constructor parameters:** + - `base_url` (str) – http or https URL of the Shotgun server (no trailing slash) + - `script_name` (str) – Script entity name for authentication. If provided, `api_key` must also be provided. + - `api_key` (str) – API key for `script_name`. If provided, `script_name` must also be provided. + - `convert_datetimes_to_utc` (bool) – Convert datetimes to UTC (default: `True`) + - `http_proxy` (str) – Optional proxy URL (`[username:password@]111.222.333.444[:8080]`) + - `connect` (bool) – Connect on instantiation (default: `True`) + - `ca_certs` (str) – Optional path to external SSL certificates file + - `login` (str) – Human user login for user-based authentication + - `password` (str) – Human user password + - `sudo_as_login` (str) – Impersonate a user; event logs show this user with `sudo_actual_user` in meta-data + - `session_token` (str) – Session token as alternative to script or user authentication + - `auth_token` (str) – One-time token for two-factor authentication (requires `login` + `password`) + + ## Module Attributes + + `shotgun_api3.shotgun.LOG` — Logging instance for `shotgun_api3`. Provides a logging instance + where log messages are sent during execution. This instance has no handler associated with it. + + ## Transport + + Most methods use a single JSON-RPC endpoint: + + ``` + POST /api3/json + Content-Type: application/json + ``` + + Each request body contains `method_name` and `params`. For all methods except `info`, + `params[0]` is an authentication object and `params[1]` is the method-specific argument object. + + File operations (`upload`, `download_attachment`, etc.) use separate multipart/binary HTTP endpoints. + + ## Python Client-Only Methods + + The following methods are handled entirely by the Python client and do not make HTTP requests: + + - `connect()` — Connect client to the server if not already connected. The client connects automatically on demand; only call this to confirm connectivity. + - `close()` — Close the current connection to the server. The client reconnects automatically if needed. + - `get_auth_cookie_handler()` — Return an urllib cookie handler containing a cookie for FPTR authentication. Used internally for downloading attachments. + - `add_user_agent(agent)` — Append `agent` string to the user-agent header sent with every API request. + - `reset_user_agent()` — Reset user-agent to the default value (e.g. `shotgun-json (3.0.17); Python 2.6 (Mac); ssl OpenSSL 1.0.2d 9 Jul 2015 (validate)`). + - `set_session_uuid(session_uuid)` — Set the browser `session_uuid` so events generated by this API instance appear in that browser session. + + ## Authentication + + Pass one of the following as `params[0]` for all methods except `info`: + + | Auth type | Fields | + |---------------|---------------------------------| + | Script token | `script_name` + `script_key` | + | Session token | `session_token` | + | User/password | `user_login` + `user_password` | + + ## Data Types + + Shotgun field data types (used in `schema_field_create` and returned by schema methods): + + - `addressing` — Addressing field + - `checkbox` — Boolean checkbox + - `color` — Color value + - `currency` — Currency value + - `date` — Date (`YYYY-MM-DD`) + - `date_time` — Date and time (UTC) + - `duration` — Duration in minutes + - `entity` — Single entity link + - `float` — Floating point number + - `footage` — Footage value + - `image` (read-only) — Image/thumbnail URL. Three states: `None` (no image), transient placeholder URL (image processing), or signed S3 URL. + - `list` — List value + - `multi_entity` — Multiple entity links + - `number` — Integer number + - `password` — Password field + - `percent` — Percentage value + - `serializable` — Serializable data + - `status_list` — Status list value + - `system_task_type` (deprecated) — System task type + - `tag_list` — Tag list + - `text` — Text string + - `timecode` — Timecode value + - `url` — File/link field. For API v3.0.3+: `{"link_type": "local"|"url"|"upload", "name": "string", "content_type": "string", "url": "string", "local_path": "string", "local_storage": {...}, "relative_path": "string|null"}`. For API < v3.0.3: `{"url": "string", "name": "string", "content_type": "string"}`. + + ## Filter Syntax + + ### Basic Filters + + Filters are a list of conditions combined with `filter_operator` (`"all"` = AND, `"any"` = OR): + + ```python + filters = [ + ["sg_status_list", "is", "ip"], + ["assets", "is", {"type": "Asset", "id": 9}] + ] + ``` + + ### Complex Filters + + Complex filters use a dict with `filter_operator` and nested `filters`: + + ```python + filters = [ + ["sg_status_list", "is", "ip"], + { + "filter_operator": "any", + "filters": [ + ["assets", "is", {"type": "Asset", "id": 9}], + ["assets", "is", {"type": "Asset", "id": 23}] + ] + } + ] + ``` + + ### Operators + + | Operator | Arguments | + |---|---| + | `is` | `[field_value]` or `None` | + | `is_not` | `[field_value]` or `None` | + | `less_than` | `[field_value]` or `None` | + | `greater_than` | `[field_value]` or `None` | + | `contains` | `[field_value]` | + | `not_contains` | `[field_value]` | + | `starts_with` | `[string]` | + | `ends_with` | `[string]` | + | `between` | `[min_value, max_value]` | + | `not_between` | `[min_value, max_value]` | + | `in_last` | `[int, "HOUR"\|"DAY"\|"WEEK"\|"MONTH"\|"YEAR"]` | + | `in_next` | `[int, "HOUR"\|"DAY"\|"WEEK"\|"MONTH"\|"YEAR"]` | + | `in` | `[[field_value, ...]]` | + | `not_in` | `[[field_value, ...]]` | + | `type_is` | `[entity_type_string]` | + | `type_is_not` | `[entity_type_string]` | + | `name_contains` | `[string]` | + | `name_not_contains` | `[string]` | + | `name_starts_with` | `[string]` | + | `name_ends_with` | `[string]` | + + ### Additional Filter Presets + + Pass via `additional_filter_presets` parameter in `find()` and `find_one()`: + + ```python + additional_filter_presets = [{"preset_name": "pipeline_step_id", "pipeline_step_id": 3}] + ``` + + These presets are ANDed together and ANDed with the main `filters` argument. + + ## Interpreting Image Field Strings + + Three possible states for values returned by an `image` field: + + | Type | Value | + |---|---| + | `None` | No thumbnail uploaded, or thumbnail generation failed | + | `str` | `:///images/status/transient/thumbnail_pending.png` — Transient placeholder (image between upload and availability). Constant string per site. | + | `str` | Signed URL for S3 object — Final thumbnail | + + Use the prefix part of the placeholder path to detect transient URLs rather than the full path. + + ## Event Types + + Structure: `Application_EntityType_Action` + + - `Application` — Always `"Shotgun"` for server-generated events. Other products use their name (e.g. `"Toolkit"`). + - `EntityType` — Entity type acted upon (e.g. `Shot`, `Asset`) + - `Action` — `New`, `Change`, `Retirement`, `Revival` + + ### Standard Event Types + - `Shotgun_EntityType_New` — Entity created (e.g. `Shotgun_Task_New`) + - `Shotgun_EntityType_Change` — Entity modified (e.g. `Shotgun_HumanUser_Change`) + - `Shotgun_EntityType_Retirement` — Entity deleted (e.g. `Shotgun_Ticket_Retirement`) + - `Shotgun_EntityType_Revival` — Entity revived (e.g. `Shotgun_CustomEntity03_Revival`) + + ### Additional Event Types + - `Shotgun_Attachment_View` — Attachment viewed + - `Shotgun_Reading_Change` — Threaded entity marked read/unread + - `Shotgun_User_Login` — User logged in + - `Shotgun_User_Logout` — User logged out + + Custom event types can be created via `EventLogEntry` entities using the standard `create()` method. + + ## Environment Variables + + - `SHOTGUN_API_CACERTS` — Override the default Root CA certificate store. Equivalent to `ca_certs` constructor argument (constructor takes precedence). + - `SHOTGUN_API_RETRY_INTERVAL` — Milliseconds to wait between request retries (default: `3000`). Equivalent to `sg.config.rpc_attempt_interval` (config property takes precedence). + - `SHOTGUN_API_DISABLE_ENTITY_OPTIMIZATION` — Set to `1` to disable entity optimization. When enabled (default), reduces payload size by stripping extra entity attributes from filter values before sending to the server. + - `SHOTGUN_ALLOW_OLD_PYTHON` — Set to `1` to allow importing on unsupported Python versions (not recommended). + + ## Localization + + Display names in schema methods can be returned in the current user's language. Requests from script/API users are localized per site settings. + + Supported by: `schema_entity_read`, `schema_field_read`, `schema_read`. + + Disabled by default. Enable with `sg.config.localized = True`. + + contact: + name: "Autodesk Flow Production Tracking" + url: "https://www.autodesk.com/products/flow-production-tracking" + license: + name: "Other" + url: "https://github.com/shotgunsoftware/python-api/blob/master/LICENSE" + +servers: + - url: "https://{site}.shotgrid.autodesk.com" + description: "Production site" + variables: + site: + default: "yoursite" + description: "Your Flow Production Tracking site subdomain" + - url: "https://{site}.shotgunstudio.com" + description: "Legacy production site" + variables: + site: + default: "yoursite" + description: "Your Flow Production Tracking site subdomain (legacy)" + +tags: + - name: "Connection & Authentication" + description: | + Methods for connecting and authenticating with your Flow Production Tracking server. + Most of this is done automatically when you instantiate your `Shotgun` instance. + - name: "Subscription Management" + description: "Methods for reading and assigning user subscriptions." + - name: "CRUD" + description: | + Create, read, update, delete, and revive entity records. + Includes specialized convenience methods for notes, search, scheduling, preferences, and export. + - name: "Working With Files" + description: "Upload and download file attachments. These methods use separate HTTP endpoints (multipart upload, binary download)." + - name: "Activity Stream" + description: "Retrieve activity stream data and manage entity follow/unfollow." + - name: "Schema" + description: "Introspect and modify the Shotgun schema (entity types and fields)." + +security: + - api3RequestBodyAuth: [] + +paths: + + /api3/json: + post: + operationId: api3Dispatch + summary: "JSON-RPC Dispatch" + security: + - api3RequestBodyAuth: [] + description: | + Single dispatch endpoint for all API3 JSON-RPC methods. + The method is selected via the `method_name` field in the request body. + + Authentication is passed as `params[0]` for all methods except `info`. + tags: + - "Connection & Authentication" + - "Subscription Management" + - "CRUD" + - "Activity Stream" + - "Schema" + requestBody: + required: true + content: + application/json: + schema: + oneOf: + - $ref: '#/components/schemas/InfoRequest' + - $ref: '#/components/schemas/AuthenticateHumanUserRequest' + - $ref: '#/components/schemas/GetSessionTokenRequest' + - $ref: '#/components/schemas/UserSubscriptionsReadRequest' + - $ref: '#/components/schemas/UserSubscriptionsCreateRequest' + - $ref: '#/components/schemas/CreateRequest' + - $ref: '#/components/schemas/FindRequest' + - $ref: '#/components/schemas/FindOneRequest' + - $ref: '#/components/schemas/UpdateRequest' + - $ref: '#/components/schemas/DeleteRequest' + - $ref: '#/components/schemas/ReviveRequest' + - $ref: '#/components/schemas/BatchRequest' + - $ref: '#/components/schemas/SummarizeRequest' + - $ref: '#/components/schemas/NoteThreadReadRequest' + - $ref: '#/components/schemas/TextSearchRequest' + - $ref: '#/components/schemas/UpdateProjectLastAccessedRequest' + - $ref: '#/components/schemas/WorkScheduleReadRequest' + - $ref: '#/components/schemas/WorkScheduleUpdateRequest' + - $ref: '#/components/schemas/PreferencesReadRequest' + - $ref: '#/components/schemas/ExportPageRequest' + - $ref: '#/components/schemas/ActivityStreamReadRequest' + - $ref: '#/components/schemas/FollowRequest' + - $ref: '#/components/schemas/UnfollowRequest' + - $ref: '#/components/schemas/FollowersRequest' + - $ref: '#/components/schemas/FollowingRequest' + - $ref: '#/components/schemas/SchemaEntityReadRequest' + - $ref: '#/components/schemas/SchemaFieldReadRequest' + - $ref: '#/components/schemas/SchemaFieldCreateRequest' + - $ref: '#/components/schemas/SchemaFieldUpdateRequest' + - $ref: '#/components/schemas/SchemaFieldDeleteRequest' + - $ref: '#/components/schemas/SchemaReadRequest' + - $ref: '#/components/schemas/SchemaDeprecatedRequest' + discriminator: + propertyName: method_name + mapping: + info: '#/components/schemas/InfoRequest' + authenticate_human_user: '#/components/schemas/AuthenticateHumanUserRequest' + get_session_token: '#/components/schemas/GetSessionTokenRequest' + user_subscriptions_read: '#/components/schemas/UserSubscriptionsReadRequest' + user_subscriptions_create: '#/components/schemas/UserSubscriptionsCreateRequest' + create: '#/components/schemas/CreateRequest' + read: '#/components/schemas/FindRequest' + find_one: '#/components/schemas/FindOneRequest' + update: '#/components/schemas/UpdateRequest' + delete: '#/components/schemas/DeleteRequest' + revive: '#/components/schemas/ReviveRequest' + batch: '#/components/schemas/BatchRequest' + summarize: '#/components/schemas/SummarizeRequest' + note_thread_read: '#/components/schemas/NoteThreadReadRequest' + text_search: '#/components/schemas/TextSearchRequest' + update_project_last_accessed_by_current_user: '#/components/schemas/UpdateProjectLastAccessedRequest' + work_schedule_read: '#/components/schemas/WorkScheduleReadRequest' + work_schedule_update: '#/components/schemas/WorkScheduleUpdateRequest' + preferences_read: '#/components/schemas/PreferencesReadRequest' + export_page: '#/components/schemas/ExportPageRequest' + activity_stream_read: '#/components/schemas/ActivityStreamReadRequest' + follow: '#/components/schemas/FollowRequest' + unfollow: '#/components/schemas/UnfollowRequest' + followers: '#/components/schemas/FollowersRequest' + following: '#/components/schemas/FollowingRequest' + schema_entity_read: '#/components/schemas/SchemaEntityReadRequest' + schema_field_read: '#/components/schemas/SchemaFieldReadRequest' + schema_field_create: '#/components/schemas/SchemaFieldCreateRequest' + schema_field_update: '#/components/schemas/SchemaFieldUpdateRequest' + schema_field_delete: '#/components/schemas/SchemaFieldDeleteRequest' + schema_read: '#/components/schemas/SchemaReadRequest' + schema: '#/components/schemas/SchemaDeprecatedRequest' + entity_types: '#/components/schemas/SchemaDeprecatedRequest' + examples: + info: + summary: "Get server info (no auth required)" + value: + method_name: "info" + params: [] + create_shot: + summary: "Create a Shot entity" + value: + method_name: "create" + params: + - script_name: "my_script" + script_key: "abc123" + - entity_type: "Shot" + data: + project: {"type": "Project", "id": 161} + sg_sequence: {"type": "Sequence", "id": 109} + code: "001_100" + sg_status_list: "ip" + find_assets: + summary: "Find Character Assets in Sequence 100_FOO" + value: + method_name: "read" + params: + - script_name: "my_script" + script_key: "abc123" + - entity_type: "Asset" + filters: + - ["project", "is", {"type": "Project", "id": 4}] + - ["sg_asset_type", "is", "Character"] + - ["sequences", "is", {"type": "Sequence", "id": 2}] + fields: ["id", "code", "sg_asset_type"] + summarize_assets: + summary: "Count Assets by type for a Project" + value: + method_name: "summarize" + params: + - script_name: "my_script" + script_key: "abc123" + - entity_type: "Asset" + filters: + - ["project", "is", {"type": "Project", "id": 4}] + summary_fields: + - {"field": "id", "type": "count"} + grouping: + - {"field": "sg_asset_type", "type": "exact", "direction": "asc"} + responses: + '200': + description: "Successful response" + content: + application/json: + schema: + $ref: '#/components/schemas/ApiV3Response' + '400': + description: "Bad request — malformed JSON or invalid parameters" + content: + application/json: + schema: + $ref: '#/components/schemas/ApiV3ErrorResponse' + '401': + description: "Authentication failure — invalid or missing credentials" + content: + application/json: + schema: + $ref: '#/components/schemas/ApiV3ErrorResponse' + '403': + description: "Authorisation failure — insufficient permissions" + content: + application/json: + schema: + $ref: '#/components/schemas/ApiV3ErrorResponse' + '500': + description: "Internal server error" + content: + application/json: + schema: + $ref: '#/components/schemas/ApiV3ErrorResponse' + + /upload: + post: + operationId: upload + summary: "Upload a file to the specified entity" + tags: + - "Working With Files" + description: | + Upload a file to the specified entity. + + **Python client**: `sg.upload(entity_type, entity_id, path, field_name=None, display_name=None, tag_list=None)` + + Uploads a local file and attaches it to the specified entity. If `field_name` is provided, + the file is uploaded to that field directly. If `image` or `filmstrip_image` fields are + provided in a `create()` or `update()` call, the file path will be uploaded automatically. + + Parameters: + - `entity_type` (str) – Entity type + - `entity_id` (int) – Entity id + - `path` (str) – Path to local file to upload + - `field_name` (str) – Optional field name to attach the file to + - `display_name` (str) – Optional display name for the file + - `tag_list` (str) – Optional comma-separated tags + + Returns the Attachment id of the uploaded file. + requestBody: + required: true + content: + multipart/form-data: + schema: + type: object + required: [entity_type, entity_id, file] + properties: + entity_type: + type: string + description: "Entity type" + example: "Version" + entity_id: + type: integer + description: "Entity id" + example: 42 + field_name: + type: string + description: "Optional field name to attach file to" + display_name: + type: string + description: "Optional display name for the file" + tag_list: + type: string + description: "Optional comma-separated tags" + file: + type: string + format: binary + description: "File to upload" + responses: + '200': + description: "Attachment id of the uploaded file" + content: + application/json: + schema: + type: object + properties: + id: + type: integer + description: "Attachment entity id" + + /upload_thumbnail: + post: + operationId: uploadThumbnail + summary: "Upload a file and assign it as the thumbnail for the specified entity" + tags: + - "Working With Files" + description: | + Upload a file from a local path and assign it as the thumbnail for the specified entity. + + **Python client**: `sg.upload_thumbnail(entity_type, entity_id, path, **kwargs)` + + Parameters: + - `entity_type` (str) – Entity type + - `entity_id` (int) – Entity id + - `path` (str) – Path to local file + + Returns the Attachment id. + requestBody: + required: true + content: + multipart/form-data: + schema: + type: object + required: [entity_type, entity_id, file] + properties: + entity_type: + type: string + entity_id: + type: integer + file: + type: string + format: binary + responses: + '200': + description: "Attachment id" + content: + application/json: + schema: + type: object + properties: + id: + type: integer + + /upload_filmstrip_thumbnail: + post: + operationId: uploadFilmstripThumbnail + summary: "Upload filmstrip thumbnail to specified entity" + tags: + - "Working With Files" + description: | + Upload filmstrip thumbnail to specified entity. + + **Python client**: `sg.upload_filmstrip_thumbnail(entity_type, entity_id, path, **kwargs)` + + Parameters: + - `entity_type` (str) – Entity type + - `entity_id` (int) – Entity id + - `path` (str) – Path to filmstrip image file + + Returns the Attachment id. + requestBody: + required: true + content: + multipart/form-data: + schema: + type: object + required: [entity_type, entity_id, file] + properties: + entity_type: + type: string + entity_id: + type: integer + file: + type: string + format: binary + responses: + '200': + description: "Attachment id" + content: + application/json: + schema: + type: object + properties: + id: + type: integer + + /download_attachment: + get: + operationId: downloadAttachment + summary: "Download the file associated with a Shotgun Attachment" + tags: + - "Working With Files" + description: | + Download the file associated with a Shotgun Attachment. + + **Python client**: `sg.download_attachment(attachment, file_path=None, field_name=None, entity=None)` + + The Python client handles authentication and redirects automatically. Pass either an + Attachment entity dict or an attachment id. Optionally specify `field_name` and `entity` + to download from a field directly. + + Parameters: + - `attachment` – Attachment entity dict `{"type": "Attachment", "id": N}` or int id + - `file_path` (str) – Optional path to write the file to. If not provided, returns file data as bytes. + - `field_name` (str) – Optional field name for direct field download + - `entity` (dict) – Entity the attachment is linked to (required with `field_name`) + + Returns the file data as bytes, or writes to `file_path`. + parameters: + - name: id + in: query + schema: + type: integer + description: "Attachment entity id" + - name: field_name + in: query + schema: + type: string + description: "Optional field name for direct field download" + responses: + '200': + description: "File contents" + content: + application/octet-stream: + schema: + type: string + format: binary + + /get_attachment_download_url: + post: + operationId: getAttachmentDownloadUrl + summary: "Return the URL for downloading provided Attachment" + tags: + - "Working With Files" + description: | + Return the URL for downloading provided Attachment. + + **Python client**: `sg.get_attachment_download_url(attachment)` + + Parameters: + - `attachment` – Attachment entity dict `{"type": "Attachment", "id": N}` or int id + + Returns the download URL string. + requestBody: + required: true + content: + application/json: + schema: + type: object + properties: + attachment: + description: "Attachment entity dict or integer id" + responses: + '200': + description: "Download URL" + content: + application/json: + schema: + type: object + properties: + url: + type: string + format: uri + + /share_thumbnail: + post: + operationId: shareThumbnail + summary: "Associate a thumbnail with more than one Shotgun entity" + tags: + - "Working With Files" + description: | + Associate a thumbnail with more than one Shotgun entity. + + **Python client**: `sg.share_thumbnail(entities, thumbnail_path=None, source_entity=None, **kwargs)` + + Parameters: + - `entities` (list) – List of entity dicts to update with the shared thumbnail + - `thumbnail_path` (str) – Optional path to a local thumbnail file to upload + - `source_entity` (dict) – Optional entity whose existing thumbnail will be shared + + Returns the Attachment id of the thumbnail. + requestBody: + required: true + content: + application/json: + schema: + type: object + required: [entities] + properties: + entities: + type: array + items: + $ref: '#/components/schemas/EntityLink' + maxItems: 500 + description: "List of entities to update with the shared thumbnail" + thumbnail_path: + type: string + description: "Optional path to a local thumbnail file" + source_entity: + $ref: '#/components/schemas/EntityLink' + description: "Optional entity whose existing thumbnail will be shared" + responses: + '200': + description: "Attachment id of the thumbnail" + content: + application/json: + schema: + type: object + properties: + id: + type: integer + +components: + + securitySchemes: + api3RequestBodyAuth: + type: apiKey + in: header + name: X-SG-Auth-Placeholder + description: | + API3 authentication is handled inside the JSON request body as `params[0]`, + not via HTTP headers. This scheme is defined to satisfy OpenAPI tooling + requirements. Pass one of the following in `params[0]`: + - Script auth: `{"script_name": "...", "script_key": "..."}` + - Session token: `{"session_token": "..."}` + - User/password: `{"user_login": "...", "user_password": "..."}` + See `AuthParams` in the schemas section for full details. + + schemas: + + # ------------------------------------------------------------------------- + # Authentication + # ------------------------------------------------------------------------- + + ScriptAuth: + description: "Script-based authentication using a script user name and API key." + type: object + required: [script_name, script_key] + properties: + script_name: + type: string + description: "Name of the Script entity used to authenticate" + example: "my_integration_script" + script_key: + type: string + description: "API key for the provided script_name" + example: "abc123def456" + sudo_as_login: + type: string + description: "Optional — impersonate a human user. Event logs show this user performing actions with sudo_actual_user in meta-data." + example: "artist.jane" + + SessionTokenAuth: + description: "Session token authentication. Retrieve the token using get_session_token()." + type: object + required: [session_token] + properties: + session_token: + type: string + description: "Session token obtained from get_session_token()" + + UserPasswordAuth: + description: "Human user login/password authentication." + type: object + required: [user_login, user_password] + properties: + user_login: + type: string + description: "The user login string" + user_password: + type: string + format: password + description: "The password string" + + AuthParams: + description: | + Authentication object passed as `params[0]` for all methods except `info`. + Provide exactly one of: script auth, session token auth, or user/password auth. + oneOf: + - $ref: '#/components/schemas/ScriptAuth' + - $ref: '#/components/schemas/SessionTokenAuth' + - $ref: '#/components/schemas/UserPasswordAuth' + + # ------------------------------------------------------------------------- + # Common types + # ------------------------------------------------------------------------- + + EntityLink: + description: "A lightweight reference to a Shotgun entity." + type: object + required: [type, id] + properties: + type: + type: string + description: "Entity type (e.g. 'Project', 'Shot', 'Asset')" + example: "Project" + id: + type: integer + description: "Entity id" + example: 4 + name: + type: string + description: "Display name (returned by server, not required on input)" + + FilterCondition: + description: | + A single filter condition: `[field, relation, value]`. + + - `field` (str) — Field name, optionally using dot notation for deep linking (e.g. `sg_task.Task.step.Step.id`) + - `relation` (str) — One of the valid operators (see Filter Syntax in the info description) + - `value` — Value to compare against (type depends on field and operator) + type: array + minItems: 3 + maxItems: 3 + items: {} + example: ["sg_status_list", "is", "ip"] + + FilterSpec: + description: | + Filter specification passed to `find()`, `find_one()`, `summarize()`, and `text_search()`. + + Either a list of conditions (shorthand, all combined with AND by default), + or a dict with `filter_operator` (`"all"` or `"any"`) and a `filters` list. + + Complex nested filters are supported by using dicts inside the list. + oneOf: + - type: array + items: + $ref: '#/components/schemas/FilterCondition' + maxItems: 1000 + - type: object + required: [filter_operator, filters] + properties: + filter_operator: + type: string + enum: [all, any] + filters: + type: array + items: {} + maxItems: 1000 + + OrderSpec: + description: "Sort specification for find() queries." + type: object + required: [field_name, direction] + properties: + field_name: + type: string + example: "created_at" + direction: + type: string + enum: [asc, desc] + default: asc + + SummaryFieldSpec: + description: "Summary field specification for summarize()." + type: object + required: [field, type] + properties: + field: + type: string + description: "Internal Shotgun field name to summarize" + example: "id" + type: + type: string + description: "Summary operation type" + enum: + - record_count + - count + - sum + - maximum + - minimum + - average + - earliest + - latest + - percentage + - status_percentage + - status_list + - checked + - unchecked + + GroupingSpec: + description: "Grouping specification for summarize()." + type: object + required: [field, type] + properties: + field: + type: string + description: "Internal Shotgun field name to group by" + example: "sg_asset_type" + type: + type: string + description: "Type of grouping to perform" + enum: + - exact + - tens + - hundreds + - thousands + - tensofthousands + - hundredsofthousands + - millions + - day + - week + - month + - quarter + - year + - clustered_date + - oneday + - fivedays + - entitytype + - firstletter + direction: + type: string + enum: [asc, desc] + default: asc + + BatchItem: + description: "A single operation within a batch() request. Supports create, update, and delete." + type: object + required: [request_type, entity_type] + properties: + request_type: + type: string + enum: [create, update, delete] + description: "Type of operation" + entity_type: + type: string + description: "Entity type" + example: "Shot" + entity_id: + type: integer + description: "Required for update and delete" + data: + type: object + description: "Field key/value pairs for create or update" + additionalProperties: true + return_fields: + type: array + items: + type: string + maxItems: 500 + description: "Fields to return (create only, defaults to [id])" + multi_entity_update_modes: + type: object + description: "Optional per-field update mode for multi-entity fields" + additionalProperties: + type: string + enum: [set, add, remove] + + # ------------------------------------------------------------------------- + # Response schemas + # ------------------------------------------------------------------------- + + ApiV3Response: + description: "Standard API3 response envelope." + type: object + properties: + results: + description: | + Method-specific result. Type varies by method: + - `create` / `update` — entity dict + - `find` (`read`) — list of entity dicts + - `find_one` — single entity dict or null + - `delete` / `revive` — boolean + - `batch` — list of per-item results + - `info` — server metadata dict (`full_version` [major, minor, patch, hotfix], `version` [major, minor, patch], `user_authentication_method` one of `default`, `ldap`, `saml2`) + - `summarize` — `{"summaries": {...}, "groups": [{"group_name": ..., "group_value": ..., "summaries": {...}}, ...]}` + - `schema_*` — nested schema dict + - `authenticate_human_user` — HumanUser dict or null + - `get_session_token` — session token string + - `work_schedule_read` — dict keyed by date + - `preferences_read` — dict of preference name to value + - `export_page` — CSV string + - `activity_stream_read` — activity stream dict + - `follow` / `unfollow` — dict with followed/unfollowed boolean and entity/user + - `followers` — list of HumanUser dicts + - `following` — list of entity dicts + - `note_thread_read` — list of Note/Reply/Attachment dicts + - `text_search` — `{"matches": [...], "terms": [...]}` + - `user_subscriptions_read` — list of subscription dicts + - `user_subscriptions_create` — boolean + + ApiV3ErrorResponse: + description: "Error response from API3." + type: object + properties: + exception: + type: boolean + example: true + error_code: + type: integer + description: | + API3 error codes: + - 100: Unknown error + - 101: Initialisation error + - 102: Authentication failure + - 103: Invalid arguments + - 104: CRUD error + - 106: Two-factor authentication required + error_string: + type: string + example: "Authentication failure" + error_data: + type: object + + # ------------------------------------------------------------------------- + # Exceptions + # ------------------------------------------------------------------------- + + ShotgunError: + description: "Base for all Shotgun API Errors. Bases: `Exception`." + type: object + properties: + message: + type: string + + ShotgunFileDownloadError: + description: "Exception for file download-related errors. Bases: `ShotgunError`." + type: object + properties: + message: + type: string + + Fault: + description: "Exception when server-side exception detected. Bases: `ShotgunError`." + type: object + properties: + message: + type: string + + AuthenticationFault: + description: "Exception when the server side reports an error related to authentication. Bases: `Fault`." + type: object + properties: + message: + type: string + + MissingTwoFactorAuthenticationFault: + description: "Exception when the server side reports an error related to missing two-factor authentication credentials. Bases: `Fault`. These tokens can be short lived so a session is established right away if an `auth_token` is provided." + type: object + properties: + message: + type: string + + # ------------------------------------------------------------------------- + # Connection & Authentication request schemas + # ------------------------------------------------------------------------- + + InfoRequest: + description: | + Get API-related metadata from the Shotgun server. No authentication required. + + **Python client**: `sg.info()` + + Returns a dict of server metadata. Key tokens: + + | Token | Value | + |---|---| + | `full_version` | Ordered array `[major, minor, patch, hotfix]` | + | `version` | Ordered array `[major, minor, patch]` | + | `user_authentication_method` | `"default"` (username/password), `"ldap"`, or `"saml2"` (SSO) | + + Other values are unsupported and for internal use only. + + Example: + ```python + sg.info() + # {"full_version": [8, 2, 1, 0], "version": [8, 2, 1], "user_authentication_method": "default", ...} + ``` + type: object + required: [method_name, params] + properties: + method_name: + type: string + enum: [info] + params: + type: array + maxItems: 0 + items: {} + example: [] + + AuthenticateHumanUserRequest: + description: | + Authenticate a Shotgun HumanUser. + + **Python client**: `sg.authenticate_human_user(user_login, user_password, auth_token=None)` + + Authenticates a user given login, password, and optionally a one-time auth token (when + two-factor authentication is required). The user must be a `HumanUser` entity and the + account must be active. + + Parameters: + - `user_login` (str) – Login name of Shotgun HumanUser + - `user_password` (str) – Password for Shotgun HumanUser + - `auth_token` (str) – One-time token required when two-factor authentication is turned on + + Returns a standard Shotgun dictionary representing the HumanUser if authentication + succeeded, or `None` if authentication failed for any reason. + + Example: + ```python + sg.authenticate_human_user("rhendriks", "c0mPre$Hi0n", None) + # {"type": "HumanUser", "id": 123, "name": "Richard Hendriks"} + ``` + type: object + required: [method_name, params] + properties: + method_name: + type: string + enum: [authenticate_human_user] + params: + type: array + maxItems: 500 + items: {} + description: "params[0]: auth object; params[1]: {user_login, user_password, auth_token}" + + GetSessionTokenRequest: + description: | + Get the session token associated with the current session. + + **Python client**: `sg.get_session_token()` + + If a session token has already been established, this is returned; otherwise a new one + is generated on the server and returned. + + Returns a string containing the session token. + + Example: + ```python + sg.get_session_token() + # "dd638be7d07c39fa73d935a775558a50" + ``` + type: object + required: [method_name, params] + properties: + method_name: + type: string + enum: [get_session_token] + params: + type: array + maxItems: 500 + items: {} + + # ------------------------------------------------------------------------- + # Subscription Management request schemas + # ------------------------------------------------------------------------- + + UserSubscriptionsReadRequest: + description: | + Get the list of user subscriptions. + + **Python client**: `sg.user_subscriptions_read()` + + Returns a list of user subscriptions where each subscription is a dictionary + containing `humanUserId` and `subscription` fields. + type: object + required: [method_name, params] + properties: + method_name: + type: string + enum: [user_subscriptions_read] + params: + type: array + maxItems: 500 + items: {} + + UserSubscriptionsCreateRequest: + description: | + Assign subscriptions to users. + + **Python client**: `sg.user_subscriptions_create(users)` + + Parameters: + - `users` (list) – List of user subscriptions to assign. Each must be a dict with + `humanUserId` and `subscription` fields. The `subscription` is either `None`, + a single string, or an array of strings. + + Returns `True` if the request succeeded, `False` otherwise. + type: object + required: [method_name, params] + properties: + method_name: + type: string + enum: [user_subscriptions_create] + params: + type: array + maxItems: 500 + items: {} + description: "params[0]: AuthParams; params[1]: list of {humanUserId, subscription} dicts" + + # ------------------------------------------------------------------------- + # CRUD request schemas + # ------------------------------------------------------------------------- + + CreateRequest: + description: | + Create a new entity of the specified `entity_type`. + + **Python client**: `sg.create(entity_type, data, return_fields=None)` + + Parameters: + - `entity_type` (str) – Shotgun entity type to create + - `data` (dict) – Dictionary of fields and values to set on the new entity. + If `image` or `filmstrip_image` fields are provided, the file path will be + uploaded to the server automatically. + - `return_fields` (list) – Optional list of additional field values to return. + Defaults to `["id"]`. + + Returns a Shotgun entity dict containing the field/value pairs set (from `data`) + plus defaults `type` and `id`. Additional fields from `return_fields` are also included. + + Example: + ```python + data = { + "project": {"type": "Project", "id": 161}, + "sg_sequence": {"type": "Sequence", "id": 109}, + "code": "001_100", + "sg_status_list": "ip" + } + sg.create("Shot", data) + # {"code": "001_100", "id": 2557, "project": {"id": 161, "name": "Pied Piper", "type": "Project"}, "sg_sequence": {...}, "sg_status_list": "ip", "type": "Shot"} + ``` + type: object + required: [method_name, params] + properties: + method_name: + type: string + enum: [create] + params: + type: array + minItems: 2 + maxItems: 2 + items: {} + + FindRequest: + description: | + Find entities matching the given filters. + + **Python client**: `sg.find(entity_type, filters, fields=None, order=None, filter_operator=None, limit=0, retired_only=False, page=0, include_archived_projects=True, additional_filter_presets=None)` + + **Note**: The wire `method_name` is `read`. The Python client method is `find`. + + Parameters: + - `entity_type` (str) – Shotgun entity type to find + - `filters` (list) – List of filters. See Filter Syntax in the info description. + Supports dot notation for deep linking: `"sg_task.Task.step.Step.id"` + - `fields` (list) – Optional list of fields to include. Defaults to `["id"]`. + - `order` (list) – Optional list of `{"field_name": ..., "direction": "asc"|"desc"}` dicts. + Defaults to sorting by `id` ascending. + - `filter_operator` (str) – `"all"` (AND) or `"any"` (OR). Defaults to `"all"`. + - `limit` (int) – Max entities to return. `0` returns all. Defaults to `0`. + - `page` (int) – Page of results. Use with `limit`. Defaults to `0`. + - `retired_only` (bool) – Return only retired entities. Defaults to `False`. + No option to return both retired and non-retired in the same query. + - `include_archived_projects` (bool) – Include entities from archived projects. Defaults to `True`. + - `additional_filter_presets` (list) – Optional preset list `[{"preset_name": ..., ...}]`. + ANDed with the `filters` argument. + + Returns a list of entity dicts with requested fields plus `"id"` and `"type"`. + + Example: + ```python + fields = ["id", "code", "sg_asset_type"] + filters = [ + ["project", "is", {"type": "Project", "id": 4}], + ["sg_asset_type", "is", "Character"], + ["sequences", "is", {"type": "Sequence", "id": 2}] + ] + sg.find("Asset", filters, fields) + # [{"code": "Gopher", "id": 32, "sg_asset_type": "Character", "type": "Asset"}, ...] + ``` + type: object + required: [method_name, params] + properties: + method_name: + type: string + enum: [read] + params: + type: array + minItems: 2 + maxItems: 2 + items: {} + + FindOneRequest: + description: | + Shortcut for `find()` with `limit=1` so it returns a single result. + + **Python client**: `sg.find_one(entity_type, filters, fields=None, order=None, filter_operator=None, retired_only=False, include_archived_projects=True, additional_filter_presets=None)` + + Parameters are the same as `find()` except `limit` and `page` are not available. + + Returns a single entity dict or `None` if no match found. + + Example: + ```python + sg.find_one("Asset", [["id", "is", 32]], ["id", "code", "sg_status_list"]) + # {"code": "Gopher", "id": 32, "sg_status_list": "ip", "type": "Asset"} + ``` + type: object + required: [method_name, params] + properties: + method_name: + type: string + enum: [find_one] + params: + type: array + minItems: 2 + maxItems: 2 + items: {} + + UpdateRequest: + description: | + Update the specified entity with the supplied data. + + **Python client**: `sg.update(entity_type, entity_id, data, multi_entity_update_modes=None)` + + Parameters: + - `entity_type` (str) – Entity type to update + - `entity_id` (int) – Id of the entity to update + - `data` (dict) – Dictionary of field/value pairs to update + - `multi_entity_update_modes` (dict) – Optional `{field_name: mode}` dict where mode + is `"set"`, `"add"`, or `"remove"` for multi-entity fields. Defaults to `"set"`. + + Returns the updated entity dictionary. + type: object + required: [method_name, params] + properties: + method_name: + type: string + enum: [update] + params: + type: array + minItems: 2 + maxItems: 2 + items: {} + + DeleteRequest: + description: | + Retire the specified entity. + + **Python client**: `sg.delete(entity_type, entity_id)` + + Entities are moved to the trash. Use `revive()` to restore them. + + Parameters: + - `entity_type` (str) – Entity type + - `entity_id` (int) – Entity id + + Returns `True` if the entity was retired, `False` if the entity does not exist. + type: object + required: [method_name, params] + properties: + method_name: + type: string + enum: [delete] + params: + type: array + minItems: 2 + maxItems: 2 + items: {} + + ReviveRequest: + description: | + Revive an entity that has previously been deleted (retired). + + **Python client**: `sg.revive(entity_type, entity_id)` + + Parameters: + - `entity_type` (str) – Entity type + - `entity_id` (int) – Entity id + + Returns `True` if the entity was revived, `False` if the entity is not in the trash. + type: object + required: [method_name, params] + properties: + method_name: + type: string + enum: [revive] + params: + type: array + minItems: 2 + maxItems: 2 + items: {} + + BatchRequest: + description: | + Make a batch request of several `create()`, `update()`, and `delete()` calls. + + **Python client**: `sg.batch(requests)` + + All operations succeed or all are rolled back. Each request dict contains: + - `request_type` (str) – `"create"`, `"update"`, or `"delete"` + - `entity_type` (str) – Entity type + - `entity_id` (int) – Required for `update` and `delete` + - `data` (dict) – Field data for `create` and `update` + - `return_fields` (list) – Fields to return for `create` (defaults to `["id"]`) + + Returns a list of results, one per request. + + Example: + ```python + batch_data = [ + { + "request_type": "create", + "entity_type": "Shot", + "data": {"code": "New Shot 1", "project": {"type": "Project", "id": 4}} + }, + { + "request_type": "update", + "entity_type": "Shot", + "entity_id": 2, + "data": {"sg_status_list": "ip"} + }, + { + "request_type": "delete", + "entity_type": "Shot", + "entity_id": 3 + } + ] + sg.batch(batch_data) + ``` + type: object + required: [method_name, params] + properties: + method_name: + type: string + enum: [batch] + params: + type: array + minItems: 2 + maxItems: 2 + items: {} + + SummarizeRequest: + description: | + Summarize field data returned by a query. + + **Python client**: `sg.summarize(entity_type, filters, summary_fields, filter_operator=None, grouping=None, include_archived_projects=True)` + + Parameters: + - `entity_type` (str) – Entity type to summarize + - `filters` (list) – Filters using the same syntax as `find()` + - `summary_fields` (list) – List of `{"field": ..., "type": ...}` dicts. + Types: `record_count`, `count`, `sum`, `maximum`, `minimum`, `average`, + `earliest`, `latest`, `percentage`, `status_percentage`, `status_list`, `checked`, `unchecked` + - `filter_operator` (str) – `"all"` or `"any"`. Defaults to `"all"`. + - `grouping` (list) – Optional list of `{"field": ..., "type": ..., "direction": ...}` dicts. + Types: `exact`, `tens`, `hundreds`, `thousands`, `tensofthousands`, `hundredsofthousands`, + `millions`, `day`, `week`, `month`, `quarter`, `year`, `clustered_date`, `oneday`, + `fivedays`, `entitytype`, `firstletter` + + Returns a dict with `summaries` (total) and `groups` (per-group, each with `group_name`, + `group_value`, and `summaries`). When grouping by more than one field, groups are nested. + + Note: `group_name` is the display name; `group_value` is the actual value (may differ + for entity types where `group_name` might be `"PuppyA"` and `group_value` + `{"type": "Asset", "id": 922, "name": "PuppyA"}`). + + Example: + ```python + sg.summarize( + entity_type="Asset", + filters=[["project", "is", {"type": "Project", "id": 4}]], + summary_fields=[{"field": "id", "type": "count"}], + grouping=[{"field": "sg_asset_type", "type": "exact", "direction": "asc"}] + ) + # {"groups": [{"group_name": "Character", "group_value": "Character", "summaries": {"id": 3}}, ...], "summaries": {"id": 15}} + ``` + type: object + required: [method_name, params] + properties: + method_name: + type: string + enum: [summarize] + params: + type: array + minItems: 2 + maxItems: 2 + items: {} + + NoteThreadReadRequest: + description: | + Return the full conversation for a given note, including Replies and Attachments. + + **Python client**: `sg.note_thread_read(note_id, entity_fields=None)` + + Parameters: + - `note_id` (int) – The id for the note to be retrieved + - `entity_fields` (dict) – Additional fields to retrieve per entity type. Example: + ```python + { + "Note": ["created_by.HumanUser.image", "addressings_to", "playlist", "user"], + "Reply": ["content"], + "Attachment": ["filmstrip_image", "local_storage", "this_file", "image"] + } + ``` + + Returns a list of dicts in descending chronological order. Each has `type` set to + `Note`, `Reply`, or `Attachment`. + + Example: + ```python + sg.note_thread_read(6013) + # [{"content": "Please add more awesomeness to the color grading.", "id": 6013, "type": "Note", ...}, + # {"id": 159, "type": "Attachment", ...}, + # {"content": "More awesomeness added", "id": 5, "type": "Reply", ...}] + ``` + type: object + required: [method_name, params] + properties: + method_name: + type: string + enum: [note_thread_read] + params: + type: array + maxItems: 500 + items: {} + + TextSearchRequest: + description: | + Search across the specified entity types for the given text. + + **Python client**: `sg.text_search(text, entity_types, project_ids=None, limit=None)` + + Can be used to implement auto-completion or global search. Requires text of at least + three characters, or an exception will be raised. + + Parameters: + - `text` (str) – Text to search for (minimum 3 characters) + - `entity_types` (dict) – Dict of entity type to optional filter list. Each entity type + can be associated with a filter query to reduce matches: + ```python + {"Asset": [["sg_asset_type", "is", "Character"]], "Task": []} + ``` + - `project_ids` (list) – Optional list of Project ids to search across. + Defaults to `None` (all projects). + - `limit` (int) – Specify the maximum number of matches to return + + Returns a dict with `matches` (list of match dicts with `id`, `type`, `name`, + `project_id`, `image`, `links`, `status`) and `terms` (list of search terms). + The `links` field contains information about any linked entity. + + Example: + ```python + entity_types = {"Asset": [["sg_asset_type", "is", "Character"]], "Task": []} + sg.text_search("bunny", entity_types) + # {"matches": [{"id": 734, "type": "Asset", "name": "Bunny", "project_id": 65, ...}, ...], "terms": ["bunny"]} + ``` + type: object + required: [method_name, params] + properties: + method_name: + type: string + enum: [text_search] + params: + type: array + maxItems: 500 + items: {} + + UpdateProjectLastAccessedRequest: + description: | + Update a Project's `last_accessed_by_current_user` field to the current timestamp. + + **Python client**: `sg.update_project_last_accessed(project, user=None)` + + Requires Shotgun v5.3.20+. + + Helps keep track of recent Projects per user, enabling "Recent Projects" features. + + Parameters: + - `project` (dict) – Standard Project entity dictionary + - `user` (dict) – Optional standard user entity dictionary. If not provided and using + user-based authentication or `sudo_as_login`, that user is used instead. + + Example: + ```python + sg.update_project_last_accessed({"type": "Project", "id": 66}, {"type": "HumanUser", "id": 43}) + ``` + type: object + required: [method_name, params] + properties: + method_name: + type: string + enum: [update_project_last_accessed_by_current_user] + params: + type: array + maxItems: 500 + items: {} + + WorkScheduleReadRequest: + description: | + Return the work day rules for a given date range. + + **Python client**: `sg.work_schedule_read(start_date, end_date, project=None, user=None)` + + Requires Shotgun server v3.2.0+. + + Returns the defined WorkDayRules between `start_date` and `end_date` inclusive as a dict + keyed by date string. Each value is a dict with: + - `Description` – Description entered for the exception (if applicable) + - `Reason` – One of: `STUDIO_WORK_WEEK`, `STUDIO_EXCEPTION`, `PROJECT_WORK_WEEK`, + `PROJECT_EXCEPTION`, `USER_WORK_WEEK`, `USER_EXCEPTION` + - `Working` – Boolean indicating working day or not + + Parameters: + - `start_date` (str) – Start date `YYYY-MM-DD` + - `end_date` (str) – End date `YYYY-MM-DD` + - `project` (dict) – Optional Project entity to query WorkDayRules for + - `user` (dict) – Optional HumanUser entity to query WorkDayRules for + + Example: + ```python + sg.work_schedule_read("2015-12-21", "2015-12-25") + # { + # "2015-12-21": {"description": None, "reason": "STUDIO_WORK_WEEK", "working": True}, + # "2015-12-24": {"description": "Closed for Christmas Eve", "reason": "STUDIO_EXCEPTION", "working": False}, + # ... + # } + ``` + type: object + required: [method_name, params] + properties: + method_name: + type: string + enum: [work_schedule_read] + params: + type: array + maxItems: 500 + items: {} + + WorkScheduleUpdateRequest: + description: | + Update the work schedule for a given date. + + **Python client**: `sg.work_schedule_update(date, working, description=None, project=None, user=None, recalculate_field=None)` + + Requires Shotgun server v3.2.0+. + + If neither `project` nor `user` are passed, the studio work schedule is updated. + `project` and `user` can only be used exclusively of each other. + + Parameters: + - `date` (str) – Date `YYYY-MM-DD` + - `working` (bool) – Whether the day is a working day + - `description` (str) – Optional reason for time off + - `project` (dict) – Optional Project entity (cannot be used with `user`) + - `user` (dict) – Optional HumanUser entity (cannot be used with `project`) + - `recalculate_field` (str) – Optional field to recalculate on affected Tasks: + `"due_date"` or `"duration"`. Defaults to the value in Shotgun Site Preferences. + + Returns a dict of the updated work day rule key/value pairs. + + Example: + ```python + sg.work_schedule_update("2015-12-31", working=False, description="Studio closed for New Years Eve") + # {"date": "2015-12-31", "description": "Studio closed for New Years Eve", "project": None, "user": None, "working": False} + ``` + type: object + required: [method_name, params] + properties: + method_name: + type: string + enum: [work_schedule_update] + params: + type: array + maxItems: 500 + items: {} + + PreferencesReadRequest: + description: | + Get a subset of the site preferences. + + **Python client**: `sg.preferences_read(prefs=None)` + + Parameters: + - `prefs` (list) – Optional list of preference names to return + + Returns a dictionary of preferences and their values. + + Example: + ```python + sg.preferences_read() + # {"pref_name": "pref value"} + ``` + type: object + required: [method_name, params] + properties: + method_name: + type: string + enum: [preferences_read] + params: + type: array + maxItems: 500 + items: {} + + ExportPageRequest: + description: | + Export the specified page to the given format. + + **Python client**: `sg.export_page(page_id, format, layout_name=None)` + + Allows exporting a page to CSV. The respective layout or page must be marked as + API Exportable in the Flow Production Tracking UI. If `layout_name` is not passed, + the default layout is used. + + Parameters: + - `page_id` (int) – The ID of the page to export + - `format` (str) – Format to export to. Supported: `"csv"` + - `layout_name` (str) – Optional layout name as seen in the Flow Production Tracking UI + + Returns a string containing the exported data. + + Example: + ```python + sg.export_page(12345, "csv", layout_name="My Layout") + # "ID,Name,Status\n1,Shot 001,ip\n2,Shot 002,rev\n" + ``` + type: object + required: [method_name, params] + properties: + method_name: + type: string + enum: [export_page] + params: + type: array + maxItems: 500 + items: {} + + # ------------------------------------------------------------------------- + # Activity Stream request schemas + # ------------------------------------------------------------------------- + + ActivityStreamReadRequest: + description: | + Retrieve activity stream data from Shotgun. + + **Python client**: `sg.activity_stream_read(entity_type, entity_id, entity_fields=None, max_id=None, min_id=None, limit=None)` + + Returns data displayed in the Activity tab for an entity in the Shotgun Web UI. + + Parameters: + - `entity_type` (str) – Entity type to retrieve activity stream for + - `entity_id` (int) – Entity id to retrieve activity stream for + - `entity_fields` (list) – Additional fields per entity type (e.g. `{"Shot": ["sg_sequence"], "Asset": ["sg_asset_type"]}`) + - `max_id` (int) – Do not retrieve ids greater than this (for paging) + - `min_id` (int) – Do not retrieve ids lesser than this (for cache top-up) + - `limit` (int) – Maximum records to return (system default if not specified) + + Returns a complex dict with `earliest_update_id`, `entity_id`, `entity_type`, + `latest_update_id`, and `updates` (list in descending date order). Each update dict + may have: `created_at`, `created_by`, `id`, `meta`, `primary_entity`, `read`, `update_type`. + type: object + required: [method_name, params] + properties: + method_name: + type: string + enum: [activity_stream_read] + params: + type: array + maxItems: 500 + items: {} + + FollowRequest: + description: | + Add the entity to the user's followed entities. + + **Python client**: `sg.follow(user, entity)` + + If the user is already following the entity, succeeds without change. + + Parameters: + - `user` (dict) – User entity that will follow the entity + - `entity` (dict) – Shotgun entity to be followed + + Returns a dict with `"followed": True` plus the passed `user` and `entity` values. + + Example: + ```python + sg.follow({"type": "HumanUser", "id": 42}, {"type": "Shot", "id": 2050}) + # {"followed": True, "user": {"type": "HumanUser", "id": 42}, "entity": {"type": "Shot", "id": 2050}} + ``` + type: object + required: [method_name, params] + properties: + method_name: + type: string + enum: [follow] + params: + type: array + maxItems: 500 + items: {} + + UnfollowRequest: + description: | + Remove entity from the user's followed entities. + + **Python client**: `sg.unfollow(user, entity)` + + Does nothing if the user is not following the entity. + + Parameters: + - `user` (dict) – User entity that will unfollow the entity + - `entity` (dict) – Entity to be unfollowed + + Returns a dict with `"unfollowed": True` plus the passed `user` and `entity` values. + + Example: + ```python + sg.unfollow({"type": "HumanUser", "id": 42}, {"type": "Shot", "id": 2050}) + # {"entity": {"type": "Shot", "id": 2050}, "user": {"type": "HumanUser", "id": 42}, "unfollowed": True} + ``` + type: object + required: [method_name, params] + properties: + method_name: + type: string + enum: [unfollow] + params: + type: array + maxItems: 500 + items: {} + + FollowersRequest: + description: | + Return all followers for an entity. + + **Python client**: `sg.followers(entity)` + + Parameters: + - `entity` (dict) – Entity to find followers of + + Returns a list of HumanUser dicts representing each follower. + + Example: + ```python + sg.followers({"type": "Shot", "id": 2050}) + # [{"status": "act", "valid": "valid", "type": "HumanUser", "name": "Richard Hendriks", "id": 42}, ...] + ``` + type: object + required: [method_name, params] + properties: + method_name: + type: string + enum: [followers] + params: + type: array + maxItems: 500 + items: {} + + FollowingRequest: + description: | + Return all entity instances a user is following. + + **Python client**: `sg.following(user, project=None, entity_type=None)` + + Optionally restrict by project and/or entity type. + + Parameters: + - `user` (dict) – Find what this person is following + - `project` (dict) – Optional filter to only return results from a specific project + - `entity_type` (str) – Optional filter to only return results from one entity type + + Returns a list of entity dicts with `type` and `id`. + + Example: + ```python + sg.following({"type": "HumanUser", "id": 1234}, project={"type": "Project", "id": 1234}, entity_type="Task") + # [{"type": "Task", "id": 1}, {"type": "Task", "id": 2}, ...] + ``` + type: object + required: [method_name, params] + properties: + method_name: + type: string + enum: [following] + params: + type: array + maxItems: 500 + items: {} + + # ------------------------------------------------------------------------- + # Schema request schemas + # ------------------------------------------------------------------------- + + SchemaEntityReadRequest: + description: | + Return all active entity types, their display names, and their visibility. + + **Python client**: `sg.schema_entity_read(project_entity=None)` + + If `project_entity` is specified, schema visibility for that project is returned. + If omitted, a full global listing is returned without per-project visibility settings. + + **Note**: Display names are localized when `sg.config.localized = True`. + See Localization in the info description. + + Parameters: + - `project_entity` (dict) – Optional Project entity (e.g. `{"type": "Project", "id": 3}`) + + Returns a dict of entity type to dict with display name and visibility. + + Example: + ```python + sg.schema_entity_read() + # { + # "Asset": {"name": {"editable": False, "value": "Asset"}, "visible": {"editable": False, "value": True}}, + # "ApiUser": {"name": {"editable": False, "value": "Script"}, "visible": {"editable": False, "value": True}}, + # ... + # } + ``` + type: object + required: [method_name, params] + properties: + method_name: + type: string + enum: [schema_entity_read] + params: + type: array + maxItems: 500 + items: {} + + SchemaFieldReadRequest: + description: | + Get schema for all fields on the specified entity type, or just the field specified. + + **Python client**: `sg.schema_field_read(entity_type, field_name=None, project_entity=None)` + + **Note**: Results of `schema_field_read()` are not directly compatible with + `schema_field_create()` or `schema_field_update()` input format. Data must be reformatted. + + **Note**: If `project_entity` is not specified, everything is reported as visible. + + **Note**: Display names are localized when `sg.config.localized = True`. + + Parameters: + - `entity_type` (str) – Entity type to get the schema for + - `field_name` (str) – Optional internal field name. If excluded, all fields are returned. + Example: `"sg_temp_field"` + - `project_entity` (dict) – Optional Project entity. Example: `{"type": "Project", "id": 3}` + + Returns a nested dict for the field(s) with properties: `data_type`, `description`, + `editable`, `entity_type`, `mandatory`, `name`, `properties`, `unique`, `visible`. + Properties marked `editable: True` can be updated via `schema_field_update()`. + + Example: + ```python + sg.schema_field_read("Asset", "shots") + # {"shots": {"data_type": {"editable": False, "value": "multi_entity"}, "name": {"editable": True, "value": "Shots"}, ...}} + ``` + type: object + required: [method_name, params] + properties: + method_name: + type: string + enum: [schema_field_read] + params: + type: array + maxItems: 500 + items: {} + + SchemaFieldCreateRequest: + description: | + Create a field for the specified entity type. + + **Python client**: `sg.schema_field_create(entity_type, data_type, display_name, properties=None)` + + **Note**: If the internal field name derived from `display_name` already exists, it is + appended with `_1` (incrementing until a unique name is found). + + Parameters: + - `entity_type` (str) – Entity type to add the field to + - `data_type` (str) – Shotgun data type for the new field (see Data Types in info description) + - `display_name` (str) – Display name. The system name is derived from this and returned. + - `properties` (dict) – Optional additional field properties such as `description` or `summary_default` + + Returns the internal Shotgun name for the new field (different from `display_name`). + + Example: + ```python + properties = {"summary_default": "count", "description": "Complexity breakdown of Asset"} + sg.schema_field_create("Asset", "text", "Complexity", properties) + # "sg_complexity" + ``` + type: object + required: [method_name, params] + properties: + method_name: + type: string + enum: [schema_field_create] + params: + type: array + maxItems: 500 + items: {} + + SchemaFieldUpdateRequest: + description: | + Update the properties for the specified field on an entity. + + **Python client**: `sg.schema_field_update(entity_type, field_name, properties, project_entity=None)` + + **Note**: Although a property name may be a nested key like `summary_default`, + it is treated the same as top-level keys. + + **Note**: The `project_entity` parameter can only affect the `visible` property. + If `visible` is in `properties` and `project_entity` is not set, an exception is raised. + + Parameters: + - `entity_type` (str) – Entity type of the field to update + - `field_name` (str) – Internal Shotgun name of the field to update + - `properties` (dict) – Key/value pairs: property name → new value + - `project_entity` (dict) – Optional Project entity for modifying `visible` property + + Returns `True` if the field was updated. + + Example: + ```python + properties = {"name": "Test Number Field Renamed", "summary_default": "sum", "description": "this is only a test"} + sg.schema_field_update("Asset", "sg_test_number", properties) + # True + ``` + type: object + required: [method_name, params] + properties: + method_name: + type: string + enum: [schema_field_update] + params: + type: array + maxItems: 500 + items: {} + + SchemaFieldDeleteRequest: + description: | + Delete the specified field from the entity type. + + **Python client**: `sg.schema_field_delete(entity_type, field_name)` + + Parameters: + - `entity_type` (str) – Entity type to delete the field from + - `field_name` (str) – Internal Shotgun name of the field to delete + + Returns `True` if the field was deleted. + + Example: + ```python + sg.schema_field_delete("Asset", "sg_temp_field") + # True + ``` + type: object + required: [method_name, params] + properties: + method_name: + type: string + enum: [schema_field_delete] + params: + type: array + maxItems: 500 + items: {} + + SchemaReadRequest: + description: | + Get the schema for all fields on all entities. + + **Python client**: `sg.schema_read(project_entity=None)` + + **Note**: If `project_entity` is not specified, everything is reported as visible. + + **Note**: Display names are localized when `sg.config.localized = True`. + + Parameters: + - `project_entity` (dict) – Optional Project entity. Example: `{"type": "Project", "id": 3}`. + Defaults to `None`. + + Returns a nested dict of all entity types and all their field properties. + Properties marked `editable: True` can be updated via `schema_field_update()`. + + Example: + ```python + sg.schema_read() + # {"ActionMenuItem": {"created_at": {"data_type": {"editable": False, "value": "date_time"}, ...}, ...}, ...} + ``` + type: object + required: [method_name, params] + properties: + method_name: + type: string + enum: [schema_read] + params: + type: array + maxItems: 500 + items: {} + + SchemaDeprecatedRequest: + description: | + **Deprecated since version 3.0.0.** + + - `schema(entity_type)` — Use `schema_field_read()` instead. + - `entity_types()` — Use `schema_entity_read()` instead. + type: object + required: [method_name, params] + properties: + method_name: + type: string + enum: [schema, entity_types] + params: + type: array + maxItems: 500 + items: {}