Looking for every endpoint and schema in one place? See the Full OpenAPI reference.
One delivery: the public endpoints
| Request | Returns |
|---|---|
GET /api/public/track/{token} | JSON snapshot: delivery, driver, statusUpdates, pod (once delivered, if your company shows it), updates |
GET /api/public/track/{token}/events | Server-Sent Events stream for that delivery |
{token} is the delivery’s public_tracking_token. No API key is needed and none must be used. Both endpoints
allow cross-origin reads (Access-Control-Allow-Origin: *, GET, HEAD and OPTIONS, no
cookies), so a page on any domain can call them directly, as in the JavaScript
quickstart. Optional: proxy them through your own server if you want the requests on your own domain. They return only public fields (first name of the driver, positions, status, ETA, addresses), never
phone numbers, email addresses or codes.
| Status | Meaning |
|---|---|
| 404 | Unknown or invalid token (code: LEGACY_TRACKING_DISABLED for old short tracking codes, which are no longer accepted). |
| 410 | TRACKING_EXPIRED: the delivery ended more than seven days ago. |
| 429 | Too many open streams: at most 5 per tracking link and 20 per IP address. |
What the stream sends
Frames are unnamed SSE data: lines containing JSON with a type, so EventSource.onmessage receives
them all. Each frame has an id; browsers send it back as Last-Event-ID when they reconnect and missed events are
replayed (up to 50 per delivery, for ten minutes).
type | Payload |
|---|---|
connected | delivery and driver: the current snapshot |
driver_location | driverId, rideId, location: { latitude, longitude, accuracy, timestamp } |
ride_status_change | rideId, status, estimatedArrival |
eta_update | rideId, eta, distance_m, duration_s, source (routes, estimate or manual), leg |
ride_update | update: a card shown on the tracking page, such as “Your driver has arrived” |
heartbeat | Every 30 seconds; ignore it |
resync | An update was too large to send; fetch the JSON snapshot again |
reconnect | The server is restarting; the browser reconnects automatically |
Driver positions are sent at most once every three seconds per driver.
Your whole company: the private stream
To follow all your drivers, your server first exchanges its API key for a token with
POST /api/v1/auth/sse-token (see authentication), then opens (or relays to your dashboard). This
stream does not allow cross-origin reads; open it from your server:
GET /api/v1/tracking/events?token=<sse token>
It starts with an initial_data frame listing recent deliveries, then sends the same event types for every delivery in your
company. Each API key can hold three company streams open; a fourth closes the oldest with a replaced frame. Do not reconnect
after replaced, or the two streams will keep closing each other.