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

# HTTP API

> The gateway's routes, authentication, request fields, response headers, and errors.

The gateway serves three protocols and a model list. Its base URL is wherever you started it, such as `http://127.0.0.1:8080`.

## Routes

| Method | Path | Protocol |
| - | - | - |
| `POST` | `/v1/messages` | Anthropic Messages. Claude Code and Anthropic SDKs. |
| `POST` | `/v1/chat/completions` | OpenAI Chat Completions. |
| `POST` | `/v1/responses` | OpenAI Responses. |
| `GET` | `/v1/models` | Model list, in the shape of the calling client. |
| `GET` | `/v1/models?detail=1` | The model catalog. See [Models](https://docs.dari.dev/gateway/models.md). |
| `GET` | `/healthz` | Health check. No key needed. |

Each protocol route is also served under a router's name: `/<router>/v1/messages`, `/<router>/v1/chat/completions`, and so on. Without a name, `/v1/...` uses the `default` router.

The CLI's subscription commands use `/v1/organizations/current/credentials/...`. You do not need to call those routes directly.

### Router Specs

`dari router` reads and saves [router spec files](https://docs.dari.dev/gateway/configure-routers.md#router-spec-files) through these routes. They take any gateway key.

| Method | Path | Effect |
| - | - | - |
| `GET` | `/v1/routers` | Every router, with its `source`: `config` or `saved`. |
| `GET` | `/v1/routers/<name>` | The router as a spec, in YAML. |
| `PUT` | `/v1/routers/<name>` | Saves `{"spec_yaml": "..."}` and serves it at once. |
| `DELETE` | `/v1/routers/<name>` | Removes a saved spec. |

### Model Lists

The model picker reads and changes a router's model lists through these routes. They take any gateway key, and `/<router>/v1/router/models` reaches a router other than `default`.

| Method | Path | Effect |
| - | - | - |
| `GET` | `/v1/router/models` | The router's lists as served. |
| `PUT` | `/v1/router/models` | Save the router's own list. |
| `DELETE` | `/v1/router/models` | Forget the saved list and serve the config file's. |
| `PUT` | `/v1/router/models/<agent>` | Save one [coding agent's](https://docs.dari.dev/gateway/configure-routers.md#models-per-coding-agent) list. |
| `DELETE` | `/v1/router/models/<agent>` | Forget that agent's saved list. |

A `PUT` body is `{"models": [...]}`, with entries written as in the config file: a model id, or an object with `id` and `thinking`. A list the config file would refuse is refused with `400`. Every route answers with the lists as served after the change:

```json theme={null}
{
  "models": [{ "id": "anthropic/claude-sonnet-5-5" }],
  "agent_models": { "codex": [{ "id": "openai/gpt-6.2-sol", "thinking": ["high"] }] },
  "chosen": true
}
```

`chosen` is `false` while the router serves the gateway's built-in default models: no config file is loaded and no list is saved.

Set `"stream": true` to receive server-sent events from the three generation routes.

## Authentication

Send a gateway key from `DARI_GATEWAY_KEYS` as a bearer token:

```
Authorization: Bearer <gateway key>
```

Anthropic clients may send the key in `x-api-key` instead. Provider keys are never sent by clients; the gateway holds them.

## Choosing A Model

The `model` field in a generation request selects how the router picks:

| Value | Behavior |
| - | - |
| `dari/routing` | The router chooses the model and thinking level for each request. |
| `dari/model/<id>` | Exactly that model, with no selection. The model must be in the router's `models` list. |

The `<id>` is a model id such as `anthropic/claude-sonnet-5-5`. See [Models](https://docs.dari.dev/gateway/models.md).

## Response Headers

Every generation response includes headers that status lines and tools can read:

| Header | Value |
| - | - |
| `X-Dari-Selected-Model` | The model that served the request, such as `anthropic/claude-sonnet-5-5`. |
| `X-Dari-Thinking-Level` | The thinking level the request was served at. |
| `X-Dari-Conversation-Id` | The conversation the request belongs to. Repeat turns of one conversation share it. |

## Errors

Errors carry an HTTP status, a message, and a `code`. Common ones:

| Status | Code | Meaning |
| - | - | - |
| `400` | `model_not_enabled` | `dari/model/<id>` names a model the router does not list. |
| `401` | `authentication_error` | The gateway key is missing or does not match `DARI_GATEWAY_KEYS`. |
| `404` | `router_not_found` | The path names a router the config does not define. |
| `424` | `provider_credentials_missing` | No credential on the router can serve it. Set a provider key or connect a subscription. |
| `424` | `personal_subscription_unavailable` | Every connected subscription for the provider is held, and no API key can serve instead. |
| `502` | `provider_output_invalid`, `selector_execution_failed`, and others | A provider or the selector returned a failed or unusable response. |

For provider failures, the gateway retries and fails over to the router's next model before it returns an error.

## Examples

Chat Completions with the router's choice:

```bash theme={null}
curl -i http://127.0.0.1:8080/v1/chat/completions \
  -H "Authorization: Bearer $DARI_GATEWAY_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "dari/routing", "messages": [{"role": "user", "content": "Hello"}]}'
```

Anthropic Messages, pinned to one model on the `local` router:

```bash theme={null}
curl http://127.0.0.1:8080/local/v1/messages \
  -H "x-api-key: $DARI_GATEWAY_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "Content-Type: application/json" \
  -d '{"model": "dari/model/local/qwen3-coder", "max_tokens": 256, "messages": [{"role": "user", "content": "Hello"}]}'
```


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