Passports
Create, update, suspend, archive, and bulk-import Digital Product Passports. Includes the parties block for economic-operator chains.
/api/v1/passportsCreate a passport
Create a single Digital Product Passport. The passport is bound to a product (productId) and identified by a GS1 GTIN + serial number that's unique within that GTIN. New passports start in `draft` status — fields are populated via subsequent PATCH calls and the passport is published from the dashboard once review is complete.
/api/v1/passports/{id}Get a single passport
Read one passport by ID. Default response includes the full passport — translatable fields carry their `sourceLocale` and a per-locale `translations` map. Pass `?lang=<locale>` to have the server resolve every field through the public-viewer chain (viewer-locale translation → source-locale value → English → first-applied → universal source) and return one resolved value per field; the `translations` map is dropped from lang-resolved responses.
/api/v1/passports/{id}/qrRender the passport QR
Returns a freshly-rendered QR code for the passport, encoding its `gs1.digitalLinkUri`. Use this when you want our renderer (consistent quiet zone, error correction, optional branding) instead of encoding the URI yourself. Defaults to `image/svg+xml`; `?format=png` returns a PNG and `?format=json` returns a `{ result: "<svg>" }` wrapper for embedding.
/api/v1/passports/{id}/complianceCheck passport compliance
Returns a three-tier compliance verdict for one passport — `compliant`, `compliant_with_warnings`, or `incomplete` — together with regulation-cited findings, so an integration can gap-check a passport, fix the cited gaps, then call again to confirm. That read → fix → verify loop is the point: the response tells an agent exactly what to set next.
/api/v1/passportsList passports
Paginated list of passports the workspace owns. Filter by `productId`, `status`, or a free-text search across GTIN and serial number. Counts against the daily passport-read budget (`maxV1PassportsPerDay`); the response items use the same shape as the single-read endpoint but trimmed to the listing fields.
/api/v1/passports/{id}/fields/{key}Update one field on a passport
Patch a single field on a passport. The value is validated against the field key (must exist on the passport's template) and persisted with an audit trail entry tagged `via API key <prefix>`. Use this in preference to writing the whole `fields` map when you only need to update one number — it's a smaller write and the per-field audit entry is what dashboard reviewers see.
/api/v1/passports/{id}/parties/{role}Upsert an economic-operator party
Create or replace the Party for a single role on a passport. The role path segment determines the slot you're writing — `manufacturer`, `importer`, `authorisedRepresentative`, `distributor`, `recycler`, `producerResponsibilityOrg`. Sending the same role twice is an upsert: the existing block is replaced atomically.
/api/v1/passports/{id}/suspendSuspend a passport
Reversible suspend. The public viewer flips to the suspended state page (HTTP 423 with structured body); QR scans effectively die without the URL going to 404. Use for recalls, disputes, internal holds, or product-quality investigations. Republish from the dashboard once resolved.
/api/v1/passports/{id}/archiveArchive a passport (irreversible)
**Irreversible.** Public viewer returns 404, the GS1 Digital Link URL stops resolving, the QR code dies for good. Use ONLY for products that never shipped — archiving a passport for a product already in customers' hands breaks every QR scan they'll ever make of it.
/api/v1/passports/{id}Delete a passport permanently
**Permanent and irreversible** — the passport row plus every cascaded dependent is removed from the database. Cascade includes AI extractions, agent-session state, supplier requests linked to this passport alone, scan + service events, and any uploaded documents whose only reference was this passport (documents shared across other passports/products stay). R2 storage under the passport's folder is swept too.
/api/v1/passports/batchBatch-create passports
Create up to 100 passports in one call. Each item carries the same body shape as the single-create endpoint (`{ productId, gs1: { gtin, serialNumber }, parties?, confirmOverage? }`). Partial-success per item — each gets its own status in the response array.