REST API quick reference

Overview

TrackLayer’s REST API covers ingestion, configuration reads, diagnostics, and limited administrative actions. Use workspace-scoped keys, include Idempotency-Key on mutating calls, and target the regional base URL shown in the dashboard banner.

Steps

1. Authenticate with Authorization: Bearer <token>; prefix distinguishes ingest vs management scopes.
2. Send POST /v1/events with JSON bodies validated against your workspace schema registry.
3. Poll GET /v1/deliveries/:id when debugging downstream failures.

curl -sS -H "Authorization: Bearer $TL_TOKEN" \
  "https://api.tracklayer.io/v1/workspaces/me/health"

4. For automation, prefer the official SDKs—they handle retries and clock skew.

Troubleshooting

• 401 scope errors reference the missing permission in the JSON body—rotate keys when roles change.
• Rate limits return Retry-After; exponential backoff starting at ~200ms works well for batch workers.
• Version pins: pass TrackLayer-Version: 2026-05-05 header once you opt into dated beta endpoints.