# impartire API — Reference: Delivery requirements and readiness

Every path is under `https://impartire.com/api/v1`. The machine-readable contract is https://impartire.com/api/v1/openapi.json (OpenAPI 3.1).

#### GET /api/v1/delivery-requirements

List the org's delivery requirements

Standing demands: content in a project's subtree must meet a pinned spec profile, for a client, delivered to a target. Poll with `updated_after` (exclusive, millisecond). For an OAuth token, its person needs the read-delivery permission (no platform-admin bypass); a key reads the whole org. 404 when the org does not have delivery, and for an OAuth token whose person may not read it.

Scopes: `delivery:read`

Parameters:

- `project_id` (query, string (uuid)) — Only the requirements bound to this project (not its ancestors' or descendants').
- `status` (query, "active" | "fulfilled" | "cancelled") — Only requirements with this status.
- `updated_after` (query, string (date-time)) — Only requirements changed strictly after this instant (ISO 8601 with offset), compared to the millisecond.
- `sort` (query, "-updated_at" | "updated_at" | "created_at") — Sort key; a leading `-` is descending. Default `-updated_at`. Ties break on id.
- `limit` (query, integer) — Page size, default 50. Values above 100 are treated as 100.
- `cursor` (query, string) — next_cursor from the previous page, with the other parameters unchanged.

Response 200 — `DeliveryRequirementList`

- `data` (array of DeliveryRequirement, required) — In the requested sort (default `-updated_at`), ties broken by id.
  - `id` (string (uuid), required)
  - `project` (object, required) — The project the requirement covers, with every sub-project under it.
    - `id` (string (uuid), required)
    - `name` (string, required)
  - `client` (string or null, required) — Who the content is owed to; null for an internal demand (a house standard).
  - `target` (object or null, required) — The delivery target the obligation is delivered to (GET /api/v1/delivery-targets); null for an internal demand or when the target is gone.
    - `id` (string (uuid), required)
    - `name` (string, required)
  - `spec_profile` (SpecProfileRef or null, required) — The spec revision the content must meet, pinned when the requirement was made.
    - `id` (string (uuid), required)
    - `name` (string, required)
    - `revision` (integer, required) — The spec's revision: a published spec changes only by a new revision, which supersedes this one.
  - `status` ("active" | "fulfilled" | "cancelled", required) — `active` — in force (readiness and the spec gate apply it); `fulfilled`; `cancelled`.
  - `created_at` (string (date-time), required)
  - `updated_at` (string (date-time), required)
- `next_cursor` (string or null, required) — Pass as `cursor` to get the next page; null means this is the last page.

Other responses:

- 401 (Problem) — unauthenticated — no key, or an unknown, revoked or expired one.
- 403 (Problem) — insufficient-scope — the key lacks a required scope.
- 404 (Problem) — not-found.
- 422 (Problem) — validation — a bad filter, `sort`, `limit` or `cursor` (`errors[].path` names it).
- 429 (Problem) — rate-limited — the key's request budget is spent; wait Retry-After seconds.
- 500 (Problem) — internal.

#### GET /api/v1/delivery-requirements/{id}

Get one delivery requirement

One requirement, in the list's shape. 404 when the org does not have delivery, and for an OAuth token whose person may not read it.

Scopes: `delivery:read`

Parameters:

- `id` (path, string (uuid), required) — The requirement's id, from GET /api/v1/delivery-requirements.
- `If-None-Match` (header, string) — An ETag from a previous response; 304 if unchanged.

Response 200 — `DeliveryRequirement`: A standing demand: content in a project's subtree must meet a spec profile, for a client, delivered to a target.

- `id` (string (uuid), required)
- `project` (object, required) — The project the requirement covers, with every sub-project under it.
  - `id` (string (uuid), required)
  - `name` (string, required)
- `client` (string or null, required) — Who the content is owed to; null for an internal demand (a house standard).
- `target` (object or null, required) — The delivery target the obligation is delivered to (GET /api/v1/delivery-targets); null for an internal demand or when the target is gone.
  - `id` (string (uuid), required)
  - `name` (string, required)
