Base URL
Authentication
Every endpoint requiresAuthorization: Bearer <token>. The token is an organization API key (gauge_sk_…) or a token from a gauge CLI sign-in. See Authenticate with the API.
Requests that change data or launch work need a Read & write key. GET requests, POST /orgs/{org}/query, and POST /orgs/{org}/runs/compare need only Read only.
Scope
Gauge checks access on every request. Removing a user’s membership also removes access through that user’s sign-in and older personal tokens.
Format
Request bodies are JSON, sent withContent-Type: application/json. Most responses are JSON. Endpoints that return a diff or event stream document a different content type.
Pagination
Collection endpoints commonly return anitems array and an optional nextCursor value. Pass nextCursor as cursor to get the next page. Each endpoint documents its own limit range.
Errors
Retired routes, including shared presets, cycles, scenarios, and schedules, return
403 or 410 with an upgrade message.
Rate limits
Requests are limited per credential, per minute. The default is 240 requests per minute. Over the limit, requests return429 rate_limited.
OpenAPI specification
The endpoint pages are generated from an OpenAPI 3.1 document:/agents/openapi.json.
Some request and response bodies use generic object schemas, so the document is an endpoint catalog, not a complete typed contract for client generation. Validate payloads and handle validation errors when integrating directly.