SG Ground Truth

Findings

One finding answers one question and ends in a single actionable sentence. Each names the probe that produced it and quotes the status code and error string verbatim.

They are grouped by the phase of a session they bite in, which is the order a client meets them. The number is still the probe that produced it. The field types, entity types, endpoints and filters are the other half: complete, and addressed by name.

Only findings marked scope: api are published here. A finding that measures one site, or one project inside it, stays in the repository and is excluded from this build. Why that distinction exists.

Authgetting a token, and what it is

  • 001 auth

    Send the token request as application/x-www-form-urlencoded: application/json is 400 Invalid JSON body. client_credentials returns a 600s bearer, so ignore the refresh_token and re-auth.

    • auth
    • client
    • token
  • 027 auth permissions

    The token endpoint accepts password and session_token. Impersonation is the OAuth2 scope sudo_as_login:<login>, never a body field, and a lower level reads far fewer rows and as many fields.

    • auth
    • token
    • permission
    • user
    • client
    • sudo
  • 052 app session launcher partial

    Post appName and machineId, open url in a browser, PUT the id until approved. The sessionToken spends at grant_type=session_token as that person, and every mint renews the session.

    Not measured. a person clicking deny, and a session left idle past the site's expiry window; both wait on time and on the site, not on the probe

    • auth
    • token
    • user
    • launcher
    • permission
  • 126 session idle partial

    The token endpoint refuses a session token it does not accept with 400 code 102 in errors[], "Can't authenticate session token ending with '<last 4>'". No API read exposes the session window.

    Not measured. a real session token left idle past the window. Needs a person to approve 052 --login, then a day of nobody spending it. Blocked on time

    • auth
    • token
    • launcher
    • error-handling
  • 130 launcher answers partial

    sessionRequestId is 21 characters of A-Za-z0-9_-. url is on the site's host unless the create call sends X-Forwarded-Host, which url copies: a proxy strips that header.

    Not measured. the create call on a site with authentication_app_session_launcher_enabled false. The probed site has it on and no preference is changed; blocked on the site

    • auth
    • launcher
    • header
    • trap
  • 131 session revoke partial

    The REST spec has no revoke or sign-out call. Of five candidate routes only /user/logout answers (302 to login); whether it ends a launcher session is unmeasured.

    Not measured. whether /user/logout ends a live session and what a bearer minted before it then reads. Needs a person to approve `python probes/131_session_revoke.py --login`. Blocked on the work

    • auth
    • token
    • launcher
  • 133 bearer expiry

    Every bearer refusal is 401 code 102 Unauthorized; only detail differs: Token Expired past exp, Token invalid for a bad signature, null for garbage or none. Re-mint on 401 code 102.

    • auth
    • token
    • error-handling
    • client

Protocolheaders, and what a status code is worth

  • 004 array vs hash

    api3_array/api3_hash are a POST _search request Content-Type, not a GET Accept header: as Accept they 406, and entity fields are returned under relationships either way.

    • query
    • header
    • entity-field
    • error-handling
    • trap
  • 028 loud and silent

    A 400 is trustworthy and usually names the legal set, but a 200 proves nothing: an unknown field, sort key or query param is a no-op, and a batch can return an id for a row it never made.

    • query
    • filter
    • sort
    • write
    • operator
    • error-handling
    • trap
    • silent
  • 051 api version

    /api/v1 and /api/v1.1 are the same API. Across 20 read-only calls the only difference is api_version in the root document and the prefix each echoes in its own links. Any other segment is 404.

    • discovery
    • client
    • paging
    • protocol
  • 062 cors partial

    Every path under /api/v1 answers the preflight and echoes any Origin, credentials true. /internal_api and the web paths send no CORS header, so a page on another origin proxies those.

    Not measured. what a live session cookie authenticates on /api/v1, since allow-credentials invites one, and the presigned upload host, which is not this site. A live session needs a person at a browser

    • cors
    • browser
    • header
    • launcher
    • client
  • 128 rate limit partial

    60 GETs from 10 threads in 1.9 s all answered 200 with no rate-limit header of any kind. Code a backoff on 429 and 503 without having seen either.

    Not measured. the load at which a limit bites, if one exists. The burst was kept small on a shared site. Blocked on the work

    • header
    • protocol
    • cost
  • 129 hosted domains partial

    The probed site answers only at its own host; its name under shotgunstudio.com is 404 HTML, no redirect. Both domains resolve any name, so allowlist the configured host, not a suffix.

    Not measured. a site created under shotgunstudio.com, and a European-hosted site's hostname. The probed site is neither; blocked on the site

    • client
    • launcher
    • discovery
  • 144 rate limit burst partial

    300 mixed reads and writes at 28 per second for 10 s all answered 200 with no rate-limit header. Median latency doubled from 0.3 s to 0.6 s instead. Back off on latency, not on a status.

    Not measured. the load at which a limit bites, if one exists. The burst was capped at about 30/s on a shared site. Blocked on the work

    • header
    • protocol
    • cost
    • write

