API reference overview

Base URL

The Integration API (/api/v1) and the platform pages are served at:

https://app.traceable.digital

Public passports are served from the passport host:

https://dpp.traceable.digital

Example: to retrieve a DPP, the full URL is https://dpp.traceable.digital/api/dpp/{slug}. When the passport host is active, app.traceable.digital answers /api/dpp/... paths with a 307 redirect to the same path on the passport host, so follow redirects or call the passport host directly.

Response format

The public DPP and health endpoints return Content-Type: application/json, except GET /api/dpp/{slug}/jsonld, which returns application/ld+json. The GS1 Digital Link resolver (/01/...) can return application/ld+json, application/json or application/linkset+json, depending on the Accept header. The Integration API can also return text/csv or text/html from its schema endpoints. JSON is UTF-8 encoded.

HTTP methods

The public DPP and health endpoints use these HTTP methods:

Method	Semantics
GET	Read data. Safe and idempotent. No request body.
OPTIONS	CORS preflight on the public DPP routes. Answers 204 with no body.

The PoLI access form and the BMS ingestion endpoint use POST. The Integration API also uses PUT, PATCH and DELETE; see its own reference.

Error response envelope

Error responses use one of three envelopes, depending on the surface.

Public DPP endpoints use a nested error object with a code and a message:

{
  "error": {
    "code": "PRODUCT_NOT_FOUND",
    "message": "No DPP found for 'swiftvolt-48v-100ah-ev-pack'"
  }
}

Field	Type	Description
error.code	string	A stable machine-readable error identifier. See Error Codes for the full reference.
error.message	string	A human-readable description of the error. Do not parse this string programmatically; use code instead.

The Integration API (/api/v1) uses { "error": { "code", "message", "requestId", ... } }, with any extra context as additional keys inside error (there is no details object). A validation error looks like this:

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Request body failed validation.",
    "requestId": "9b2f1c6e-4a3d-4f0e-8c55-2d7a1e6b9f10",
    "fields": ["productName"]
  }
}

See Integration API: Errors and conventions.

The BMS endpoint uses a flat { "error": "<text>", "code": "<CODE>" } body, with issues added on validation errors. See BMS Endpoints.

The per-IP edge rate limiter answers with { "error": "Too many requests" } and no code. See Rate limiting.

Success response structure

Successful responses return the resource data directly at the top level. There is no wrapper object or envelope. For example, a successful DPP fetch returns:

{
  "productId": "0f6c1c1e-8d3e-4b2a-9c1a-5e2f7a9d4b10",
  "versionId": "1.0",
  "productName": "SwiftVolt 48V 100Ah EV Pack",
  ...
}

Not:

{
  "data": { ... },
  "success": true
}

Pagination

Pagination is not currently used. All DPP endpoints return a complete object for the requested product. There are no list/collection endpoints in the public API.

API versioning

The public DPP, PoLI, and health endpoints described in this section are served at the root path (no /v1/ prefix). See the Introduction for the full versioning and deprecation policy.

Integration API

The Integration API for headless DPP authoring uses the /api/v1/products/... path prefix and has its own authentication model, error envelope, and endpoint reference. See Integration API.

CORS policy

Public DPP endpoints (GET /api/dpp/{slug}, GET /api/dpp/{slug}/jsonld and GET /api/dpp/{slug}/v/{version}) allow requests from any origin:

Access-Control-Allow-Origin: *

This is intentional: DPP data is public by design and must be accessible to browser-based applications and QR scanner web apps.

PoLI access links (GET /api/poli/verify, GET /api/poli/access) are tokenised, single-purpose links delivered by email and opened in a browser. They redirect rather than returning data, and take no Authorization header. See PoLI access.

Request ID header

The public DPP, PoLI and health endpoints return no request identifier. When contacting support about one of them, quote the time of the request and the slug.

Every /api/v1 response includes an X-Traceable-Request-Id header holding a UUID, which is also returned as requestId in error bodies:

X-Traceable-Request-Id: 9b2f1c6e-4a3d-4f0e-8c55-2d7a1e6b9f10

Include this value when contacting support about a specific Integration API request.

Timestamps

All timestamps in API responses are ISO 8601 formatted strings in UTC:

2025-03-14T09:26:40.123Z

Parse these with your language's standard date library. Do not rely on the specific sub-second precision format.