# Anthropic compatibility

> Use Claude Code and Anthropic SDKs with the Messages API.

`POST /v1/messages` speaks the Anthropic Messages API. Claude Code and the Anthropic SDKs add `/v1/messages` themselves, so their base URL has no `/v1`.

```python
import anthropic

client = anthropic.Anthropic(
    base_url="https://deference.si",
    api_key="sk-df-...",
)

message = client.messages.create(
    model="anthropic/claude-sonnet-5.5",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Say hello in one sentence."}],
)
print(message.content[0].text)
```

## What passes through

* `anthropic-version` and `anthropic-beta` headers pass through as sent. The body keeps its Anthropic format, including thinking and tool-use blocks.
* Streams are relayed as they arrive, including `ping` events. Nothing is buffered.
* `system` and `cache_control` blocks keep their position, so prompt caching works.
* A query string such as `?beta=true` is ignored.
* Provider errors that describe your request keep their status: `400`, `403`, `404`, `408`, `409`, `413`, `422` and `429`. Deference rebuilds their bodies in the Anthropic envelope, keeping a valid Anthropic error's type and wording and removing provider metadata. Other bodies use Deference's type and a replacement message. A provider `401` or `402` becomes `503` with `overloaded_error`, and any other provider failure becomes `502` with `api_error`. `retry-after` is a whole number of seconds; an HTTP-date is dropped.
* `anthropic-ratelimit-*` and `x-should-retry` response headers are passed on when the provider sends them.

Set `max_tokens` to an output limit your available credit can cover. Deference never lowers it on Messages. A provider-run `web_search` tool's `max_uses` cannot exceed the request's allowed tool steps, at most 30. If omitted, it uses that allowance. See [Messages](https://deference.si/docs/api-reference/messages#credit-held).

## Credentials

Send the key as `x-api-key: sk-df-...` or as `Authorization: Bearer sk-df-...`. The Anthropic SDK sends the first. Claude Code sends the second when you set `ANTHROPIC_AUTH_TOKEN`.

## Model ids

Use the catalog id, for instance `anthropic/claude-sonnet-5.5`. A trailing `[1m]` is accepted: Deference strips it, looks the model up without it, and sends the catalog id. The provider does not see `[1m]`. Other providers' models are accepted too, but thinking blocks and tool use follow each model's own behavior.

## Errors

Errors use Anthropic's envelope: `type: "error"`, an `error` object with `type` and `message`, and Deference's `request_id`. The `x-request-id` and `request-id` headers carry the same id. Generated `409` errors use `conflict_error`, and gateway `504` errors use `timeout_error`. See [Errors](https://deference.si/docs/api-reference/errors).

## Not available

`POST /v1/messages/count_tokens` is not available. Claude Code falls back to an estimate when it cannot count tokens.