2.3 The Messages API: Request/Response Mechanics

The Messages API is the core surface for talking to Claude programmatically. A request is a list of messages, each with a role (user or assistant) and content, plus a model, a required max_tokens, and optional system, tools, temperature, and stream parameters.

Conversations alternate user and assistant turns. Unlike some other chat APIs you may have used, the system prompt in the Messages API is not a message with role: "system" -- it is a separate, top-level system parameter that sits alongside messages, not inside it. This is one of the most consistently tested facts on the exam because it's an easy habit to carry over incorrectly from a different API's convention.

Every response reports why generation stopped, and integration code should branch on that value instead of assuming a response always ends the same way.

A response with stop_reason == "max_tokens" is not a complete answer that happens to be short -- it's a truncated one, and code that treats it as final without checking will silently ship cut-off output.

Every response includes a usage object (input_tokens, output_tokens, plus cache read/creation tokens where caching is in play) -- the basis for any cost model you build on top of the API. Separately, and just as important: the Messages API itself is stateless. It retains no memory of previous calls. If you want a multi-turn conversation, you resend the entire conversation history yourself on every request.

Three capabilities round out the core surface. Streaming (stream=True) delivers the response as server-sent events as Claude generates it -- you consume message_start, content_block_delta, and message_stop events and assemble the text incrementally. This lowers perceived latency for interactive UIs; it does not reduce total tokens or cost, and it does not change what gets billed -- only when it arrives.

Tool use lets Claude call functions you've described. Pass a tools array of JSON-schema tool definitions; when Claude decides to use one, stop_reason is tool_use and content contains a tool_use block naming the tool and its arguments. Your code executes the tool and sends the result back as a tool_result block inside a new user message -- the response is not a final answer, it's a signal to continue the loop.

Vision means content blocks can include images (base64-encoded or by URL) alongside text in the same request, so Claude can read a screenshot, a chart, or a scanned document as part of the same call that carries your text instruction. It's the same Messages API, not a separate endpoint.

Every prompting technique covered so far -- system prompts, few-shot examples, a written output constraint -- shapes output by asking Claude to follow a format and hoping it does. That works on the inputs you tested and can still slip on an edge case you didn't, because a written instruction is a request, not an enforcement mechanism. Structured outputs take a different approach: through constrained decoding, the API itself narrows which tokens Claude is even allowed to generate next to whatever stays valid against your schema, so a response breaking that schema was never a token sequence the model had access to. That's a categorically different guarantee than "the model was told to produce JSON and usually does."

Two distinct mechanisms fall under structured outputs, and they constrain two different parts of a request. JSON outputs constrain the final response text -- set output_config.format with type json_schema and your schema, and the response text is guaranteed to match it. Strict tool use constrains the arguments Claude sends to a tool -- set strict: true directly on the tool definition, and Claude's arguments are validated against input_schema before your code ever runs.

Strict tool use matters most in agentic loops: a malformed tool argument doesn't just produce an odd response, it can crash the function it's handed to or trigger the wrong action outright. strict: true pushes that risk earlier in the pipeline -- by the time your code receives the call, the arguments have already passed validation against the contract you wrote, so there's nothing left to check before acting on them. This complements the manual schema-design discipline covered later in this module (required/optional fields, exclusion conditions in descriptions) -- that discipline decides what the schema means; strict: true guarantees Claude's arguments actually respect that shape every single time, not just on the inputs you happened to test.

• •First-request latency: before the API can enforce a schema it has to compile it into a grammar, a one-time build cost on the first call. That compiled grammar sits in cache for 24 hours since it was last used, so a schema that stays stable across many calls pays the build cost once; a workload that swaps schemas constantly re-pays it every time.
• •Input tokens tick up: turning on structured outputs makes the API inject its own system prompt describing the required format, and that addition is billed as ordinary input -- a small bump per call, but one to fold into a cost model once volume is high.
• •A schema guarantee isn't a success guarantee: stop_reason values of refusal (the model declined to answer for safety reasons) or max_tokens (generation was cut off partway) can still leave you without valid output, constraint or not. Your code still has to check stop_reason.
• •Won't combine with message prefilling: JSON outputs and prefilling the assistant's turn can't both govern one request -- pick whichever one the task actually needs.

