Operator API documentation

Authentication

Create an operator API key from the ColdChainHQ dashboard. The complete secret is shown once when the key is created and cannot be retrieved later.

Send the key using the HTTP Bearer authentication scheme:

Authorization: Bearer cch_live_your_api_key

curl \
  --request GET \
  --url https://www.coldchainhq.co.uk/api/v1/shipments \
  --header "Authorization: Bearer cch_live_your_api_key"

Test keys begin with cch_test_. Live keys begin with cch_live_.

Permission scopes

Each API key is restricted to the read permissions selected when it is created.

shipments:read

Read shipment lists and individual shipment records.

tracking:read

Read shipment tracking and operational progress data.

temperature:read

Read recorded temperature and humidity evidence.

compliance:read

Download operator-grade compliance report PDFs.

drivers:read

Read minimal tenant-scoped driver identity and status.

vehicles:read

Read minimal tenant-scoped vehicle identity, registration and status.

Endpoints

GET/api/v1/shipments

List shipments belonging to the authenticated operator.

Required scope: shipments:read

GET/api/v1/shipments/{id}

Retrieve one tenant-scoped shipment.

Required scope: shipments:read

GET/api/v1/shipments/{id}/temperature

Retrieve temperature and humidity evidence for a shipment.

Required scope: temperature:read

GET/api/v1/shipments/{id}/compliance-report

Download the operator compliance report as a PDF.

Required scope: compliance:read

GET/api/v1/drivers/{id}

Retrieve minimal tenant-scoped driver identity and status.

Required scope: drivers:read

GET/api/v1/vehicles/{id}

Retrieve minimal tenant-scoped vehicle identity, registration and status.

Required scope: vehicles:read

Download a compliance report

curl \
  --request GET \
  --url "https://www.coldchainhq.co.uk/api/v1/shipments/SHIPMENT_UUID/compliance-report" \
  --header "Authorization: Bearer cch_live_your_api_key" \
  --output compliance-report.pdf

Error responses

API errors use a consistent JSON envelope. Shipment records outside the authenticated operator account return the same not-found response as nonexistent records.

{
  "error": {
    "code": "shipment_not_found",
    "message": "The requested shipment was not found.",
    "requestId": "request-id"
  }
}

Status	Meaning
401	Missing, invalid or expired key
403	Required scope unavailable
404	Shipment unavailable
429	Rate limit exceeded

Security and lifecycle

API keys are tenant-scoped. A key can only access data belonging to the operator account that created it.

Keys can be assigned an expiry date and revoked immediately from the dashboard. Store secrets in a server-side secrets manager and do not expose them in browser code, public repositories or logs.

Rate limiting is applied as defence-in-depth. Clients should respect the Retry-After response header after a 429 response.

Machine-readable specification

Import the OpenAPI 3.1 document into compatible API clients, code generators and testing tools.

View OpenAPI specification