multi_entity

Data type multi_entity, probed on Version.sg_ai_generated_from (stock, editable, valid_types: ["Version"]). Version has 10: cuts, notes, open_notes, playlists, published_files, sg_ai_generated_from, sg_deliveries, tags, tasks, version_sg_ai_generated_from_versions, the last a reverse field of sg_ai_generated_from. valid_types is under properties, not at the top level, and holds one type on each (tasks: ["Task"], playlists: ["Playlist"], notes: ["Note"]), matching the one-element rule creation enforces (probe 019); single entity is the opposite, Version.entity listing 15. attachment_links is a field on Attachment, not on Version: filter it with [["attachment_links", "is", {"type": "Version", "id": N}]] from /entity/attachments/_search (probe 014).

Read Under relationships, never attributes, as {data: [...], links: {self}}. Each element is {id, name, type}, where name is the target's cached_display_name, already resolved and identical to the single-link form on every type measured (probe 060). A deleted target is removed from the list rather than left as a stale element.

relationships.sg_ai_generated_from = {"data": [{"id": 26332, "name": "zzprobe_..._target_a",
  "type": "Version"}, {"id": 26333, "name": "zzprobe_..._target_b", "type": "Version"}],
  "links": {"self": "/api/v1/entity/versions/26334/relationships/sg_ai_generated_from"}}
unset -> {"data": [], "links": {...}}     <- empty list. never null, never an absent key

Write PUT /entity/versions/{id} with Content-Type: application/json. The field value is either a bare list of {type,id} hashes or the wrapper {"multi_entity_update_mode": "add"|"remove"|"set", "value": [{type,id}]}. Starting from [A]:

Value shapes, on the bare-list form:

A dead id and a forbidden type are indistinguishable. value is the only accepted payload key: values, entities, data and inline type/id all 400 with invalid/missing array of entity hashes 'value', and an unknown mode is rejected. There is no relationship endpoint: GET on relationships/sg_ai_generated_from returns 200, while POST and DELETE there, and PATCH /entity/versions/{id}, all 404.

Clear

A cleared field reads back {"data": []}, identical to one never set; no round trip separates them.

Filter From a bogus operator, verbatim:

"API read() Version.tasks's 'multi_entity' data type doesn't support 'definitely_not_an_operator'
 'relation'"  source: {"Version.tasks": " ... Value: {"path" => "tasks", "relation" => ...}
 Valid relations: ["is", "is_not", "name_contains", "name_not_contains", "name_is", "type_is",
 "type_is_not", "in", "not_in"]"}

Nine against text's eight, trading contains/not_contains/starts_with/ends_with for the five name_* and type_*. Four rows: AB links both targets, A_only and B_only link one, empty links nothing. A and B below stand for those two targets, each sent as {"type": "Version", "id": <id>}.

Two filter rows intersect, and a dotted path reaches the target's own fields:

Traps

• Both incremental spellings that live in the query string return 200 having silently replaced the list. The loss is a success response, not an error; send the mode in the body.
• A bare list replaces, so an append coded as read-then-PUT loses any link a concurrent writer added between the two calls. Use the multi_entity_update_mode wrapper, not read-modify-write.
• in [X] means "links any of X" and not_in [X] means "links none of X", so it matches empty rows, as does is_not. "Links all of X" has no operator: repeat is once per entity, as separate filter rows.
• in with only unresolvable ids is field-dependent, so a negative control built that way must be checked per field. On Version.sg_ai_generated_from it returns the rows linking nothing rather than zero rows; on Note.note_links it returns zero rows though rows with an empty list exist (recipes/009). Mixed, in [A, 99999999] returns A's rows. Which side varies, and why, is unprobed.
• A dotted path through this field reads back nothing: 200, key absent from attributes, in GET ?fields and in _search alike, while the identical path filters correctly (probe 016). To read the far side, query the child entity filtered by the parent.
• Read order is not insertion order (adding B then A read back A then B), so never treat it as a sequence.