A tool-use conversation is not plain text -- each turn's content is a list of typed blocks, and four block types do the work: text (Claude's prose), tool_use (a tool name, a unique id, and input arguments), tool_result (the matching tool_use_id, result content, and an optional is_error flag), and thinking (Claude's internal reasoning, present only when extended thinking is enabled, carrying an opaque signature).

The pairing invariant is the rule the exam leans on hardest: every tool_use block an assistant turn emits must be answered by a tool_result block with a matching id, in the user turn immediately after -- not two turns later, not with a mismatched id, not omitted. A violation fails request validation. This isn't a prompting problem; it's structural, and your code has to get the sequence right on every request. Domain 8 covers the broader question of who executes a tool call inside the agent loop; this note is about the wire-level block contract that loop has to satisfy underneath, regardless of who's driving it.

Streaming turns the tool_use block into a moving target. Its input argument arrives as a partial JSON string spread across many content_block_delta events, and that string is not valid JSON until content_block_stop fires. Parsing or acting on it earlier either throws on malformed JSON or, worse, occasionally succeeds on a syntactically valid but semantically incomplete fragment -- and the tool then runs with arguments missing. The discipline is simple: collect the deltas, act only after content_block_stop.

The same discipline extends to how a stream ends. A turn is complete only once message_stop has arrived -- not whenever the read loop happens to exit. If a handler commits whatever it accumulated to conversation history the moment its loop ends, a dropped network connection mid-tool_use-block leaves a partially-assembled block sitting in history. The next request then fails validation, and because the corrupted turn is now several messages back, the error looks unrelated to the dropped stream that actually caused it. On an interrupted stream, discard the partial assistant turn entirely and retry the original request -- don't save it and don't patch around it.

count_tokens is a dedicated endpoint that accepts the same request body you'd send to a real Messages API call -- model, messages, system, tools, everything -- and returns the token count that request would consume, without running inference. No completion is generated and no output tokens are billed; you get back a number that reflects the exact request shape, including the token weight of tool definitions and any images or documents in the payload.

This endpoint does two different jobs in the same lifecycle. During development, run it against production-shaped inputs -- not just short test fixtures -- to verify your context-budget assumptions actually hold; a budget that looks comfortable against an 800-token fixture can be badly wrong against a 3,200-token production tool result. In production, call it as a pre-flight gate before an expensive or context-sensitive request goes out, so an over-budget call gets compacted, trimmed, or rejected before you pay for it -- rather than discovering the overrun only after a model_context_window_exceeded stop_reason comes back.

Images are not free against the context budget, and the cost is computable, not vague. Claude views images in 28x28-pixel patches, and each patch is one visual token: visual_tokens = ceil(width / 28) x ceil(height / 28). A 1,000 x 1,000 pixel image works out to ceil(1000/28) x ceil(1000/28) = 36 x 36 = about 1,296 visual tokens. At that rate, a handful of full-resolution screenshots in one request can outweigh a substantial system prompt.

Each model tier has its own maximum native image resolution -- a long-edge pixel limit and a visual-token ceiling, and both differ by model tier and generation. An image that exceeds either limit is downscaled before processing, and the token-cost formula then runs on the scaled dimensions, not the original ones -- so a naive calculation against the original size will overstate the actual cost of an oversized image, while also losing whatever detail the downscale discarded.

PDFs get their own block type -- document, distinct from image. Inside it, the source follows the same shape used for images (base64, a URL, or a Files API file_id), though a document block doesn't require a name field the way some other blocks do. It supports optional title (a human-readable label) and context (extra metadata), and skipping both still produces a valid PDF submission.

Once loaded, a PDF's pages are tokenized under the same visual-token accounting as any other image content -- the patch formula and per-tier resolution limits both still apply. Separately, inline base64 encoding puts the full payload directly in the message content, which means it travels on every single request. That's fine for a genuinely one-off image or document, where an upload step would add complexity with no payoff. But for an asset reused across many requests -- a reference diagram, a standing policy PDF -- base64 means re-transferring (and, where it counts toward tokens, re-tokenizing) the same bytes on every call. That's exactly the case the Files API exists to solve: upload once, reference by file_id thereafter.