Schemawhat the site has, and adding to it

  • 002 schema

    Fetch /schema once for the type list, then /schema/<Type>/fields only for types you actually need: it is the expensive call (48KB, ~330ms each) and must never be looped over all types.

    • schema
    • cost
    • discovery
  • 008 custom entities

    Presence in /schema is the enablement test for a custom entity: a slot absent from the listing 404s. Slot numbers are non-contiguous and site-specific, so read name.value and never hardcode one.

    • schema
    • custom-entity
    • discovery
  • 009 status lists

    A project's usable statuses are valid_values minus hidden_values, read with project_id: valid_values is identical at every scope, hidden_values is the only thing that varies.

    • schema
    • status
    • list-field
    • inspector
  • 019 create fields

    Custom fields are creatable over REST, but you pass a display name and a duplicate silently becomes <name>_1: an idempotent ensure() must read /schema first, never POST-and-hope.

    • schema
    • write
    • custom-field
    • provenance
    • entity-field
    • trap
    • silent
  • 040 field revive

    A trashed field is revived by POST /schema/<Type>/fields/<name> with {"revive": true} at 204, but it returns at its original data_type, and a PUT changing data_type is a 200 that does nothing.

    • schema
    • custom-field
    • create
    • error-handling
    • trap
    • discovery
    • silent
  • 042 spec coverage

    GET /spec.json returns the deployment's own OpenAPI v3 document. It advertises 62 operations against the 23 this corpus covers, and it disagrees with the published documentation.

    • schema
    • discovery
    • cost
  • 047 site facts and the working week

    Three site-fact calls, three different envelopes: {data, status}, a bare hash, and JSON:API. Only /schedule/work_day_rules reports a bad scope id, and it reports it as a 200.

    • discovery
    • silent
    • user
    • date
    • error-handling
  • 056 stock vs custom field

    A field with visible.editable false is stock and safe to depend on; true means the site can hide it, which is every custom field and a few stock ones. The sg_ prefix decides nothing.

    • schema
    • custom-field
    • discovery
  • 061 shipped statuses

    Nothing in the schema marks a shipped Status. system is true on a minority of them; the stock set is created_by is null, plus options[return_only]=retired for the rows a site retired.

    • status
    • icon
    • discovery
    • enumeration
  • 091 status summary exclusions partial

    Excluded statuses are invisible to REST: not in /schema at any scope, not writable by PUT. status_list honours them: fin plus an excluded omt rolls up to fin, omt alone to na.

    Not measured. status_list with the exclusion removed on the same rows: the setting is not API-writable, so the before state rests on probe 079's rule, not on a toggle. Blocked on the API.

    • status
    • summary
    • schema
  • 114 schema admin recheck partial

    On 2026-11-10 /spec.json names calls to enable, disable and configure a custom entity, all 400 code 111 on the probed site. No call deletes a trashed field forever or writes hidden_values.

    Not measured. a custom entity call that succeeds. The probed site answers 400 code 111 to all three, so the bodies and responses in /spec.json are unverified. Blocked on the site.

    • schema
    • custom-entity
    • custom-field
    • status-list
    • discovery
    • error-handling
  • 115 field visibility per project

    visible is per project. Read it with ?project_id=N; write it with PUT and project_id in the body or the query, never without one. A new field is visible in every project.

    • schema
    • custom-field
    • project
    • write
    • error-handling
  • 116 field settings create update

    A create takes description, unique, valid_values, default_value and valid_types. unique and a multi_entity's valid_types never change afterwards; an entity's valid_types and list values do.

    • schema
    • custom-field
    • create
    • write
    • list-field
    • status-list
    • entity-field
    • multi-entity
    • error-handling
    • trap
  • 117 field types and names partial

    One non-ASCII character in the display name and the field is named sg_<data_type>, at 201. ASCII names are lowercased, every other character becomes _, nothing is trimmed or cut.

    Not measured. a non-ASCII display name on a data type other than currency. Not sent: it would spend sg_<data_type> on the site. Blocked on the work.

    • schema
    • custom-field
    • create
    • trap
    • silent
    • error-handling
  • 118 field writes other types partial

    Create, update, per-project visible, retire, the retired-name 400 and revive answer on a custom entity and on Tag, which has no project field, exactly as on Version.

    Not measured. a CustomNonProjectEntityNN. None is enabled on the probed site. Blocked on the site.

    • schema
    • custom-field
    • custom-entity
    • create
    • project
  • 119 field absent retired live partial

    Revive is 204 only on a retired field: 404 Retired field ... does not exist. on an unused name, 400 ... is not retired. on a live one. A retired field is a 404 to GET, PUT and DELETE.

    Not measured. a schema write by a person below Admin, and the permission groups as anyone but the script. Both need that person's session; none was available. Blocked on the site.

    • schema
    • custom-field
    • error-handling
    • permission
    • discovery
  • 120 field trash page partial

    The page that lists retired fields is a Page row: ui_category "trash", entity_type "DisplayColumn", named "Trash - Fields". Its id is per site, so search for it.

    Not measured. the web address itself. `/page/<id>` is the web interface's scheme, not a REST call, and it was not opened. Blocked on the work: it needs a browser session.

    • schema
    • custom-field
    • page
    • discovery
  • 121 field settings edges partial

    A PUT applies all its properties or none, in any order. A description or name cannot be emptied. valid_types keeps the sent order, and a lowercase type name is a 500 that retires the field.

    Not measured. whether the field the 500 retired can be revived, and the order valid_types take at creation. The first is the site owner's call, the second needs a new name.

    • schema
    • custom-field
    • write
    • list-field
    • status-list
    • entity-field
    • error-handling
    • trap
  • 122 onset entity types partial

    Slate, Camera, MocapTake, ShootDay and Scene create like Version: project required, code generated. None has attachments, and only Version.entity and Note.note_links reach them all.

    Not measured. a stock site, and enabling a hidden type: Element is off on the probed site and only the web UI turns a type on. Blocked on the site

    • on-set
    • schema
    • create
    • link
    • custom-entity
    • discovery
  • 132 field create rights partial

    An Artist creating a field gets 500 code 105 User doesn't have permission to create a Field, with a traceback. An Admin person gets 201. Treat any 500 from a schema write as a possible refusal.

    Not measured. Manager, Vendor and the site's Artist variant: nobody active in them has impersonation on. Blocked on the site; then run `132 --write --only Manager,Vendor`

    • schema
    • custom-field
    • permission
    • sudo
    • error-handling
  • 142 reverse field

    Every entity or multi_entity field makes a visible, editable multi_entity on each linked type. No create property stops it, and DELETE of the reverse field retires the forward field too.

    • schema
    • custom-field
    • entity-field
    • multi-entity
    • destructive
    • trap
  • 157 project custom field partial

    An Admin person creates a text field on Project with name and description at 201; it reads back like a field on any type. An Artist gets 500 code 105 User doesn't have permission to create a Field.

    Not measured. Manager, Vendor and the Artist variant: nobody active in them has impersonation on. Blocked on the site; then `157 --write --only Manager`

    • schema
    • custom-field
    • project
    • permission
    • sudo
    • error-handling
  • 160 jsonb field create

    A jsonb or serializable field cannot be created over REST, on Project or any type tried: 400 code 103 data_type is not valid. Store JSON in a text field and parse it.

    • schema
    • custom-field
    • jsonb
    • create
    • error-handling
  • 162 permission rules rest

    Rules are readable over REST with their condition trees: an Admin person reads every group, a person only their own. No call writes one: PUT, POST and PATCH on the permission routes are 404.

    • permission
    • sudo
    • schema
    • discovery

