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. 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 — 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.

The full reference (OpenAPI 3.1, GraphQL, EPCIS) lives at /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.

6. GraphQL query limits

The GraphQL endpoint is authenticated (send your API key) and bounds every query so a hostile or accidental query cannot exhaust the server:

Maximum depth: 8. Nested selections beyond eight levels are rejected before execution.
Maximum complexity: 1000. Each resolved field costs 1; a query — including alias-batched fields — may resolve at most 1000 fields. A query over the cap is rejected with a validation error, not executed.

Alias batching (requesting the same field many times under different aliases) is allowed up to that complexity cap, so a single request can never fan out to unbounded work. Together with the per-key rate limit (rate limits & plans), total throughput is bounded by complexity × requests-per-minute, not by how cleverly a query is shaped.