SG Ground Truth

Recipes

A verified call and its real response, addressed by the task. The heading is the intent and the rules are the recipe's own Notes. The code is in the entry.

API

001_publish_version_with_media

Publish a generated image to Flow PT as a Version, with provenance and the workflow attached

  • project is not schema-mandatory on Version but omitting it returns 400 (probe 012).

  • entity must be a {type, id} hash; a bare shot id 400s (probe 012, field_types/entity).

  • sg_status_list accepts only a code in the field's valid_values, and hidden_values is not enforced, so subtract it per project yourself (field_types/status_list).

  • upload_data must be present in the complete call even though it is empty (probe 013).

  • The complete call takes Content-Type: application/json; the vendor type 415s there (probe 014).

  • The field in the path picks the upload type: /image/ a Thumbnail, any other field an Attachment, no field at all a generic Attachment on attachment_links (probes 013, 014).

  • Reading image straight back gives a placeholder under /images/status/transient/ until the transcode lands, so test that prefix rather than truthiness (probe 013, field_types/image).

  • To find the attachments again use POST /entity/attachments/_search with Content-Type: application/vnd+shotgun.api3_array+json and an entity hash filter (probe 014).

corpus/recipes/001_publish_version_with_media.md

002_batch

Apply many creates, updates and deletes in one atomic call, and match the results back to the requests

  • A batch cannot use an id it creates. Every way of pointing request 1 at request 0's row was rejected, and the failure is the whole batch, so nothing at all lands.

    entity value sent result
    {"type": "Shot", "id": "$0"} 400 Invalid field value, update failed [5 - Update failed for [Version.entity]: Value is not legal.]
    {"type": "Shot", "id": -1} 400, the same
    {"type": "Shot", "id": "0"} 400, the same
    {"type": "Shot", "id": "u1"}, request 0 sent with "uuid": "u1" 400, the same
    {"type": "Shot", "uuid": "u1"}, request 0 sent with "uuid": "u1" 400 Invalid field value, update failed [5 - Update failed for [Version.entity]: Invalid statement.]

    The uuid a delete row returns is generated per request and is not an input. Build a dependent graph as one batch per level: create the parents, read their ids out of the response, substitute, then send the children. Steps 1 and 2 above are that sequence.

  • Results are in request order, one row per request, interleaved by neither id nor type. A batch of [update 29926, create, update 29927, create, update Shot 7557] answered in exactly that order, so zip(requests, response["data"]) is correct and no key matching is needed.

  • Two creates sending the same code came back as two rows distinguished only by position and by the new ids, 29930 and 29931.

  • One failing request rolls back every other one. Each round below sent a good create, one bad request, and an update of an existing row whose description read before:

    the bad request status after it
    update record_id 999999999 404 Entity of type [Version] with id=999999999 does not exist. 0 rows created, description still before
    delete record_id 999999999 404, the same 0 rows created, description still before
    create with sg_not_a_field 400 Invalid field value, update failed [2 - Invalid field name: field [Version.sg_not_a_field] does not exist or user does not have access permission.] 0 rows created, description still before
    create with sg_status_list: not_a_status 400 Invalid field value, update failed [5 - Update failed for [Version.sg_status_list]: 'not_a_status' is not a valid status. Valid statuses: 'na', 'rev', 'vwd', 'apr', 'custom', 'fin', 'ip', 'clsd', 'cmpt', 'cfrm', 'pndad', 'pndl', 'pndvs', 'part', 'pass', 'pndng'.] 0 rows created, description still before

    | create TaskDependency naming a retired Task, after a task_template apply in the same batch | 400 Invalid field value, update failed [5 - Update failed for [TaskDependency.dependent_task]: Value is not legal.] | no Task made, no claim, task_template unchanged, no EventLogEntry row (probe 113) |

    The rollback covers the server-side work a request triggers, a template apply's Tasks and edges included, and the event log. The rollback is the reason to use the endpoint. A timeout is not covered by it: see the size note.

  • A batch create skips the validation a single create applies, and the row it makes is unreadable. POST /entity/versions with no project is 400 API create() missing 'project' attribute: {"code" => "v001"}. The same create inside a batch answered 200 with id 29932 and a create row holding no project relationship.

  • GET /entity/versions/29932 then answered 404 Version: 29932 not found, and a site-wide POST /entity/versions/_search on its code returned 0 rows. DELETE /entity/versions/29932 answered 204, so the row exists and only the id from the create response can reach it.

  • Validate a batch payload yourself; a 200 is not proof the row is addressable. A link to an id that does not exist is rejected on both paths, 400 Update failed for [Version.entity]: Value is not legal.

  • Size. No cap was found. A requests array of 5001 was validated in full, answering one data hash containing field/value pairs is required for the given request per element.

  • On the probed site a committing batch of 200 answered in 11.7s, 500 in 31.0s and 1001 in 47.7s on one run and not at all on another, where the client gave up at its own 60s read timeout. All 1001 rows had committed anyway.

  • A read timeout tells you nothing about what landed, and there is no request id to ask about, so keep a batch inside the response window, around 200 requests, and make each chunk re-runnable by reading back on code before resending.

  • The contract, one 400 at a time. Every rejection below names what it wanted.

    sent result
    Content-Type: application/vnd+shotgun.api3_array+json 415 Unsupported Content-Type 'application/vnd+shotgun.api3_array+json', {"content_type": "Content-Type must be one of: 'application/json'."}
    a top-level array 400 Invalid JSON body. Expected Hash but received Array.
    {"entity": "Version"} 400 Request Parameters invalid. {"requests": ["requests is missing"]}
    {"requests": []} 200 {"data": []}
    a request with no entity 400 {"requests": {"0": {"entity": ["entity is missing"]}}}
    a create with no data 400 {"data": ["data hash containing field/value pairs is required for the given request"]}
    "request_type": "read" 400 {"requests": {"0": {"request_type": ["request_type must be one of: create, update, delete"]}}}
    "entity": "versions", the URL slug 400 Invalid entity type: entity type [] does not exist.
    delete with no record_id, or with entity_id 404 Entity of type [Version] with id=0 does not exist.
  • delete in a batch and the DELETE verb do the same thing and report it differently.

    body after it
    batch delete 200 {"request_type": "delete", "type": "Version", "id": N, "uuid": "...", "did_delete": true} GET that id 404s
    DELETE /entity/versions/N 204, 0 bytes GET that id 404s

    Deleting an already deleted id inside a batch is 404 Entity of type [Version] with id=N does not exist. and takes the rest of the batch down with it, so a delete pass is not idempotent.

  • Response shape differs by request_type: a create row is the thin create subset, an update row is the whole record wrapped with links and status, a delete row is flat (probe 024 for the field-level table). ?fields on /entity/_batch is accepted and ignored, as on every other write (probe 024), and no row resolves a dotted path, so re-read for those.

