Claude Messages API

The Claude Messages API is Anthropic's primary request and response contract for building on Claude: a structured array of content blocks (text, images, tool calls, and tool results) that the model continues turn by turn, with streaming and a tool-use loop.

How it works

A request is an ordered array of messages, the first from the user and the roles alternating from there, and each message's content is either a plain string or a list of typed blocks: text, images, a tool call, a tool result, or model reasoning. The model reads the whole array as the current state and appends one assistant turn. When that turn needs a client-side tool, the model emits a tool-call block and stops; the caller runs the tool and sends the result back as a block in the next user turn, and the model resumes from there, so one logical exchange can span several request and response round trips, while server-side tools run inside the vendor infrastructure without that caller pause. Responses can be returned whole or streamed incrementally as a sequence of events, which is the same content assembled progressively rather than a different contract. Capabilities such as caching part of the input, asking the model to reason before it answers, and defining structured tools all live on this one request rather than on separate endpoints, carried by dedicated request fields and extra block types.

Why it matters

Treating the model as a black box is what makes an integration brittle, because the behavior you actually control is the contract: which blocks you send, in what order, and how you handle the turn where the model hands control back. Most integration failures I have seen are contract failures rather than model failures: a tool result returned in the wrong shape, state dropped between turns, a streamed response reassembled incorrectly. The trade-off the contract imposes is that it is essentially stateless, since the model does not remember the last call and the caller resends the relevant history every turn, which keeps the protocol simple but means the request grows with the conversation and the caller owns what to keep and what to drop. Getting the contract right is therefore less about prompt wording than about the plumbing around it, and contract failures are deterministically testable where model behavior has to be evaluated instead. The contract is still not the whole reliability story, since a well-formed request can meet a model that hallucinates a tool argument or drifts from an instruction, so the framing makes failures legible without replacing evaluation of the model itself.

In practice

An assistant that can look up live data sends the model a tool definition alongside the conversation. The model replies not with an answer but with a tool-call block naming the lookup and its arguments, then stops; the integration runs the lookup, appends the result as a block in the next turn, and the model continues from the real value instead of guessing. If that result block is out of order or malformed the API rejects the request outright, and if it is well-formed but wrong the model quietly reasons from bad input, which is why the loop is the part worth testing first.

Practical considerations

The contract is versioned, and a request names the API version it targets, so a robust integration pins a version rather than tracking the latest implicitly and being surprised when defaults move. Some capabilities are gated behind opt-in headers while they stabilize, which means a feature can be available to one request and absent from another against the same model depending on what the caller declared. Because the protocol is stateless, the practical cost center is the growing message array: every turn resends history, so a long conversation pays for that history on each call, and managing what to carry forward is the caller's job, not the model's. Streaming trades a single response for a sequence of partial events the caller must reassemble, which is worth it for latency-sensitive interfaces and an avoidable complication when it is not. A single request can combine text and images in its content blocks, define tools, and constrain whether the model may, must, or must not call one, so the levers are composed per request rather than chosen once globally.

Defined by Ready Solutions AI