API reference

Delivery requirements and readiness

Every path is under https://impartire.com/api/v1. Generated from the API’s own contract, openapi.json (OpenAPI 3.1), which you can load into any OpenAPI tool. Errors are Problems — see Conventions.

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_idquery · string (uuid)
Only the requirements bound to this project (not its ancestors' or descendants').
statusquery · "active" | "fulfilled" | "cancelled"
Only requirements with this status.
updated_afterquery · string (date-time)
Only requirements changed strictly after this instant (ISO 8601 with offset), compared to the millisecond.
sortquery · "-updated_at" | "updated_at" | "created_at"
Sort key; a leading - is descending. Default -updated_at. Ties break on id.
limitquery · integer
Page size, default 50. Values above 100 are treated as 100.
cursorquery · string
next_cursor from the previous page, with the other parameters unchanged.

Response 200DeliveryRequirementList

dataarray of DeliveryRequirementrequired
In the requested sort (default -updated_at), ties broken by id.
- idstring (uuid)required
- projectobjectrequired
  The project the requirement covers, with every sub-project under it.
  - idstring (uuid)required
  - namestringrequired
- clientstring or nullrequired
  Who the content is owed to; null for an internal demand (a house standard).
- targetobject or nullrequired
  The delivery target the obligation is delivered to (GET /api/v1/delivery-targets); null for an internal demand or when the target is gone.
  - idstring (uuid)required
  - namestringrequired
- spec_profileSpecProfileRef or nullrequired
  The spec revision the content must meet, pinned when the requirement was made.
  - idstring (uuid)required
  - namestringrequired
  - revisionintegerrequired
    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_atstring (date-time)required
- updated_atstring (date-time)required
next_cursorstring or nullrequired
Pass as cursor to get the next page; null means this is the last page.

Other responses

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

idpath · string (uuid)required
The requirement's id, from GET /api/v1/delivery-requirements.
If-None-Matchheader · string
An ETag from a previous response; 304 if unchanged.

Response 200DeliveryRequirement

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

idstring (uuid)required
projectobjectrequired
The project the requirement covers, with every sub-project under it.
- idstring (uuid)required
- namestringrequired
clientstring or nullrequired
Who the content is owed to; null for an internal demand (a house standard).
targetobject or nullrequired
The delivery target the obligation is delivered to (GET /api/v1/delivery-targets); null for an internal demand or when the target is gone.
- idstring (uuid)required
- namestringrequired
spec_profileSpecProfileRef or nullrequired
The spec revision the content must meet, pinned when the requirement was made.
- idstring (uuid)required
- namestringrequired
- revisionintegerrequired
  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_atstring (date-time)required
updated_atstring (date-time)required

Other responses

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

idpath · string (uuid)required
The requirement's id, from GET /api/v1/delivery-requirements.
limitquery · integer
Assets per page, default 50. Values above 100 are treated as 100.
cursorquery · string
next_cursor from the previous page.

Response 200DeliveryReadiness

Every asset in the requirement's project subtree against its spec, as the app's readiness matrix shows it.

requirementDeliveryRequirementrequired
A standing demand: content in a project's subtree must meet a spec profile, for a client, delivered to a target.
- idstring (uuid)required
- projectobjectrequired
  The project the requirement covers, with every sub-project under it.
  - idstring (uuid)required
  - namestringrequired
- clientstring or nullrequired
  Who the content is owed to; null for an internal demand (a house standard).
- targetobject or nullrequired
  The delivery target the obligation is delivered to (GET /api/v1/delivery-targets); null for an internal demand or when the target is gone.
  - idstring (uuid)required
  - namestringrequired
- spec_profileSpecProfileRef or nullrequired
  The spec revision the content must meet, pinned when the requirement was made.
  - idstring (uuid)required
  - namestringrequired
  - revisionintegerrequired
    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_atstring (date-time)required
- updated_atstring (date-time)required
assetsarray of ReadinessEntryrequired
By asset id. Paginated: an asset's verdict is computed for the page that lists it.
- assetobjectrequired
  An asset in the requirement's project subtree (its current version).
  - idstring (uuid)required
  - namestringrequired
- 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).
- cellobjectrequired
  - failuresarray of ReadinessFailurerequired
    Why the asset fails the spec; empty unless failed.
    - fieldstringrequired
      The spec field the file fails, as the validator names it (e.g. frame_rate, loudness).
    - reasonstringrequired
      What was measured and what the spec requires, in words.
    - codestringrequired
      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.
  - fileobject or nullrequired
    The file the verdict is about ({ id, name: its filename }); null when the asset has no deliverable file.
    - idstring (uuid)required
    - namestringrequired
next_cursorstring or nullrequired
Pass as cursor to get the next page of assets; null means this is the last page.

Other responses

401 unauthenticated — no key, or an unknown, revoked or expired one.
403 insufficient-scope — the key lacks a required scope.
404 not-found.
422 validation — a bad limit or cursor.
429 rate-limited — the key's request budget is spent; wait Retry-After seconds.
500 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

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

Response 200DeliveryReceiptList

