Skip to content
Gamut AI Gamut AI Docs

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

Section titled “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

Section titled “Status codes”

The API uses standard HTTP status codes:

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

Errors

Section titled “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

Section titled “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

Section titled “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.

CSRF

Section titled “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

Section titled “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

Section titled “Next”