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

# Media retention

> Derivatives are durable; media bytes exist only under a time-boxed hold you control.

Refmatter keeps two tiers:

| Tier    | What                                                                   | Lifetime                        |
| ------- | ---------------------------------------------------------------------- | ------------------------------- |
| Durable | Poster frame, observations, provenance, raw capture, human annotations | As long as the reference exists |
| Held    | Verified video bytes (`primaryMediaId`)                                | While a media hold is active    |

There is no permanent media library. This keeps the service on the right side of storage-related copyright exposure and keeps your costs tied to what you actually use.

## Holds

* A successful ingestion opens a hold for **30 days** by default.
* `PUT /v1/references/{id}/media-hold` with `{ "ttlDays": 1..365 }` extends it from now (deployment cap 365 days).
* `DELETE /v1/references/{id}/media-hold` releases it; the bytes are deleted at the next retention pass.
* Deleting a reference releases its hold. Bytes shared with another workspace stay until every holder releases.

## After expiry

The reference stays `ready` with `mediaAvailability: "expired"`, `primaryMediaId: null`, and `mediaExpiredAt` set. Poster, metadata, provenance, and your annotations remain. Importing the URL again re-acquires the bytes and opens a new hold. Extending a hold on expired media is `400 invalid_input` with reason `media_expired`.

<Note>
  Download URLs are presigned and valid for five minutes with `Cache-Control: no-store`.
  Fetch the bytes when you need them; do not treat the URL as durable.
</Note>