Readgetting rows back

  • 003 query

    A dotted ?fields path comes back flat under literal key "sg_task.Task.content" in attributes; an entity field is returned under relationships as {data, links}. Never read a row from attributes alone.

    • query
    • filter
    • dotted-field
    • paging
    • version
  • 006 pagination

    links.next is emitted on every page forever, including zero-row ones, so stop paging when data is empty and never on a missing next.

    • paging
    • query
    • enumeration
  • 018 project listing

    sg_status is not a liveness filter and is null on 15 of 22 projects; is_template, is_demo and archived are the discriminators, so pick the ones your list wants - is_demo hides the demo show.

    • project
    • query
    • filter
    • inspector
    • list-field
    • trap
  • 021 media resolution

    PublishedFile.path is returned with the LocalStorage join already done, so a client never reads LocalStorage or reassembles a root, but a platform whose storage root is unset reads null.

    • version
    • media
    • published-file
    • path
    • storage
    • inspector
    • query
  • 023 pages

    A page's layout is the PageSetting row whose user is null; settings_json reads back as decoded JSON and body/list_content settings.columns is the column list. Every filter on it is ignored.

    • page
    • query
    • filter
    • schema
    • project
    • inspector
    • trap
    • silent
  • 026 result order

    Rows come back id ascending unless you sort; ["id", "in", [...]] discards the order of the list, and an unsortable or unknown sort field is a silent 200 no-op where the same name in a filter 400s.

    • query
    • sort
    • paging
    • filter
    • dotted-field
    • trap
    • silent
  • 048 one record beyond crud

    POST on one record is revive, not update: ?revive=1 is required and the body is ignored. /<field> reads image and attachment fields only, and relationships/<field> is the same data, unpaged.

    • page
    • entity-field
    • multi-entity
    • attachment
    • cost
    • discovery
    • silent
  • 059 dotted path type check partial

    The middle segment of a dotted path is checked against the field's valid_types in a projection and against the schema alone in a filter: the projection drops the key at 200, the filter 400s.

    Not measured. whether a filter through a type outside valid_types is evaluated or matches nothing; no row on a read-only project links one, so it needs a write

    • dotted-field
    • entity-field
    • error-handling
    • trap
    • silent
  • 060 entity dict name

    The name in an entity dict is the target's cached_display_name, filled on every type measured, single and multi alike. Read it, not the per-type identity field, and expect decoration.

    • entity-field
    • multi-entity
    • link
    • destructive
  • 064 hierarchy expand buckets partial

    Dedupe children by path and keep the first. The __none__ bucket is repeated once per group, byte-identical every time, and its rows are disjoint from every group's.

    Not measured. how the web interface draws the repeated node. Its tree needs a session a person approves (probe 052), and the saved token had expired

    • path
    • project
    • sequence
    • trap
  • 072 page layouts partial

    A page's views are root settings.layouts [{name, display_name}], each name a child of the root. Query widgets sit at /body, inside a view, or in tabs: walk the tree, never read /body alone.

    Not measured. Which name the export's <layout_name> takes: every export on the probed site answers the page-level 422, so layouts[].name and display_name could not be told apart. Blocked on the site.

    • page
    • schema
    • inspector
  • 073 page grid settings

    Stored pages group one level deep (one of 438 goes two), summarise a column once in 41 grids, and colour columns by DisplayColumn id, a type REST cannot read. mode is list on 94%.

    • page
    • summary
    • pivot-column
    • inspector
  • 075 page overrides

    A per-user override patches columns, widths, sorts, mode and the filter panel at any spec_path, "" meaning the root. One row per user and page; 3 of 32 patches name a path the shared tree lacks.

    • page
    • user
  • 076 page visibility

    The script user is not the widest reader of Page: an Admin read 2048 pages where the script read 1107 and 404s on the rest. An Artist read 107. Every level reads every person's override.

    • page
    • permission
    • sudo
    • user
    • trap
  • 081 dotted image

    entity.Shot.image returns the Shot's thumbnail as a presigned S3 URL under attributes, same object, fresh signature, in the same call. image is_not null matched 50 Shots whose image reads null.

    • image
    • dotted-field
    • media
    • trap
  • 082 page size cap

    page[size] takes 1 to 5000 inclusive; 5001 is 400 "size must be less than 5000". Omitted, it is 500. A page costs ~330 ms whatever its size up to 500, so read big pages.

    • paging
    • cost
  • 088 project template defaults partial

    The per-entity-type default is readable at Project.tracking_settings.default_task_template.<Type>, a {type, id, name, valid} dict. Project.task_templates is a separate list, not the default.

    Not measured. Whether a Shot or Asset created over REST without `task_template` gets the default: blocked on the site, since testing it means writing a project's tracking settings.

    • task-template
    • project
    • serializable
    • discovery
  • 138 dotted custom field

    A dotted path reaches an sg_ field through an sg_ entity field, on a custom entity and on a built-in one, and across two hops: projection on GET and _search, and filter, all match.

    • dotted-field
    • custom-field
    • custom-entity
    • entity-field
    • on-set
  • 163 vendor rows

    On the probed site a Vendor reads every Bid in an assigned project, the other vendor's included: Vendor's read on Bid is allowed. A Group filter the client adds narrows the list, not the rights.

    • permission
    • sudo
    • custom-entity
    • group
  • 165 hidden row paths partial

    A see rule hides a row from fetch, search, summarize, text search and links, but a dotted filter still matches through it, a grouped _summarize shows its id and total, the event log its values.

    Not measured. the same paths under a see rule on Bid: no REST call adds a rule (probe 162) and the web interface was out of bounds. Blocked on the site

    • permission
    • sudo
    • dotted-field
    • event-log
    • summary
    • group