- `spec_profile` (SpecProfileRef or null, required) — The spec revision the content must meet, pinned when the requirement was made.
  - `id` (string (uuid), required)
  - `name` (string, required)
  - `revision` (integer, required) — The spec's revision: a published spec changes only by a new revision, which supersedes this one.
- `status` ("active" | "fulfilled" | "cancelled", required) — `active` — in force (readiness and the spec gate apply it); `fulfilled`; `cancelled`.
- `created_at` (string (date-time), required)
- `updated_at` (string (date-time), required)

Other responses:

- 304 — Not modified — the ETag in If-None-Match is current.
- 401 (Problem) — unauthenticated — no key, or an unknown, revoked or expired one.
- 403 (Problem) — insufficient-scope — the key lacks a required scope.
- 404 (Problem) — not-found.
- 429 (Problem) — rate-limited — the key's request budget is spent; wait Retry-After seconds.
- 500 (Problem) — internal.

#### GET /api/v1/delivery-requirements/{id}/readiness

Read a requirement's readiness

Every asset in the requirement's project subtree (current versions, by asset id) against its pinned spec — the app's readiness matrix for this requirement, a page of assets at a time. A passing verdict on any of an asset's files counts (a conformed rendition). Reading it is a demand: for an ACTIVE requirement, an asset's current deliverable file that has no verdict for the spec yet is evaluated now (and stored), as the app does; a fulfilled or cancelled requirement is served from stored verdicts only. 404 when the org does not have delivery, and for an OAuth token whose person may not read it.

Scopes: `delivery:read`

Parameters:

- `id` (path, string (uuid), required) — The requirement's id, from GET /api/v1/delivery-requirements.
- `limit` (query, integer) — Assets per page, default 50. Values above 100 are treated as 100.
- `cursor` (query, string) — next_cursor from the previous page.

Response 200 — `DeliveryReadiness`: Every asset in the requirement's project subtree against its spec, as the app's readiness matrix shows it.

- `requirement` (DeliveryRequirement, required) — A standing demand: content in a project's subtree must meet a spec profile, for a client, delivered to a target.
  - `id` (string (uuid), required)
  - `project` (object, required) — The project the requirement covers, with every sub-project under it.
    - `id` (string (uuid), required)
    - `name` (string, required)
  - `client` (string or null, required) — Who the content is owed to; null for an internal demand (a house standard).
  - `target` (object or null, required) — The delivery target the obligation is delivered to (GET /api/v1/delivery-targets); null for an internal demand or when the target is gone.
    - `id` (string (uuid), required)
    - `name` (string, required)
  - `spec_profile` (SpecProfileRef or null, required) — The spec revision the content must meet, pinned when the requirement was made.
    - `id` (string (uuid), required)
    - `name` (string, required)
    - `revision` (integer, required) — The spec's revision: a published spec changes only by a new revision, which supersedes this one.
  - `status` ("active" | "fulfilled" | "cancelled", required) — `active` — in force (readiness and the spec gate apply it); `fulfilled`; `cancelled`.
  - `created_at` (string (date-time), required)
  - `updated_at` (string (date-time), required)
- `assets` (array of ReadinessEntry, required) — By asset id. Paginated: an asset's verdict is computed for the page that lists it.
  - `asset` (object, required) — An asset in the requirement's project subtree (its current version).
    - `id` (string (uuid), required)
    - `name` (string, required)
  - `status` ("passed" | "failed" | "indeterminate" | "pending", required) — `passed` — a file of the asset meets the spec (a conformed rendition counts); `failed` — measured and out of spec; `indeterminate` — measured, no failure, but a demanded value could not be measured; `pending` — nothing to judge yet (no deliverable file, not yet measured, or a conform in flight).
  - `cell` (object, required)
    - `failures` (array of ReadinessFailure, required) — Why the asset fails the spec; empty unless `failed`.
      - `field` (string, required) — The spec field the file fails, as the validator names it (e.g. `frame_rate`, `loudness`).
      - `reason` (string, required) — What was measured and what the spec requires, in words.
      - `code` (string, required) — A stable code, e.g. `CONFORMANCE_FRAME_RATE`.
      - `severity` ("error" | "warning", required)
      - `correctability` ("correct" | "transcode" | "reject", required) — `correct` — fixable in place; `transcode` — fixable by a conform transcode; `reject` — needs a new upload.
    - `file` (object or null, required) — The file the verdict is about ({ id, name: its filename }); null when the asset has no deliverable file.
      - `id` (string (uuid), required)
      - `name` (string, required)
