TraceHub API

Authentication

Send your key on every request as the X-API-Key header (or Authorization: Bearer ...).

curl -X POST https://tracehub.1dts.com/api/v1/me \
  -H "X-API-Key: th_live_a1b2c3d4e5f6g7h8..."

Error envelope

All non-2xx responses use the same JSON shape:

{
  "error": "code",
  "message": "human-readable",
  "details": ...
}

Codes: unauthorized (401), validation_error (400), rate_limited (429), not_found (404), internal_error (500).

Rate limiting

• Per-minute limit per API key. Default 60; varies by plan (see /me.quota.perMinute).
• Per-day quota per company. Varies by plan (see /me.quota.perDay). When unlimited, null is returned.
• 429 responses include { "window": "minute" | "day", "limit": N }.

GET /api/v1/me

Returns the company + key + current quota usage. Useful for health checks.

200 response:

{
  "company": { "id": 1, "name": "Acme Pharma Test", "slug": "acme-pharma-test" },
  "key": { "name": "Production ERP", "prefix": "th_live_5K9p", "environment": "live", "createdAt": "2026-05-16T10:00:00Z", "lastUsedAt": "2026-05-16T12:34:56Z" },
  "plan": { "name": "Pro", "slug": "pro" },
  "quota": { "perMinute": 60, "perDay": 5000, "usedToday": 312 }
}

POST /api/v1/epc/encode

Encode GS1 components into an EPC URI. Supported types: SGTIN, SSCC, SGLN.

Request:

{
  "type": "SGTIN",
  "gtin": "09501101530003",
  "serial": "12345",
  "companyPrefixLength": 7
}

200 response:

{
  "type": "SGTIN",
  "uri": "urn:epc:id:sgtin:9501101.530003.12345",
  "elementString": "(01)09501101530003(21)12345",
  "components": { "gtin": "09501101530003", "serial": "12345" }
}

POST /api/v1/epc/decode

Parse a Pure Identity URI back into GS1 components.

Request:

{ "value": "urn:epc:id:sgtin:9501101.530003.12345", "companyPrefixLength": 7 }

200 response:

{
  "type": "SGTIN",
  "gtin": "09501101530003",
  "serial": "12345",
  "companyPrefix": "9501101",
  "components": { "companyPrefix": "9501101", "itemReference": "530003", "serial": "12345", "gtin": "09501101530003" }
}

POST /api/v1/barcode/decode

Decode a GS1-128 or DataMatrix-style application-identifier string into individual fields.

Request:

{ "data": "010109501101530003172112310010A123456" }

200 response:

{
  "isValid": true,
  "barcodeType": "GS1-128",
  "gtin": "09501101530003",
  "serial": "23456",
  "batch": "A1",
  "expirationDate": "2021-12-31",
  "applicationIdentifiers": [ ... ]
}

POST /api/v1/serial/validate

Validate a serial number's format + GTIN check digit. Pass countryCode for system-specific rules (TATMEEN, RSD, EPTTS, NHRA, JFDA, EFDA-MVC).

Request:

{ "gtin": "09501101530003", "serial": "ABC123", "countryCode": "AE" }

200 response:

{
  "valid": true,
  "errors": [],
  "warnings": [],
  "countryRules": { "system": "TATMEEN", "serialMaxLength": 20, "allowedChars": "alphanumeric" }
}