Filterselecting the rows you want

  • 016 dotted multi entity

    A dotted path through a multi_entity field reads back nothing: HTTP 200 with the key silently absent from attributes. Filters on that same path work, including two hops.

    • query
    • dotted-field
    • multi-entity
    • filter
    • paging
    • trap
    • silent
  • 017 filter operators

    is/is_not/contains/not_contains/starts_with/ends_with/in/not_in all work, on text fields and through dotted paths; an unknown operator 400s on all 21 data types, naming the valid list on 16.

    • query
    • filter
    • operator
    • dotted-field
    • entity-field
    • error-handling
    • silent
  • 020 summarize

    _summarize needs the same vendor Content-Type as _search, and one grouping call returns a field's distinct-value count and its empty count. At ~300ms a field, rank a shortlist, never scan.

    • query
    • inspector
    • fill-rate
    • schema
    • cost
    • list-field
  • 030 complex filters

    api3_hash nests and/or groups 265 deep and mixes leaves with sub-groups; api3_array cannot express or, query-string filter[] is ignored on _search, and {path,relation,values} runs nowhere.

    • query
    • filter
    • operator
    • header
    • page
    • error-handling
    • trap
    • silent
  • 046 search without a path

    /hierarchy/_expand and /hierarchy/_search refuse the vendor content types every other POST requires and take application/json alone, so one shared POST helper 415s on half the API.

    • query
    • filter
    • header
    • project
    • trap
  • 053 text search matching partial

    page.size caps at 25 and defaults to 25 with no links, so page with page.number. Every word must match a case-insensitive substring of the name or of the linked row's name.

    Not measured. Only `description` and a linked row's name were tried as fields beyond the name, and the tie-break between equal-length names was not reached. The probe's limit, not the site's.

    • query
    • paging
    • cost
    • link
    • silent
  • 063 text search filter shape

    An entity_types value follows the request Content-Type: an array of triples under api3_array, a logical_operator group under api3_hash, which alone nests. The other shape is 400 code 103.

    • header
    • error-handling
    • trap
  • 068 note read state

    read_by_current_user is per person and missing from the schema; is and is_not are evaluated, while in, not_in and an unknown is value all return the unread rows at 200.

    • note
    • list-field
    • user
    • permission
    • silent
    • trap
  • 071 note link name filter

    Filter notes about a thing on note_links.<Type>.cached_display_name: it resolves for every valid type, code 400s on Booking and name on all but Department. The path cannot be read back.

    • note
    • dotted-field
    • multi-entity
    • link
  • 074 page filter coverage partial

    Every stored page filter with its tokens filled converts and runs 200 but one, yet recipe 003 kept unticked leaves (active "false"): 11 trees returned the wrong count. Drop them.

    Not measured. in_calendar_* relations, multi-hop paths and summary-field paths: no stored tree on the probed site uses one. 306 trees whose parent type has no row here. Blocked on the site.

    • page
    • filter
    • operator
    • query
    • trap
  • 079 summarize multi grouping

    _summarize nests one group level per grouping entry, 3 deep tested, counts summing exactly. status_list rolls a group up to one status; status_percentage ignores any value and is no per-status share.

    • summary
    • status
    • query
    • page
  • 080 query field cost partial

    One _summarize with the parent leaf as in [N rows], grouped on that link, reproduced open_notes_count for 300 Shots in 573 ms, against ~290 ms a row one call at a time.

    Not measured. A Note linked to two Shots: the probed project has none, so crediting one group to several parents is untested. single_record fields have no grouped form. Blocked on the site.

    • query
    • summary
    • cost
    • page
  • 150 group resolution

    task_assignees is <person> misses a Task assigned to their Group; filter task_assignees.Group.users. Group assignment makes the members followers once, and an Artist reads Groups and members.

    • group
    • task
    • user
    • follow
    • dotted-field
    • permission
  • 167 rollup on shot

    A query (summary) field cannot be created over REST: 400 data_type is not valid, with or without a query. Total each Shot's Bid Lines with one _summarize grouped on the link.

    • summary
    • query
    • schema
    • custom-field
    • error-handling

