The Messages API request shape

Everything in this exam's biggest domain hangs off one endpoint. Learn its shape properly once and a third of the questions stop being scary.

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." }]
}

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. If your parser assumes content[0].text exists, it will explode the first time the model reaches for a tool.

stop_reason is your control flow

The response tells you why generation ended, and your code branches on it. Four values carry almost all the weight:

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.

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.