- `next_cursor` (string or null, required) — Pass as `cursor` to get the next page of assets; null means this is the last page.

Other responses:

- 401 (Problem) — unauthenticated — no key, or an unknown, revoked or expired one.
- 403 (Problem) — insufficient-scope — the key lacks a required scope.
- 404 (Problem) — not-found.
- 422 (Problem) — validation — a bad `limit` or `cursor`.
- 429 (Problem) — rate-limited — the key's request budget is spent; wait Retry-After seconds.
- 500 (Problem) — internal.

#### GET /api/v1/delivery-requirements/{id}/receipts

List a requirement's receipts

GET /delivery-receipts pre-filtered to the requirement (404 for an unknown one). 404 when the org does not have delivery, and for an OAuth token whose person may not read it.

Scopes: `delivery:read`

Parameters:

- `id` (path, string (uuid), required) — The requirement's id, from GET /api/v1/delivery-requirements.
- `asset_id` (query, string (uuid)) — Only deliveries of this asset: any version's id or its root id matches every version's receipts.
- `status` (query, "pending" | "delivered" | "failed" | "rejected") — Only receipts with this status.
- `created_after` (query, string (date-time)) — Only receipts created strictly after this instant (ISO 8601 with offset), compared to the millisecond.
- `limit` (query, integer) — Page size, default 50. Values above 100 are treated as 100.
- `cursor` (query, string) — next_cursor from the previous page, with the other parameters unchanged.

Response 200 — `DeliveryReceiptList`

- `data` (array of DeliveryReceipt, required) — Newest first (by `created_at`, then id).
  - `id` (string (uuid), required)
  - `requirement` (object or null, required) — The requirement the delivery fulfils ({ id, name: its client, or `Internal` for an internal demand }); null for a social delivery or when the requirement is gone.
    - `id` (string (uuid), required)
    - `name` (string, required)
  - `asset` (object or null, required) — The asset delivered, by its root id (GET /api/v1/assets/{id} takes it); `name` is the delivered version's. Null when the asset is deleted (soft or hard).
    - `id` (string (uuid), required)
    - `name` (string, required)
  - `file` (object or null, required) — The file delivered ({ id, name: its filename }); null when not recorded.
    - `id` (string (uuid), required)
    - `name` (string, required)
  - `target` (object or null, required) — The delivery target; null for a social delivery or when the target is gone.
    - `id` (string (uuid), required)
    - `name` (string, required)
  - `spec_profile` (SpecProfileRef or null, required) — The spec revision the delivery was made against.
    - `id` (string (uuid), required)
    - `name` (string, required)
    - `revision` (integer, required) — The spec's revision: a published spec changes only by a new revision, which supersedes this one.
  - `client` (string, required) — Who it was delivered to (kept when the requirement is gone).
  - `status` ("pending" | "delivered" | "failed" | "rejected", required) — `pending` — in flight; `delivered`; `failed` (see `error`); `rejected` — the receiving org refused it (see `rejection_note`).
  - `error` (string or null, required)
  - `rejection_note` (string or null, required) — Why the receiving org rejected the delivery.
  - `attestation` (object or null, required) — For a delivery to another org on the platform: what the supplier attested. Null otherwise.
    - `verdict` (string, required) — The supplier's conformance verdict on the file at delivery time (`ready` or `conformed`).
    - `sha256` (string or null, required) — The delivered file's SHA-256 (lowercase hex) as it landed; null until it has.
  - `created_at` (string (date-time), required)
  - `delivered_at` (string (date-time) or null, required)
- `next_cursor` (string or null, required) — Pass as `cursor` to get the next page; null means this is the last page.

