Ingest a URL

Submit

curl -X POST https://api.refmatter.com/v1/ingestions \
  -H "Authorization: Bearer $REFMATTER_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://www.youtube.com/watch?v=aqz-KE-bpKQ","mediaProfile":"full"}'

Idempotency-Key is required: 8 to 128 unreserved characters, unique per intent. Replays return the original ingestion; a different body under the same key is 409 idempotency_conflict.

Layers

A reference is assembled in layers, each with its own switch and its own timing:

Layer	Request field	Default	Ready after
Metadata and provenance	always	on	seconds
Transcript from source captions	`transcript`	`true`	seconds, with the metadata
Media bytes and poster	`mediaProfile: none / analysis / full`	`analysis`	minutes, in the background

The reference becomes readable as soon as the metadata layer is durable: referenceId appears on the ingestion while media is still transferring, and the reference reports mediaAvailability: "processing" until the bytes are verified. With mediaProfile: "none" the media stages are skipped and the reference reports mediaAvailability: "unavailable"; a later ingestion of the same URL with analysis or full adds the bytes to the same reference instead of creating a new one.

Follow progress

{
  "id": "01a0a040-…",
  "state": "running",
  "progress": {
    "stage": "transfer_media",
    "completedStages": [
      "validate_url",
      "resolve_identity",
      "acquire_metadata",
      "discover_media"
    ],
    "attemptNumber": 1,
    "nextAttemptAt": null
  },
  "attempts": [
    { "number": 1, "state": "running", "stages": ["…"], "failureCode": null }
  ],
  "referenceId": "01a0a04b-…",
  "outcomeCode": null
}

Stages run in order: validate_url, resolve_identity, acquire_metadata, persist_canonical, create_reference (the reference is readable from here), then discover_media, transfer_media, verify_media, finalize for the media layer. Transient failures are retried with backoff; attempts shows each try.

Outcomes

`state`	`outcomeCode`	Next step
`succeeded`	`null`	Read `referenceId` (already available once the reference is readable)
`failed`	e.g. `unavailable_private`, `limit_exceeded`, `route_disabled`	Do not retry unless `retryable` is true. If the reference was already readable it stays `ready` and only `mediaAvailability` becomes `failed`
`cancelled`	`null`	Nothing; completed effects are never undone

Cancel

POST /v1/ingestions/{id}/cancel requests cancellation. The worker yields at the next stage boundary; the ingestion settles as cancelled.

Get started

Concepts

Guides

SDK and agents

Policies

Submit

Layers

Follow progress

Outcomes

Cancel

​Submit

​Layers

​Follow progress

​Outcomes

​Cancel

Submit

Layers

Follow progress

Outcomes

Cancel