API reference overview

Base URL

All API endpoints are available at:

https://app.traceable.digital

Example: to retrieve a DPP, the full URL is https://app.traceable.digital/api/dpp/{slug}.

Response format

All responses use Content-Type: application/json. JSON is UTF-8 encoded.

HTTP methods

Traceable uses a small set of HTTP methods:

Method	Semantics
GET	Read data. Safe and idempotent. No request body.
POST	Create a resource or initiate an action. May have a JSON request body.

Error response envelope

All error responses use a consistent envelope:

{
  "error": "Human-readable description of what went wrong",
  "code": "MACHINE_READABLE_CODE",
  "details": {}
}

Field	Type	Description
error	string	A human-readable description of the error. Do not parse this string programmatically — use code instead.
code	string	A stable machine-readable error identifier. See Error Codes for the full reference.
details	object	Optional additional context. May contain field-level validation errors for 400 responses. May be an empty object {}.

Example validation error:

{
  "error": "Request body validation failed",
  "code": "VALIDATION_ERROR",
  "details": {
    "fields": {
      "contactEmail": "Must be a valid email address",
      "jurisdiction": "Must be a 2-letter ISO 3166-1 alpha-2 country code"
    }
  }
}

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:

{
  "id": "dpp_01HXYZ...",
  "slug": "swiftvolt-48v-100ah-ev-pack",
  "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

There is no /v1/ path prefix. The current API version is served at the root path. See the Introduction for the full versioning and deprecation policy.

CORS policy

Public DPP endpoints (GET /api/dpp/*, GET /api/health) 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.

Authenticated endpoints (POST /api/poli/access, GET /api/poli/verify) restrict cross-origin requests. These endpoints are intended for server-to-server use only. Do not call them directly from a browser.

Request ID header

Every response includes an X-Request-Id header with a unique identifier for the request:

X-Request-Id: req_01HXYZ9KP2MNTV3QW8JBDCF4A

Include this value when contacting support about a specific request. It allows the support team to locate the request in server logs.

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.