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, building monitoring tooling, or working with the PoLI authority access system.

What the Traceable API covers​

Traceable exposes a public HTTP API that supports three 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 requests (PoLI) The Person of Legal Interest (PoLI) system enables market surveillance authorities, customs bodies, and other entities with a legal right under EU Battery Regulation 2023/1542 to request access to restricted DPP fields that are not publicly visible. This surface requires authentication via an API key.

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

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)
  • 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 admin APIs — endpoints used by the Traceable platform itself (product creation, user management, document upload) are not documented here and are not intended for third-party use
  • 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
  • Webhook integrations — not currently available; contact support if you have a use case

API versioning policy​

The Traceable API is currently at version 1. There is no /v1/ path prefix — the current version is served at the root path.

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 external developers. Test integrations against production with low-volume requests.

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.