Endpoints — Records, GET
Every call in this family: what the card records, the edge cases that live on the call, and the verdict of every entry that measured it. Each of those lines names the door holding that entry's rules. The map is corpus/INDEX.md.
GET /entity/<type>
Pages rows. An entity field is returned under relationships and never attributes, an unknown fields name is dropped at 200, and links.next is emitted on empty pages forever.
| you send | what happens |
|---|---|
fields=code,sg_not_a_field |
200, and the key is absent from attributes |
page[number]=99999 |
200, data: [], and links.next points at page 100000 |
page[size]=5000 |
200, 5000 rows. No cap was reached; the 500 limit is folklore |
page[size]=0 |
400 |
Stop paging when
datais empty.links.nextis never absent, so a loop waiting for it to disappear never ends.An entity link is under
relationships, with the row'snamealongside itsid. Readingattributesalone makes every link look null.
Measured by
001_auth(findings) — Send the token request asapplication/x-www-form-urlencoded:application/jsonis 400 Invalid JSON body. client_credentials returns a 600s bearer, so ignore the refresh_token and re-auth.
rules:doors/findings-auth027_auth_permissions(findings) — The token endpoint accepts password and session_token. Impersonation is the OAuth2 scope sudo_as_login:, never a body field, and a lower level reads far fewer rows and as many fields.
rules:doors/findings-auth133_bearer_expiry(findings) — Every bearer refusal is 401 code 102Unauthorized; onlydetaildiffers:Token Expiredpast exp,Token invalidfor a bad signature, null for garbage or none. Re-mint on 401 code 102.
rules:doors/findings-auth004_array_vs_hash(findings) — 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.
rules:doors/findings-protocol028_loud_and_silent(findings) — 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.
rules:doors/findings-protocol051_api_version(findings) — /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.
rules:doors/findings-protocol128_rate_limit(findings) — 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.
rules:doors/findings-protocol144_rate_limit_burst(findings) — 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.
rules:doors/findings-protocol061_shipped_statuses(findings) — Nothing in the schema marks a shipped Status.systemis true on a minority of them; the stock set iscreated_by is null, plusoptions[return_only]=retiredfor the rows a site retired.
rules:doors/findings-schema122_onset_entity_types(findings) — Slate, Camera, MocapTake, ShootDay and Scene create like Version:projectrequired,codegenerated. None hasattachments, and only Version.entity and Note.note_links reach them all.
rules:doors/findings-schema003_query(findings) — 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.
rules:doors/findings-read005_link_usage(findings) — On the sample project every Version links throughentity(99% Shot, 1% Asset) and only 1% throughsg_task, so measure link usage per site rather than hardcoding Task-linking.
rules:doors/findings-read006_pagination(findings) — 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.
rules:doors/findings-read007_fill_rates(findings) — On the sample project 30 of 71 Version fields are populated. Rank by fill rate, but drop checkbox, summary and computed fields first: False and 0 are not null and read as 100% filled.
rules:doors/findings-read018_project_listing(findings) — 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.
rules:doors/findings-read023_pages(findings) — 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.
rules:doors/findings-read026_result_order(findings) — 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.
rules:doors/findings-read059_dotted_path_type_check(findings) — 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.
rules:doors/findings-read082_page_size_cap(findings) — 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.
rules:doors/findings-read138_dotted_custom_field(findings) — A dotted path reaches ansg_field through ansg_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.
rules:doors/findings-read163_vendor_rows(findings) — On the probed site a Vendor reads every Bid in an assigned project, the other vendor's included: Vendor'sreadon Bid isallowed. A Group filter the client adds narrows the list, not the rights.
rules:doors/findings-read016_dotted_multi_entity(findings) — 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.
rules:doors/findings-filter030_complex_filters(findings) — 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.
rules:doors/findings-filter150_group_resolution(findings) —task_assignees is <person>misses a Task assigned to their Group; filtertask_assignees.Group.users. Group assignment makes the members followers once, and an Artist reads Groups and members.
rules:doors/findings-filter011_create_project(findings) — 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.
rules:doors/findings-write136_unique_scope_retired(findings) — A deleted row frees itsuniquevalue: 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.
rules:doors/findings-write158_project_text_size(findings) — A custom text field on Project stored 1,000,000 characters of JSON byte for byte,\n,\r\nand tabs kept, with no refusal. Leading and trailing whitespace is stripped.
rules:doors/findings-write010_status_icons(findings) — 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.
rules:doors/findings-render004_register_published_file(recipes) — Register the next PublishedFile without overwriting the last one, and write a path the server resolves for every platform
rules:doors/recipes003_sort_fails_silently(reports) — A sort on an unknown or unsortable field answers 200 with the rows in default order, while the same field name in a filter answers 400 and names the reason.
rules:doors/reports008_jsonb_filters_return_everything(reports) — A filter on PageSetting.settings_json or EventLogEntry.audit_trail is accepted and ignored, so the unfiltered set comes back at 200 and is_null and is_not_null each return every row.
rules:doors/reports
Silent on this call
get_entity_type— Pages rows. An entity field is returned underrelationshipsand neverattributes, an unknownfieldsname is dropped at 200, andlinks.nextis emitted on empty pages forever.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.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.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.059_dotted_path_type_check— 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.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.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.
corpus/endpoints/get_entity_type.md
GET /entity/<type>/<id>
One row, and the only read where fields is honoured on a single record. A retired row is 404 here and 200 under options[return_only]=retired.
The 404 for "never existed" and the 404 for "retired" are the same message with the same code. Only a second call with
options[return_only]=retiredtells them apart, and that distinction is the whole of whatDELETEdoes.A row a conditional see rule hides from the caller answers the same 404,
Shot: <id> not foundcode 104 (probe 165), so a caller cannot tell hidden from absent.Code 104 here, against code 103 for a bad type name. 104 is "this row is not there", 103 is "your request is wrong".
This is the only read where
fieldsis honoured on a single record. Every write ignores it.
Measured by
157_project_custom_field(findings) — 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 105User doesn't have permission to create a Field.
rules:doors/findings-schema060_entity_dict_name(findings) — Thenamein an entity dict is the target'scached_display_name, filled on every type measured, single and multi alike. Read it, not the per-type identity field, and expect decoration.
rules:doors/findings-read076_page_visibility(findings) — 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.
rules:doors/findings-read081_dotted_image(findings) — 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.
rules:doors/findings-read088_project_template_defaults(findings) — The per-entity-type default is readable atProject.tracking_settings.default_task_template.<Type>, a{type, id, name, valid}dict.Project.task_templatesis a separate list, not the default.
rules:doors/findings-read138_dotted_custom_field(findings) — A dotted path reaches ansg_field through ansg_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.
rules:doors/findings-read163_vendor_rows(findings) — On the probed site a Vendor reads every Bid in an assigned project, the other vendor's included: Vendor'sreadon Bid isallowed. A Group filter the client adds narrows the list, not the rights.
rules:doors/findings-read165_hidden_row_paths(findings) — A see rule hides a row from fetch, search, summarize, text search and links, but a dotted filter still matches through it, a grouped_summarizeshows its id and total, the event log its values.
rules:doors/findings-read150_group_resolution(findings) —task_assignees is <person>misses a Task assigned to their Group; filtertask_assignees.Group.users. Group assignment makes the members followers once, and an Artist reads Groups and members.
rules:doors/findings-filter167_rollup_on_shot(findings) — A query (summary) field cannot be created over REST: 400data_type is not valid, with or without a query. Total each Shot's Bid Lines with one_summarizegrouped on the link.
rules:doors/findings-filter058_local_storage_roots(findings) — One create fills everylocal_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.
rules:doors/findings-write078_page_setting_write(findings) — 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.
rules:doors/findings-write083_task_template_on_create(findings) — A create withtask_templatemakes the Tasks inside the same call, byPOSTand by_batch, copying every field set on the template tasks and their dependency types and offsets.
rules:doors/findings-write085_task_dependency_types(findings) — TaskDependency takes fourdependency_typevalues, defaultfinish-to-start-next-day;offset_dayscounts working days and snaps the dependent both ways.shift_ratiomoved nothing.
rules:doors/findings-write086_batch_tasks_with_dependencies(findings) — Tasks and their dependencies take two_batchcalls: create the Tasks, then create TaskDependency rows.upstream_taskson a create links without rescheduling.
rules:doors/findings-write089_task_delete_side_effects(findings) — Deleting a Task retires its TaskDependency rows, unlinks both neighbours without bridging them, and nullsVersion.sg_taskandPublishedFile.task. Revive restores all of it.
rules:doors/findings-write095_dependency_remove_undo(findings) — Remove an edge withDELETEon its TaskDependency row: revive restores its type and offset. Aremoveonupstream_tasksordownstream_taskserases the row for good.
rules:doors/findings-write096_task_template_unmerge(findings) — 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.
rules:doors/findings-write101_template_edge_conflict(findings) — 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.
rules:doors/findings-write103_batch_delete_revive(findings) — Adeleteinside_batchretires a Task or TaskDependency exactly asDELETEdoes: same retired read-back, and revive returns the same id, fields, edges andVersion.sg_task.
rules:doors/findings-write105_offset_days_null_vs_zero(findings) — TaskDependencyoffset_daysnull 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.
rules:doors/findings-write107_dependency_three_task_loop(findings) — 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.
rules:doors/findings-write109_template_apply_outside_edge(findings) — 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.
rules:doors/findings-write111_template_undo_outside_edge(findings) — 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.
rules:doors/findings-write113_batch_atomic_after_template_write(findings) — A_batchholding atask_templateapply is atomic: a later or earlier failing request left no Task, no claim, no field write, no edge and no EventLogEntry row.
rules:doors/findings-write148_note_author_fields(findings) —userandcreated_byare both honoured on a Note or Version create, though the schema flagscreated_byread only; a PUT to it is 400. Under sudo_as_login all three author fields are the person.
rules:doors/findings-write154_batch_multi_entity_mode(findings) —multi_entity_update_modein a_batchupdate'sdataadds, 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.
rules:doors/findings-write156_action_menu_item(findings) — An ActionMenuItem creates from{}at 201 andurlis not checked; an Artist is refused. Run from the web interface, an httpurlgot a form POST in a new tab,jsonor not, with no token.
rules:doors/findings-write158_project_text_size(findings) — A custom text field on Project stored 1,000,000 characters of JSON byte for byte,\n,\r\nand tabs kept, with no refusal. Leading and trailing whitespace is stripped.
rules:doors/findings-write159_project_field_update_rights(findings) — An Admin updates a custom field on a Project, member or not. An Artist in the project reads it and gets 400 code 104The field is not editable for this useron a PUT; outside it, 404 on the read.
rules:doors/findings-write161_link_to_deleted_row(findings) — 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 104Value is not legal.
rules:doors/findings-write166_vendor_award(findings) — On the probed site a Group added toShot.sg_vendor_groupsshows the Shot to its people on their next request; removing it hides it.sg_peoplegrants asusersdoes; other projects stay hidden.
rules:doors/findings-write168_group_create_rights(findings) — 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.
rules:doors/findings-write134_attachment_field_second_upload(findings) — A second_uploadto a multi_entity field to Attachment adds: the field holds both. Each Attachment gets the row'sprojectand the row inattachment_links, so a project filter finds it.
rules:doors/findings-upload151_video_on_take(findings) — Onsg_uploaded_movieanHEVC.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.
rules:doors/findings-upload152_audio_on_take(findings) — Audio onsg_uploaded_movietranscodes to an audio-only mp4 (aac), status 1, no thumbnail. The storedcontent_typeis not the PUT's: an Opus.webmsent asaudio/webmreadsvideo/webm.
rules:doors/findings-upload147_note_addressing(findings) — 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 withaddressings_to.Group.usersas well asaddressings_to.
rules:doors/findings-observe149_note_update_activity(findings) — A person's Note create streams at once; a PUT tocontentoraddressings_towrites no stream row in 150 s but turns the addressee back to unread. An addressee added later follows at once.
rules:doors/findings-observe003_query_fields_and_pages(recipes) — Resolve a query field's value, and run the rows a saved Page shows
rules:doors/recipes005_propagate_status(recipes) — Roll a status up from a parent's Tasks and Versions onto the parent, without racing a concurrent write
rules:doors/recipes006_media_round_trip(recipes) — Take media off one Version and put the same bytes on another, which is what every sync, transfer and hand-off does
rules:doors/recipes007_build_and_reconcile_a_cut(recipes) — Write a Cut and its CutItems from an edit, read the timeline back, and reconcile a second edit against the Cut already there
rules:doors/recipes009_multi_entity_safely(recipes) — Add to and remove from a multi_entity field without destroying the links you did not mean to touch
rules:doors/recipes013_publish_file_bytes(recipes) — Publish a file's bytes onto a PublishedFile when the caller has no LocalStorage root to write under
rules:doors/recipes015_apply_task_template_without_duplicates(recipes) — Apply a task template to an entity that already has Tasks, without duplicating the ones it already holds
rules:doors/recipes017_check_permission_before_writing(recipes) — Learn whether the signed-in person may update, create or delete a type before writing, with calls that change nothing
rules:doors/recipes019_undo_task_template_merge(recipes) — Undo a task template merge, returning an entity's Tasks, fields and dependencies to their state before it
rules:doors/recipes022_undo_task_template_merge_in_one_batch(recipes) — Undo a task template merge in one atomic call, returning Tasks, fields and dependencies to their state before it
rules:doors/recipes026_note_per_shot(recipes) — Keep one Note per Shot, addressed to the people on the Shot's Tasks, found again by a client key and updated in place
rules:doors/recipes027_media_on_a_take(recipes) — Put a video or audio clip on a custom entity row so a browser can play it, and know when it is ready
rules:doors/recipes028_settings_on_project(recipes) — 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
rules:doors/recipes030_create_a_group_as_a_person(recipes) — Create a Group as the signed-in person, once their permission group allows it, without a second Group of the same name
rules:doors/recipes
Silent on this call
058_local_storage_roots— One create fills everylocal_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.086_batch_tasks_with_dependencies— Tasks and their dependencies take two_batchcalls: create the Tasks, then create TaskDependency rows.upstream_taskson a create links without rescheduling.005_propagate_status— Roll a status up from a parent's Tasks and Versions onto the parent, without racing a concurrent write009_multi_entity_safely— Add to and remove from a multi_entity field without destroying the links you did not mean to touch
corpus/endpoints/get_entity_type_id.md
GET /entity/<type>/<id>/<field>
Reads one image or attachment field, and with ?alt redirects to the bytes. Every other data type is a 400, so this is not a cheap single-field read.
<field> |
result |
|---|---|
image, an image field |
200, data is a URL string |
sg_uploaded_movie, a url field |
200, data is the attachment hash |
code, sg_status_list, id |
400 is not an image or attachment |
entity, playlists |
400, the same message. Use relationships/<field> |
entity.Shot.code |
406, one byte |
| a name the type does not have | 404, code 103 |
A dotted path 406s because the segment after the last dot is read as a format extension, not as a field. There is no single-field read for a dotted path.
Rangewithout?altis ignored and the field hash comes back at 200. The header only reaches storage once the redirect is in play.Reading
imagehere costs about the same asGET /entity/<type>/<id>?fields=image, because the presigned URL is most of both bodies.An empty field answers 200 with
"data": null. Add?altto the same call and it is a 404, worded differently per data type:Field sg_uploaded_movie is empty.forurl,File not foundforimage. Read the field first if the difference between empty and missing matters.
Measured by
048_one_record_beyond_crud(findings) — POST on one record is revive, not update:?revive=1is required and the body is ignored./<field>reads image and attachment fields only, andrelationships/<field>is the same data, unpaged.
rules:doors/findings-read081_dotted_image(findings) — 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.
rules:doors/findings-read125_upload_host_cors(findings) — The presigned upload host answers any Origin with*, allows PUT with content-type and exposesETag, so a page can upload, multipart included. A URL is refused after 900 s.
rules:doors/findings-upload140_presigned_put_size(findings) — 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.
rules:doors/findings-upload141_download_headers(findings) — 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.HEADis 403.
rules:doors/findings-upload
Silent on this call
048_one_record_beyond_crud— POST on one record is revive, not update:?revive=1is required and the body is ignored./<field>reads image and attachment fields only, andrelationships/<field>is the same data, unpaged.
corpus/endpoints/get_entity_type_id_field.md
GET /entity/<type>/<id>/relationships/<related_field>
The entity or multi_entity link list on its own, unpaged and unsorted. page, fields and sort are accepted and ignored, and every link is returned in one body.
| you send | result |
|---|---|
page[size]=2 on a 60-link field |
200, all 60 rows |
page[number]=2 |
200, the same 60 rows |
fields=code |
ignored, links stay {id, name, type} |
sort=code |
ignored, source order kept |
an image field |
400 is not a relationship field |
datais byte-identical to whatGET /entity/<type>/<id>?fields=<field>returns underrelationships, in the same order, minus thelinks.relatedpointer to the linked row.There is no
links.nextand no measured page cap. The whole link list is in the one response.The saving is small: on the probed site 120 bytes against 353 for a single link, and 3048 against 3231 for 60. Call it when the link list is the entire request, not to trim a read you are making anyway.
options[return_only]=retiredis evaluated against the owning record, so it 404s on a live row rather than filtering the links.GETis the only verb.POSTandDELETEon this path are 404 (field_types/multi_entity); edit links withPUT /entity/<type>/<id>.
Measured by
048_one_record_beyond_crud(findings) — POST on one record is revive, not update:?revive=1is required and the body is ignored./<field>reads image and attachment fields only, andrelationships/<field>is the same data, unpaged.
rules:doors/findings-read165_hidden_row_paths(findings) — A see rule hides a row from fetch, search, summarize, text search and links, but a dotted filter still matches through it, a grouped_summarizeshows its id and total, the event log its values.
rules:doors/findings-read161_link_to_deleted_row(findings) — 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 104Value is not legal.
rules:doors/findings-write
Silent on this call
048_one_record_beyond_crud— POST on one record is revive, not update:?revive=1is required and the body is ignored./<field>reads image and attachment fields only, andrelationships/<field>is the same data, unpaged.
corpus/endpoints/get_entity_type_id_relationships_field.md