corpus/recipes/002_batch.md

003_query_fields_and_pages

Resolve a query field's value, and run the rows a saved Page shows

The field is not a shortcut

The four flavours

The tree runs nowhere as stored

Tokens

Relations whose value is a list

Reading the page

  • columns are schema field names in display order and go straight into ?fields. All six on the page above were returned. On the probed site another Shot page lists the pivot columns step_35 and step_106, which are real fields in /schema/Shot/fields and were returned like any other.

  • id is a legal column and is not a field. On an EventLogEntry page listing it, ?fields=id,user answered 200 with attributes: {} and the id under the row's own id key. Drop id from the list and read row["id"].

  • A column absent from /schema/<Type>/fields is dropped at 200 with no error (probe 004), so check the list against the schema to know which columns you lost (probe 023).

  • sorts and grouping are lists of {column, direction}. ?sort takes one field, so the second and later sort keys and the grouping have to be applied client-side.

The stored project can be a project that is gone

Once translated, the field is still unusable as a field

The URL slug

Beyond /body

corpus/recipes/003_query_fields_and_pages.md

004_register_published_file

Register the next PublishedFile without overwriting the last one, and write a path the server resolves for every platform

  • The version query is the whole guard, and it is a read-then-write race. No field on PublishedFile is unique and no combination is enforced, so the identical body posted twice returns two 201s and there is no conflict error to catch (entity_types/PublishedFile). Two clients that read next_version at the same moment both publish version 4.

  • The API offers nothing to close this: no unique constraint to create, no conditional write, no returned row to lose the race against.

  • What a client can do is narrow the query to the same context it publishes into (name plus project, plus entity or task if the stream is scoped to one), re-run it immediately before the create, and treat the answer as advisory.

  • Production code pairs it with a filesystem probe of the publish directory and a retry cap because either source alone goes stale; that belongs in the client, and the API cannot confirm or deny what the retry found.

  • A caller with no storage root has a second route. The same field takes the three-call upload, which puts the bytes on the site and names no LocalStorage at all (recipes/013_publish_file_bytes). Everything below still applies to the local shape.

  • Each accepted path write mints an Attachment, on the create and again on every corrective PUT. The id is inside the path object. Nothing removes the previous one, so a publish loop that rewrites paths accumulates Attachment rows silently. Delete by DELETE /entity/attachments/<id>, which answered 204.

  • Creating a PublishedFileType for an unknown extension adds it to every project on the site. PublishedFileType has no project field and no filter narrows it (entity_types/PublishedFileType). Resolve against the full listing with a case-normalised compare, and create only from an allowlist. The create call is shown in step 3 and was not run for this reason.

  • The 201 body already holds the resolved path, so a publish needs no read-back to log the paths it wrote. This is the one place a create returns more than it was sent; ?fields on a write is still ignored (probe 024).

  • path_cache is null after a REST create even though the path resolved. A filter on path_cache misses every row published this way (entity_types/PublishedFile).

  • sg_status_list takes a raw code from the field's valid_values minus the project's hidden_values (probe 009, field_types/status_list). On the probed site the set is ['wtg', 'ip', 'cmpt'].

  • Reading the path back later: GET /entity/published_files/<id>?fields=path returns the local shape, which has no url key, so value["url"] raises on exactly the shape a publish writes. Test link_type first (field_types/url, probe 021).

corpus/recipes/004_register_published_file.md

005_propagate_status

