Skip to main content
You need a workspace API key. Keys are issued per workspace by the workspace owner (see Authentication); during early access we issue the first one for you.
1

Submit the URL

The response is 202 Accepted with the ingestion projection and a Location header. Replaying the same idempotency key and body returns the original ingestion with X-Idempotent-Replay: true.
2

Wait for the reference

Poll the ingestion until referenceId is set: that happens within seconds, once metadata, provenance, and the transcript are durable. Media bytes keep transferring in the background (state stays running until they are verified); wait for succeeded only if you need the bytes right away.
3

Read the reference

A succeeded ingestion carries referenceId.
refmatter.resolve(url) in the SDK does all three steps and returns { ingestion, reference } as soon as the reference is readable; pass { waitFor: 'media' } to wait for the bytes too.

Choosing a media profile

The profile is part of the idempotency hash: the same URL with a different profile is a different ingestion.