Conventions & errors

The Gamut API follows consistent conventions so integrations are predictable. This page covers the request and response shape, status codes, rate limiting and error handling.

Requests and responses

• JSON. Requests and responses use JSON. Send Content-Type: application/json on requests with a body.
• HTTPS only. All requests are over HTTPS. Plain HTTP is not accepted.
• Versioned path. Endpoints live under /api/compass/v1/. The version segment lets the API evolve without breaking existing integrations.
• Authentication. Send a bearer token on every request, see Authentication.

Status codes

The API uses standard HTTP status codes:

Code	Meaning
200 / 201	Success.
400	The request was malformed or failed validation.
401	Missing or invalid authentication.
403	Authenticated, but not permitted, check the token owner’s role and entitlements.
404	The resource does not exist, or is not visible in your workspace.
429	Rate limit exceeded, slow down and retry later.
5xx	An unexpected server-side error.

Errors

Error responses return a JSON envelope with a machine-readable code, a human-readable message and the HTTP status:

{
  "code": "quota_exceeded",
  "message": "Daily limit reached (20/20). Resets at midnight UTC.",
  "status": 429
}

Handle errors by checking code (stable, safe to branch on) rather than parsing the message (human-facing, may change). Treat 4xx as something to fix in your request, and 5xx as transient unless it persists.

Rate limiting and quotas

AI-assisted endpoints are bound by your plan’s usage quotas, enforced server-side. Two limits apply independently:

• a daily limit that resets at midnight UTC, and
• a monthly limit that resets on the 1st.

Exceeding either returns 429 with code quota_exceeded and a message stating the current usage and reset point. Policy generation carries its own separate daily and monthly quotas. Back off and retry after the stated reset rather than retrying immediately.

Listing and limits

List endpoints accept a limit query parameter to bound the number of records returned, and relevant filters (for example workspace_id, status) as query parameters. Request only what you need.

Idempotency, retries and concurrency

Do not assume every write is safe to repeat. Retry network and 5xx failures only with bounded backoff and only when the operation is known to be idempotent or the current contract provides a request/idempotency mechanism. Do not retry 400, 401, 403 or validation failures without changing the underlying request or authority.

For updates, re-read the current record and use returned version or update metadata where the resource supports it. Route conflicting governance edits to review rather than silently applying last-write-wins. External-agent operations have their own signed, request-bound anti-replay contract; never reuse stale signed material.

Validation and data minimisation

Send only documented fields and the records needed for the integration purpose. Do not place credentials, access tokens or unrestricted evidence payloads in notes or logs. Treat server-side validation as a second boundary, not a replacement for client validation.

CSRF

CSRF protection applies to cookie-based browser sessions, which must send the per-session token as an x-csrf-token header (or form field) on state-changing requests. Bearer-token API calls are not cookie-authenticated and do not need a CSRF token; authenticate with the Authorization header instead.

Permissions and scope

Every call runs within the token owner’s workspace and is subject to their role. You will only ever see and affect data in that workspace, isolation applies to the API exactly as it does in the interface.

Next

• API overview: base URL and capabilities.
• Authentication: bearer tokens.