Roll a status up from a parent's Tasks and Versions onto the parent, without racing a concurrent write

  • The trigger is not the rule. A run started by one Task changing answers "do all siblings satisfy the condition now", so the sibling set is re-queried in full and the triggering row's own status is used for nothing but the guard in step 4.

  • Two child types are two calls. _search is per entity type, so a rule over Tasks and Versions queries /entity/tasks/_search and /entity/versions/_search with the same entity filter. One call per child type per parent, not one per row.

  • Many parents in one call. ["entity", "in", [{"type": "Shot", "id": a}, {"type": "Shot", "id": b}]] is accepted at 200, as is ["entity.Shot.id", "in", [a, b]]. Ask for entity in fields and group the rows by relationships.entity.data.id yourself, then pair that with the batch write in step 5.

  • A sibling can hold a status outside usable. REST does not enforce hidden_values (field_types/status_list), so a code the project hides writes and reads back fine. On the probed site hld is hidden on Task in this project and PUT {"sg_status_list": "hld"} answered 200 and read back hld.

  • The two spellings of the rule then disagree over the same siblings ['fin', 'fin', 'hld']:

    rule result parent
    all(s in done) False ip, correct
    not any(s in blocking) True fin, wrong: blocking was built from usable, which excludes hld

    Build the "every status except these" set from the schema for the operator-facing list, and decide with in done so an unknown or hidden code blocks instead of passing.

  • hidden_values can name codes that are not in valid_values. On the probed site the project hides ['blk', 'hld', 'na', 'rdy', 'rev'] on Task while valid_values holds no blk and no rdy; PUT {"sg_status_list": "blk"} is 400. Subtracting one list from the other is still correct, and the difference is not the set of writable codes.

  • Display labels fail two different ways. PUT {"sg_status_list": "Final"} is a 400 that names the legal set, and the same string in a filter is a silent 0 rows:

    400 {"status": 400, "code": 104, "source": null, "detail": null, "meta": null,
         "title": "Update failed for [Task.sg_status_list]: 'Final' is not a valid status.
                   Valid statuses: 'wtg', 'ip', 'fin', 'apr', 'dis', 'na', 'hld', 'rev', 'omt', 'ready'."}
    

    The 400 enumerates site-wide valid_values, hidden codes included. Round-trip through display_values for anything an operator reads and send the code everywhere else.

  • The read-then-write race has no server-side guard. The step 4 comparison narrows the window; it does not close it, and there is no conditional write to close it with:

    sent on PUT /entity/tasks/{id} result
    If-Match: "zzstale" 200, applied
    If-Unmodified-Since: Mon, 01 Jan 1990 00:00:00 GMT 200, applied
    If-None-Match: * 200, applied
    updated_at echoed back in the body 400 API update() Task.updated_at is editable on create only.

    A GET does return a weak ETag (W/"6829a03d..."), and no verb honours it. Two propagations racing over one parent both write; the last one wins, and the loser leaves no trace. Serialise the runs per parent on your side if the answer has to be exact.

  • Batch is worth it for the write half only. The decision is reads, which _batch does not do. On the probed site two parent updates answered in 474ms as one batch against 857ms as two PUTs, one failing row rolls the whole call back, and the rows come back in request order. Recipe 002 has the contract, the size limits and the rollback matrix.

  • A batch update row returns the whole record including the new sg_status_list, and it is still not the confirmation: ?fields is ignored on every write (probe 024) and a write can be a 200 no-op (probe 028). Step 6 is the confirmation.

corpus/recipes/005_propagate_status.md

006_media_round_trip

Take media off one Version and put the same bytes on another, which is what every sync, transfer and hand-off does

  • No server-side copy, and no reference to reuse. The only value sg_uploaded_movie accepts is an object holding a url (field_types/url). Wrapping the source's presigned url in {"url": …, "name": …} answers 200 and stores a link_type: web link that dies with the signature, with no transcode and no thumbnail. Moving the bytes is the only transfer that survives.

  • The signature expires, and re-reading the field is the fix. The window is X-Amz-Expires seconds from X-Amz-Date, and the number is not a constant: two reads one second apart returned 847 and 900.

  • Both reads returned different strings for the same Attachment, so a client that outlives its url re-reads the field and starts the transfer again rather than retrying the string. A string held 706 seconds past expiry 403s AccessDenied (field_types/image). Persist the Attachment id or the Version id; never the url.

  • HEAD 403s with an application/xml body. The signature covers GET alone, so size and type come from the GET response or from GET /entity/attachments/{id}.

  • Where the extension lives depends on the field.

    field source of the filename
    sg_uploaded_movie and the three derived url fields name, and response-content-disposition agrees with it
    image, filmstrip_image response-content-disposition only: an image field is a bare string with no name

    Parse the query parameter in both cases and the same code handles all six. Uploading with the wrong extension is accepted, so nothing downstream corrects it.

  • Clearing is per field, and two readings never clear.

    after sg_uploaded_movie _mp4 image, filmstrip_image _frame_rate _transcoding_status
    PUT {"sg_uploaded_movie": null} null old file old file '25.0' 1
    PUT all six null null null null '25.0' 1
    the new upload, before the transcode new file null /images/status/transient/ '25.0' 0
    the new upload, after the transcode new file new file new file '25.0' 1

    _frame_rate and _transcoding_status are a float and a number, not url fields, and neither null nor the upload resets them. Between the clear and the transcode landing they describe a file the Version no longer holds, exactly as a replacement does (probe 022). _frame_rate reads back as a JSON string (field_types/float).

  • sg_uploaded_movie_transcoding_status was 0 in flight, 1 after the transcode landed, and 2 for a 16x16 png the transcoder refused, which left every derived field null. Treat 1 as "a transcode finished", never as "this media is transcoded": 1 was the reading throughout the clear, when the Version held no media at all.

  • The target does not end up with the source's rendition set. Uploading the source's mp4 produced a second transcode of an already transcoded file (<hash3>_<hash>_bunny.mp4), a thumbnail and a filmstrip, and left sg_uploaded_movie_image null, which the source had. Compare Versions on the file you sent, not on which fields are filled.

  • Attachments accumulate and the clear does not touch them. One file synced twice left 5 Attachments on the target: the seed, both uploads and both transcodes. PUT … null unlinks nothing; DELETE /entity/attachments/{id} does, and only the rows you made.

  • The download's Content-Type is not the media's. Reading the round-tripped file back served binary/octet-stream while the field reads video/mp4. Trust the field's content_type.

  • Wrap the download so the temp file is removed even when the upload raises. A failed sync that keeps its scratch file fills the disk of whatever runs the job.

corpus/recipes/006_media_round_trip.md

007_build_and_reconcile_a_cut

Write a Cut and its CutItems from an edit, read the timeline back, and reconcile a second edit against the Cut already there

  • The four stages exist because a batch cannot use an id it creates (recipes/002). A CutItem needs a Cut id, a Shot id and a Version id at once, and a Version needs a Shot id, so the graph is four levels deep and each level is its own call. Within a level, batch, and chunk at around 200 requests.

  • An id alone does not say which Cut a row is on. code repeats across Cuts: [["code", "is", "reel1_sh010"]] returned items (46, cut 19) and (53, cut 20). A blind PUT /entity/cut_items/53 with no cut key answered 200, left cut at 20, and overwrote that Cut's metadata.

  • Before updating, confirm the row's Cut: filter on cut when reading, or ask for cut.Cut.id in fields and drop every id that does not match. A dotted read through this single entity field works, unlike one through a multi_entity field (probe 016).

  • Sending cut in an update moves the item. PUT with {"cut": {"type": "Cut", "id": other}} answers 200 and the item leaves its old Cut. So does the other side: PUT /entity/cuts/<a> with {"cut_items": {"multi_entity_update_mode": "add", "value": [...]}} answered 200 and left the item's former Cut holding [].

  • CutItem.cut is single-valued, so an add on the parent is a re-parent, not an addition.

  • Cut.cut_items is not the running order. It is returned sorted by the item's display name: ['aaa_last', 'sh010', 'sh020', 'sh030', 'sh030_gap', 'sh030_overlap'] against cut_order 1, 2, 3, 4, 5, 6 on the same six rows.

  • Read the items with POST /entity/cut_items/_search, [["cut", "is", {"type": "Cut", "id": N}]], sort: "cut_order". A null cut_order sorts last in both directions.

  • No frame rate is reachable from a CutItem. Cut.fps is the only rate on either type, it is null until someone writes it, and no CutItem field points at the Cut's value. Read Cut.fps once and pass it down; float reads back as a string, so float() it (field_types/float).

  • Drop frame is expressible only inside the text fields, which validate nothing, so the client owns that flag too.

  • Deleting a Cut does not delete its CutItems. DELETE /entity/cuts/<id> answered 204 and the item survived with cut null, reachable only through [["project", "is", ...], ["cut", "is", None]]. Delete the items first. A delete inside a batch is not idempotent: a second delete of the same id 404s and takes the whole batch with it (recipes/002).

  • Nothing about a Cut is unique either. Three Cuts created with the same code all answered 201. revision_number is a plain number the client maintains, and the display name the server builds from it is code plus v%03d: reel1 v001, reel1 v002, and bare reel1 when revision_number is null. "The current cut" is sort: "-revision_number" over a code filter.

  • Cut.entity accepts ['Sequence', 'Scene', 'Episode', 'Reel'] and Cut.version a Version, whose reverse Version.cuts fills in on the same write.

corpus/recipes/007_build_and_reconcile_a_cut.md

008_delivery_progress

Keep a Delivery honest about what a long transfer is doing, including when it is cancelled and when it crashes

  • Write the pair from a finally, not from the success path. An uncaught exception between two progress writes leaves a Delivery reading ip and a line describing work that stopped an hour ago, and nothing in the API times a row out.

  • A 200 on the write is not proof of the value. Re-read the row (probe 028); say() above returns the re-read, not the response to the PUT.

  • Always send entity on the Reply. A Reply created without one cannot be deleted: DELETE /entity/replies/<id> answers 400 code 104 undefined method 'reflect_on_association' for class NilClass (entity_types/Reply). A failure reporter that drops the link leaves permanent litter on exactly the runs that already went wrong.

  • Reply.entity names 113 of the 114 types in /schema, Delivery among them, and Delivery.replies is one of only two fields anywhere with valid_types: ['Reply'] (entity_types/Reply). A Reply on a Delivery is ordinary, and it is readable back both from Delivery.replies and from POST /entity/replies/_search on [["entity", "is", {"type": "Delivery", "id": N}]].

  • Delivery.reply_content is not the thread. It read 'Warning: If you see this displayed in the UI, it means the widget is not respecting grid_column = false.' on a Delivery holding one real Reply. Read replies.

  • Reply.cached_display_name comes back HTML-escaped where content does not: a traceback containing " reads back with &quot; in cached_display_name and with " in content and in the name of the Delivery.replies link.

  • Writing "" to description stores null, so an empty progress line erases the previous one rather than blanking it (field_types/text). Send a real line every time.

  • sg_delivery_type has valid_values: [] on the probed site, so every write to it is 400 … 'Final' is not a valid list value. Valid list values: ''. An empty vocabulary is a field that cannot be set, not a free-text field.

  • Uploading with no field in the path stores the file as an Attachment on Delivery.attachments (probes 013, 014). Delete the Attachment rows, not just the link, when a run is rolled back.

corpus/recipes/008_delivery_progress.md

009_multi_entity_safely

Add to and remove from a multi_entity field without destroying the links you did not mean to touch

  • The removal direction is the dangerous one. An append that goes wrong loses one link; a removal that skips the other-parents check breaks a relationship something else still needs, and a child that left one parent is not a child nothing claims.

  • Remove from the parent, then ask [[<field>, "is", <child hash>], ["id", "is_not", <parent id>]] on the parent type, and strip the child only on an empty answer.

  • On the probed site the same query over an existing project answered 200, [332, 4473, ... 4491] for one Shot, 20 Notes claiming it, 19 once the one it left is excluded.

  • Use is with one entity hash for that query. A bare id is 400 API read() invalid/missing entity hash: 954, is with a list is 400 'is' 'relation' expects a 1-element array, and in means "links any of", which on some fields returns the rows that link nothing when a member is unresolvable (field_types/multi_entity).

  • One _search answers for one child; batch it by asking in [child, child, ...] and grouping the returned parents yourself.

  • The query-string trap. ?multi_entity_update_mode=add and ?options[multi_entity_update_modes][<field>]=add both answer 200 having replaced the whole list. The loss is a success response, so the mode is only ever correct in the body (field_types/multi_entity, probe 028).

  • The same body works as a _batch update's data, and several edits to one row in one batch apply in request order (probe 154).

  • The lost-update race. Read-then-PUT is not an append. A bare list replaces, the window between the read and the write is open, and no conditional write closes it: If-Match, If-Unmodified-Since and If-None-Match are ignored at 200 and updated_at echoed back is 400 editable on create only (probe 024). The wrapper is not a narrower window, it is no window.

  • Verify by re-reading. ?fields is ignored on every write (probe 024) and a 200 proves nothing about a multi_entity field, since the query-string form returns one after replacing (probe 028).

  • Compare the set you wanted against a fresh GET /entity/<slug>/<id>?fields=<field>. A dotted path is not a shortcut: ?fields=versions.Version.code answered 200 with attributes and relationships both empty (probe 016).

  • Order is not stored. Playlist.versions reads back sorted by the target's code, whatever order was written, and the human order is sg_sort_order on the PlaylistVersionConnection join row, which a write through the field leaves null.

  • remove then add the same member replaces the join row and the order with it, so reorder by writing sg_sort_order, never by rewriting the member list (entity_types/Playlist).

  • Know the field before sending a bare list. PUT {"replies": []} on a Note deletes the Reply rows outright, and the ids answer 404 afterwards (entity_types/Note). A bare list is a replace on most fields and a delete on some, and nothing in the response distinguishes them.

  • A multi_entity field reads back as a list. Unset is [], never null and never an absent key.

  • relationships.<field>.data was a list on every read taken here: 100 rows of Note.note_links and 100 of Version.playlists and Version.tasks from _search, 20 of those re-read singly by GET, and 72 sandbox reads split across 0, 1 and 2 members over GET, _search under both filter Content-Types, and GET .../relationships/<field>.

  • One implementation reported by the survey defends against the field coming back as a single mapping instead; that did not reproduce, so the defensive read below is recorded unverified, on the survey's word rather than on a measurement here.

  • The one field that does return a mapping is a single entity field, {"data": {"id", "name", "type"}}, which is what a caller reading the wrong field name gets.

    d = row["relationships"][field]["data"] or []
    d = [d] if isinstance(d, dict) else d
    

corpus/recipes/009_multi_entity_safely.md

010_status_picker

List the statuses a project actually offers, each with the label, colour and icon needed to draw it

Two calls, not one per status

Icon.url is empty unless image_data is asked for beside it

The three renderings

Rediscover the sprite; never hardcode it

Fall back to bg_color

The picker is not a validator

The other pieces

  • Read the schema per entity type. Codes do not transfer: on the probed site Version has 16 and Task 10, overlapping on five, and HumanUser has act and dis, which no other type offers.

  • display_values is a map from code to label and a key can be missing, so fall back to the code rather than dropping the option.

  • valid_values order is the order to show. It is not alphabetical by label, and there is no substring operator on a status_list field, so a type-ahead filters the list client-side (field_types/status_list).

  • icon_type has two values and no more. Over all 98 Icon rows on the probed site: permanent_status/image_map 94, custom_status/html 3, custom_status/image 1. Page 2 of the same listing returned 0 rows, so that census covers the whole table (probe 006).

  • Probe 010 left the question open; the answer is site configuration, and a site with more custom statuses will hold more custom_status rows, not a third icon_type.

corpus/recipes/010_status_picker.md

011_audit_webhook_subscriptions

Inventory every webhook subscription on a site, and see which have ever delivered

  • The listing is the whole site. A script with API access reads every other integration's consumer url, its entity_types and its project scoping. Treat the output as sensitive.

  • The secret token is never returned. is_token_set is the only readable fact about it.

  • num_deliveries: 0 on an active hook means it has never delivered in its lifetime, not that it is idle. That is the one field that separates a working subscription from a subscription that was accepted and never fired, which the create contract cannot tell you (045_webhooks).

  • A hook may name entity_types or event_type, never both, so read whichever is populated (050_webhook_subscriptions).

  • status is one of active, unstable, failed or disabled. Only disabled is set by a caller; the other three are the site's own assessment of the endpoint's health.

corpus/recipes/011_audit_webhook_subscriptions.md

012_sign_in_as_a_person

Reach the REST API as a person, with no script key and no password, by having them approve a login in their browser

  • user is a HumanUser, so every row this bearer writes has the person as created_by and, on a Version, as user, which the web UI shows as Artist. A script key gets the same result only through sudo_as_login, and that needs an administrator to grant can_impersonate_this_user per person (027_auth_permissions). This needs nobody.

  • The person's permission level applies, not a script's. Rows collapse to what they may see (027_auth_permissions); on the probed site the approver was in the Admin set and saw everything.

  • expires_in is 600, the same as a script token, and grant_type=refresh_token on the returned refresh_token answers 200 with another 600. Re-minting from the session token costs the same one call and needs no refresh bookkeeping.

  • The session token is the credential to keep, not the bearer. How long the site keeps it alive is the site's User Session Expiry preference (052_app_session_launcher), and is not returned anywhere.

  • machineId is not checked when polling, so it is a label for the person, not a binding.

corpus/recipes/012_sign_in_as_a_person.md

013_publish_file_bytes

Publish a file's bytes onto a PublishedFile when the caller has no LocalStorage root to write under

  • The url is not the file. It is minted per read and signed for 900 seconds, so persist path["id"], the Attachment, and re-read the field when the bytes are wanted (field_types/url). Two reads of the same unchanged row return two different strings.

  • local_path_mac is absent, not null. A reader doing (path or {}).get("local_path_mac") returns None for every row published this way and reports it as a row with no path. Branch on link_type first: an upload or web value has url, a local value has the three platform paths and no url (field_types/url).

  • Deleting the PublishedFile leaves the Attachment. DELETE /entity/published_files/<id> answered 204 and GET /entity/attachments/<id> still answered 200 with the filename. The bytes stay on the site until the Attachment is deleted by id, which is the same accumulation a local path write causes on every rewrite (recipes/004_register_published_file).

  • file_size on that Attachment reads null even after the bytes landed, so it distinguishes nothing (endpoints/put_links_upload).

  • Step three answers 201 whether or not step two ever ran, and its body is a single space rather than JSON (endpoints/post_links_complete_upload). Fetch the url to prove the bytes exist.

  • A file:// url is a third shape, and it moves nothing. {"url": "file:///…", "name": …} on the same field answers 201 on create and 200 on a PUT, at link_type web, and stores the string only: no bytes reach the site and any reader without that mount sees a dead link. A space in the url is refused, so percent-encode before sending (field_types/url).

  • The three-call flow needs no LocalStorage row to exist on the site at all, and no published_file_type. What it costs is that the file is one object: a sequence has to be archived first, and the archive is what a consumer downloads.

corpus/recipes/013_publish_file_bytes.md

014_notes_about

Find the Notes about a Shot, Asset or Version by the name of the thing, and read what each Note is linked to

  • cached_display_name resolves for every one of the 28 valid_types. code is 400 on Booking and name on every type but Department, with the same doesn't exist. string for a wrong type and a wrong field.

  • ?fields=note_links.Shot.code answers 200 with the key absent from attributes (probe 016). The links are readable only through note_links itself, as {id, name, type} triples.

  • ["note_links", "contains", NAME] without a type is 400 'multi_entity' data type doesn't support 'contains' 'relation'. There is no search across all types in one filter by name; resolve ids first and use ["note_links", "in", [{"type": ..., "id": ...}, ...]].

  • A Note about a Task is in tasks, not note_links. Search it on tasks.Task.content.

  • Two hops resolve: note_links.Shot.sg_sequence.Sequence.code narrows to a sequence.

corpus/recipes/014_notes_about.md

015_apply_task_template_without_duplicates

Apply a task template to an entity that already has Tasks, without duplicating the ones it already holds

  • The claim writes only template_task; the entity write then overwrites every Task linked to T, claimed or not (probe 102):

    field after step 2
    content, step, est_in_mins, sg_description, sg_sort_order, task_reviewers, milestone, a custom field (one list and one checkbox field probed on one site) T's value, where T sets one
    task_assignees, start_date, due_date kept; filled from T only when empty
    duration T's on a Task without dates; kept on a dated one; on a Task with only one date, kept null (probe 108)
    sg_status_list kept (paint kept ip)
    a numeric 0 on T (est_in_mins; duration on a Task without dates) 0: it overwrites (probe 108)
    any field T leaves empty: null, a checkbox's false, a text "" (stored as null) kept (probe 108)

    Tasks linked by an earlier apply of T are re-synced too: re-running step 2 wipes their hand edits.

  • The apply resets the edges between Tasks linked to T to T's. Every pairing of claimed, kept and created ends gets T's missing edges (probes 092, 099): paint and comp both existed before the apply and still got the start-to-start edge.

    the pair already holds the apply
    no edge, T has one creates T's
    the edge in T's direction with another type or offset, or the reverse edge deletes it and creates T's, a new id; the old row is erased, not retired (probes 101, 102)
    T's edge with offset_days null where T holds 0, or 0 where T holds null the same: erased, re-created with T's value (probe 105)
    an edge T lacks, both ends linked to T deletes it (probe 102)
    an edge T lacks, a Task linked to T depending on a Task not linked to T (unlinked, another template, another entity) erases it (probes 107, 109)
    an edge T lacks, a Task not linked to T depending on one linked to T keeps it (probes 101, 102, 109)

    The PUT is 200 in every case. Read each linked Task's upstream_tasks before the apply and re-create the outside edges to keep; write offset_days on an entity edge exactly as T holds it, null or 0, to keep its id.

  • A copied edge reschedules. The server moves an unpinned downstream Task to satisfy an edge it copied; a pinned one keeps its dates and flags dependency_violation (probe 092). Pin the Tasks whose dates must hold before step 2.

  • The claim rewrites template_task. A Task that pointed at another template's task (comp above) now points at this template's, so the provenance of the first apply is lost.

  • No Task is removed. roto at the old step stays; deleting what the new template lacks is the caller's decision, and probe 089 lists what a Task delete unlinks.

  • The key is content plus step id. Two Tasks on the entity with the same key keep only the last in free, so the other is left unclaimed and a duplicate stays.

  • Before an apply, at most one Task per template task may be linked to it. With two, the apply re-syncs and wires one, the server's pick, not predictable by id, age, name or edges. The other keeps its fields and link; its edges of T's shape were deleted or kept unevenly (probe 106). Unlink the others (template_task null) first; taken above keeps the claim from making a second link.

  • The claims, the clear and the set fit one _batch, in that order, with the same result: recipe 020 (probe 098). Undo is recipe 019 (probe 096).

corpus/recipes/015_apply_task_template_without_duplicates.md

016_create_tasks_with_dependencies

Create a set of Tasks and the dependencies between them, with types and offsets, in two calls

  • A Task sent with only duration gets its dates from its dependency in call 2: anim started the working day after layout ended and ran its 2400 minutes, five 8-hour days on the probed site.

  • offset_days is working days: light starts two working days after anim starts (probe 085).

  • The four dependency_type values, and the error that lists them, are in probe 085. Omitting the type stores finish-to-start-next-day.

  • A loop or a repeated pair in call 2 is a 400 and rolls the whole call back; the Tasks from call 1 stay. Delete them, or resend call 2 fixed.

  • Keep each call under about 200 requests (recipe 002, size note).

corpus/recipes/016_create_tasks_with_dependencies.md

017_check_permission_before_writing

Learn whether the signed-in person may update, create or delete a type before writing, with calls that change nothing [partial]

not measured: a launcher session (probe 052) of a lower-level person, and the allowed side of a conditional rule; both need a person, the first at a browser

  • editable False in the schema is a refusal without a write, and one call covers every field. True can still be refused by a conditional rule, such as an Artist setting sg_status_list on a Task they are not assigned to; the 400 then prints the rule's condition tree (probe 094).

  • The no-op PUT and the rolled-back update test different things: the first the current value, the second the value about to be written. Use can_update_to when a rule may depend on the value.

  • Check create with the invalid status, not with a rolled-back batch create: that one moved the parent Shot's updated_at a few seconds later in 4 of 15 tries, with no event (probe 094).

  • An empty PUT ({}), an unknown field and a missing id test nothing: the first passes for everyone, the other two fail before permission is read.

  • record_id 0 or negative is rejected before the first request runs, so it cannot be the sentinel.

corpus/recipes/017_check_permission_before_writing.md

018_remove_and_restore_a_dependency

Remove one dependency between two Tasks and put it back on undo, with its type and offset

  • The revived edge places the Task from the upstream's current dates, not the dates it had when the edge was removed. An undo that wants those dates writes them after the revive; the start_date write pins the Task (probe 093).

  • A pinned downstream Task keeps its dates through both calls. Its dependency_violation reads false while the edge is retired and true again after revive if it is still placed too early.

  • If something re-linked the same pair in between, revive is a 400 on the unique index. Delete the new row first, or keep it and drop the undo entry.

  • A remove through the multi_entity fields has no undo: re-create the row with its type and offset (recipe 016), which gets a new id.

corpus/recipes/018_remove_and_restore_a_dependency.md

019_undo_task_template_merge

Undo a task template merge, returning an entity's Tasks, fields and dependencies to their state before it

  • Revive before step 2. A Task retired since the snapshot does not count as linked: step 2 re-creates its template task and wires the copy, and a later revive leaves two Tasks on one template task, both upstream of the same Task. Revive restores template_task (probe 110).

  • Step 4 is what makes it an undo rather than a reapply of A. Status survives both applies, so it is not in KEEP. Assignees and dates are only filled where empty (probe 102): add them when the Task had none before. snapshot reads attributes only; read step and task_reviewers with link if you add them.

  • When the entity had no template before, step 2 writes null and the server does nothing. Step 3's dependency sweep is then the only thing that removes the new template's edges between old Tasks.

  • The dependency sweep compares ids, so an edge the merge deleted is not restored. A merge deletes an edge between two claimed Tasks that the template lacks, or holds with another type, offset or direction, and erases the row (probes 101, 102): revive cannot bring it back. Snapshot each edge's ends, type and offset and re-create the missing ones (recipe 016).

  • Step 2 erases every edge whose downstream Task is on the old template and that the template lacks, pre-merge edges the merge kept included (probe 111). Snapshot ends, type and offset to re-create them.

  • The step 3 skip of edges downstream on the old template follows probe 111's read after step 2, where the template's own edge came back under a new id and the unskipped sweep deleted it. Re-run as written, with content in KEEP, on three sandbox Shots merged by recipe 015:

    Shot undo Tasks, links, fields, status edges after
    the Response case ok equal roto on comp, same id
    no template before, comp and lay by hand ok, undo to null equal none, as before
    probe 111's W, 3 hand edges before and 3 after the merge ok equal roto on comp, new id

    The third lost roto on x, roto on lay (step 2) and comp on x (the merge), as the notes above say.

  • In one _batch (recipe 022), leave out the edges step 2 removes. A batch takes its ids before it runs, so it cannot read after step 2 as step 3 does here. A DELETE of an edge the non-null task_template write already removed is 404 Entity of type [TaskDependency] with id=... does not exist. and rolls back the whole batch (probe 104).

  • Undo to null removes nothing, so a batch undo to null keeps those DELETEs (probe 104).

  • Events: each write logs like any other (probe 090). The undo leaves Shotgun_Task_Change rows for template_task behind; the history is not rewritten.

corpus/recipes/019_undo_task_template_merge.md

020_apply_task_template_in_one_batch

Apply a task template to an entity that already has Tasks, without duplicates, in one atomic call

  • Two reads and one write, against recipe 015's two reads and up to four writes. The read of the entity's current task_template is gone: the unconditional null makes the set always a change.

  • The server still re-syncs the claimed Tasks and resets their edges to the template's, as in recipe 015.

  • The key caveat of recipe 015 stands: two Tasks with the same content and step leave one unclaimed.

  • As in recipe 015, at most one Task per template task may be linked before the batch: with two, the apply re-syncs and wires the server's pick (probe 106).

  • A request appended to the batch (a field write-back, a re-created edge) that fails takes the apply down with it. A TaskDependency naming a Task deleted since the plan was read is 400 Update failed for [TaskDependency.dependent_task]: Value is not legal.: re-read both ends first.

  • Keep the batch inside the size window of recipe 002 when an entity holds hundreds of Tasks.

corpus/recipes/020_apply_task_template_in_one_batch.md

021_undo_a_batch_delete

Delete Tasks or dependencies in one batch and undo it by reviving the same rows

  • _batch takes no revive request (request_type must be one of: create, update, delete, recipe 002), so the undo is one call per row.

  • Measured one row per batch. A Task and its own edge in the same batch was not measured; the check for an already live row in undo covers the edge coming back with its Task (probe 089).

  • A revived Task or edge is rescheduled from the upstream's current dates (probes 089, 095).

  • If the same pair was re-linked in between, the edge's revive is 400 on sgcu_task_dependencies (recipe 018).

corpus/recipes/021_undo_a_batch_delete.md

022_undo_task_template_merge_in_one_batch

Undo a task template merge in one atomic call, returning Tasks, fields and dependencies to their state before it

  • The dependency read happens before the batch, after the merge; recipe 019 reads after step 2 and so never meets the 404.

  • Mixed ends (probe 111): an edge re-created after the merge from a Task going back to A onto an unlinked Task is erased by step 2. The earlier version of this recipe, which left out only edges with both ends back on A, DELETEd it and got the 404. An edge whose upstream end alone goes back to A is kept by step 2 and deleted here.

  • Step 2 also erases pre-merge edges the merge kept, where the downstream Task is on A and A lacks the edge (probe 111). Snapshot each edge's ends, type and offset and re-create those after the undo.

  • Revive before the batch. _batch takes no revive (recipe 021), and a Task still retired when step 2 runs is re-created from its template task, so its revive leaves two Tasks on one template task (probe 110). Revive by separate calls, then send the batch.

  • Two Tasks on one template task in the snapshot: A's apply wires the server's pick of the two, the one that held no edge 11 of 14 times, and renames it with A's content (probe 112). Recipe 023 orders the claims for that case.

  • snapshot stores template_task per Task and task_template from recipe 019, keyed by Task id.

  • Atomic: any failing request rolls back the claims and the template write too (recipe 002), so a rejected batch leaves the merged state, not a half undo. Re-read before a retry.

  • The recipe 019 caveats stand: an edge the merge deleted is not restored, and the history of template_task writes stays in the event log (probe 090).

corpus/recipes/022_undo_task_template_merge_in_one_batch.md

023_undo_task_template_merge_with_a_task_linked_twice

Undo a task template merge when two Tasks pointed at the same old template task, without the server picking which one gets the edges

  • The end state equals the one-link undo, which is not the pre-merge state to the id: an edge the merge erased, a claimed Task on a Task outside the new template (probe 109), comes back new.

  • Only the case of one Task that held A's edges and one that held none was measured. Two Tasks that both held edges: not measured.

  • The deferred link leaves the second Task pointing at the template task, so a later apply of A meets the same pick (probe 106). Leave it null instead if nothing reads the link.

corpus/recipes/023_undo_task_template_merge_with_a_task_linked_twice.md

024_field_visibility_in_a_project

Read which fields of an entity type a project hides, and show or hide one field in one project without touching the others

  • A field just created is visible in every project. A field retired and revived is too, whatever it was before (probe 115).

  • project_id is also accepted in the query. Inside the property object it is not read (probe 119).

  • A project_id that does not exist reads as a project hiding nothing, at 200. The write refuses it, 400 code 105.

  • There is no site-wide write and no call that sets several projects: one PUT per field and project.

corpus/recipes/024_field_visibility_in_a_project.md

025_retry_safe_create

Create rows from a client that retries after timeouts, without duplicating any row [partial]

not measured: whether unique spans projects and whether deleting a row frees its value (probe 127). Blocked on the work

  • Generate the UUID when the record is captured and keep it with the local record, so every retry, on any day, sends the same value.

  • Uniqueness ignores case and outer spaces; a UUID is unaffected, a human-typed code is.

  • In a batch, one collision rolls back every request in it. On a 104 from _batch, look up each UUID and re-send only the ones not found.

  • The title names the field by display name and ends in <br> ; match code 104 and the phrase.

corpus/recipes/025_retry_safe_create.md

026_note_per_shot

Keep one Note per Shot, addressed to the people on the Shot's Tasks, found again by a client key and updated in place [partial]

not measured: the Inbox the addressees see, and a launcher bearer as the writer. Needs a browser and a person (probes 147, 148, 149)

  • A bare list on addressings_to replaces the set (field_types/multi_entity); the call sends the whole current list each sync. Whether someone dropped from it stops following is unmeasured; on a Task, a member removed from the Group kept following (probe 150).

  • The create is the only stream row; edits write none (probe 149). A feed polls updated_at.

  • For a key the server enforces, add a unique: true text field to Note (an administrator's call, probe 132) and send it on create; a duplicate is then 400 code 104 (probe 146).

corpus/recipes/026_note_per_shot.md

027_media_on_a_take

Put a video or audio clip on a custom entity row so a browser can play it, and know when it is ready

  • sg_uploaded_movie keeps the original byte for byte; play sg_uploaded_movie_mp4, and store ids, not URLs (probe 125).

  • Audio has no thumbnail: image goes from the transient placeholder to null. Draw the icon yourself.

  • The stored content_type is the server's: an Opus .webm reads video/webm. Tell audio from video on the client.

  • Any custom slot is accepted as Version.entity at 201, valid_types or not (probe 122, field_types/entity). A type with an sg_versions field also lists the Version there (probe 122).

  • A large clip goes up in parts (probe 044) and each part URL lives 900 s (probes 125, 153).

corpus/recipes/027_media_on_a_take.md

028_settings_on_project

Keep an app's settings for a project as JSON on the Project row, written by an Admin and read by everyone in the project [partial]

not measured: a Manager's create and write (probes 157, 159). Blocked on the site: nobody active in Manager has impersonation on

  • Compare parsed values, never the raw string: a leading or trailing newline is stripped on write.

  • An Artist cannot save settings. Show them read-only when can_write is false, or send the write through the script.

  • A field on Project is site-wide: creating it adds it to every project. The value is per project.

  • GET /entity/projects/<id> with no fields returns the whole settings string, so every other client reading a Project without fields pays for its size.

corpus/recipes/028_settings_on_project.md

029_check_site_ready_for_vendor_bids

Check that a site's Vendor permission group is set up for bidding, from its rules, before an app relies on it

  • Read as an Admin person, or as the vendor themselves with me set to their HumanUser id: a person reading their own group gets their own row in place of logged_in_user_token, so a check matching the token alone answers MISS for a rule that is there (probe 162). The script, an API Admin, gets 404 Unknown permission group code 'vendor'; a person asking for another group gets 403.

  • read: allowed is every row (probe 163). A MISS on the two Bid lines means every vendor reads every Bid, whatever the app filters.

  • A rule on Bid alone is not enough. A Bid Line visible to everyone still answers a filter on its Bid's fields and groups its total, and the event log shows values written to hidden rows (probe 165). Check Bid Line, and whether Vendor reads EventLogEntry.

  • The rule's path must be the one the app writes. A rule naming users ignores sg_people (probe 166).

  • "See entities in assigned Projects only" has no key in these responses. Its effect is that an award reaches a vendor only in a project they are assigned to (probe 166); check HumanUser.projects.

  • No REST call adds a missing rule (probe 162). Report the MISS lines to an administrator.

corpus/recipes/029_check_site_ready_for_vendor_bids.md

030_create_a_group_as_a_person

Create a Group as the signed-in person, once their permission group allows it, without a second Group of the same name [partial]

not measured: an App Session Launcher bearer (recipe 012); it needs the person at a browser. sudo_as_login applies the same permission set (probe 094)

  • Show the control when create is allowed. On the probed site that is Manager and Admin; the rule is site configuration and changes only in the web interface (probe 162).

  • The same rule lets the person rename, re-member and retire every Group on the site, not only the ones they made. Keep those controls to the Groups the app made, by id.

  • Without code the server names the Group New Group <id> and answers 201. Always send one.

  • The _search and the POST are two calls, so two people creating the same name at once can still make two Groups.

  • A new Group in Shot.sg_vendor_groups reaches the vendor's next request (probes 166, 168).

corpus/recipes/030_create_a_group_as_a_person.md

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.