# impartire API — Reference: Delivery receipts

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-receipts

List the org's delivery receipts

The org's delivery ledger, newest first: one receipt per delivery attempt (a redelivery is a new receipt), to a target or to a social platform. A delivery to another org on the platform carries `attestation` (the supplier's verdict and, once landed, the file's SHA-256). Receipts have no `updated_at`; poll new ones with `created_after` and re-read a pending one by id. 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:

- `asset_id` (query, string (uuid)) — Only deliveries of this asset: any version's id or its root id matches every version's receipts.
- `requirement_id` (query, string (uuid)) — Only deliveries made for this requirement.
- `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.

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

Get one delivery receipt

One receipt, 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 receipt's id, from GET /api/v1/delivery-receipts.
- `If-None-Match` (header, string) — An ETag from a previous response; 304 if unchanged.

Response 200 — `DeliveryReceipt`: 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:

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

#### POST /api/v1/delivery-receipts/{id}/reject

Reject a delivery made to the org (guarded)

A guarded action (ADR 0081). The receiving org refuses a delivery another org made to it through a supply link (`{id}` from GET /inbound-deliveries): a `delivered` one becomes `rejected` with `rejection_note`, which the supplier reads on their receipt; the landed asset stays in your intake project. **An API key's rejection happens at once** (200). **An OAuth token's does not**: 202 with a Confirmation naming the asset and the supplier; its person, an org admin, confirms it in impartire. Audited: a `receipt.rejected` event in your org. 404 when the org does not have delivery, and for an OAuth token whose person may not read it. Also 404 when the org does not have supply links.

Scopes: `delivery:write`

Parameters:

- `id` (path, string (uuid), required) — The delivery's id, from GET /api/v1/inbound-deliveries (the supplier's receipt id).
- `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 — `RejectDeliveryRequest`

- `rejection_note` (string, required) — Why your org refuses the delivery. Required: the supplier reads it on their receipt.

Response 200 — `InboundDelivery`: A delivery another org made to yours through a supply link (the receiver's view of its receipt).

- `id` (string (uuid), required)
- `supplier_org` (object, required) — The org that delivered.
  - `id` (string (uuid), required)
  - `name` (string, required)
- `asset_name` (string or null, required) — The supplier's asset name.
- `spec_profile` (SpecProfileRef or null, required) — Your spec revision it was delivered 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.
- `status` ("pending" | "delivered" | "failed" | "rejected", required)
- `received` (object or null, required) — Where the delivery landed in your org; null until it has.
  - `asset_id` (string (uuid) or null, required) — Your asset the delivery landed as (GET /api/v1/assets/{id}).
  - `file_id` (string (uuid) or null, required) — The landed primary file.
  - `sha256` (string or null, required) — The landed primary file's SHA-256 (lowercase hex).
  - `landed_at` (string or null, required) — When it landed (ISO 8601).
  - `redelivery` (boolean, required) — True when it landed as a new version of an asset an earlier delivery landed.
- `rejection_note` (string or null, required) — Why you rejected it, when you did.
- `error` (string or null, required)
- `created_at` (string (date-time), required)
- `delivered_at` (string (date-time) or null, required)

Response 202 — `Confirmation`: A guarded action an OAuth token asked for, waiting for its person to confirm it in impartire (ADR 0081). A guarded endpoint answers 202 with this and a Location; poll it until `status` is executed, declined or expired.

- `id` (string (uuid), required)
- `status` ("pending" | "confirmed" | "declined" | "expired" | "executed", required) — pending: waiting for the person to confirm or decline it in impartire (at `confirm_url`). confirmed: they confirmed and the action is running — poll again. executed: it ran; `result` holds its answer, or `problem` why it failed. declined: they said no; it will never run. expired: nobody decided within 15 minutes; it will never run (GET /api/v1/confirmations/{id} answers 410 confirmation-expired instead of this body; the person still sees it in impartire).
- `action` (string, required) — The guarded action, e.g. `run.signal`.
- `resource` (object, required)
  - `type` (string, required) — The kind of resource the action is on, e.g. `run`.
  - `id` (string (uuid) or null, required)
  - `name` (string, required) — The resource as the person was shown it when the action was asked for.
- `summary` (string, required) — The action in words, as the person reads it on the confirmation page.
- `client_id` (string, required) — The OAuth client that asked.
- `confirm_url` (string, required) — Where the person confirms or declines it. Show it to them; the API cannot confirm.
- `created_at` (string (date-time), required)
- `expires_at` (string (date-time), required) — 15 minutes after it was asked for. A pending confirmation past it is expired.
- `decided_at` (string (date-time) or null, required) — When the person confirmed or declined it, or when it expired; null while pending.
- `result` (any, required) — When executed and the action succeeded: the action's answer (what the endpoint would have returned with a key). Null otherwise.
- `problem` (Problem or null, required) — When executed and the action failed: the Problem it failed with. Null otherwise.
  - `type` (string, required) — A stable URL naming the problem: https://impartire.com/problems/<code>. Branch on this.
  - `title` (string, required)
  - `status` (integer, required)
  - `detail` (string, required) — What went wrong and what to do about it, written for the caller.
  - `instance` (string, required) — The request path.
  - `request_id` (string, required) — Also sent as the Request-Id header. Quote it when reporting a problem.
  - `errors` (array of object) — On 422 validation: one entry per invalid field.
    - `path` (string, required) — The field or parameter, as a dotted path.
    - `message` (string, required)
  - `edit_seq` (integer) — On 412 precondition-failed: the resource's current edit_seq.
  - `etag` (string) — On 412 precondition-failed for a project, a collection, a playlist or a schedule slot: its current ETag.
  - `item_id` (string) — On 409 already-member: the existing item's id (in the collection or playlist).
  - `schema_version` (integer) — On 409 type-changed: the asset type's current schema_version.
  - `confirmation_id` (string) — On 409 confirmation-pending: the confirmation already waiting for its person (GET /api/v1/confirmations/{id}).
  - `confirm_url` (string) — On 409 confirmation-pending: where the person confirms or declines it, in impartire.

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 is not an org admin.
- 404 (Problem) — not-found.
- 409 (Problem) — conflict — the delivery is not `delivered`; confirmation-pending; or idempotency-in-flight.
- 422 (Problem) — validation (`rejection_note` missing or empty), or idempotency-mismatch.
- 429 (Problem) — rate-limited — the key's request budget is spent; wait Retry-After seconds.
- 500 (Problem) — internal.