Writecreating and updating

  • 011 create project

    A script user can create a Project with nothing but {"name": ...}, at 201, but the response echoes only 6 attributes, so read the project back if you need anything else.

    • write
    • project
    • create
    • schema
  • 012 create version

    The schema's mandatory flags are not the create contract: on every project-scoped type measured, project is required and the identity field is optional, server-generated and not unique.

    • write
    • version
    • create
    • entity-field
  • 024 read after write

    Every write ignores ?fields. A create returns what you sent plus the server defaults, an update returns the whole record, and neither resolves a dotted path, so re-read for those and after an upload.

    • write
    • create
    • batch
    • upload
    • async
    • entity-field
    • trap
    • silent
  • 045 webhooks partial

    The hook contract validates the url and the entity type, and silently accepts a field name, a project id and an entity-type count it will never honour. test_connection answers 204 for any uuid.

    Not measured. No entity event reached a hook on the probed site, so the delivery payload, the `X-SG-SIGNATURE` and `x-sg-event-batch-*` headers, and `batch_deliveries`, are all unrecorded.

    • webhook
    • silent
    • trap
    • create
    • write
    • delivery
    • error-handling
    • token
  • 050 webhook subscriptions

    entity_types and event_type are mutually exclusive and one 400 covers giving neither and giving both. revive is a fourth action, and every entity the guide calls excluded is accepted at 201.

    • webhook
    • silent
    • trap
    • create
    • error-handling
    • enumeration
  • 058 local storage roots

    One create fills every local_path_* the storage row defines, whichever platform's root the path was under. The server picks the deepest matching root, and no conditional-write header is honoured.

    • path
    • storage
    • published-file
    • etag
    • silent
  • 069 client note

    client_note cannot be set over REST: true on create is 400 and any PUT is 400 editable on create only. sg_note_type: "Client" is the one marker a caller can write.

    • note
    • list-field
    • create
    • sudo
  • 070 authored timestamps partial

    A create body sets created_at and updated_at and they read back exactly, on Note, Task and Version, though the schema flags both editable false; every PUT on either 400s.

    Not measured. Whether an EventLogEntry create can date itself is untried: that row cannot be deleted afterwards (probe 025), so the probe did not spend one.

    • date
    • create
    • sudo
    • trap
  • 078 page setting write partial

    A script cannot create a Page (HumanUser expected), a person can. settings_json writes only as a JSON string, reads back identical. DELETE on a PageSetting is 400: every created row is permanent.

    Not measured. What the web interface draws for a person whose override the script wrote: needs a person at a browser. Blocked on the work.

    • page
    • write
    • create
    • sudo
    • destructive
    • trap
  • 083 task template on create

    A create with task_template makes the Tasks inside the same call, by POST and by _batch, copying every field set on the template tasks and their dependency types and offsets.

    • task-template
    • task
    • dependency
    • create
    • shot
  • 084 task template reapply

    Changing task_template to T creates a Task per T task no Task links by template_task, duplicating a same-name hand-made one, and re-syncs the linked Tasks' fields and edges (probe 102).

    • task-template
    • task
    • shot
    • trap
  • 085 task dependency types

    TaskDependency takes four dependency_type values, default finish-to-start-next-day; offset_days counts working days and snaps the dependent both ways. shift_ratio moved nothing.

    • dependency
    • task
    • date
    • create
    • enumeration
  • 086 batch tasks with dependencies

    Tasks and their dependencies take two _batch calls: create the Tasks, then create TaskDependency rows. upstream_tasks on a create links without rescheduling.

    • batch
    • dependency
    • task
    • create
    • silent
  • 087 dependency cascade

    An upstream date write reschedules every unpinned downstream Task, later and earlier alike; a null one moves none (097). A pinned Task stays put and flags dependency_violation while broken.

    • dependency
    • task
    • date
  • 089 task delete side effects

    Deleting a Task retires its TaskDependency rows, unlinks both neighbours without bridging them, and nulls Version.sg_task and PublishedFile.task. Revive restores all of it.

    • dependency
    • task
    • published-file
    • version
    • destructive
  • 092 dependency edge reschedule

    A new edge reschedules an unpinned downstream Task at once, whether POSTed or copied by a template apply on claim. A pinned one keeps its dates and flags dependency_violation.

    • dependency
    • task
    • date
    • task-template
  • 093 clear dates pin

    On a dependent Task a start_date write pins it, null or real; a due_date write never does, null or real. A pinned null Task holds; PUT pinned:false refills both dates.

    • dependency
    • task
    • date
  • 094 permission preflight partial

    Ask with a write that cannot land: a no-op PUT per field (update), a POST with a bad status (create), a _batch of [delete, 404 sentinel] (delete). Permission is checked first, and nothing is written.

    Not measured. a launcher session (probe 052) of a lower-level person, and the allowed side of a conditional rule (an Artist assigned to the Task); both need a person, the first at a browser

    • permission
    • batch
    • sudo
    • task
    • write
  • 095 dependency remove undo

    Remove an edge with DELETE on its TaskDependency row: revive restores its type and offset. A remove on upstream_tasks or downstream_tasks erases the row for good.

    • dependency
    • task
    • date
    • multi-entity
    • destructive
  • 096 task template unmerge

    A template write re-syncs every Task linked to it: fields but status reset, edges rewired. Undo: old template_task per Task first, then old task_template, then delete what B made.

    • task-template
    • task
    • dependency
    • destructive
  • 097 null dates unpin

    A Task with no upstream never pins, on a null or a real date write; nulling its dates leaves its downstream unmoved, and pinned:false refills nothing.

    • dependency
    • task
    • date
  • 098 template merge in one batch

    Recipe 015's merge fits one _batch: requests run in order, so a task_template write sees claims made earlier in the batch, and null then T on the same Shot re-runs the apply.

    • task-template
    • batch
    • task
    • dependency
  • 099 template apply edge copy kept

    A template apply copies a missing edge between two Tasks whose template_task already match it, whether either was claimed, kept, or created by that same call.

    • task-template
    • dependency
    • task
    • batch
  • 100 duration write pin

    Writing duration on a dependent Task does not pin it; a start_date write in the same run does. It keeps following the upstream, and a duration write upstream moves it.

    • dependency
    • task
    • duration
  • 101 template edge conflict

    On a claimed pair, a template apply replaces an existing edge of another type, or the reverse edge, with the template's edge: the old row is erased, not retired, and the PUT is a plain 200.

    • task-template
    • dependency
    • destructive
  • 102 task template resync

    Writing task_template T re-syncs every Task linked to T: T's non-empty values overwrite, status kept, dates and assignees kept or filled if empty; edges between linked Tasks reset to T's.

    • task-template
    • task
    • dependency
    • destructive
    • trap
  • 103 batch delete revive

    A delete inside _batch retires a Task or TaskDependency exactly as DELETE does: same retired read-back, and revive returns the same id, fields, edges and Version.sg_task.

    • batch
    • task
    • dependency
    • destructive
  • 104 template unmerge in one batch

    Recipe 019's undo fits one _batch with the same end state, if the batch skips edges its own task_template write removes: deleting one 404s and rolls back all. Undo to null deletes them.

    • task-template
    • batch
    • task
    • dependency
    • destructive
  • 105 offset days null vs zero

    TaskDependency offset_days null and 0 are stored and compared as different: a template apply deletes an entity edge with null against a template 0 (or the reverse) and re-creates it with a new id.

    • task-template
    • dependency
    • trap
  • 106 template task linked twice

    With two Tasks linked to one template task, an apply re-syncs and wires only one of them, picked unpredictably (not by id, age or edges); the other is left as is. No error, nothing duplicated.

    • task-template
    • task
    • dependency
    • trap
  • 107 dependency three task loop

    A three-Task loop is a 400 on a direct create and inside _batch, which rolls back whole. A template apply deletes a claimed Task's upstream edge from a Task outside the template, loop or not.

    • dependency
    • task-template
    • batch
    • destructive
  • 108 task template resync empties

    Re-sync to T: a numeric 0 on T's task overwrites (est, duration); milestone false and "" (stored null) keep the Task's value; a Task with only start or only due keeps its null duration.

    • task-template
    • task
    • duration
    • trap
  • 109 template apply outside edge

    A template apply erases an edge where a linked Task depends on a Task not linked to the template (root or not, other template, other Shot); it kept the edge with the outside Task downstream.

    • dependency
    • task-template
    • destructive
  • 110 template task after revive

    Revive restores template_task. A task_template write while the Task is retired re-creates it, so a later revive leaves two Tasks on one template task. Revive first, then write.

    • task-template
    • batch
    • trap
  • 111 template undo outside edge

    An undo's write back to template A erases every edge whose downstream Task is A-linked and that A lacks, pre-merge edges included; recipe 022 DELETEs one such edge, 404s and rolls back.

    • task-template
    • dependency
    • batch
    • destructive
    • trap
  • 112 template unmerge linked twice

    Undo relinking two Tasks to one template task: A wires either one (11 of 14 picked the loser), nothing is made. Relink the loser after the task_template write: then it matches the one-link undo.

    • task-template
    • batch
    • dependency
    • trap
  • 113 batch atomic after template write

    A _batch holding a task_template apply is atomic: a later or earlier failing request left no Task, no claim, no field write, no edge and no EventLogEntry row.

    • batch
    • task-template
    • error-handling
    • event-log
  • 127 retry and client uuid partial

    A text field created with unique: true refuses a second create with the same value, case and outer spaces ignored, in a batch too. It is the only idempotency key: the API has no header for it.

    Not measured. whether `unique` spans projects, and whether a deleted row's value frees. One project only. Blocked on the work

    • batch
    • create
    • custom-field
    • trap
    • idempotency
  • 136 unique scope retired partial

    A deleted row frees its unique value: a new row may take it. Reviving the old row while another holds the value is a 400 code 104 PG transaction error, and the row stays retired.

    Not measured. uniqueness across two projects. Probes write only into the sandbox and a project entity refuses a row with no project. Blocked on the site: needs a second writable project

    • custom-field
    • idempotency
    • create
    • trap
  • 137 batch create coercion

    A _batch create on a custom entity takes a numeric string in a float and honours created_at, as a single POST does. It also takes an Integer and "1e3", which a single POST refuses.

    • batch
    • create
    • custom-entity
    • number
    • date
    • trap
  • 143 nonadmin rows partial

    On the probed site an Artist may not create, edit or delete custom-entity rows (status only) and may create but not delete an Attachment, its own included. The group rights call predicts each answer.

    Not measured. Manager and Vendor writes; rights read, not exercised. Blocked on the site: impersonation on for one of each in the sandbox, then `143 --write`

    • permission
    • sudo
    • custom-entity
    • attachment
    • write
  • 145 time fields

    date_time rounds to the second on POST and PUT (.999 goes up, .5 stays) but truncates in a _batch create. A new timecode field has no rate property; it is integer ms rendered at the site's fixed rate.

    • date
    • timecode
    • duration
    • batch
    • custom-field
    • trap
  • 146 note unique key partial

    A unique: true text field works on Note as on Version (probe 127), and refuses a duplicate on PUT and under sudo too. A Note.meta key is found by contains, case-sensitive, and enforces nothing.

    Not measured. uniqueness across two projects. Probes write only into the sandbox. Blocked on the site: run `146 --write --second-project <name>` with a second writable project

    • note
    • custom-field
    • idempotency
    • jsonb
  • 148 note author fields partial

    user and created_by are both honoured on a Note or Version create, though the schema flags created_by read only; a PUT to it is 400. Under sudo_as_login all three author fields are the person.

    Not measured. a launcher session bearer (auth_type session_token). Needs a person: `052 --login`, then `148 --write --session`

    • note
    • version
    • user
    • sudo
    • create
    • trap
  • 154 batch multi entity mode

    multi_entity_update_mode in a _batch update's data adds, removes and sets as on a PUT, and several updates of one record in one batch apply in request order, each row echoing the state after it.

    • batch
    • multi-entity
    • write
  • 156 action menu item partial

    An ActionMenuItem creates from {} at 201 and url is not checked; an Artist is refused. Run from the web interface, an http url got a form POST in a new tab, json or not, with no token.

    Not measured. a custom-protocol `url` opening an app, whether `permissions_groups` hides an item in the web interface, and Manager rights. Each needs a person, steps below. Blocked on the work

    • create
    • permission
    • sudo
    • url
    • browser
    • header
  • 158 project text size

    A custom text field on Project stored 1,000,000 characters of JSON byte for byte, \n, \r\n and tabs kept, with no refusal. Leading and trailing whitespace is stripped.

    • custom-field
    • project
    • cost
  • 159 project field update rights partial

    An Admin updates a custom field on a Project, member or not. An Artist in the project reads it and gets 400 code 104 The field is not editable for this user on a PUT; outside it, 404 on the read.

    Not measured. Manager and Vendor writes; rights read, not exercised. Blocked on the site: impersonation on for one of each, then `159 --write`

    • custom-field
    • project
    • permission
    • sudo
    • write
  • 161 link to deleted row

    A link to a deleted row is hidden, not removed: it reads null or drops out, and returns on revive, even after a replace. A write naming a deleted row is 400 code 104 Value is not legal.

    • entity-field
    • multi-entity
    • link
    • trap
  • 164 vendor writes

    On the probed site a Vendor creates no Bid or Bid Line, by POST or _batch, and updates only sg_status_list, each refusal 400 code 104. Both preflight reads predicted every answer.

    • permission
    • sudo
    • custom-entity
    • batch
    • write
  • 166 vendor award

    On the probed site a Group added to Shot.sg_vendor_groups shows the Shot to its people on their next request; removing it hides it. sg_people grants as users does; other projects stay hidden.

    • permission
    • sudo
    • group
    • shot
    • multi-entity
  • 168 group create rights partial

    On the probed site a Manager or Admin person creates, renames, re-members and retires any Group; Artist and Vendor get 400 code 104. The person's own group rights on Group predict each answer.

    Not measured. an App Session Launcher bearer (probe 052); it needs the person to approve at a browser. `sudo_as_login` applies the same permission set (probe 094)

    • group
    • permission
    • sudo
    • shot
    • trap

