Skip to main content

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 (Early Access) 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. Enabled per-customer on request. See Integration API (Early Access).

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 (Early Access) 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 (Early Access) for authorised integration partners.
  • 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
  • Outbound webhook integrations (where Traceable pushes events to your system) — not currently available; contact support if you have a use case. Note: the BMS ingestion endpoint is an inbound API endpoint (you POST data to Traceable) and is a separate capability — 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 (Early Access)
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

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 (Early Access): A staging environment is available for Integration API sandbox testing at https://staging.traceable.digital. See Sandbox for details on requesting sandbox access.

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​

All endpoints are subject to rate limiting enforced at the edge. Public endpoints are limited per IP address; authenticated endpoints are limited per API key. See the Rate Limiting page for current limits, response headers, and recommended backoff strategies.