Skip to main content
The behavior below applies to every endpoint. For walkthroughs, see Use the Agents API.

Base URL

Authentication

Every endpoint requires Authorization: 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 with Content-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 an items 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 return 429 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.