API reference

Delivery receipts

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-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_idquery · string (uuid)
Only deliveries of this asset: any version's id or its root id matches every version's receipts.
requirement_idquery · string (uuid)
Only deliveries made for this requirement.
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.

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

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

Response 200DeliveryReceipt

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

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.

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

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

Request bodyRejectDeliveryRequest

rejection_notestringrequired
Why your org refuses the delivery. Required: the supplier reads it on their receipt.

Response 200InboundDelivery

A delivery another org made to yours through a supply link (the receiver's view of its receipt).

idstring (uuid)required
supplier_orgobjectrequired
The org that delivered.
- idstring (uuid)required
- namestringrequired
asset_namestring or nullrequired
The supplier's asset name.
spec_profileSpecProfileRef or nullrequired
Your spec revision it was delivered against.
- idstring (uuid)required
- namestringrequired
- revisionintegerrequired
  The spec's revision: a published spec changes only by a new revision, which supersedes this one.
status"pending" | "delivered" | "failed" | "rejected"required
receivedobject or nullrequired
Where the delivery landed in your org; null until it has.
- asset_idstring (uuid) or nullrequired
  Your asset the delivery landed as (GET /api/v1/assets/{id}).
- file_idstring (uuid) or nullrequired
  The landed primary file.
- sha256string or nullrequired
  The landed primary file's SHA-256 (lowercase hex).
- landed_atstring or nullrequired
  When it landed (ISO 8601).
- redeliverybooleanrequired
  True when it landed as a new version of an asset an earlier delivery landed.
rejection_notestring or nullrequired
Why you rejected it, when you did.
errorstring or nullrequired
created_atstring (date-time)required
delivered_atstring (date-time) or nullrequired

Response 202Confirmation

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.

idstring (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).
actionstringrequired
The guarded action, e.g. run.signal.
resourceobjectrequired
- typestringrequired
  The kind of resource the action is on, e.g. run.
- idstring (uuid) or nullrequired
- namestringrequired
  The resource as the person was shown it when the action was asked for.
summarystringrequired
The action in words, as the person reads it on the confirmation page.
client_idstringrequired
The OAuth client that asked.
confirm_urlstringrequired
Where the person confirms or declines it. Show it to them; the API cannot confirm.
created_atstring (date-time)required
expires_atstring (date-time)required
15 minutes after it was asked for. A pending confirmation past it is expired.
decided_atstring (date-time) or nullrequired
When the person confirmed or declined it, or when it expired; null while pending.
resultanyrequired
When executed and the action succeeded: the action's answer (what the endpoint would have returned with a key). Null otherwise.
problemProblem or nullrequired
When executed and the action failed: the Problem it failed with. Null otherwise.
- typestringrequired
  A stable URL naming the problem: https://impartire.com/problems/<code>. Branch on this.
- titlestringrequired
- statusintegerrequired
- detailstringrequired
  What went wrong and what to do about it, written for the caller.
- instancestringrequired
  The request path.
- request_idstringrequired
  Also sent as the Request-Id header. Quote it when reporting a problem.
- errorsarray of object
  On 422 validation: one entry per invalid field.
  - pathstringrequired
    The field or parameter, as a dotted path.
  - messagestringrequired
- edit_seqinteger
  On 412 precondition-failed: the resource's current edit_seq.
- etagstring
  On 412 precondition-failed for a project, a collection, a playlist or a schedule slot: its current ETag.
- item_idstring
  On 409 already-member: the existing item's id (in the collection or playlist).
- schema_versioninteger
  On 409 type-changed: the asset type's current schema_version.
- confirmation_idstring
  On 409 confirmation-pending: the confirmation already waiting for its person (GET /api/v1/confirmations/{id}).
- confirm_urlstring
  On 409 confirmation-pending: where the person confirms or declines it, in impartire.

Other responses

401 unauthenticated — no key, or an unknown, revoked or expired one.
403 insufficient-scope, or insufficient-permission — the token's person is not an org admin.
404 not-found.
409 conflict — the delivery is not delivered; confirmation-pending; or idempotency-in-flight.
422 validation (rejection_note missing or empty), or idempotency-mismatch.
429 rate-limited — the key's request budget is spent; wait Retry-After seconds.
500 internal.