# API reference (/docs/api)



Every page in this section is generated from the gateway's own route definitions at build time,
so it always matches what `https://api.gridrouter.io` serves. The same operations are
[MCP tools](/docs/mcp) with the same names.

## Base URL and auth [#base-url-and-auth]

```text
https://api.gridrouter.io
```

Send a GridRouter [API key](/docs/getting-started/api-keys) as a bearer token:

```http
Authorization: Bearer grid_live_…
```

Catalog and status routes are public and need no key. Everything else checks the key's scopes;
each operation lists the scope it needs.

## Conventions [#conventions]

* **JSON in, JSON out.** Request bodies are validated at the edge; a bad field is
  `400 invalid_request` or `422 validation_failed` with the field's path.
* **Money** is integer micro-USD everywhere: 1,000,000 = $1. The one exception is the
  `X-Grid-Max-Cost` header, which is in USD.
* **Timestamps** are ISO 8601 in UTC.
* **Paging.** Routes that page take `limit` and an opaque `cursor`.
* **Idempotency.** Send `Idempotency-Key` on `POST`s that run something; see
  [idempotency](/docs/errors#idempotency).
* **Errors** share one [envelope](/docs/errors).

## Machine-readable [#machine-readable]

| Document                        | URL                                                                |
| ------------------------------- | ------------------------------------------------------------------ |
| OpenAPI 3.1                     | `https://api.gridrouter.io/openapi.json`                           |
| OpenAPI 3.0 (for older tooling) | `https://api.gridrouter.io/openapi-3.0.json`                       |
| Tool schemas                    | `https://api.gridrouter.io/v1/tools?format=openai\|anthropic\|mcp` |
| Execution options JSON Schema   | `https://api.gridrouter.io/v1/options/schema`                      |

The playground on each operation page sends real requests from your browser straight to the API,
with the key you enter. Use a test or read-only key there.