Findings — protocol: headers, and what a status code is worth: a door into the Flow PT corpus

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.

?fields can change the value of a field you did ask for, not only drop ones you did not. ?fields=display_type,url on an Icon returns url as ""; adding image_data to the same request returns the real data:image/png;base64 URI, and omitting ?fields returns it too. Narrowing a projection is not free, and the wrong answer is a plausible one (recipes/010).

Trap. Where a bogus name appears decides whether you hear about it:

bogus name in	result
`?fields`	200, the field absent
`filter[]`	400 `API read() Version.sg_not_a_field doesn't exist.`
a filter operator	400 (probe 017)

Only ?fields fails quietly, and a typo there reads as "no data" rather than "wrong field".

Representation is not negotiable: entity and multi-entity fields are returned under relationships as {data, links} under the default, under api3_array and under api3_hash, the two 200 _search rows matching byte for byte. As an Accept header both vendor types 406 with an empty body. Neither one is a rendering switch.
application/vnd+shotgun.api3_array+json and ...api3_hash+json belong on POST /entity/<type>/_search (and _summarize), which rejects application/json with 415 (probe 020). What the vendor type selects is the filters syntax of the request body, not the response:

Content-Type	`filters`
`api3_array`	`[[field, op, value]]`
`api3_hash`	`{"logical_operator": "and", "conditions": [[field, op, value]]}`

The conditions inside the hash form stay triples. An object of path/relation/values is 400 Missing logical operator, and a bare list under api3_hash is 400 Query is not an Hash. The per-type filters of POST /entity/_text_search split the same way, one key at a time (probe 063).

corpus/findings/004_array_vs_hash.md

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.

Every case below is measured elsewhere in the corpus; this entry is the map. The rows marked verified were re-run read-only on the date of this probe and none had changed.

Loud, and usually self-documenting. The rejection names the legal set, which is what made the field-type matrix cheap to build.

sent	answer	recorded
an operator no data type has	400 naming every legal relation for that data type. All 21 reachable types reject; 16 enumerate, the five unfilterable ones answer `cannot be used in a filter` (verified)	probe 017, `field_types/*`
a `_summarize` `type` that is not one of the fourteen	400 `Request Parameters invalid.`, `source.summary_fields` indexed by position, naming all fourteen (verified)	probe 020
an entity type name that does not exist, in a path or in `/schema`	404 `Entity type '<x>' does not exist.`, quoting the name back (verified)	`entity_types/Project`, probe 023
a field name that does not exist, in a filter	400 `API read() <Type>.<field> doesn't exist.` (verified)	probe 026
a `list` value outside `valid_values`, on a write	400 naming the legal values	`field_types/list`
a wrong Python type, on a write or as a filter value	400 naming the accepted Ruby classes (verified as a filter value)	`field_types/number`, `float`, `percent`
a malformed `POST /entity/_batch` body	400 per missing key, and `request_type must be one of: create, update, delete`	probe 024
sort syntax: empty, a space, a leading `+`	400 `sort must be filled` or `sort list is not valid` (verified)	probe 026

Silent. HTTP 200, and the part of the request the server did not understand is gone.

sent	answer	recorded
a name in `?fields` that is not a field, on a read	200, the key absent from `attributes` (verified)	probe 004, probe 023
`?fields` on a create or an update	ignored entirely, both verbs, plain names and dotted paths alike	probe 024
`?fields=display_type,url` on an Icon	200 with `url` reading `""`, which is indistinguishable from no image; adding `image_data` to the same request returns the real data URI, and omitting `?fields` also returns it	`recipes/010`
a `list` filter value outside `valid_values`	0 rows, no error; inside `in` the junk member is evaluated and matches nothing, so the rest of the list still returns (verified)	`field_types/list`
`sort` on an unsortable or unknown field	200 in default order, identical to no sort, ascending and descending alike (verified)	probe 026, `field_types/summary`, `field_types/url`
`["id", "in", [...]]`	200, id ascending; the order of the list is discarded (verified)	probe 026
any filter on `PageSetting.settings_json`	200 and the full unfiltered set, while another field on the same type filters (verified)	probe 023
any filter on `EventLogEntry.audit_trail`	the same (verified)	`field_types/jsonb`
`["read_by_current_user", "in", [...]]` on a Note	200 and the caller's unread rows, whatever the list holds; `not_in` and an `is` value outside `read`/`unread` answer the same. `is "read"` and `is_not` do filter	probe 068
`GET /schema/<Type>/fields/<field>` for a field the census omits	200 with `data: null`, while a name that is nothing at all 404s `Field '<Type>.<name>' does not exist.`	probe 068
`filter[]` query params on `POST _search`	ignored entirely: a body filter wins and a bogus param name still returns 200, while the same param filters correctly on `GET /entity/<type>`	probe 030
a batch create missing a required attribute	200 with an id for a row that does not exist: `GET` 404s, `_search` returns 0, `DELETE` answers 204. The single-create path 400s on the same body	`recipes/002_batch`

