Conventions
Conventions
The rules every /v2 endpoint follows, so you learn them once.
Every /v2 endpoint shares the same contract. Build your client around these once and every new
endpoint behaves the way you expect.
| Convention | In one line |
|---|---|
| Versioning | /v2 in the path; pin a dated Gauge-Version for additive changes. |
| Errors | One envelope; branch on error.code, never on the message. |
| Request ids | Every response has X-Request-Id; quote it to support. |
| Idempotency | Every POST needs an Idempotency-Key; retries replay the first answer. |
| Pagination | Opaque cursors, { data, nextCursor, prevCursor }, up to 100 per page. |
| Rate limits | Per key and per workspace, by plan; RateLimit-* headers, 429 with Retry-After. |
| Plans | The API is included on Growth and Scale. |
Requests and responses are JSON (Content-Type: application/json), in UTF-8. Timestamps are
ISO 8601 in UTC (2026-10-21T09:12:44.000Z). Ids are opaque strings, today UUIDs; do not parse them.