Conventions

Bodies

• Request and response bodies are JSON (Content-Type: application/json) with camelCase keys.
• Ids are UUIDs, for example 3f6c1e2a-8b4d-4f1e-9c2a-6d5e7f8a9b0c.
• Times are RFC 3339 in UTC (2026-10-28T06:12:00Z); calendar dates are YYYY-MM-DD.
• A request body is at most 8 MiB; a larger one gets 413.
• Webhook payloads are the exception: their envelope keys are snake_case (see Webhooks).

Paths

Resources are nouns under /v1/; an action on one is a verb after a colon, always POST:

GET  /v1/drivers/{id}
POST /v1/drivers/{id}:suspend
POST /v1/alerts/{id}:acknowledge
POST /v1/dispatch/jobs/{id}/stops/{stopId}:complete

Versions and If-Match

Resources carry a version that grows with each change. An update or action that must not overwrite someone else's change takes the version you read in If-Match:

curl -X PATCH "https://api.zaitrack.app/v1/drivers/$ID" \
  -H "Authorization: Bearer zk_test_…" \
  -H 'If-Match: "7"' \
  -H "Content-Type: application/json" \
  -d '{"phone": "+966501234567"}'

If the resource changed since, the request is refused (412, or 409 on report schedules) and nothing is written: read it again and retry. Each operation in the API reference says when it reads If-Match.

Headers worth keeping

Response header	Means
X-Zaitrack-Request-Id	The request's id. Quote it when you report a problem.
X-Zaitrack-Region	The region that served the request.
ETag	The version of what was returned, where the operation sets it.
X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset	Your organisation's budget for this operation.
Idempotency-Replayed: true	The response is a replay of an earlier request with the same key.