Skip to main content
A reference is the durable record of one acquired source object in one workspace. Two workspaces importing the same video get two references that share the canonical content underneath; neither can see the other.

​
States

mediaAvailability tracks the media layer on its own: processing while bytes transfer, ready when they are verified and held, expired after the hold lapsed, failed when acquisition failed after the reference was already readable, and unavailable when no media was requested (mediaProfile: none).

​
Fields

Title, description, channel, publication time, and counts exactly as observed at acquisition time. Absent values are null, never guessed. Refreshing the reference records a new observation; earlier observations stay in the history.
What we measured from the bytes: container, size, duration, dimensions, and tracks. creativeSpec and aiProvenance are versioned placeholders (currently null) reserved for structural analysis and generation lineage.
customTitle, notes, and tags. Written through PATCH /v1/references/{id} with optimistic concurrency (revision), never overwritten by a refresh.
The source route id and contract version that produced the reference, the acquisition time, and the raw capture the observation was parsed from.
primaryMediaId and posterMediaId name the objects you can request download URLs for. mediaAvailability is processing, ready, expired, failed, or unavailable; mediaHold and mediaExpiredAt describe the retention window.

​
Duplicates

Importing a URL whose canonical content already has a ready reference in your workspace succeeds immediately without transferring media again. The ingestion’s outcomeMessage says it was a duplicate and referenceId points at the existing reference.

​
Listing

GET /v1/references returns the newest first with an opaque signed nextCursor. Filter by state, platform, mediaKind, createdAfter, createdBefore; page size limit is 1..100 (default 30). A tampered or expired cursor is 400 invalid_input.