Uploadgetting bytes in and out

  • 013 upload media

    Media upload is three calls: GET {field}/_upload, PUT the bytes, POST links.complete_upload. Transcoding is async: poll until the field stops reading /images/status/transient/.

    • write
    • upload
    • media
    • attachment
    • version
    • async
  • 014 attach file

    Leave the field out of the _upload path and the file is stored as an Attachment on attachment_links; read it back with POST /entity/attachments/_search, never flat filter[].

    • write
    • upload
    • attachment
    • provenance
    • version
    • multi-entity
    • filter
    • header
  • 022 sequence on version

    sg_uploaded_movie is single-valued, and replacing it leaves sg_uploaded_movie_mp4 describing the old file while status reads 1. A sequence belongs in sg_path_to_frames.

    • version
    • media
    • upload
    • sequence
    • path
    • attachment
    • write
  • 039 upload silent failures

    complete_upload returns 201 and creates an Attachment even when the bytes were never PUT, and file_size is null on a good upload too, so only fetching the stored file proves it exists.

    • media
    • attachment
    • upload
    • error-handling
    • trap
    • note
    • silent
  • 044 multipart upload

    multipart_upload=true on the init sets upload_id and adds links.get_next_part. Every part but the last must be at least 5 MiB, and completion needs an etags array inside upload_info.

    • multipart
    • upload
    • etag
    • storage
  • 123 photos per record partial

    image keeps only a 480x320 thumbnail. A url field holds one original, a Note's attachments or a multi_entity to Attachment hold many; all return the bytes unchanged.

    Not measured. completing a field-less upload on Slate and reading where it links; the web interface itself. Blocked on the work

    • on-set
    • upload
    • attachment
    • image
    • url
    • published-file
  • 125 upload host cors partial

    The presigned upload host answers any Origin with *, allows PUT with content-type and exposes ETag, so a page can upload, multipart included. A URL is refused after 900 s.

    Not measured. a real browser run, and a size cap: the largest single PUT sent was 7.6 MB (probe 123). Blocked on the work

    • cors
    • browser
    • upload
    • etag
    • multipart
    • header
  • 134 attachment field second upload

    A second _upload to a multi_entity field to Attachment adds: the field holds both. Each Attachment gets the row's project and the row in attachment_links, so a project filter finds it.

    • upload
    • attachment
    • multi-entity
    • custom-field
    • on-set
  • 135 attachment custom field filename

    Attachment takes a custom field over REST. filename keeps 90 and 200 characters but stores each space as _; is and starts_with ignore case, so filter on the name with _ for spaces.

    • attachment
    • custom-field
    • upload
    • on-set
    • trap
  • 139 multipart lifetime partial

    An upload_id still completed 1230 s after its init, with part 2 minted then. The link's timestamp is not age-checked: it is part of the stored key, so another value signs a URL S3 answers 404.

    Not measured. an upload_id older than 1230 s. Blocked on time: `139 --write --wait <seconds>` measures any age

    • multipart
    • upload
    • storage
    • trap
  • 140 presigned put size partial

    One presigned PUT took 1000 MB at 200 and the stored object read back at exactly 1000000000 bytes. No refusal up to there; at about 8 MB/s a 1000 MB PUT took two minutes.

    Not measured. sizes above 1000 MB, stopped there by design. S3 documents five gigabytes as one PUT's ceiling

    • upload
    • storage
    • cost
  • 141 download headers

    A stored file's GET sends Content-Length and Accept-Ranges, answers * to any Origin and allows a Range preflight, so a page can show progress, resume with Range and abort. HEAD is 403.

    • browser
    • cors
    • header
    • attachment
    • media
  • 151 video on take partial

    On sg_uploaded_movie an HEVC .mov becomes an H.264 mp4 with a thumbnail and a filmstrip, ready in under a minute. As a plain Attachment, video gets a 480 px thumbnail and nothing else.

    Not measured. playback in the web interface and an upload from iPad Safari. Needs a browser and a person with an iPad, see below

    • on-set
    • upload
    • transcode
    • version
    • attachment
    • media
  • 152 audio on take partial

    Audio on sg_uploaded_movie transcodes to an audio-only mp4 (aac), status 1, no thumbnail. The stored content_type is not the PUT's: an Opus .webm sent as audio/webm reads video/webm.

    Not measured. playback in the web interface and a recording from iPad Safari. Needs a browser and a person with an iPad, see below

    • on-set
    • upload
    • transcode
    • version
    • attachment
    • media
  • 153 presigned put slow partial

    A presigned PUT started at once and ending at 965 s was stored, 3 runs of 3. Every PUT started at 600 s or later and ending past 900 s was 403 Request has expired, whatever it sent first.

    Not measured. a PUT started between 4 s and 600 s, and a real upload at Wi-Fi speed. Blocked on time: each run takes 17 minutes

    • upload
    • storage
    • browser

