# Messages

> POST /v1/messages — the Anthropic Messages contract, over the same canonical core.

URL: https://boelabs.com/en/docs/ai-gateway/messages
Language: English

Send messages using the Anthropic API format. The selected deployment can use Anthropic or another
provider that supports the requested capabilities.

## Example request

Set `GATEWAY` to the gateway origin and `API_KEY` to your virtual key. Replace the example
public model with one from [Model discovery](https://boelabs.com/docs/ai-gateway/models-discovery).

```bash
curl -X POST "$GATEWAY/v1/messages" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude",
    "max_tokens": 1024,
    "messages": [{ "role": "user", "content": "Say hi" }]
  }'
```

The native Anthropic wire shape — `stop_sequences` instead of `stop`, `system` as a top-level field or
message, `output_config.format` instead of `response_format` — rendered onto the same canonical request
as [Chat completions](https://boelabs.com/docs/ai-gateway/chat-completions) and [Responses](https://boelabs.com/docs/ai-gateway/responses). You can request any
provider through this contract, not just Anthropic models; the reverse also works (Anthropic models are
reachable through Chat Completions and Responses too).

Messages `document` blocks support URL, base64, and provider file sources. They stay native on the
Anthropic transport and use the same portable routing policy elsewhere. See
[Content inputs](https://boelabs.com/docs/ai-gateway/file-inputs).

The router prefers the native Messages transport when it is available. `top_k` is canonicalized and
translated to providers that expose the same control. Request metadata is native-only and requires a
Messages-capable deployment instead of being silently dropped.

## Prompt-caching breakpoints

`cache_control: { "type": "ephemeral" }` on a system block, content block, or tool is preserved
end-to-end as an opaque pass-through — the canonical core doesn't interpret it, only the Anthropic
adapter emits it. Because dropping a cache breakpoint changes billing and latency semantics, requests
that contain one require a native Messages deployment instead of silently degrading on another wire.

## Structured output

`output_config.format` maps to the same canonical `responseFormat` as `response_format` elsewhere —
`json_schema` is native strict structured output and requests a schema-adherent response on models
that declare `structuredOutputs: true`. Anthropic tool definitions preserve `strict: true` end to end.

## Reasoning

Anthropic's `thinking` block is resolved from the same canonical `reasoning.effort`/`summary` as every
other contract. Two distinct kinds exist in the catalog — `anthropic_adaptive` (the model picks its own
depth, driven by `output_config.effort`) and `anthropic_budget` (an explicit `budget_tokens` per
level) — see [Reasoning](https://boelabs.com/docs/ai-gateway/reasoning) for the exact wire shape of each and which models use which.
For adaptive models, `output_config.effort: "max"` stays distinct from `"xhigh"` end to end.

Signed thinking and redacted thinking blocks are opaque provider state. The gateway preserves and
replays the complete blocks, including signatures and redacted data, but does not fabricate signed
blocks when a different provider only returns a visible reasoning summary.

## Error shape

Errors follow Anthropic's own envelope (`{"type": "error", "error": {"type": "...", "message": "..."}}`)
on this endpoint specifically, even though the gateway's internal classification is identical across
all three text contracts — see [Troubleshooting](https://boelabs.com/docs/ai-gateway/troubleshooting) for the class-to-type mapping.

## Streaming

Same SSE mechanics as every other endpoint, rendered into Anthropic's own event names
(`message_start`, `content_block_delta`, ...). See [Streaming](https://boelabs.com/docs/ai-gateway/streaming).

## Next steps

- [Reasoning](https://boelabs.com/docs/ai-gateway/reasoning) — `anthropic_adaptive` vs. `anthropic_budget` in depth.
- [Chat completions](https://boelabs.com/docs/ai-gateway/chat-completions) and [Responses](https://boelabs.com/docs/ai-gateway/responses) — the other two text contracts.
- [Providers → Anthropic](https://boelabs.com/docs/ai-gateway/providers-anthropic) — credentials and adapter specifics.