Integration API

Availability

The full Integration API is GA on production (app.traceable.digital) as of release v0.99.6.1 (2026-07-03). This includes the entire Phase 1.5 surface: the headless authoring wizard, discovery, schema versioning, ERP field mapping, API key management with per-key IP allow-lists, signed webhooks (retried, with a dead-letter queue), and GDPR data-subject endpoints. Every endpoint is behind per-key authentication (default-deny: an unknown or missing key returns 401). Both live (pk_live_*) and sandbox (pk_test_*) keys are supported. See the Availability matrix.

The Traceable Integration API (/api/v1) lets software systems author Digital Product Passports without the Traceable operator portal. An ERP, PLM, or manufacturing system can reproduce the entire operator wizard over HTTP: discover the fields a category requires, write them, check the same readiness numbers the wizard shows, and submit for review.

The headless wizard flow

The defining idea of this API is that an integration can walk the operator wizard end to end:

1. Discover the industries and categories your key is authorized for, then fetch a category's full field schema.
2. Create a draft product and ingest its field data in batches, with fail-closed, per-field validation.
3. Close the publish gates by writing supply-chain traceability, components, and GS1 prefixes, and by attaching evidence documents.
4. Check readiness to get the same completeness and compliance numbers the wizard displays.
5. Submit for review.

A human operator reviews and publishes the DPP in the portal. The API can move a passport from Draft to Submitted and no further. See The wizard flow for the full narrative with endpoints, and Regulatory boundary for why.

The publish firewall

A connected system can create, fill, attach documents to, check the gate of, and submit a DPP, all headless. It can never publish or approve one. Publication is a human act performed by an operator in the Traceable UI, and the published record carries that natural person's attribution under EU Battery Regulation 2023/1542 Article 77. There is no dpp:publish scope and no AI (ai.*) scope, and no endpoint that sets a product to Approved or Published. This is a deliberate compliance design, not a limitation.

What this API does NOT do

• Publish or approve. Every state-changing call terminates at Submitted (or, for withdrawal, at Withdrawn).
• Run AI. There is no AI scope; AI-assisted flows are portal-only.
• Manage users, companies, or plans. Account administration stays in the portal.

Base URLs

Environment	Base URL	Use
Production	https://app.traceable.digital	GA — the full API, live
Staging	https://staging.traceable.digital	Pre-release testing

Live and sandbox are selected by your key type (pk_live_* vs pk_test_*), not by base URL. A sandbox key authors throwaway data and never touches a real passport. See Sandbox mode.

Scopes

Keys carry least-privilege scopes. The grantable vocabulary is thirteen scopes: dpp:read, dpp:draft:write, dpp:gate:read, dpp:submit, dpp:withdraw, document:write, category:read, schema:read, supplier:read, mapping:read, mapping:write, webhook:read, and webhook:write. Two further privileged scopes, keys:admin and gdpr:admin, sit outside the grantable set and are minted only from the Company Portal. There is no publish scope and no AI scope. See Scopes.

Request correlation

Every response carries an X-Traceable-Request-Id header, and the same value appears as requestId in any error envelope. Log it: it links your call to the entry on the Traceable tamper-evident audit trail.

Machine contract

The canonical specification is the OpenAPI 3.1 document integration-v1.yaml, maintained in the platform repository and synced here byte-for-byte. The API reference is rendered from it, and you can download the raw spec. Where the prose pages and the OpenAPI document ever disagree, the OpenAPI document is authoritative.

In this section

• The wizard flow — the headless operator-wizard narrative, step by step
• Authentication — bearer keys, HMAC signing, idempotency, default-deny
• Scopes — the grantable scopes, and the privileged keys:admin / gdpr:admin
• Errors and conventions — error envelope, the code catalog, field-level validation, idempotency, rate limits
• Availability — the per-endpoint GA-versus-staging matrix
• API reference (OpenAPI) — all endpoints rendered from the canonical spec
• Response examples — concrete success responses for every endpoint, verified on staging
• Category schema formats — the ?format=json-schema, csv, and html outputs of the schema endpoint
• Lifecycle quickstart — curl and Node walkthrough, the Odoo example, and the Postman collection
• Regulatory boundary — the publish firewall and what it means for compliance
• Sandbox — how to test on staging
• Roadmap — the rest of Phase 1.5, planned and not yet available