Step: Flow PT entity type reference

Type Schema name Step, REST path slug steps. Site-wide: 13 fields, none of them project, and no project scope on the endpoint. Every project on the site reads the same Steps.

path	result
`GET /entity/steps`	200
`GET /entity/step`, `GET /entity/Step`	200, the same rows; `links.self` normalises to `/api/v1/entity/steps/<id>`
`GET /entity/pipeline_steps`	404 `Entity type 'pipeline_steps' does not exist.`
`GET /entity/steps/1`	404 code 104 `Step: 1 not found`; ids are not dense, so read them from the listing

project scope attempted	result
`_search` `[["project", "is", {"type": "Project", "id": N}]]`	400 code 103 `API read() Step.project doesn't exist.`
`GET ?filter[project]=N`	400, same title, `source` `{"Step.project": " does not exist. ..."}`
`GET ?project_id=N`	200, accepted and ignored: the same row count as the unscoped call

entity_type is the only partition. It is the entity_type data type (field_types/entity_type): a bare schema name under attributes, Shot and never the slug shots, read-only after create, case-sensitive on filter. On the probed site 35 Steps split three ways.

`entity_type`	Steps	`short_name` unique within it	`code` unique within it
`Asset`	13	yes	no
`Shot`	12	yes	no
`Level`	10	yes	yes

Listing the Steps a client may offer for one entity type, in the order the web UI shows them:

POST /entity/steps/_search   Content-Type: application/vnd+shotgun.api3_array+json
{"filters": [["entity_type", "is", "Shot"]],
 "fields": ["code", "short_name", "list_order", "color"], "sort": ["list_order"]}

Identity code is what a human reads, short_name is what a pipeline keys on. Neither is unique, and the schema says so: unique: false on both.

field	distinct of 35	repeated
`code`	25	6 values
`short_name`	28	5 values
`cached_display_name`	1	`null` on all 35 rows

Duplicates are cross-type: one Step for Asset and one for Shot under the same code. Key on id, or on the pair (entity_type, short_name). On the probed site the repeated codes are Animation, Character FX, FX, Layout, Lighting and Model, and the repeated short names ANM, CFX, FX, MDL and layout. layout is lower case where every other short name is upper case, so a client that upper-cases before filtering returns 0 rows for it.

Create Not attempted. A Step is shared by every project, so one created here would appear in every project's Task pipeline and add a step_<n> pivot column to its entity type (field_types/pivot_column); deleting the row does not free the column name. What the schema declares, unverified against the server, which requires a different set (probe 012):

field	schema
`code`, `short_name`	`mandatory: true`
`entity_type`	`mandatory: false`, `editable: false`; a `PUT` returns 400 `API update() Step.entity_type is editable on create only.`

Links

field	data type	`valid_types`	editable
`department`	`entity`	`['Department']`	yes
`created_by`, `updated_by`	`entity`	`['HumanUser', 'ApiUser']`	no

Two fields anywhere in the 114 types of /schema name Step specifically. Step itself has no reverse field to Task, so the direction is Task to Step, one Step per Task.

field	data type	`valid_types`
`Task.step`	`entity`	`['Step']`
`Department.steps`	`multi_entity`	`['Step']`

51 further fields (EventLogEntry.entity, and image_source_entity on 50 types) list Step among 114 valid_types. Those are generic any-entity links, not Step links; see field_types/entity.

Resolve a Task's Step with a dotted path in the same call (probe 003), never a second fetch:

POST /entity/tasks/_search   fields: content, step.Step.code, step.Step.short_name,
                                     step.Step.entity_type, step.Step.color, step.Step.id
{"content": "Art", "step.Step.code": "Art", "step.Step.short_name": "ART",
 "step.Step.entity_type": "Asset", "step.Step.color": "253,94,99", "step.Step.id": 13}

Status None. Step has no status_list and no list field. list_order (number, editable) is the display order, and nulls sort last in both directions: on the probed site the 12 Shot Steps sort [1, 2, 3, 4, 5, 6, 7, 8, 9, null, null, null] ascending and [9, 8, 7, 6, 5, 4, 3, 2, 1, null, null, null] descending.

Traps

entity_type groups Steps; it does not constrain Task.step. On the probed site 6 Tasks hold a Step declared for another type: 4 Level Steps and 2 Shot Steps on Asset Tasks. Check the pair yourself before trusting a Step to describe the entity it is attached to.
["entity", "type_is_not", "Shot"] also matches a Task whose entity is null. Of 205 apparent cross-type Tasks on the probed site, 199 have no entity at all. Add ["entity", "is_not", null].
cached_display_name is null on every Step on the probed site, though it is editable: true and reads as an ordinary text field. Display code.
Task.step takes a {type, id} hash. A bare id returns 400 API summarize() Task.step expected [Hash, ActiveSupport::HashWithIndifferentAccess, ... NilClass] data type(s) but got Integer: 2 (probe 012).