The exam is scenario-driven, but the confusing part is underneath the scenarios: what exactly goes into the Messages API, and what exactly comes back. Once you can picture the JSON, half the distractors in Domains 1 and 4 stop being plausible — because they describe a field that does not exist, or put a value in the wrong half of the round trip.
So this is not a set of exam scenarios. It is a construct reference. Eleven entries, each with the same four parts, in the same order:
| Part | What it gives you |
|---|---|
| 1 · Scenario | One paragraph — the situation in plain language. |
| 2 · Client code | The minimal Python that produces the call. |
| 3 · Request JSON | The body sent to the model, annotated field by field. |
| 4 · Response JSON | What comes back, annotated, including stop_reason. |
capture.py in this folder runs eight
of these scenarios against a live API key and writes the actual request and response bodies
to disk. See Capturing the real thing.
1 · The API is stateless. There is no conversation on the server. Every request
carries the entire history, and the model's "memory" is just the array you resend.
A 40-turn conversation means a 40-turn messages array on turn 40 — which is why
context and caching are cost questions, not just capacity questions.
2 · There are three inputs, and their order is fixed. The prompt is assembled as
tools → system → messages. That order is why tool
definitions sit at the very front of the cache prefix, and why editing your tool list
invalidates everything downstream of it.
3 · content is always an array of typed blocks — never a string. On the
way in you may write a plain string as a shorthand; on the way back you always get an array.
A response can hold a text block and two tool_use blocks at once.
content[0].text is the single most common bug in beginner Claude code.
4 · stop_reason is the router. It tells your code what to do next, and
the whole agentic loop is a switch over it:
| Value | What your code must do |
|---|---|
end_turn | Nothing — Claude finished. Exit the loop. |
tool_use | Execute the requested tool(s), append results, call again. |
max_tokens | Output was truncated mid-thought. Raise max_tokens or stream. |
stop_sequence | Hit one of your custom stop strings. |
pause_turn | A long server-side tool turn — resend to resume. Do not add "Continue." |
refusal | Declined on safety grounds. Check stop_details. |
thinking parameter runs adaptive thinking. But
display defaults to "omitted", so the reasoning is not readable in
the response; pass thinking: {"type": "adaptive", "display": "summarized"} to get
a summary back. The practical consequence for every example below: branch on
block.type rather than assuming content[0] is your text.POST /v1/messages — plus the Batches endpoint. Agent SDK shapes (hooks, subagent
spawn payloads) are deliberately excluded: they sit a layer above this one, and mixing them in
would blur the exact distinction this page exists to make. Entry 10 is the one place two
protocols appear side by side, and that contrast is the point of it.Scenario. The simplest possible call. One question, one answer, no tools, no system prompt, no history. Everything else on this page is this shape with more fields — so learn where each part lives here and the rest is additive.
import anthropic
client = anthropic.Anthropic() # reads ANTHROPIC_API_KEY from the environment
response = client.messages.create(
model="claude-opus-5",
max_tokens=1024,
messages=[{"role": "user", "content": "What is the capital of France?"}],
)
for block in response.content: # content is a LIST of typed blocks
if block.type == "text":
print(block.text)
POST https://api.anthropic.com/v1/messages
x-api-key: sk-ant-...
anthropic-version: 2023-06-01 ← required on every request, always this value
content-type: application/json
{
"model": "claude-opus-5", ← exact ID; never append a date suffix
"max_tokens": 1024, ← REQUIRED. A hard ceiling on the response
"messages": [
{
"role": "user", ← must be "user" for the first message
"content": "What is the capital of France?"
} a plain string here is shorthand for
] [{"type":"text","text":"..."}]
}
{
"id": "msg_01XFDUDYJgAACzvnptvVoYEL", ← log this; it is what support asks for
"type": "message",
"role": "assistant", ← always "assistant" on a response
"model": "claude-opus-5", ← which model actually served it
"content": [
{ "type": "text",
"text": "The capital of France is Paris." }
], ← an ARRAY. May also hold thinking / tool_use blocks
"stop_reason": "end_turn", ← finished naturally; nothing for you to do
"stop_sequence": null,
"usage": {
"input_tokens": 14, ← what you were billed to send
"output_tokens": 9 ← what you were billed to receive (5x the input rate)
}
}
content (an
array, always), stop_reason (your router), usage (your bill). Almost
every later entry changes only what is inside content and what
stop_reason says.Scenario. A third user message in an ongoing conversation, with a persistent instruction. This is where the statelessness becomes concrete: to ask the third question you must resend the first two exchanges, including Claude's own replies.
response = client.messages.create(
model="claude-opus-5",
max_tokens=1024,
system="You are a terse geography tutor. Answer in one sentence.",
messages=[
{"role": "user", "content": "What is the capital of France?"},
{"role": "assistant", "content": "Paris is the capital of France."}, # Claude's PRIOR reply
{"role": "user", "content": "And its population?"},
],
)
{
"model": "claude-opus-5",
"max_tokens": 1024,
"system": "You are a terse geography tutor. Answer in one sentence.",
← TOP-LEVEL, not a message with role "system"
"messages": [
{ "role": "user", "content": "What is the capital of France?" },
{ "role": "assistant", "content": "Paris is the capital of France." },
← you replay Claude's own words back to it
{ "role": "user", "content": "And its population?" }
← "its" only resolves because of the history above
]
}
{
"id": "msg_01BqXR7kL2mNpQrStUvWxYz",
"type": "message", "role": "assistant", "model": "claude-opus-5",
"content": [
{ "type": "text",
"text": "Paris has a population of roughly 2.1 million in the city proper." }
],
"stop_reason": "end_turn",
"stop_sequence": null,
"usage": {
"input_tokens": 48, ← grew: the whole history is re-billed every turn
"output_tokens": 17
}
}
input_tokens climbs on
every turn because you resend everything. A long chat is quadratic in total tokens, not
linear — turn N re-bills turns 1…N−1. That is the entire economic case for prompt caching,
and the reason context management is a Domain 5 topic rather than a footnote.user. Consecutive same-role messages are legal — the API merges them into one
turn. The exception: on Claude Opus 5 you may append a {"role": "system"}
message mid-array for an operator instruction that arrives late — it must follow a user
message and cannot be messages[0]. That is a cache-preserving trick, not the
normal way to set a system prompt.stop_reason: "tool_use"Scenario. You give Claude a tool and ask something it cannot answer without it. Claude does not call anything — it asks you to, and stops. Nothing has executed yet; the ball is in your court.
WEATHER_TOOL = {
"name": "get_weather",
"description": "Get the current weather for a location. Call this whenever the user "
"asks about current conditions, temperature, or whether to bring a coat.",
"input_schema": {
"type": "object",
"properties": {
"location": {"type": "string", "description": "City and country, e.g. Paris, France"},
"unit": {"type": "string", "enum": ["celsius", "fahrenheit"]},
},
"required": ["location"],
},
}
response = client.messages.create(
model="claude-opus-5", max_tokens=1024,
tools=[WEATHER_TOOL],
messages=[{"role": "user", "content": "What is the weather in Paris?"}],
)
print(response.stop_reason) # "tool_use"
{
"model": "claude-opus-5",
"max_tokens": 1024,
"tools": [ ← rendered FIRST in the prompt, before system
{
"name": "get_weather", ← how Claude will refer to it
"description": "Get the current weather for a location. Call this whenever
the user asks about current conditions, temperature, or
whether to bring a coat.",
← the selection mechanism. Say WHEN, not just what
"input_schema": { ← snake_case here. (MCP spells it inputSchema — entry 10)
"type": "object",
"properties": {
"location": { "type": "string", "description": "City and country, e.g. Paris, France" },
"unit": { "type": "string", "enum": ["celsius", "fahrenheit"] }
← enum beats prose for a fixed value set
},
"required": ["location"] ← "unit" is optional; Claude may omit it
}
}
],
"messages": [
{ "role": "user", "content": "What is the weather in Paris?" }
]
}
{
"id": "msg_01Aq9w8ZfLmNoPqRsTuVwXyZ",
"type": "message", "role": "assistant", "model": "claude-opus-5",
"content": [
{ "type": "text",
"text": "Let me check the current weather in Paris." },
← optional. Claude may or may not narrate first
{ "type": "tool_use",
"id": "toolu_01A09q90qw90lq917835lq9",
← REMEMBER THIS ID. You must echo it back verbatim
"name": "get_weather",
"input": { "location": "Paris, France" }
← already parsed JSON, matching your input_schema.
} Note "unit" is absent — it was optional
],
"stop_reason": "tool_use", ← THE SIGNAL: Claude is waiting on you
"stop_sequence": null,
"usage": { "input_tokens": 384, "output_tokens": 65 }
← input jumped: the tool definition is part of the prompt
}
tool_use block is a request,
not an execution. The model has no ability to reach your function — it emits a structured
intention and stops. Every side effect in an agent happens in your code, which is why
approval gates live client-side and are actually enforceable.tool_result — and ID pairingScenario. You ran get_weather("Paris, France") and got
"18°C, light rain". Now you hand it back. The surprise for most people: the result goes in a
message with role user, not "tool" — and it must quote the exact ID from entry 03.
tool_use = next(b for b in response.content if b.type == "tool_use")
result = execute_tool(tool_use.name, tool_use.input) # your code, your risk
followup = client.messages.create(
model="claude-opus-5", max_tokens=1024,
tools=[WEATHER_TOOL], # tools must still be present
messages=[
{"role": "user", "content": "What is the weather in Paris?"},
{"role": "assistant", "content": response.content}, # the WHOLE content array
{"role": "user", "content": [{
"type": "tool_result",
"tool_use_id": tool_use.id, # exact echo
"content": result,
}]},
],
)
{
"model": "claude-opus-5",
"max_tokens": 1024,
"tools": [ { "name": "get_weather", ... } ],
← still required. Dropping it 400s: the history
references a tool the request no longer declares
"messages": [
{ "role": "user", "content": "What is the weather in Paris?" },
{ "role": "assistant", ← replay Claude's turn EXACTLY as it came back
"content": [
{ "type": "text", "text": "Let me check the current weather in Paris." },
{ "type": "tool_use",
"id": "toolu_01A09q90qw90lq917835lq9",
"name": "get_weather",
"input": { "location": "Paris, France" } }
] },
{ "role": "user", ← "user", NOT "tool". There is no tool role
"content": [
{ "type": "tool_result",
"tool_use_id": "toolu_01A09q90qw90lq917835lq9",
← must match the tool_use id character for character
"content": "18°C, light rain, wind 12 km/h"
} ← a string, or an array of blocks for richer results
] }
]
}
{
"id": "msg_01CdEfGhIjKlMnOpQrStUvWx",
"type": "message", "role": "assistant", "model": "claude-opus-5",
"content": [
{ "type": "text",
"text": "It's currently 18°C in Paris with light rain and a 12 km/h wind — worth taking an umbrella." }
],
"stop_reason": "end_turn", ← Claude had what it needed. The loop ends here
"stop_sequence": null,
"usage": { "input_tokens": 471, "output_tokens": 31 }
}
tool_result without replaying
the tool_use block that caused it — an orphaned result referencing an ID the
conversation never mentioned.{"role": "assistant", "content": block.text}
silently discards the tool_use block. Append response.content, the
whole array.tool_use_id. The pairing is how the API knows
which request this answers; there is no positional fallback.Scenario. Entries 03 and 04 joined up, seen as one flow. This is the
agentic loop in its entirety — there is nothing else to it. Two HTTP requests, one tool
execution in between, and a stop_reason switch controlling the whole thing.
stop_reasonmessages = [{"role": "user", "content": "What is the weather in Paris?"}]
while True:
response = client.messages.create(
model="claude-opus-5", max_tokens=1024,
tools=[WEATHER_TOOL], messages=messages,
)
if response.stop_reason == "end_turn":
break # done
if response.stop_reason == "pause_turn": # long server-tool turn
messages.append({"role": "assistant", "content": response.content})
continue # resend; do NOT add "Continue."
# stop_reason == "tool_use"
messages.append({"role": "assistant", "content": response.content}) # whole array
results = []
for block in response.content:
if block.type == "tool_use":
results.append({
"type": "tool_result",
"tool_use_id": block.id,
"content": execute_tool(block.name, block.input),
})
messages.append({"role": "user", "content": results}) # ALL results, ONE message
print(next(b.text for b in response.content if b.type == "text"))
┌─ REQUEST 1 ─────────────────────────────────────────────────────────┐
│ messages: [ user:"What is the weather in Paris?" ] │
│ tools: [ get_weather ] │
└─────────────────────────────────────────────────────────────────────┘
↓
┌─ RESPONSE 1 ────────────────────────────────────────────────────────┐
│ content: [ text, tool_use(id=toolu_01A09…, {location:"Paris"}) ] │
│ stop_reason: "tool_use" ← your loop does NOT exit │
│ usage: in 384 / out 65 │
└─────────────────────────────────────────────────────────────────────┘
↓
YOUR CODE RUNS THE TOOL — no network call to Anthropic
get_weather({"location": "Paris, France"}) → "18°C, light rain"
↓
┌─ REQUEST 2 ─────────────────────────────────────────────────────────┐
│ messages: [ user:"What is the weather in Paris?", │
│ assistant:[text, tool_use(id=toolu_01A09…)], ← replay │
│ user:[tool_result(tool_use_id=toolu_01A09…)] ← pairing │
│ tools: [ get_weather ] ← still present │
└─────────────────────────────────────────────────────────────────────┘
↓
┌─ RESPONSE 2 ────────────────────────────────────────────────────────┐
│ content: [ text:"It's currently 18°C in Paris…" ] │
│ stop_reason: "end_turn" ← loop exits │
│ usage: in 471 / out 31 ← request 1's tokens re-billed │
└─────────────────────────────────────────────────────────────────────┘
end_turn, not on an answer.
Beginner loops test "did I get text back?" — but a tool_use response often
contains text too (the narration in entry 03). Switch on stop_reason; it is the
only reliable signal.Scenario. "Compare the weather in Paris, Tokyo and Cairo." Claude does
not need the first answer to know it wants the other two, so it emits three
tool_use blocks in a single assistant turn. Parallel calling is on by
default.
{
"id": "msg_01DeFgHiJkLmNoPqRsTuVwXy",
"type": "message", "role": "assistant", "model": "claude-opus-5",
"content": [
{ "type": "text", "text": "I'll check all three cities." },
{ "type": "tool_use", "id": "toolu_01aaa", "name": "get_weather",
"input": { "location": "Paris, France" } },
{ "type": "tool_use", "id": "toolu_01bbb", "name": "get_weather",
"input": { "location": "Tokyo, Japan" } },
{ "type": "tool_use", "id": "toolu_01ccc", "name": "get_weather",
"input": { "location": "Cairo, Egypt" } }
← three blocks, three DISTINCT ids, one turn
],
"stop_reason": "tool_use", ← still just "tool_use" — no plural variant
"usage": { "input_tokens": 402, "output_tokens": 132 }
}
{ "role": "user",
"content": [
{ "type": "tool_result", "tool_use_id": "toolu_01aaa", "content": "18°C, light rain" },
{ "type": "tool_result", "tool_use_id": "toolu_01bbb", "content": "24°C, clear" },
{ "type": "tool_result", "tool_use_id": "toolu_01ccc", "content": "35°C, sunny" }
] } ← order does not matter; the ids do the pairing
for loop throws away the entire benefit. And if one fails, still return a
tool_result for it with is_error: true (entry 09) — never drop a
block, or you orphan an ID."disable_parallel_tool_use": true
inside tool_choice — e.g.
{"type": "auto", "disable_parallel_tool_use": true}. It is a field on
tool_choice, not a top-level request parameter.tool_choice: three responses, same request otherwiseScenario. The user says "Hello! How are you today?" — a message that
plainly needs no weather tool. Holding everything else constant and changing only
tool_choice shows exactly what the parameter controls.
"tool_choice": { "type": "auto" } ← default. Claude decides
"tool_choice": { "type": "any" } ← must call SOMETHING, model picks which
"tool_choice": { "type": "tool", "name": "get_weather" } ← must call THIS one
"tool_choice": { "type": "none" } ← may not call anything
{"type": "auto"} "content": [
{ "type": "text", "text": "I'm doing well, thank you! How can I help you today?" }
],
"stop_reason": "end_turn" ← correctly ignored the tool. No call needed
{"type": "any"} "content": [
{ "type": "tool_use", "id": "toolu_01ddd", "name": "get_weather",
"input": { "location": "New York, USA" } }
← forced to call something, so it invented a plausible
], argument. The user never mentioned a city
"stop_reason": "tool_use"
{"type": "tool", "name": "get_weather"} "content": [
{ "type": "tool_use", "id": "toolu_01eee", "name": "get_weather",
"input": { "location": "London, UK" } }
← same story: a required argument had to come from
], somewhere, so the model supplied one
"stop_reason": "tool_use"
required: ["location"], so on a greeting it fabricates a location. Note also that
with any or a forced tool, the narrating text block disappears: there
is no room for "let me check" when the turn must be a tool call.Scenario. You need JSON you can hand straight to
json.loads() and then to a typed model — no "sometimes it wraps it in a code
fence" defensive parsing. Two different mechanisms do this, and they solve different halves of
the problem.
output_config.format — constrains the RESPONSE{
"model": "claude-opus-5",
"max_tokens": 1024,
"output_config": {
"format": {
"type": "json_schema",
"schema": {
"type": "object",
"properties": {
"name": { "type": "string" },
"email": { "type": "string" },
"plan": { "type": "string" },
"demo_requested": { "type": "boolean" }
},
"required": ["name", "email", "plan", "demo_requested"],
"additionalProperties": false ← REQUIRED on every object. Not optional
}
}
},
"messages": [ { "role": "user",
"content": "Extract: Jane Doe (jane@co.com) wants Enterprise and asked for a demo." } ]
}
"content": [
{ "type": "text",
"text": "{\"name\":\"Jane Doe\",\"email\":\"jane@co.com\",\"plan\":\"Enterprise\",\"demo_requested\":true}" }
], ← still a text block — but guaranteed-valid JSON inside it
"stop_reason": "end_turn"
strict: true — constrains the TOOL INPUT "tools": [ {
"name": "book_flight",
"description": "Book a flight to a destination",
"strict": true, ← TOP-LEVEL on the tool. NOT inside tool_choice,
and not inside input_schema
"input_schema": {
"type": "object",
"properties": {
"destination": { "type": "string" },
"date": { "type": "string", "format": "date" },
"passengers": { "type": "integer", "enum": [1,2,3,4,5,6,7,8] }
},
"required": ["destination", "date", "passengers"],
"additionalProperties": false
} } ]
WITHOUT strict — the schema is a strong hint, and hints are sometimes missed:
{ "type": "tool_use", "name": "book_flight",
"input": { "destination": "Tokyo",
"passengers": "two", ← STRING where the schema said integer
"date": "March 15" } } ← not an ISO date; "format":"date" was advisory
→ your code raises on int("two"), mid-agent, at runtime.
WITH strict: true — the decoder is constrained as tokens are generated:
{ "type": "tool_use", "name": "book_flight",
"input": { "destination": "Tokyo", "date": "2026-03-15", "passengers": 2 } }
→ the invalid shape is not merely rejected. It cannot be produced.
enum, const, anyOf,
allOf, $ref/$def, the string format
keywords, and additionalProperties: false (required). Not supported:
recursive schemas, numeric bounds (minimum/maximum), string length
bounds, and complex array constraints. Note the workaround visible above — passengers
uses enum: [1..8] precisely because maximum: 8 is unavailable.stop_reason of max_tokens gives you truncated — therefore invalid —
JSON, and a refusal bypasses the schema entirely. Check
stop_reason before you parse. Structured outputs are also incompatible with
citations (400) and with prefilling.is_error on a tool_result, and what happens nextScenario. Claude asked for the weather in "Atlantis". Your API returns 404. You have three options — crash, lie, or tell Claude the truth in a form it can act on. Only the third keeps the agent running.
{ "role": "user",
"content": [
{ "type": "tool_result",
"tool_use_id": "toolu_01fff", ← still required. An error is still an ANSWER
"content": "Error: no location named 'Atlantis'. Provide a real city and country.",
← write it for the model to act on, not for a log file
"is_error": true ← snake_case. (MCP spells it isError — entry 10)
}
] }
"content": [
{ "type": "text",
"text": "I couldn't find a location called Atlantis — it isn't a real city. Did you mean Atlanta, in the USA?" }
],
"stop_reason": "end_turn" ← recovered in one turn, without a retry loop
tool_result for a
failed call — because "it didn't work, so there's nothing to send" — leaves a
tool_use with no answer, which is a 400 on the next request. Every
tool_use gets exactly one tool_result, success or failure.is_error: true is your tool reporting a failure — HTTP 200, the
conversation continues, Claude sees it and adapts. An HTTP 4xx/5xx from
/v1/messages is the API itself failing — no response body to hand to
Claude, and your SDK raises. The first is a conversation event; the second is an outage.Scenario. The single most clarifying entry on this page. An MCP tool and a hand-written tool look identical to the model — MCP is a protocol between the host and your server, and the model never speaks it. Here are both wire formats for the same tool, stacked.
{
"model": "claude-opus-5",
"max_tokens": 1024,
"mcp_servers": [ ← Anthropic makes the MCP connection server-side
{ "type": "url",
"url": "https://weather.example.com/mcp",
"name": "weather-mcp" }
],
"tools": [
{ "type": "mcp_toolset",
"mcp_server_name": "weather-mcp" } ← MUST match a name in mcp_servers
],
"messages": [ { "role": "user", "content": "What is the weather in Paris?" } ]
}
requires header: anthropic-beta: mcp-client-2025-11-20
mcp_servers without the
matching mcp_toolset entry in tools is a validation error, not a
silent no-op. Every server listed must be referenced by exactly one toolset.→ discovery, at connection time the HOST asks; the model is not involved
{ "jsonrpc": "2.0", "id": 1, "method": "tools/list" }
← the server answers
{ "jsonrpc": "2.0", "id": 1,
"result": { "tools": [
{ "name": "get_weather",
"description": "Get the current weather for a location.",
"inputSchema": { ← camelCase. The Messages API says input_schema
"type": "object",
"properties": { "location": { "type": "string" } },
"required": ["location"] } } ] } }
→ invocation
{ "jsonrpc": "2.0", "id": 2, "method": "tools/call",
"params": { "name": "get_weather",
"arguments": { "location": "Paris, France" } } }
← "arguments". The Messages API says "input"
← the result
{ "jsonrpc": "2.0", "id": 2,
"result": { "content": [ { "type": "text", "text": "18°C, light rain" } ],
"isError": false } } ← camelCase. The Messages API says is_error
| Concept | MCP (JSON-RPC) | Messages API |
|---|---|---|
| Tool's schema | inputSchema | input_schema |
| Call arguments | params.arguments | tool_use.input |
| Failure flag | isError | is_error |
| Correlation | id (JSON-RPC, integer) | tool_use_id (string) |
| Discovery | tools/list, at connect time | tools[], on every request |
| Naming | get_weather | mcp__weather-mcp__get_weather (host-prefixed) |
tool_use block. Every
design decision in MCP
Skeletons is about what lands in that right-hand column.custom_id, retrievalScenario. Ten thousand support tickets to classify. Latency is irrelevant; cost is not. The Batches API runs the same Messages requests asynchronously at 50% of standard price — the same request bodies, wrapped in an envelope.
from anthropic.types.message_create_params import MessageCreateParamsNonStreaming
from anthropic.types.messages.batch_create_params import Request
batch = client.messages.batches.create(requests=[
Request(custom_id=f"ticket-{t.id}",
params=MessageCreateParamsNonStreaming(
model="claude-haiku-4-5", max_tokens=50,
messages=[{"role": "user", "content": f"Classify: {t.body}"}]))
for t in tickets
])
while client.messages.batches.retrieve(batch.id).processing_status != "ended":
time.sleep(60)
for result in client.messages.batches.results(batch.id):
if result.result.type == "succeeded":
store(result.custom_id, result.result.message.content[0].text)
POST /v1/messages/batches{
"requests": [
{ "custom_id": "ticket-8814", ← YOUR key. The ONLY way to match results back
"params": { ← a complete, ordinary Messages API body
"model": "claude-haiku-4-5",
"max_tokens": 50,
"messages": [ { "role": "user", "content": "Classify: my order never arrived" } ]
} },
{ "custom_id": "ticket-8815",
"params": { "model": "claude-haiku-4-5", "max_tokens": 50,
"messages": [ { "role": "user", "content": "Classify: love the new packaging" } ] } }
]
} up to 100,000 requests or 256 MB per batch
{
"id": "msgbatch_013Zva2CMHLNnXjNJJKqJ2EF",
"type": "message_batch",
"processing_status": "in_progress", ← in_progress → ended. Poll this, not the results
"request_counts": {
"processing": 2, "succeeded": 0, "errored": 0, "canceled": 0, "expired": 0
},
"created_at": "2026-08-23T11:02:14.061162Z",
"expires_at": "2026-08-24T11:02:14.061162Z",
← 24h ceiling; most batches finish within the hour
"results_url": null ← populated only once processing_status is "ended"
}
{ "custom_id": "ticket-8815", ← NOTE THE ORDER: 8815 came back before 8814
"result": { "type": "succeeded",
"message": { "id": "msg_01…", "type": "message", "role": "assistant",
"content": [ { "type": "text", "text": "positive" } ],
"stop_reason": "end_turn",
"usage": { "input_tokens": 19, "output_tokens": 2 } } } }
{ "custom_id": "ticket-8814",
"result": { "type": "errored",
"error": { "type": "invalid_request", ← invalid_request = your bug, do not retry blindly.
"message": "…" } } } Anything else is server-side and safe to retry
custom_id exists, and the mistake the exam probes: zipping the results list
against your input list by position silently mis-labels your data, with no error anywhere. Key
by custom_id, always. And note that each result carries its own
type — succeeded, errored, canceled,
expired — so a batch that "ended" is not a batch that all worked.params object is an
ordinary Messages body — tools, vision, caching, structured outputs all work. What you give up
is streaming and latency; what you get is half price. Results stay available for 29 days.| Field | Where | Notes |
|---|---|---|
model | request, top level | Exact ID, no date suffix. Echoed in the response. |
max_tokens | request, top level | Required. A ceiling the model is unaware of; hitting it gives stop_reason: "max_tokens". |
system | request, top level | Not a message. String, or an array of blocks when you need cache_control. |
tools | request, top level | Rendered first, before system. Must stay present for the whole conversation. |
tool_choice | request, top level | auto / any / tool / none. Hosts disable_parallel_tool_use. |
strict | request, on a tool | Top-level on the tool object — not in input_schema, not in tool_choice. |
output_config | request, top level | Holds format (JSON schema) and effort. Replaces the deprecated output_format. |
content | both | String shorthand accepted inbound; always an array outbound. |
tool_use.id | response block | Echo verbatim as tool_use_id. No positional fallback. |
is_error | request, on a tool_result | Your tool failed. Not an HTTP error. |
stop_reason | response, top level | The loop router. Six values. |
stop_details | response, top level | Populated only when stop_reason == "refusal"; null otherwise. Guard before reading. |
usage | response, top level | input_tokens, output_tokens, plus cache_creation_input_tokens / cache_read_input_tokens. |
custom_id | batches only | Your correlation key. Results come back unordered. |
This is the complete list for POST /v1/messages, checked against Anthropic's API reference on 31 October 2026 (API version 2026-10-21). Each row has a study label:
Must know means questions test it directly, so learn what it does and when to use it. Recognise means you should know what it's for if it appears in an option. Skip means it's not on the exam, and you can learn it later if you build with it.
| Header | What it does | Study |
|---|---|---|
x-api-key or Authorization: Bearer | Your credential | Skip |
anthropic-version | Which API version to use | Skip |
anthropic-beta | Turns on beta features | Recognise |
anthropic-workspace-id, anthropic-user-profile-id | Which workspace or user the request belongs to | Skip |
| Field | What it does | Study |
|---|---|---|
model (required) | Which Claude model answers | Must know |
max_tokens (required) | Maximum length of the reply. The model doesn't know about this limit; reaching it gives stop_reason: "max_tokens" | Must know |
messages (required) | The conversation history, which you resend in full every time because the API keeps no state | Must know |
system | The system prompt: role, rules and tone | Must know |
tools | The tools Claude may ask you to run | Must know |
tool_choice | auto, any, tool (one named tool) or none, plus disable_parallel_tool_use | Must know |
output_config.format | Structured outputs: the reply must match your JSON schema. Not in the exam guide, which uses a tool with a schema instead (see Exam vs 2026) | Recognise |
cache_control | Prompt caching, which saves cost and time when the start of the request repeats. The exam guide only expects you to know it exists | Recognise |
stream | Sends the reply as it's generated, as a series of events | Recognise |
stop_sequences | Strings that stop generation when they appear | Recognise |
thinking | Lets Claude reason before answering (adaptive on current models) | Recognise |
output_config.effort | low to max: trades thoroughness against cost | Recognise |
metadata.user_id | An anonymous user ID for abuse tracking | Skip |
service_tier, speed, inference_geo | Capacity tier, fast mode, and the region where the model runs | Skip |
container | Container for code execution and Skills | Skip |
diagnostics | Asks the API to explain why the cache missed | Skip |
temperature, top_p, top_k | Sampling settings. They return an error on API version 2026-10-21, but older material still mentions them | Recognise |
Beta only: fallbacks, context_management, mcp_servers, task_budget | Switch model after a refusal; clear or compact old context; connect remote MCP servers; a token budget for an agent loop | Skip |
messages[].content| Block | Used for | Study |
|---|---|---|
text | Plain text | Must know |
tool_result (tool_use_id, content, is_error) | Your tool's answer, linked to Claude's call by ID. is_error: true means the tool ran but failed | Must know |
tool_use | Claude's earlier tool call, sent back as part of the history | Must know |
document | A PDF or text file (base64, URL or file ID), with optional citations | Recognise |
image | A picture (base64, URL or file ID) | Recognise |
thinking, redacted_thinking | Claude's earlier thinking, sent back unchanged | Skip |
search_result, container_upload, server-tool result blocks | Your own search results to cite, files for the container, earlier built-in tool results | Skip |
tools[]| Field | What it does | Study |
|---|---|---|
name | The tool's name | Must know |
description | The main thing Claude reads when choosing a tool. Vague descriptions cause wrong choices | Must know |
input_schema | JSON Schema for the inputs. Used as a form, it's also how you get structured data out | Must know |
strict | Guarantees the inputs match the schema exactly (the shape, not whether the values are correct) | Must know |
defer_loading | Hides the tool until tool search finds it, for when there are too many tools | Recognise |
input_examples | Example inputs for the tool | Recognise |
cache_control, allowed_callers, eager_input_streaming | Cache breakpoint, programmatic tool calling, streaming large inputs | Skip |
Built-in tools by type | Web search, web fetch, code execution, bash, text editor, memory, tool search, computer and browser toolsets | Recognise |
| Field | What it is | Study |
|---|---|---|
content | A list of blocks: text, tool calls, thinking | Must know |
stop_reason | Why Claude stopped. Your loop decides what to do next from this field | Must know |
usage | Token counts, used for cost and caching | Must know |
id, type, role, model | Message ID, always "message", always "assistant", the model that answered | Recognise |
stop_sequence | Which of your stop strings was hit | Skip |
stop_details | Only for refusals: category and explanation | Skip |
container, diagnostics | Container info, and the reason for a cache miss | Skip |
stop_reason values| Value | Meaning, and what your code does | Study |
|---|---|---|
tool_use | Claude wants a tool run: run it, send a tool_result, and loop again | Must know |
end_turn | Claude has finished: stop the loop and show the answer | Must know |
max_tokens | The reply hit your length limit: raise max_tokens or continue | Recognise |
stop_sequence | One of your stop strings appeared | Recognise |
pause_turn | A long server-side turn was paused: send it back to continue | Skip |
refusal | Declined for safety reasons: read stop_details | Skip |
model_context_window_exceeded | The conversation is too long: trim or compact it | Skip |
content| Block | What it contains | Study |
|---|---|---|
text | The answer, plus citations when documents were cited | Must know |
tool_use (id, name, input) | Claude asking you to run a tool. input is the filled-in form, and id must be echoed back as tool_use_id | Must know |
thinking, redacted_thinking | Claude's reasoning (often hidden), with a signature | Recognise |
server_tool_use and built-in tool result blocks | Web search, web fetch, code execution and tool search calls and their results | Skip |
container_upload | A file created in the container | Skip |
usage| Field | Meaning | Study |
|---|---|---|
input_tokens, output_tokens | Tokens in and out. Output includes thinking | Must know |
cache_creation_input_tokens, cache_read_input_tokens | Tokens written to the cache, and tokens read from it (much cheaper). If the read count stays at zero, the cache isn't working | Recognise |
cache_creation (5-minute and 1-hour breakdown), output_tokens_details.thinking_tokens | More detailed breakdowns | Skip |
server_tool_use, service_tier, speed, inference_geo | Built-in tool request counts, capacity tier, speed and region used | Skip |
stream: true)| Event | What it carries | Study |
|---|---|---|
message_start, content_block_start, content_block_delta, content_block_stop, message_delta, message_stop | The reply in pieces. Deltas carry text, tool input JSON, thinking or citations. message_delta carries the final stop_reason and usage | Skip |
model, max_tokens, messages, system, tools (with name, description, input_schema and strict), tool_choice (auto, any, forced), tool_use and tool_result with is_error, stop_reason (tool_use and end_turn), and usage (input_tokens, output_tokens). For guaranteed JSON, the exam expects a tool with a schema, not output_config.format. Prompt caching and streaming are out of scope beyond knowing they exist. Those are about a dozen fields, and they cover nearly every API-level question.The shapes above are documented, not transcribed. To replace them with genuine captures from your own account:
cd CCA-F/Wire-Format-Reference
pip install anthropic
export ANTHROPIC_API_KEY=sk-ant-...
python capture.py # all eight capturable scenarios
python capture.py 03 07a # or just these
It POSTs each scenario with client.messages.with_raw_response.create(...) — the
raw HTTP body, not the parsed SDK object — and writes
captured/<id>_<name>/request.json and response.json. Total
cost is a few cents at the max_tokens it sets.
Entries 04, 05 and 09 need a tool to actually execute between calls, entry 10 needs a live MCP server, and entry 11 is asynchronous — the script says so at the bottom and skips them rather than faking them.
msg_01… ID come back with your own token counts are different kinds of
knowing, and the second one survives exam pressure better.| Entry | Domain | The question shape it answers |
|---|---|---|
| 1 · Single turn | D1 · Messages API substrate | "What is in a request/response?" |
| 2 · System + history | D1 · Statelessness | "Why do costs grow through a conversation?" |
3 · tool_use | D1 · Stop reasons · D2 · Tool definition | "What does the model return when it wants a tool?" |
4 · tool_result | D2 · The contract | "Why does this request 400?" |
| 5 · Full loop | D1 · Loop mechanics | "Walk through an agentic turn" |
| 6 · Parallel calls | D2 · Parallel tool use | "Claude stopped batching calls" |
7 · tool_choice | D2 · Tool choice control | "It called the tool with a made-up argument" |
| 8 · Structured output | D4 · Structured outputs | "Guarantee parseable JSON" |
9 · is_error | D2 · Results & errors | "How should a failing tool report?" |
| 10 · MCP both sides | D2 · MCP fundamentals | "What does the model actually see from MCP?" |
| 11 · Batches | D5 · Cost & throughput | "10k items, latency irrelevant" |
Pair this with MCP Skeletons — that page is about what to put in the tool list; this one is about what the wire does with it. Then re-sit Domain 1 sets 2–3 and Domain 2 sets 1 and 3.