Observewhat changed

  • 025 event log partial

    meta.old_value and meta.new_value answer "what was this before", but meta is unfilterable and unsortable: narrow on entity, event_type and attribute_name, sort -id, read meta yourself.

    Not measured. Whether event_type or meta can be set in the create body is untried: testing it costs another permanent row. Every event read was generated by another user; probe 049 covers the script's own.

    • event-log
    • query
    • filter
    • operator
    • paging
    • write
    • create
    • serializable
    • status
    • trap
    • silent
  • 043 attention

    The six attention calls share no convention with the rest of the API: no paging, no fields, links.self spelled /entity/Shot/7668, and a missing record id on activity_stream is a 500.

    • follow
    • user
    • note
    • reply
    • paging
    • header
    • async
    • trap
    • silent
  • 049 script events

    A script's writes reach the event log only while its ApiUser has generate_event_log_entries True. The default is False and nothing errors when off. One create logs one row per field plus one _New.

    • event-log
    • permission
    • write
    • silent
    • trap
    • observe
    • auth
  • 066 user feed

    A HumanUser's activity_stream is what the person created, not what they follow: 0 of 9 rows touched the 81 followed records. A feed is a fan-out over their tasks' Shots and Assets.

    • follow
    • user
    • task
    • version
    • observe
  • 067 notes in the stream

    A Reply reaches every linked stream in 33 s as create_reply, creates too; a script's Note create and status changes were absent after 430 s. Write as a person.

    • note
    • reply
    • task
    • version
    • async
    • silent
  • 077 page change stamps

    PageSetting has no updated_at; Page.updated_at moves when its layout is saved. Poll Page.updated_at; Shotgun_PageSetting_Change names which setting changed but its entity is null on 131 of 500.

    • page
    • event-log
    • schema
    • observe
  • 090 template task events

    A template-generated Task logs like a hand-made one plus a template_task change row, in_create true, credited to the caller. Filter attribute_name template_task to find them.

    • event-log
    • task-template
    • task
    • observe
  • 124 updated at bumps

    updated_at moves on a write, a finished upload and its transcode, and on a link set from either end, but not on a no-op PUT and not when a Note names the row in note_links.

    • observe
    • upload
    • link
    • multi-entity
    • on-set
  • 147 note addressing partial

    A Note's To and cc people, and every member of an addressed Group, become its followers at create, with the author. Find a person's Notes with addressings_to.Group.users as well as addressings_to.

    Not measured. the Inbox itself, which has no REST call. Needs a browser: `147 --write --hold 900`, then open each Artist's Inbox

    • note
    • group
    • follow
    • user
    • sudo
  • 149 note update activity partial

    A person's Note create streams at once; a PUT to content or addressings_to writes no stream row in 150 s but turns the addressee back to unread. An addressee added later follows at once.

    Not measured. the Inbox, which has no REST call, and a launcher bearer. Needs a browser: see the table at the end

    • note
    • follow
    • reply
    • sudo
    • async