dataarray of DeliveryReceiptrequired
Newest first (by created_at, then id).
- idstring (uuid)required
- requirementobject or nullrequired
  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.
  - idstring (uuid)required
  - namestringrequired
- assetobject or nullrequired
  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).
  - idstring (uuid)required
  - namestringrequired
- fileobject or nullrequired
  The file delivered ({ id, name: its filename }); null when not recorded.
  - idstring (uuid)required
  - namestringrequired
- targetobject or nullrequired
  The delivery target; null for a social delivery or when the target is gone.
  - idstring (uuid)required
  - namestringrequired
- spec_profileSpecProfileRef or nullrequired
  The spec revision the delivery was made against.
  - idstring (uuid)required
  - namestringrequired
  - revisionintegerrequired
    The spec's revision: a published spec changes only by a new revision, which supersedes this one.
- clientstringrequired
  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).
- errorstring or nullrequired
- rejection_notestring or nullrequired
  Why the receiving org rejected the delivery.
- attestationobject or nullrequired
  For a delivery to another org on the platform: what the supplier attested. Null otherwise.
  - verdictstringrequired
    The supplier's conformance verdict on the file at delivery time (ready or conformed).
  - sha256string or nullrequired
    The delivered file's SHA-256 (lowercase hex) as it landed; null until it has.
- created_atstring (date-time)required
- delivered_atstring (date-time) or nullrequired
next_cursorstring or nullrequired
Pass as cursor to get the next page; null means this is the last page.

Other responses

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

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

Request bodyDeliverRequest

asset_idstring (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_idstring (uuid)
Where to deliver it (GET /api/v1/delivery-targets). Omit to deliver to the requirement's own target.
file_idstring (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 202Delivery

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}.

runRunrequired
A workflow run on an asset — one the API started, a person started in the app, or an upload set off.
- idstring (uuid)required
- workflowobjectrequired
  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.
  - idstring (uuid)required
  - namestring or nullrequired
- assetobjectrequired
  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).
  - idstring (uuid)required
  - namestring or nullrequired
- status"active" | "completed" | "cancelled" | "failed"required
- privatebooleanrequired
  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).
- teamobject or nullrequired
  The team that owns the run, snapshotted from its template at start; null for an unowned run.
  - idstring (uuid)required
  - namestringrequired
- parent_run_idstring (uuid) or nullrequired
  For a sub-workflow run, the run that started it.
- started_atstring (date-time)required
- updated_atstring (date-time)required
  Moves on every change of state — poll on it with GET /api/v1/runs?updated_after=.
- completed_atstring (date-time) or nullrequired
- started_viastringrequired
  api (started through this API) | manual (in the app) | trigger (by an arrival trigger, e.g. an upload). More may be added.
- current_stepobject or nullrequired
  The first open step at the run's current gate, while the run is active; null otherwise.
  - idstring (uuid)required
  - namestringrequired
  - statusstringrequired
  - awaiting"approval" | "completion" | "automation" or nullrequired
    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.
- stepsarray of RunSteprequired
  - idstring (uuid)required
    The template step's id (of the template version the run is pinned to).
  - namestringrequired
  - statusstringrequired
    pending | in_progress | submitted | approved | completed | failed | skipped | incident (more may be added).
- incidentobject or nullrequired
  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).
  - messagestringrequired
- paramsobject (any keys) or nullrequired
  The run's launch parameters, as validated against the template's param_schema.
receiptDeliveryReceiptrequired
One delivery attempt in the org's ledger. Append-only: a redelivery is a new receipt.
- idstring (uuid)required
- requirementobject or nullrequired
  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.
  - idstring (uuid)required
  - namestringrequired
- assetobject or nullrequired
  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).
  - idstring (uuid)required
  - namestringrequired
- fileobject or nullrequired
  The file delivered ({ id, name: its filename }); null when not recorded.
  - idstring (uuid)required
  - namestringrequired
- targetobject or nullrequired
  The delivery target; null for a social delivery or when the target is gone.
  - idstring (uuid)required
  - namestringrequired
- spec_profileSpecProfileRef or nullrequired
  The spec revision the delivery was made against.
  - idstring (uuid)required
  - namestringrequired
  - revisionintegerrequired
    The spec's revision: a published spec changes only by a new revision, which supersedes this one.
- clientstringrequired
  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).
- errorstring or nullrequired
- rejection_notestring or nullrequired
  Why the receiving org rejected the delivery.
- attestationobject or nullrequired
  For a delivery to another org on the platform: what the supplier attested. Null otherwise.
  - verdictstringrequired
    The supplier's conformance verdict on the file at delivery time (ready or conformed).
  - sha256string or nullrequired
    The delivered file's SHA-256 (lowercase hex) as it landed; null until it has.
- created_atstring (date-time)required
- delivered_atstring (date-time) or nullrequired

Other responses

401 unauthenticated — no key, or an unknown, revoked or expired one.
403 insufficient-scope, or insufficient-permission — the token's person may not deliver in the org.
404 not-found — the org does not have delivery, or the requirement is not one of the org's.
409 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 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 rate-limited — the key's request budget is spent; wait Retry-After seconds.
500 internal.
502 orchestration-unavailable — the delivery run did not start; nothing was delivered.