Silent and destructive. Seven writes return success and either do nothing or destroy data. Not re-run here: they are recorded, and re-proving them costs rows.

written	answer	recorded
`cached_display_name`	200, the write discarded; the field re-reads as `code`	`field_types/text`, `entity_types/Sequence`
`Note.read_by_current_user` as an ApiUser	200, the echo and the re-read both `unread`; the same write under `sudo_as_login` stores	probe 068
`Task.splits`, any well-formed payload	200, `null` stored	`field_types/serializable`
a `multi_entity` update mode spelled in the query string	200, the whole list replaced instead of appended	`field_types/multi_entity`
an already-linked Shot added to a second `Sequence.shots`	200, the first Sequence's `shots` is now `[]`	`entity_types/Sequence`
two `summary_fields` entries over one field	200, the second overwrites the first, last entry wins	probe 020
`PUT` a Note with `{"replies": []}`	200, the Reply rows deleted outright	`entity_types/Note`

The rule. Trust a 400: the request layer validates operator, summary type, entity name, field name and value class, and says what it wanted. Trust nothing about the parts of a request that select or shape data, because ?fields, sort, a filter value and an update mode are all dropped at 200 when the server does not recognise them, and a write is confirmed by re-reading the row, never by its status code.

corpus/findings/028_loud_and_silent.md

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.

The two prefixes are one API. One token authenticates both, every status matches, and every body matches once the prefix each echoes in its own links is normalised. Everything measured in this corpus was measured on /api/v1 and transfers to /api/v1.1 unchanged.
links echo the prefix you called. A client that starts on /api/v1.1 stays there through links.next; there is no silent downgrade to follow, and no rewriting to guard against (006_pagination).
api_version in the root document reports the prefix that served the request, 1.0 or 1.1. It is not a statement about the site, so it cannot be used to discover which versions a deployment offers.
The version is not discoverable from the API. Both specs advertise only /api/v1.1, yet /api/v1 serves the same 62 operations, and there is no listing of valid prefixes. /api/v1.2 and /api/v2 answer 404 code 103 with detail null, the same shape as any unrouted path (045_webhooks), so a probe cannot tell an unreleased version from a wrong URL.
Comparing two versions needs two artefacts removed first. Every error body has a per-request errors[].id that changes on every call, and /spec.json contains the literal /api/v1.1 under servers whichever prefix served it. Left in, both read as version differences and neither is one.

corpus/findings/051_api_version.md

062_cors

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. [partial]

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

/api/v1 reflects whatever Origin reaches it. There is no allowlist to be on and nothing to register: null, an http://localhost origin and the string banana all come back in access-control-allow-origin, each with access-control-allow-credentials: true, so a browser permits a credentialed cross-origin call from any page to any Flow PT site.
Vary: Origin, Access-Control-Request-Method is on every answer, so a shared cache does not hand one origin the reply meant for another.
The preflight is answered in front of the API rather than by the route. Any path under /api/v1 answers 200 with the echo, including one no route serves; a path outside /api/v1 answers 200 with nothing. It takes no token, and the answer has an empty body.

What is allowed is fixed, except the header list, which is an echo of a closed set:

asked for	answered
`Access-Control-Request-Method` one of `GET` `POST` `PUT` `PATCH` `DELETE`	`access-control-allow-methods: GET, POST, PUT, PATCH, DELETE`
`Access-Control-Request-Method: TRACE` or `BREW`	200 with every CORS header dropped, which fails the preflight
`Access-Control-Request-Headers` drawn from `authorization`, `content-type`, `accept`, `accept-language`, `content-language`, `range`, `origin`	the same string echoed back
one name outside that set, even beside a legal one	200 with every CORS header dropped

A page may send Authorization and the application/vnd+shotgun.api3_hash+json content type (probe 004), and nothing else: cache-control, if-none-match and x-requested-with fail the preflight and the request is never made. The content type is not a safelisted value, so every call is preflighted, and access-control-max-age: 3600 is what keeps that to one extra round trip per hour.

No access-control-expose-headers, so script reads only the six safelisted response headers (cache-control, content-language, content-type, expires, last-modified, pragma).
etag and x-request-id are on the response and unreadable from a page, and if-none-match is refused at the preflight, so a browser client has no conditional request and no request id to quote in a support ticket.

What a page on another origin can call:

	from a page on another origin
everything under `/api/v1`	direct. Mint a token, read, filter, write. The `_upload` flow then leaves the site for a presigned host, whose own answer is not measured here
`/internal_api/*`: the App Session Launcher and the session	through a proxy. The browser discards an answer with no `access-control-allow-origin`, at 200, 401 and 404 alike
`/images/...`, `/dist/...`	as an `<img>` or a `<link>`, which need no CORS. Not through `fetch`, and pixels read back off a canvas are tainted

So a page signs a person in by having its own server make the two launcher calls of probe 052, opening the returned url in a tab for the person to approve, and then minting the bearer from the page, since POST /auth/access_token is one of the calls it may make. The alternative, a page holding client_credentials, ships the script key to every visitor.

corpus/findings/062_cors.md