Media retention - Refmatter

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.

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.