Anthropic Messages API
Claude's stateless generation endpoint: content-block request/response shape, client vs server tools and pause_turn, adaptive thinking with signed blocks, opt-in caching (breakpoints or automatic), Files API, versioning, limits and porting gotchas.
Contents
The Messages API (POST /v1/messages) is Anthropic’s single generation endpoint for Claude. A request carries model, max_tokens (required), an optional top-level system, optional tools, and a messages array of alternating user / assistant turns whose content is a list of typed content blocks (text, image, document, tool_use, tool_result, thinking, server-tool blocks). The response is one assistant message with its own content blocks, a stop_reason, and usage (API reference). The API is stateless: there is no stored response ID to chain from, so the client resends the whole conversation every turn and relies on opt-in prompt caching for cost. Stateful agent hosting lives in separate beta endpoints (Agents, Sessions, Environments for Managed Agents) (API overview).
Request and response essentials
- Headers:
Authorization: Bearer(or legacyx-api-key),anthropic-version(current2026-10-21),content-type;anthropic-workspace-idfor keys not scoped to a workspace. Responses include arequest-idheader for support (API overview). - Versioning: within a version, inputs and outputs stay stable, but new enum values and streaming event types can appear, so parsers must tolerate unknown ones. Version
2026-10-21removedtemperature,top_pandtop_k: sending any of them returns 400 on every model (versioning, sampling removal; see sampling parameters). stop_reason:end_turn,max_tokens,stop_sequence,tool_use,pause_turn,refusal,model_context_window_exceeded. Usage splits input intoinput_tokens+cache_creation_input_tokens+cache_read_input_tokens.max_tokens: 0pre-warms the cache without generating (API reference).- System prompts: top-level
systemplus, on most current models (not Sonnet 5), mid-conversationsystemmessages that override earlier instructions from their position on (mid-conversation system messages; see system prompts). - Assistant prefill is rejected on Claude 4.6+ (thinking docs).
- Size limits: 128 MB per Messages request first-party; 32 MB on Anthropic-operated cloud platforms, 30 MB on Google-managed Vertex, 20 MB on Bedrock (API overview).
- Models (Nov 2026): Fable 5.2, Opus 5.5, Sonnet 5.5, Haiku 5.5, all with 1M context and 128K synchronous output; Mythos 5.2 matches Fable 5.2 but is limited to verified organisations (models overview).
Tools: client, server, and the turn
flowchart TD
R["POST /v1/messages"] --> S{"stop_reason"}
S -->|"tool_use"| C["Run client tools<br/>reply: user msg with ONLY tool_result blocks"]
S -->|"pause_turn"| P["Resend assistant content unchanged<br/>same tools (+ container id)"]
S -->|"end_turn / max_tokens / refusal"| D["Done"]
C --> R
P --> RClient tools are defined with name, description, input_schema (plus optional strict, input_examples, defer_loading, cache_control). Claude returns tool_use blocks with toolu_ IDs; you answer in the next user message with matching tool_result blocks (set is_error on failures), all results in one message before any text. Parallel calls are on by default; tool_choice is auto, any, tool or none, with disable_parallel_tool_use inside it. Forced tool choice (any/tool) is rejected on Opus 5.5, Sonnet 5.5 and Fable/Mythos 5.1-5.2, and with manual extended thinking, so use auto with strict tools or structured outputs instead (tool use docs, thinking docs). Tool definitions add a hidden system prompt of roughly 286-804 tokens (tool use docs).
Server tools (web search, web fetch, code execution, tool search) run inside the request as server_tool_use blocks (srvtoolu_ IDs) followed by their result blocks; you never send a result for them. The server-side loop may stop with pause_turn: resend the assistant content as-is with the same tools, possibly several times. If Claude mixes a server tool and a client tool in one parallel group, you get stop_reason: "tool_use" with an unresolved server_tool_use; reply with only tool_result blocks and the server tool runs next request (server tools).
| Server tool | Key facts |
|---|---|
Web search (web_search_20250305 / _20260209 / _20260318) | max_uses, allow or block domains, user_location; results carry encrypted_content and citations carry encrypted_index, both of which must be sent back unchanged; $10 per 1,000 searches; newer versions filter results with code (dynamic filtering), which is not ZDR-eligible unless allowed_callers: ["direct"] (web search) |
Code execution (code_execution_20250825 / _20260120 / _20260521) | sandboxed Python/Bash, no network, 5 GiB RAM; containers last 30 days; 1,550 free hours/month then $0.05/hour (free when the request also carries web_search_20260209/web_fetch_20260209 or later); not ZDR-eligible (code execution) |
Computer use (computer_toolset_20260801) | client-executed (you run actions and return screenshots), but versioned and schema-defined by Anthropic (computer use; see computer-use agents) |
Thinking
Thinking appears as thinking blocks with an encrypted signature. The visible text is a summary written by another model, and on Claude 5 models display defaults to "omitted"; you are billed for the full reasoning either way. On Claude 5 models thinking is adaptive and on by default, steered by effort in output_config; max_tokens is the only hard spend ceiling. budget_tokens with type: "enabled" returns 400 on Claude 4.7+. Within a tool-use turn, thinking blocks (including redacted_thinking) must be returned complete and unmodified, or the request fails with 400. Changing the thinking configuration invalidates cache breakpoints (thinking docs; see extended thinking).
Synthesis: all three providers now use the same pattern of opaque, provider-signed reasoning state that the client must replay byte-for-byte: Anthropic signature, OpenAI encrypted_content, Gemini thought_signature. None of these artifacts works with another provider.
Caching, files, compaction
- Prompt caching is opt-in, either per block with
cache_controlbreakpoints or with one top-levelcache_control(“automatic caching”, which moves the breakpoint forward as the conversation grows and is unavailable on Bedrock’sbedrock-runtime) (the owner’s RAG vs CAG tutorial shows the pattern: a large handbook insystemmarkedcache_control: ephemeral): up to 4 breakpoints (automatic caching uses one), with the prefix hashed in ordertools→system→messages. TTL is 5 minutes (write 1.25x) or 1 hour (write 2x); reads cost 0.1x (0.05x on Opus/Sonnet 5.5, 0.025x on Fable/Mythos 5.1-5.2). The minimum prefix is 512 tokens on 5.x models. Changing tools invalidates everything, and a cache entry exists only once the first response starts streaming (caching docs). Cache reads do not count toward ITPM rate limits (rate limits). - Files API (stable): upload once and reference the
file_idindocument,imageorcontainer_uploadblocks; 500 MB per file, 1 TB per org. Files are workspace-scoped, so never accept file IDs from end users. Only generated files can be downloaded, and the Files API is not ZDR-eligible (Files API). - Compaction and context editing manage long histories client- or server-side (compaction).
- Structured outputs use
output_config.format, with grammar-constrained JSON Schema (constrained decoding) (no recursion,additionalProperties: false), limits of 20 strict tools, and a 24-hour grammar cache (structured outputs).
Streaming, limits, data
- Streaming SSE flow:
message_start→content_block_start/_delta/_stop→message_delta→message_stop, withpingevents. Errors such asoverloaded_errorcan arrive inside a 200 stream. SDKs require streaming for largemax_tokens(above about 21K) (streaming docs, thinking docs). - Rate limits: RPM, ITPM and OTPM per model class, enforced by a token bucket. On top sit ramp limits (
ramp_limit_exceeded) and monthly spend caps (429 with noretry-after), withanthropic-ratelimit-*headers (rate limits; see rate limits and retries). - Data: inputs and outputs are deleted within 30 days by default. Under ZDR nothing is stored once the response returns, but stateful features (Files, Batch, code execution) step outside ZDR, and Fable/Mythos models require 30-day retention (data retention).
- Batch is 50% off and stacks with cache discounts; fast mode costs a premium (pricing; see batch processing).
Porting gotchas
- From OpenAI: there is no
instructions/previous_response_id, so you resend history.systemis top-level (or a mid-conversation system message), not a message role. Tool results are user-turntool_resultblocks, not atoolrole.max_tokensis required. Sampling parameters return 400 (API reference, versioning). - Via the OpenAI-compatible endpoint:
strictis ignored, prompt caching is unavailable, system messages are hoisted and concatenated, thinking is hidden, file and audio parts return 400, andnmust be 1. Anthropic labels it a testing tool, not a production path (OpenAI compat). - Cloud platforms: partner clouds lag on features: Google-managed Vertex and Azure-hosted Foundry get only basic web search (no dynamic filtering), Bedrock is not listed for web search, and request size is capped at 20 MB (Bedrock) or 30 MB (Google-managed Vertex) (web search, API overview; see Amazon Bedrock, Google Vertex AI).
When to use / when not
Synthesis:
- Use the native Messages API (with the official SDK) for any production Claude workload; you control state, which suits ZDR, audit, and portability.
- Design your own conversation store and a cache-friendly prompt layout (stable tools and system first, a breakpoint, or automatic caching, at the end of the growing history). See context engineering.
- Prefer the Claude Agent SDK or Managed Agents if you want hosted state and an agent loop rather than raw turns.
- Avoid the OpenAI-compatible endpoint beyond quick evals. Compare with the OpenAI Responses API and the Gemini API.
Sources
- Messages API reference
- API overview
- API versions
- 2026-10-21 sampling parameter removal
- Tool use docs
- Server tools
- Web search tool
- Code execution tool
- Computer use tool
- Thinking docs
- Prompt caching docs
- Structured outputs docs
- Streaming docs
- Files API
- Mid-conversation system messages
- Compaction docs
- Rate limits docs
- API and data retention
- Models overview
- Pricing
- OpenAI SDK compatibility
- Notebook: RAG vs CAG vs GraphRAG