Skip to navigation

Submit a batch of catalog titles for ingestion

Submits a batch of catalog titles for asynchronous ingestion. Send at least 1 and at most 500 titles per request; a larger catalog is split across requests. The call is accepted immediately with a job id (202) and processed in the background — poll the job-status endpoint for progress, the coverage report, and the mapping from each submitted external title id to its platform title id. Supply an optional Idempotency-Key header to make retries safe: a repeated request with the same key, or with identical content, resolves to the same job rather than ingesting twice. The tenant and the content-rights ruleset are resolved from your credential and are never sent on the request. Note that 429 has two distinct causes on this endpoint and they carry different bodies: exceeding your usage ceiling returns the documented ceiling-exceeded body, while exceeding the per-client request rate returns the standard error envelope with a Retry-After header. Branch on the body shape, not on the status code alone.

Authentication

AuthorizationBearer

OAuth authentication of the form <token>.

Headers

Idempotency-KeystringOptional

Optional. A caller-chosen key that makes a retried submission safe: a repeated request with the same key resolves to the same job. Absent, identical content is deduplicated instead.

Request

This endpoint expects an object.
sourceSystemstringRequired

The caller’s id-namespace token: 1-64 characters of lowercase letters, digits, and hyphens (e.g. “partner-cms”). Names the source system every submitted external title id is scoped to — the same external id under two source systems is two different identities. Use the same token later when pushing a flight’s active catalog.

itemslist of objectsRequired

The titles to ingest — at least 1, at most 500 per request (a larger catalog is submitted as multiple batches). An oversized batch is rejected whole (“ingest.batch_too_large”), never partially ingested.

Response

Accepted
jobIdstring

Server-minted job identifier, scoped to the caller’s tenant — poll the matching job-status endpoint with it. Another tenant’s job id does not exist for this caller.

statusstring

The job’s initial lifecycle state — always “queued” at acceptance.

schemaVersionstringOptional

Errors

400
Bad Request Error
401
Unauthorized Error
403
Forbidden Error
422
Unprocessable Entity Error
429
Too Many Requests Error
500
Internal Server Error