Skip to main content
The Gauge API provides the same customer-facing control-plane operations used by the gauge CLI. Use it to manage measurements and run configurations, launch runs, inspect evidence, and query analytics.

​
Base URL

​
Authentication

Send a personal access token as a bearer token on every authenticated request.
Create a token with the CLI:
The plaintext token is shown once. Tokens authenticate as a user and inherit that user’s current organization memberships.

​
Organization scope

Most resources live below /api/v1/orgs/{org}. The org parameter accepts an organization slug or public ID.
Gauge checks membership on every request. Removing a user’s membership also removes access through that user’s tokens.

​
Request and response format

Send JSON request bodies with Content-Type: application/json. Most successful responses are JSON. Endpoints that return a diff or event stream document a different content type in their operation. Collection endpoints commonly return an items array and an optional nextCursor value. Pass that value as cursor to request the next page.

​
Errors

Non-success responses use a stable envelope:
Common error codes include invalid_request, unauthorized, forbidden, not_found, conflict, rate_limited, insufficient_credits, and needs_provider_key.

​
Recover from an error

After a timeout on a request that creates or launches work, inspect the existing resource or run list before resubmitting. The server may have accepted the request even though your client did not receive the response.

​
Measurement configuration

Evals own their configuration. Update it with PATCH /api/v1/orgs/{org}/eval-sets/{evalSetId}. For example, set manual cadence, three samples per target, and a selected service credential:
Replace the placeholder with an ID from GET /api/v1/orgs/{org}/connections. Omitted PATCH fields keep their stored values; supplied resource arrays replace their selections. Use connectionIds: [] to clear direct credential selection. The connections response contains an items array with identity and allowed-host metadata, never secret values. Cadence values are NONE, DAILY, WEEKLY, and MONTHLY; sample counts range from 1 to 50. Launch an eval’s saved settings with POST /api/v1/orgs/{org}/eval-sets/{evalSetId}/run and an empty JSON object. The response contains batchIds and runIds. Preference prompts own shared run settings and repository/persona scenarios. Add a scenario with POST /api/v1/orgs/{org}/visibility-prompts/{visibilityPromptId}/scenarios:
Use a repository accessible to your organization. Scenarios inherit the prompt’s agents/models, skills, MCP servers, credentials, cadence, and samples. They are not shared assets attached to evals. Shared presets, cycles, scenarios, and schedule endpoints are retired. The compatibility routes return 403 with an upgrade message.

​
API specification

The endpoint pages are generated from the OpenAPI 3.1 document in agents/openapi.json. Use Download API spec to inspect the available operations. Some request and response bodies use generic object schemas, so this document is not a complete typed contract for client generation. Use the examples above and the supported CLI for configuration workflows; validate payloads and handle API validation errors when integrating directly.

CLI guide

Use the supported CLI when you want shell-friendly commands, authentication flows, and formatted output.