> ## Documentation Index
> Fetch the complete documentation index at: https://docs.withgauge.com/llms.txt
> Use this file to discover all available pages before exploring further.

# API overview

> Authenticate with the Gauge API and understand organization scope, errors, and pagination.

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

```text theme={null}
https://agents.withgauge.com/api/v1
```

## Authentication

Send a personal access token as a bearer token on every authenticated request.

```bash theme={null}
curl https://agents.withgauge.com/api/v1/me \
  --header "Authorization: Bearer $GAUGE_API_TOKEN" \
  --header "Accept: application/json"
```

Create a token with the CLI:

```bash theme={null}
gauge auth tokens create ci-production --expires-in 90d
```

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.

```bash theme={null}
curl "https://agents.withgauge.com/api/v1/orgs/acme/runs?limit=25" \
  --header "Authorization: Bearer $GAUGE_API_TOKEN"
```

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:

```json theme={null}
{
  "error": {
    "code": "not_found",
    "message": "Run not found"
  }
}
```

Common error codes include `invalid_request`, `unauthorized`, `forbidden`, `not_found`, `conflict`, `rate_limited`, `insufficient_credits`, and `needs_provider_key`.

## API specification

The endpoint pages in this reference are generated from the OpenAPI 3.1 specification in `agents/openapi.json`. Use **Download API spec** from the page menu to generate a client or inspect the complete machine-readable surface.

<Card title="CLI guide" icon="terminal" href="/agents/guides/cli">
  Use the supported CLI when you want shell-friendly commands, authentication flows, and formatted output.
</Card>