Messages API basics
The Messages API is Anthropic's primary REST interface for sending structured conversations to Claude models and receiving generated responses. You send an array of messages — each with a role of either 'user' or 'assistant' — and the model generates the next message in that conversation. The API supports text, images, and tool-use content blocks in a single request.
The API is fundamentally stateless: it does not store conversation history on Anthropic's servers between calls. Every request must include the full conversation history you want the model to consider. This design gives developers complete control over context but means your application must manage and reconstruct message arrays for each call.
Developers access the API either by making direct HTTP POST requests to 'https://api.anthropic.com/v1/messages' or by using an official Anthropic SDK (Python, TypeScript, etc.) that handles authentication and request formatting. All requests require an API key and an 'anthropic-version' header.
When you’d use it
- ◆Customer Support Chatbot — A company routes customer questions to a chatbot backed by the Messages API. Each user turn is appended to the message history and re-sent with every request so the model understands the full conversation context before generating a reply.
- ◆Document and Image Analysis — A legal-tech startup uploads scanned contracts as base64-encoded images in the content array. Claude reads both text and image blocks in the same request and returns structured summaries of key clauses.
- ◆Autonomous Agent with Tool Use — An engineering team builds a research agent that defines custom tools (e.g., web search, database lookup). The Messages API returns structured tool-call blocks; the application executes them and sends results back in subsequent user turns until the task is complete.
- ◆Bulk Text Processing with Message Batches — A data team needs to classify 50,000 product reviews overnight. They use the Message Batches API to submit all requests asynchronously at 50% lower cost, then retrieve results when processing is complete.
- ◆Structured Output Generation via Prefilling — A developer needs Claude to return only valid JSON without any conversational preamble. They terminate the messages array with an assistant turn containing the opening brace, forcing Claude to continue from that exact point.
What changed recently
- ◆2026-05 — Cache diagnostics entered public beta. Passing 'diagnostics.previous_message_id' on a Messages request causes the API to return a 'cache_miss_reason' field explaining where the prompt cache prefix diverged from the previous turn, enabling developers to debug caching efficiency.
- ◆2026-05 — Claude Platform on AWS reached general availability, exposing the full Messages API, Files API, Message Batches API, tool use, and code execution through AWS-native endpoints with AWS billing and IAM authentication.
- ◆2026-03 — Extended output token limits introduced via the 'output-300k-2026-03-24' beta header. Opus 4 and Sonnet 4 models can now return up to 300,000 output tokens per request when this header is included, enabling generation of book-length content in a single call.
- ◆2025 — Loosened message ordering constraints: the API no longer errors on consecutive same-role messages or when the first message is an assistant turn. Consecutive same-role messages are merged automatically. This simplifies agent workflows and prefilling patterns.
This is the short version
The full chapter has three worked examples, the common pitfalls, and the workflow that makes it pay — plus the other 84 features, kept current.
Get Claude Master — $97 →