Other responses:

- 401 (Problem) — unauthenticated — no key, or an unknown, revoked or expired one.
- 403 (Problem) — insufficient-scope — the key lacks a required scope.
- 404 (Problem) — not-found.
- 422 (Problem) — validation — a bad filter, `limit` or `cursor` (`errors[].path` names it).
- 429 (Problem) — rate-limited — the key's request budget is spent; wait Retry-After seconds.
- 500 (Problem) — internal.

#### POST /api/v1/delivery-requirements/{id}/deliver

Deliver an asset against a requirement (guarded)

A guarded action (ADR 0081): it moves content out of the org. The app's own deliver runs: the asset must be one of the org's, a file of it must pass the requirement's spec (`file_id` pins one; otherwise the best, a conformed rendition first), the destination (`target_id`, or the requirement's own) must be able to take it — for another org on the platform, an active supply link and a spec revision it still accepts. Then a Deliver run pushes the file and a receipt is opened in the org's ledger. The same file already in flight to the same destination for the requirement is 409 `delivery-in-flight` (`receipt_id` names it); an asset under legal hold is 409 `legal-hold`. **An API key's delivery starts at once**: 202 with the run and the receipt (poll either). **An OAuth token's does not**: 202 with a Confirmation naming the asset, the destination and the spec revision; once its person confirms it in impartire the delivery starts as them, and the confirmation's `result` is the Delivery. Its person needs the deliver permission in the org (asked first: 403 for any requirement id without it) and read on the asset. Audited: the receipt's capture and a `delivery.requested` event.

Scopes: `delivery:write`

Parameters:

- `id` (path, string (uuid), required) — The requirement's id, from GET /api/v1/delivery-requirements.
- `Idempotency-Key` (header, string) — Makes a retry safe: the same key and request within 24 hours replays the first response. 1–255 characters.

Request body — `DeliverRequest`

- `asset_id` (string (uuid), required) — The asset to deliver: its current version's id or its root id (the current version is delivered). It must be in the requirement's org; for an OAuth token, one its person may read.
- `target_id` (string (uuid)) — Where to deliver it (GET /api/v1/delivery-targets). Omit to deliver to the requirement's own target.
- `file_id` (string (uuid)) — The file to deliver: one of the asset's files whose verdict for the requirement's spec passes (GET /api/v1/delivery-requirements/{id}/readiness names it). Omit for the best passing file, a conformed rendition first.

Response 202 — `Delivery`: A delivery that has started: `run` is the Deliver run that pushes the file (poll GET /api/v1/runs/{id} until its `status` leaves `active`), `receipt` its row in the org's ledger, `pending` until the push lands (`delivered`) or fails (`failed`) — re-read GET /api/v1/delivery-receipts/{id}.

