url

Data type url, probed on Version.sg_uploaded_movie and its three derived fields sg_uploaded_movie_mp4, _webm, _image (stock, all four editable). Schema properties are default_value, open_in_new_window, summary_default; no valid_values, no format hint. Version.image is data_type image, not url. The plain string probe 021 read back is that field; the object is this type.

Read A JSON object under attributes whose keys depend on link_type. relationships stays empty. On the probed site there are 20 url fields on 9 of 114 entity types. Reading all 20 returned three shapes and no fourth, from the 10 that held a value on any row:

One field mixes them: Attachment.this_file returned upload on 148 rows, web on 19 and local on 33. The six keys of the upload shape, on the probed Version:

The signed query holds X-Amz-Expires, X-Amz-Signature and X-Amz-Security-Token, and two reads of the same row return two different strings. Re-read for a fresh link; GET /entity/attachments/{id} gives filename, file_size and this_file.

A dotted read, ?fields=sg_uploaded_movie.Attachment.url, answers 200 with the key silently absent, the same hole as a multi_entity dotted read (probe 016). Ask for the field, not a path through it.

Write The only accepted input is an object holding url.

The url itself is validated. These four were measured on PublishedFile.path, whose write also takes two other shapes (entity_types/PublishedFile), and the refusal is the same message a {} gets:

Percent-encode a path before sending it. A raw space is the one character measured to fail, and the site's own rows hold their file:// urls encoded.

The url is read back exactly as sent and each accepted write mints an Attachment row, so a direct object publishes a link the review player will open without putting bytes on the site, with no transcode and no thumbnail. The derived fields take the same object, so a client can assert a transcode that was never made.

Clear

Read immediately after the field went null, on two Versions whose uploads had finished transcoding:

Each derived field is its own url field and has to be nulled by name. _transcoding_status is a number and stays at 1, the same stale reading a replacement leaves behind (probe 022).

Filter No relation exists, on the field or on any derived field.

["sg_uploaded_movie", "definitely_not_an_operator", null] -> 400
 title:  "API read() Version.sg_uploaded_movie's 'url' data type cannot be used in a filter."
 source: {"Version.sg_uploaded_movie": " data type cannot be used in a filter. Value:
          {"path" => "sg_uploaded_movie", "relation" => "definitely_not_an_operator",
           "values" => [nil]}"}

There is no legal relation to list, so this is the one type where the bogus-operator trick (probe 017) returns nothing to build a filter editor from. sort answers 200 and is ignored, so the field is invisible to the query API in both directions:

Traps

• "Has media" is not a query. Page the rows with fields=sg_uploaded_movie and test the value client-side. _summarize refuses with the same message under API summarize() (probe 021), so a fill-rate scan must special-case data_type == "url".
• The filterable neighbours are proxies, not answers. image is_not None and sg_uploaded_movie_transcoding_status is_not None both matched exactly the media-holding rows on the sample project, and on two Versions uploaded and then cleared both still matched the row after sg_uploaded_movie had gone null. A picker built on either offers Versions with no media.
• The url is regenerated per read and signed with an expiry. Anything that caches it (a database column, a rendered page, a message to a chat client) serves a dead link once it lapses.
• Read link_type before anything else. upload and web are indistinguishable by keys, and a local value has no url key at all, so indexing value["url"] raises on the shape a published file uses.