API documentation

Build with the TracePass v1 API

Reference for every public REST endpoint TracePass exposes — passport CRUD, parties, products, webhooks, bulk JSON-LD export. Hand-written OpenAPI 3.1 spec available for download; works with Postman, Insomnia, Bruno, and any OpenAPI client generator.

Download OpenAPI 3.1 JSON mirror →

Before you start

The TracePass v1 REST API is the integration surface every ESPR-bound product team uses to mint, update, and publish Digital Product Passports at scale. It mirrors the data model that the marketing site, the platform UI, and the MCP / n8n integrations all read from — a passport you create via the API is byte-identical to one created in the UI, with the same Regulation (EU) 2024/1781 (ESPR) field coverage and the same GS1 Digital Link QR resolution.

Versioning. Every endpoint sits under /api/v1/…; v1 is a stable surface — we add fields and endpoints without notice, and never remove or rename them. A v2 would ship under /api/v2/… with 12 months of v1 overlap before any deprecation. The OpenAPI 3.1 spec is the canonical reference; this prose is a guide on top of it.

Auth + rate limits. Authenticate with a workspace API key via the Authorization: Bearer <key> header. Daily caps apply only on Free (100 v1 writes / day) and Basic (200 / day) as free-tier abuse prevention; Starter through Enterprise have no daily quota. Idempotency-Key support and 429 retry guidance live on the authentication and errors & rate limits pages.

Quickstart

Create your first passport in five minutes — register, mint an API key, post a single passport, scan the QR.

Browse Quickstart

Authentication

Two auth methods — API key (Bearer) and OAuth 2.0 with PKCE — plus Idempotency-Key for safe retries and per-plan rate limits on the v1 surface.

Browse Authentication

Passports

11 endpoints

Create, update, suspend, archive, and bulk-import Digital Product Passports. Includes the parties block for economic-operator chains.

Browse Passports

Products

7 endpoints

The catalog layer — products, images, batches. One product can have many passports (one per serialised unit).

Browse Products

Templates

2 endpoints

The DPP category field schemas — discover what a compliant passport in each category requires before you build it: field counts and the governing regulation.

Browse Templates

Webhooks

HMAC-signed event delivery for passport lifecycle events. Retry ladder, signature verification, replay protection.

Browse Webhooks

Exports

1 endpoint

Bulk JSON-LD tenant export — every product, passport, and template you own as one canonical document.

Browse Exports

EPCIS 2.0

4 endpoints

GS1 EPCIS 2.0 supply-chain events — export a passport's event history, capture events from partners and ERP systems, and query the event store.

Browse EPCIS 2.0

MCP server

MCP server — AI assistants (Claude, Cursor, IDE agents) manage products, passports, EPCIS events directly. Hosted endpoint or local npm package.

Browse MCP server

n8n community node

Automate TracePass workflows in n8n without code — products, passports, EPCIS events. Free community node, installable from any n8n instance.

Browse n8n community node

Errors & rate limits

Reference: HTTP status codes (4xx vs 5xx), error envelope shape, free-tier daily call caps, and 429 retry guidance with exponential back-off.

Browse Errors & rate limits