Developer guide

Welcome to the Traceable Developer Guide. This guide covers everything you need to integrate with the Traceable platform as a software engineer, whether you are consuming Digital Product Passport (DPP) data, authoring DPPs from an ERP system, building monitoring tooling, or working with the PoLI authority access system.

What the Traceable API covers

Traceable exposes a public HTTP API that supports four primary integration surfaces:

Public DPP data access Read published Digital Product Passport data for battery products. These endpoints are unauthenticated and designed for broad consumption. QR code scanners, compliance portals, supply chain tooling, and public registries all use this surface. Data is returned as structured JSON or as JSON-LD for semantic web use cases.

Authority access (PoLI) The Person of Legal Interest (PoLI) system lets market surveillance authorities, customs bodies, and other entities with a legal right under EU Battery Regulation 2023/1542 obtain access to restricted DPP fields that are not publicly visible. This is a human-reviewed web flow, not a keyed API: access is requested from the DPP page, confirmed by email, and approved by the manufacturer. See PoLI access.

Health monitoring A health check endpoint suitable for uptime monitors, Kubernetes probes, and CI/CD post-deploy verification. No authentication required.

Integration API A headless authoring API for ERP, PLM, and manufacturing execution systems. Lets software create DPP drafts, populate fields, attach evidence documents, and submit for human review, all over HTTP without using the Traceable portal. It is available on production; an environment where it is not enabled returns 503 FEATURE_DISABLED. See Integration API.

Who this guide is for

This guide is written for:

• Software engineers integrating third-party systems with Traceable DPP data (ERP systems, compliance portals, procurement platforms)
• ERP and PLM integration engineers using the Integration API to automate DPP authoring from systems such as Odoo, SAP, or custom manufacturing platforms
• Tool builders consuming DPP data programmatically (QR scanner apps, public registries, regulatory dashboards)
• DevOps and platform engineers setting up health monitoring, alerting, and post-deploy verification for systems that depend on Traceable
• Regulatory integration teams at market surveillance authorities implementing PoLI access workflows
• Technical architects evaluating Traceable for data integration, assessing the data model and API surface

What this guide does NOT cover

This guide documents the external-facing API only. The following are out of scope:

• Internal platform APIs: endpoints used for user management, internal platform operations, and account administration are not documented here and are not intended for third-party use. Product creation, field updates, document upload, and DPP submission via the headless authoring path are covered by the Integration API.
• Supabase direct access: Traceable's PostgreSQL database is not directly accessible; all data access is through the HTTP API
• Platform configuration: onboarding, portal setup, product registration, and compliance workflow configuration are covered in the User Guide
• Inbound BMS ingestion is a separate capability from outbound webhooks. Outbound webhooks (where Traceable pushes events to your system) are part of the Integration API, under the webhook:read and webhook:write scopes; see the Integration API. The BMS ingestion endpoint is inbound (you POST data to Traceable); see BMS Endpoints.

API versioning policy

The Traceable API is currently at version 1. The public DPP, PoLI, and health endpoints are served at the root path (no /v1/ path prefix).

Endpoints with a /v1/ path prefix:

• The BMS telemetry ingestion endpoint at /api/v1/products/{id}/bms-update
• All Integration API endpoints at /api/v1/products/..., see Integration API

API version vs platform version

The API version (currently v1) and the Traceable platform version are separate numbering schemes. The API version tracks the stability of the external integration surface; the platform version reflects internal product releases. A platform version increment does not imply an API version increment, and vice versa. The 6-month deprecation notice period described below begins from the date a specific breaking change is announced, not from the original publication date of this documentation.

Breaking changes (removing fields, changing field types, changing response structure) will be announced with a minimum 6-month deprecation notice via the developer changelog and email notification to registered API key holders. The deprecated version will continue to function for the full deprecation period.

Non-breaking additions (new optional fields, new endpoints, new optional query parameters) are made without a versioning event and may appear at any time. Your integration should be tolerant of additional fields in JSON responses.

Versioning events will be communicated via:

• Email to the address associated with your Traceable operator account
• The Traceable Status Page
• This documentation site

Base URL

All API requests are made to:

https://app.traceable.digital

Public passports are served from https://dpp.traceable.digital; see DPP endpoints.

There is no staging base URL available for the public DPP, PoLI, or health endpoints. Test those integrations against production with low-volume requests.

Integration API: sandbox testing uses the same base URL as live traffic. The mode is a property of the API key: use a pk_test_ key against https://app.traceable.digital. See Sandbox.

Transport security

All requests must use HTTPS. HTTP requests are not accepted and will not be redirected; they will be rejected. TLS 1.2 is the minimum supported version; TLS 1.3 is preferred.

Rate limiting

Sign-in, sign-up and one-time code requests are rate limited. Public endpoints are limited per IP address; most authenticated Integration API endpoints are limited per API key (three product read endpoints are not counted per key). See the Rate Limiting page for current limits, response headers, and recommended backoff strategies.