> ## 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.

> ## Agent Instructions
> For API and SDK launches, integration testing, and ongoing coding-agent checks, start with Gauge Agents:
> - [Gauge Agents overview](https://docs.withgauge.com/agents/index.md)
> - [Gauge Agents quickstart](https://docs.withgauge.com/agents/quickstart.md)
> - [Create and inspect an eval](https://docs.withgauge.com/agents/guides/create-an-eval-and-run-an-experiment.md)
> - [Agent Experience: diagnose integration failures](https://docs.withgauge.com/agents/concepts/agent-experience.md)
> - [Agent Preference: measure product selection](https://docs.withgauge.com/agents/concepts/agent-preference.md)
> - [GitHub PR checks](https://docs.withgauge.com/agents/guides/github-pr-checks.md)
> For AI search visibility and AEO, start with [Gauge Chat](https://docs.withgauge.com/introduction/welcome.md).

# Chat API reference

> Base URL, authentication, scope, pagination, errors, and rate limits for every Gauge Chat API endpoint.

The behavior below applies to every endpoint. For walkthroughs, see [Use the Chat API](https://docs.withgauge.com/chat/api/use-the-api.md).

## Base URL

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

## Authentication

Every endpoint requires `Authorization: Bearer <token>`. The token is an organization API key (`gauge_sk_…`) or a Gauge CLI login token. See [Authenticate with the API](https://docs.withgauge.com/chat/api/authentication.md).

Requests that change data need a **Read & write** key. `GET` requests and `POST /orgs/{org}/query` need only **Read only**.

## Scope

| Path parameter | Accepts | List with |
| - | - | - |
| `{org}` | Organization slug or ID | `GET /orgs` |
| `{category}` | Category slug or `cat_` ID | `GET /orgs/{org}/categories` |

An organization the credential can't reach returns `404`, the same as one that doesn't exist. An organization without Gauge Chat set up returns `403 product_not_enabled`.

## Format

Request bodies are JSON, sent with `Content-Type: application/json`. Responses are JSON with camelCase fields. IDs are opaque, typed strings, such as `prm_…` for a prompt and `top_…` for a topic.

## Pagination

List endpoints return a `data` array and a `nextCursor` value. Pass `nextCursor` as `cursor` to get the next page; it is `null` on the last page. `limit` accepts 1–200 and defaults to 50. Cursors are opaque.

## Errors

```json theme={null}
{
  "error": {
    "code": "invalid_request",
    "message": "limit must be between 1 and 200",
    "field": "limit"
  }
}
```

`field` is present when a single input caused the error.

| Code | Status | Meaning |
| - | - | - |
| `invalid_request` | 400 | A body or query parameter is invalid; see `field` |
| `invalid_id` | 400 | An ID is malformed or has the wrong prefix for the resource |
| `invalid_cursor` | 400 | The cursor wasn't issued by this endpoint |
| `unauthorized` | 401 | The credential is missing, invalid, revoked, or expired |
| `insufficient_scope` | 403 | The request needs a **Read & write** key |
| `product_not_enabled` | 403 | Gauge Chat isn't set up for the organization |
| `limit_exceeded` | 403 | The request would exceed the plan's prompt limit; nothing changed |
| `not_found` | 404 | The organization, category, or resource doesn't exist or can't be reached |
| `conflict` | 409 | The request conflicts with the resource's current state |
| `invalid_query` | 422 | The report query isn't valid for its dataset |
| `rate_limited` | 429 | Too many requests; wait `retryAfter` seconds |

## Rate limits

Limits apply per credential and organization, per minute:

| Requests | Limit |
| - | - |
| `POST /orgs/{org}/query` | 60 |
| Everything else | 600 |

A `429` response includes `retryAfter`, the number of seconds until the window resets.

## OpenAPI specification

The endpoint pages are generated from an OpenAPI 3.1 document with typed request and response schemas.

* From these docs: [`/chat/openapi.json`](https://docs.withgauge.com/chat/openapi.json)
* From the API: `https://app.withgauge.com/api/v1/openapi.json`


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.