# Messages API

> POST /api/v1/messages — the Anthropic-compatible Messages endpoint. Point any Anthropic SDK or Claude Code at AnyRouter by swapping the base URL.


# Messages API

An Anthropic-compatible endpoint. Claude Code, `@anthropic-ai/sdk` and any other Messages client work by changing the base URL.

::endpoint{method="POST" path="/api/v1/messages"}

:::note
Authenticate with an **LLM API key** (`sk-ar-v1-…`) from [/dashboard/keys](https://anyrouter.dev/dashboard/keys), passed via either `Authorization: Bearer …` or Anthropic's `x-api-key` header. Management keys (`ak_…`) are not accepted.
:::

## Request

| Header | Required | Description |
|---|---|---|
| `x-api-key` | yes | Your AnyRouter API key (prefixed `sk-ar-`). `Authorization: Bearer sk-ar-…` is also accepted. |
| `anthropic-version` | recommended | Anthropic API version. Dated values (`YYYY-MM-DD`, e.g. `2023-06-01`) are accepted; a missing header is allowed. |
| `Content-Type` | yes | `application/json`. |

Request body fields:

| Field | Type | Required | Description |
|---|---|---|---|
| `model` | string | yes | Any catalog model id (e.g. `anthropic/claude-sonnet-4-6`, `openai/gpt-4o`, `anyrouter/coding`), or a preset reference: `@preset/<slug>`, `@presets/<slug>`, or `<model>@preset/<slug>`. See [Presets](/features/presets#messages-and-responses). |
| `messages` | array | yes | `[{role, content}]` — `content` can be a string or rich blocks. |
| `max_tokens` | integer | yes | Required by the Messages API. |
| `system` | string | no | System prompt (Anthropic splits this out of `messages`). |
| `temperature` | number | no | 0–1. |
| `stream` | boolean | no | SSE streaming. |
| `stop_sequences` | string[] | no | Stop sequences. |
| `tools` | array | no | Tool definitions in Anthropic's schema. `strict: true` on a tool is kept. |
| `tool_choice` | object | no | `auto`, `any`, `tool` (with `name`) or `none`. `disable_parallel_tool_use: true` limits the model to one tool call. |
| `thinking` | object | no | `{"type": "adaptive"}`, `{"type": "enabled", "budget_tokens": N}` or `{"type": "disabled"}`. |
| `output_config` | object | no | `effort` (`low`, `medium`, `high`, `xhigh`, `max`) and `format` (`{"type": "json_schema", "schema": {…}}` for structured output). |
| `session_id` | string | no | Sticky-session id (≤256 chars) that groups related requests in [Request Logs](/features/request-logs#sessions). Also settable via the `x-session-id` header; the body field wins. |

## Response

```json
{
  "id": "msg_01XY...",
  "type": "message",
  "role": "assistant",
  "model": "anthropic/claude-sonnet-4-6",
  "content": [{ "type": "text", "text": "Hello there." }],
  "stop_reason": "end_turn",
  "usage": { "input_tokens": 10, "output_tokens": 4, "cost": 0.000342 }
}
```

### Cost of a request

`usage.cost` is the USD charged to your credits, `0` when nothing was charged (a free model or your own provider key, [BYOK](/features/byok)). It matches your usage history.

- **Non-streaming:** `usage.cost` is on the response.
- **Streaming:** `usage.cost` is on the `usage` of the final `message_delta` event, sent when the model has finished. No event is added or reordered.

It is an extra key beside `input_tokens` and `output_tokens`; Anthropic SDKs ignore unknown keys. The same field is on [chat completions](/api-reference/chat-completions#cost-of-a-request).

### Supported models

`/messages` accepts **any catalog model**. `anthropic/*` models pass through to Anthropic-native upstreams; every other model (including `anyrouter/coding`) is translated to and from the Chat Completions dialect, so requests and responses stay in Messages format. Claude Code can target the full catalog without switching to [chat completions](/api-reference/chat-completions).

### Thinking, effort and structured output on other models

On non-Anthropic models these fields map to the model's own controls:

| Messages field | Effect on a non-Anthropic model |
|---|---|
| `thinking: {"type": "disabled"}` | Reasoning off (`reasoning_effort: "none"`). It wins over any `effort`. |
| `output_config.effort` | The same reasoning level. A level the model does not offer is lowered to the nearest level it does; `xhigh` and `max` become `high` on a model that does not list its levels. A model without reasoning gets no effort. |
| `thinking: {"type": "enabled", …}` with no `effort` | `high` reasoning. |
| `thinking: {"type": "adaptive"}` with no `effort` | The model's default reasoning. |
| `output_config.format` | JSON schema structured output (`response_format`, strict). |
| `tool_choice: {"type": "none"}` | The model does not call tools. |
| `disable_parallel_tool_use: true` | At most one tool call (`parallel_tool_calls: false`). |

### Documents and search results on other models

`document` and `search_result` content blocks work on every model:

- A **text document** (`source.type: "text"` or `"content"`) is passed as text, with its `title` and `context` on top.
- A **search result** is passed as text: its title, its source and its passages.
- A **PDF** (`source.type: "base64"` or `"url"`) is passed as a file to models whose input modalities include `file`. Other models return `400 document_input_not_supported`; send the document as text instead.
- A PDF inside a `tool_result`, or a PDF referenced by `file_id`, needs an Anthropic model. Other models return `400 document_input_not_supported`.

Citations are returned by Anthropic models only.

### Message threads

Message threads (the `thread` field) are not supported yet. A request that carries `thread` returns `400` with `error.details.error_code: "thread_unsupported_request"`, on every model:

```json
{
  "type": "error",
  "error": {
    "type": "invalid_request_error",
    "code": "thread_unsupported_request",
    "message": "Message threads are not supported through AnyRouter. Send the full conversation without `thread`.",
    "details": { "error_code": "thread_unsupported_request", "unsupported": ["thread"] }
  }
}
```

The Anthropic SDK thread helper and tool runner handle this code by sending the full conversation as normal requests. Otherwise send the whole conversation in `messages` every turn.

## Count tokens

::endpoint{method="POST" path="/api/v1/messages/count_tokens"}

Returns the input token count for a Messages request, in Anthropic's shape. Send the same `model`, `system`, `messages` and `tools` as `/messages` (no `max_tokens`), with the same key headers. The account must be able to use paid models.

```json
{ "input_tokens": 42 }
```

The count is an AnyRouter estimate, not the provider's tokenizer (`x-anyrouter-token-count: estimate`). Text counts about four characters per token; each image and PDF counts a fixed amount. Use it to decide when to trim, not to predict a bill. Counting is free.

## Examples

::::tabs

:::tab{label="curl"}
```bash
curl https://anyrouter.dev/api/v1/messages \
  -H "x-api-key: sk-ar-your-key" \
  -H "anthropic-version: 2023-06-01" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "anthropic/claude-haiku-4-5",
    "max_tokens": 1024,
    "messages": [
      { "role": "user", "content": "Say hi in 5 words" }
    ]
  }'
```
:::

:::tab{label="TypeScript"}
```typescript
import Anthropic from "@anthropic-ai/sdk"

const client = new Anthropic({
  baseURL: "https://anyrouter.dev/api",
  apiKey: "sk-ar-your-key",
})

const response = await client.messages.create({
  model: "anthropic/claude-sonnet-4-6",
  max_tokens: 1024,
  messages: [{ role: "user", content: "Hello!" }],
})
```
:::

::::

:::note
For the Anthropic SDK the base URL is `https://anyrouter.dev/api`; the SDK appends `/v1/messages`.
:::

## Errors

An unknown provider or unrouteable model returns `unknown_provider` or `no_upstream`:

```json
{
  "error": {
    "code": "no_upstream",
    "message": "No upstream is available for \"<model>\".",
    "metadata": { "type": "upstream_error" }
  }
}
```

| Status | Meaning | Fix |
|---|---|---|
| 400 | Malformed body, or `max_tokens` missing. | `max_tokens` is required by the Messages API. |
| 401 | Missing or invalid key. | Send a valid `sk-ar-…` key via `x-api-key` or `Authorization`. |
| 404 | Unknown model or no upstream. | Verify the id with [List models](/api-reference/models). |

See [Errors](/guides/errors).


## Related

- [Chat Completions API](/docs/api-reference/chat-completions.md)
- [Responses API](/docs/api-reference/responses.md)
- [Streaming](/docs/guides/streaming.md)