Rendershowing it to a person

  • 010 status icons

    Status.icon is an entity link under relationships; display_type picks one of three renderings; url is empty unless image_data is asked for beside it; the stock sprite is in the site's own stylesheet.

    • status
    • icon
    • cache
    • colour
    • entity-field

Unphased

A finding answers a question. A recipe is a call that ran, with the response it returned.

4 behaviours the REST documentation does not describe

Each is a recorded probe result. The entry that measured it is linked below it.

  • An unknown filter operator returns 400 naming every legal relation.

    Measured on all 21 reachable data types: every one 400s, and 16 of them enumerate the field's whole legal vocabulary in the error. The other five take no operator at all and say so. A filter typo can never pass as "no filter".

    Valid relations: ["is", "is_not", "greater_than", "less_than",
     "in_last", "not_in_last", "in_next", "not_in_next",
     "in_calendar_week", "in_calendar_month", "in_calendar_day",
     "in_calendar_year", "between", "in", "not_in"]

    filter operators

  • An unknown ?fields name is dropped at 200.

    The opposite of the filter path. A misspelled field is removed from the response and the request succeeds, so the row comes back missing a key rather than reporting an error.

    GET /entity/versions?fields=sg_not_a_field
    -> 200, n=1

    query

  • A write can be accepted at 200 and discarded.

    Task.splits takes a well-formed array of hashes, answers 200, and stores null. A client that trusts the status code records a value that is not there.

    PUT [{"start_date": "2026-01-01", "duration": 480}]
    -> 200      reads back: null

    serializable

  • hidden_values is not enforced on write.

    REST accepts a status the project hides from its own UI, and reads it back. Only valid_values is enforced, so every client must subtract hidden_values itself.

    usable = [v for v in valid_values if v not in hidden_values]

    status_list

Every entry on this site is the output of a probe in probes/. The corpus is generated by running those probes against a live Flow Production Tracking site, not written from memory.

Not affiliated with or endorsed by Autodesk. Flow Production Tracking is their product; this is an independent record of how its REST API answers.