The Messages API request shape

A third of this exam hangs off one endpoint. One. Learn its shape properly in the next twenty minutes and the biggest domain stops being scary, because most of what looks like a hard question turns out to be a shape question wearing a costume.

And the fastest way to lose those marks is muscle memory. Almost everyone arrives here having written a thousand OpenAI-shaped requests, and two of the habits transfer wrong.

The four keys that matter

A Messages API request is a JSON body. Three fields are required and the fourth is the one people forget is not a message.

{
  "model": "claude-sonnet-5",
  "max_tokens": 1024,
  "messages": [
    { "role": "user", "content": "Summarise this in one line." }
  ]
}

model, max_tokens, messages. That is the whole requirement. max_tokens has no default, which trips people who came from other providers where you can omit it and get whatever the model feels like.

And then system:

{
  "model": "claude-sonnet-5",
  "max_tokens": 1024,
  "system": "You are a terse code reviewer.",
  "messages": [{ "role": "user", "content": "Review this diff." }]
}

Think of system as a dial on the outside of the box rather than an item inside it. It configures the call; it is not a turn in the conversation. Precisely: system is a top-level request parameter, a sibling of model and messages, and it never appears inside the messages array.

Content blocks are the real unit

content can be a plain string, which is sugar. Underneath, content is always an array of typed blocks, and once you do anything interesting you write the array yourself.

{
  "role": "user",
  "content": [{ "type": "text", "text": "Summarise this in one line." }]
}

The block types you will meet: text, image, document, tool_use, tool_result, and thinking. An assistant response is also a list of blocks, which is why a single reply can contain a paragraph of text and two tool calls at the same time.

This is the second habit that transfers wrong. If your parser assumes content[0].text exists, it will work perfectly right up until the first time the model reaches for a tool, and then it will hand undefined to something downstream that was never designed to receive it. Select blocks by their type, never by their index.

stop_reason is your control flow

The response tells you why generation ended, and your code branches on it. There are seven documented values. Four carry almost all the weight day to day:

end_turn means Claude finished naturally. Ship it.

max_tokens means you cut it off. The text is truncated, not wrong. Raise the budget or ask for less.

stop_sequence means one of your stop_sequences fired.

tool_use means the response contains at least one tool_use block and Claude is waiting on you. This is not an error, it is the middle of a loop, and treating it as terminal is the classic bug in a hand-rolled integration.

The other three are rarer but real, and a switch that does not handle them falls through to a default branch that was written for something else:

pause_turn means a server-tool loop hit its iteration limit, ten by default. Append the assistant turn and send again; the server picks up where it stopped. Do not add a “continue” message, and do not treat it as failure.

refusal means a safety classifier declined. It arrives as a normal HTTP 200, not an error, with a stop_details object naming the policy category. The practical consequence is the one that bites: code that reads content[0] unconditionally breaks here, because on a pre-output refusal content is empty.

model_context_window_exceeded means the context window filled, which is a different failure from max_tokens and wants a different fix: compact or split the conversation rather than raising a budget.

Usage comes back alongside it: input tokens, output tokens, and, once caching is in play, separate counts for cache creation and cache reads. Those fields are where every cost lesson later in this course lands, so notice now that the API tells you what you spent on every single call. You never have to guess.