- `run` (Run, required) — A workflow run on an asset — one the API started, a person started in the app, or an upload set off.
  - `id` (string (uuid), required)
  - `workflow` (object, required) — The template version the run is pinned to (any version's id names its template in GET /api/v1/workflows/{id}). `name` is null when the run is `private`.
    - `id` (string (uuid), required)
    - `name` (string or null, required)
  - `asset` (object, required) — The asset the run is about. `name` is null for an OAuth token whose person can no longer read the asset (a run they started).
    - `id` (string (uuid), required)
    - `name` (string or null, required)
  - `status` ("active" | "completed" | "cancelled" | "failed", required)
  - `private` (boolean, required) — True when the run's template is private to a team the token's person is not in: the run's existence, status, team and times are shown, its workflow name, steps, current step, incident and params are not (always false for an API key).
  - `team` (object or null, required) — The team that owns the run, snapshotted from its template at start; null for an unowned run.
    - `id` (string (uuid), required)
    - `name` (string, required)
  - `parent_run_id` (string (uuid) or null, required) — For a sub-workflow run, the run that started it.
  - `started_at` (string (date-time), required)
  - `updated_at` (string (date-time), required) — Moves on every change of state — poll on it with GET /api/v1/runs?updated_after=.
  - `completed_at` (string (date-time) or null, required)
  - `started_via` (string, required) — api (started through this API) | manual (in the app) | trigger (by an arrival trigger, e.g. an upload). More may be added.
  - `current_step` (object or null, required) — The first open step at the run's current gate, while the run is active; null otherwise.
    - `id` (string (uuid), required)
    - `name` (string, required)
    - `status` (string, required)
    - `awaiting` ("approval" | "completion" | "automation" or null, required) — What the step waits on: `approval` (a person's verdict), `completion` (a person marking it done), `automation` (the pipeline — an automated step, a gate or a sub-workflow); null while it is parked on an incident.
  - `steps` (array of RunStep, required)
    - `id` (string (uuid), required) — The template step's id (of the template version the run is pinned to).
    - `name` (string, required)
    - `status` (string, required) — pending | in_progress | submitted | approved | completed | failed | skipped | incident (more may be added).
  - `incident` (object or null, required) — Set while an active run is parked on a step that failed and waits for an operator to retry it or fail the run (in the app).
    - `message` (string, required)
  - `params` (object (any keys) or null, required) — The run's launch parameters, as validated against the template's param_schema.
- `receipt` (DeliveryReceipt, required) — One delivery attempt in the org's ledger. Append-only: a redelivery is a new receipt.
  - `id` (string (uuid), required)
  - `requirement` (object or null, required) — The requirement the delivery fulfils ({ id, name: its client, or `Internal` for an internal demand }); null for a social delivery or when the requirement is gone.
    - `id` (string (uuid), required)
    - `name` (string, required)
  - `asset` (object or null, required) — The asset delivered, by its root id (GET /api/v1/assets/{id} takes it); `name` is the delivered version's. Null when the asset is deleted (soft or hard).
    - `id` (string (uuid), required)
    - `name` (string, required)
  - `file` (object or null, required) — The file delivered ({ id, name: its filename }); null when not recorded.
    - `id` (string (uuid), required)
    - `name` (string, required)
  - `target` (object or null, required) — The delivery target; null for a social delivery or when the target is gone.
    - `id` (string (uuid), required)
    - `name` (string, required)
  - `spec_profile` (SpecProfileRef or null, required) — The spec revision the delivery was made against.
    - `id` (string (uuid), required)
    - `name` (string, required)
    - `revision` (integer, required) — The spec's revision: a published spec changes only by a new revision, which supersedes this one.
  - `client` (string, required) — Who it was delivered to (kept when the requirement is gone).
  - `status` ("pending" | "delivered" | "failed" | "rejected", required) — `pending` — in flight; `delivered`; `failed` (see `error`); `rejected` — the receiving org refused it (see `rejection_note`).
  - `error` (string or null, required)
  - `rejection_note` (string or null, required) — Why the receiving org rejected the delivery.
  - `attestation` (object or null, required) — For a delivery to another org on the platform: what the supplier attested. Null otherwise.
    - `verdict` (string, required) — The supplier's conformance verdict on the file at delivery time (`ready` or `conformed`).
    - `sha256` (string or null, required) — The delivered file's SHA-256 (lowercase hex) as it landed; null until it has.
  - `created_at` (string (date-time), required)
  - `delivered_at` (string (date-time) or null, required)

Other responses:

- 401 (Problem) — unauthenticated — no key, or an unknown, revoked or expired one.
- 403 (Problem) — insufficient-scope, or insufficient-permission — the token's person may not deliver in the org.
- 404 (Problem) — not-found — the org does not have delivery, or the requirement is not one of the org's.
- 409 (Problem) — delivery-in-flight (`receipt_id` and `run_id` name it); legal-hold; conflict — the requirement is not active, no file passes its spec, the destination is not ready or will not accept it; confirmation-pending; or idempotency-in-flight.
- 422 (Problem) — unknown-asset, validation (a bad field, or `target_id` not a target of the org), or idempotency-mismatch (an OAuth token may not send Idempotency-Key).
- 429 (Problem) — rate-limited — the key's request budget is spent; wait Retry-After seconds.
- 500 (Problem) — internal.
- 502 (Problem) — orchestration-unavailable — the delivery run did not start; nothing was delivered.