API quickstart: first track in 5 minutes

Mint a key, call /api/v1/track, understand the envelope — curl, PHP, JS, Python.

1. Get a key

Sign in and mint a key at [/my/api-keys](/my/api-keys). Keys look like tjk_live_… and are shown once — store them server-side, never in front-end code.

2. First call (60 seconds)

`` curl -H "Authorization: Bearer $TRACKJET_API_KEY" \ "https://trackjet.world/api/v1/track/TJTEST-DELIVERED" ``

TJTEST-DELIVERED is a [sandbox fixture](/docs/sandbox) — deterministic, safe, and identical every time, so your first call works before you have a real shipment.

3. The envelope

Every JSON response has the same shape:

`` { "ok": true, "data": { … }, "meta": { "request_id": "…", "api_version": "v1" } } ``

Errors are ok:false with a problem object (code, message, status). Always log meta.request_id — quote it in support requests and we can find the exact request.

4. The endpoints you will actually use

GET /api/v1/detect?number=… — what format is this number?
GET /api/v1/track/{number} — detection + carrier + tracking surfaces.
GET /api/v1/track/{number}/stream — live events over SSE where a licensed feed exists (closes honestly with no_live_feed otherwise).
GET /api/v1/carriers — the catalogue.
POST /api/v1/webhooks — see [webhooks](/docs/webhooks).

The full reference (OpenAPI 3.1, GraphQL, EPCIS) lives at [/developers/api](/developers/api).

5. Idempotency & retries

Write endpoints honour an Idempotency-Key header: retry a timed-out POST with the same key and you will never double-create. Rate limits are per key — see [rate limits & plans](/docs/rate-limits-and-plans).