> ## Documentation Index
> Fetch the complete documentation index at: https://docs.refmatter.com/llms.txt
> Use this file to discover all available pages before exploring further.

# References

> One object per acquired source, with observed, derived, and human-authored fields kept apart.

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

| `state`      | Meaning                                                                                                          |
| ------------ | ---------------------------------------------------------------------------------------------------------------- |
| `processing` | The first ingestion has not produced durable metadata yet                                                        |
| `ready`      | Metadata, provenance, and transcript are durable; the media layer is described separately by `mediaAvailability` |
| `failed`     | Acquisition ended before the reference became readable (`failureCode`, `retryable`)                              |

`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

<AccordionGroup>
  <Accordion title="sourceObserved">
    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.
  </Accordion>

  <Accordion title="machineDerived">
    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.
  </Accordion>

  <Accordion title="humanAuthored">
    `customTitle`, `notes`, and `tags`. Written through `PATCH /v1/references/{id}` with
    optimistic concurrency (`revision`), never overwritten by a refresh.
  </Accordion>

  <Accordion title="provenance">
    The source route id and contract version that produced the reference, the
    acquisition time, and the raw capture the observation was parsed from.
  </Accordion>

  <Accordion title="Media pointers">
    `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.
  </Accordion>
</AccordionGroup>

## 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`.