The Messages API Spec — Every Field In, Every Field Out

🧭 Why this page exists: an agent is two JSON shapes and a loop. The request you send and the response you get back are the entire contract between your deterministic code and the model — every SDK, every agent framework, Claude Code itself, is sugar over these two objects. Learn both field-by-field once and roughly 80% of "agent knowledge" collapses into "and then my code branches on that field." The rest of this guide assumes you can see the JSON under every SDK call.

flowchart LR
  H[Your harness
deterministic code] -->|"REQUEST JSON
model · max_tokens · system
tools · messages[]"| A["POST /v1/messages"]
  A -->|"RESPONSE JSON
content[] · stop_reason
usage"| H
  H -->|"branch on stop_reason
append assistant turn verbatim
append tool_result → call again"| H

💡 Every field name below is clickable — it opens a drill-down card with the same six tiles every time: type · required · who sets it · possible values · changes per turn? · side effects — plus origin, example and its place in the loop. Cards link to each other; the breadcrumb takes you back.

The envelope — headers and the endpoint

REQUEST — every top-level field

The two required fields are model and max_tokens, plus a non-empty messages array. Everything else shapes how the model answers.

🪤 Trap: system and tools are not inside messages. They ride alongside it as separate fields, re-sent each call — which is exactly what makes them a byte-identical stable prefix that prompt caching can hit while messages grows.

messages[] — anatomy

Each element is { "role": "user" | "assistant", "content": string | block[] } — drill into role and content. A string is shorthand for one text block.

Its lifecycle in production — four decisions your harness makes about this array, every turn. None of them is the model's:

Block types you SEND (inside content arrays):

tools[] — anatomy

{
  "name": "get_order",
  "description": "Look up one order's shipping status by order id.",
  "input_schema": {
    "type": "object",
    "required": ["order_id"],
    "properties": { "order_id": { "type": "string" } },
    "additionalProperties": false
  },
  "strict": true
}

How the model chooses among many — it reads this catalogue as text, every call, and picks by the meaning of name + description + parameter descriptions. No registry, no index. The full story with an annotated definition: how the model picks a tool.

RESPONSE — every top-level field

HTTP 200 carries this object. Read it in this order: stop_reason → content[] → usage.

usage fields: input_tokens (uncached, full price) · output_tokens · cache_creation_input_tokens (written to cache, ~1.25×) · cache_read_input_tokens (served from cache, ~0.1×). If cache_read_input_tokens stays 0 across identical-prefix calls, a silent cache invalidator is in your prompt.

content[] — block types you RECEIVE

🪤 Trap: content[0].text is the bug that ships. A text block may precede the tool_use block ("Let me look that up." then the call), thinking blocks may come first, and a tool_use-only turn has no text at all. Always iterate and branch on type.

stop_reason — the closed enum your loop branches on

🎯 Exam lens: the set is defined by Anthropic and closed — your harness and your tools can't add values. "Which field tells the harness whether to run a tool or return to the user?" is stop_reason, not the presence of a tool_use block (though in practice they agree).

When it is NOT a 200 — the error envelope

HTTP 429
{ "type": "error", "error": { "type": "rate_limit_error", "message": "…" } }

The SDKs raise typed exceptions for these (RateLimitError, BadRequestError, …) and auto-retry 429/5xx a couple of times — but the decision "retryable vs not" is yours to encode.

Streaming — the same fields, delivered as events

With "stream": true the response arrives as server-sent events. Nothing new is invented: the events reassemble into the exact object above.

The SDK's stream.get_final_message() / finalMessage() does the reassembly — you get back the same Message object, stop_reason and all.

The loop in 14 lines — where each field is read

# Abridged/pseudocode: MODEL, tools, run_tool(), and deliver() are yours.
messages = [{"role": "user", "content": "Where is order A-1042?"}]
while True:
    resp = client.messages.create(model=MODEL, max_tokens=1024,
                                  system=SYSTEM, tools=tools, messages=messages)
    messages.append({"role": "assistant", "content": resp.content})   # echo verbatim (blocks, not text)
    if resp.stop_reason == "tool_use":                                 # 1. branch on stop_reason FIRST
        results = [{"type": "tool_result", "tool_use_id": b.id,       # 2. one result per tool_use…
                    "content": run_tool(b.name, b.input)}
                   for b in resp.content if b.type == "tool_use"]      #    …walking content[] by type
        messages.append({"role": "user", "content": results})          # 3. …all in ONE user message
        continue
    if resp.stop_reason == "max_tokens": raise Truncated(resp.id)      # never parse a truncated turn
    return deliver([b.text for b in resp.content if b.type == "text"]) # end_turn (refusal → escalate)

Every line touches a field on this page — nothing else. That is the harness; Domain 1 adds the budgets, gates and audit trail around it.

Raw JSON → SDK — the translation table

🎯 Exam lens — what CCAR-F actually tests here: (1) the API is stateless, so the full messages array is re-sent; (2) stop_reason is checked before anything is parsed, and max_tokens means incomplete; (3) a tool_result answers a specific tool_use_id, rides in a user message, and parallel results share one message; (4) system/tools live outside messages and form the cacheable prefix; (5) input_schema with additionalProperties: false is a closed schema — the model is steered by it, your harness still validates.

{
  "model": "claude-sonnet-5",
  "max_tokens": 1024,
  "system": "You are a support agent for an online store…",
  "tools": [{ "name": "get_order", "description": "…", "input_schema": { "…": "…" }, "strict": true }],
  "messages": [{ "role": "user", "content": "Where is order A-1042?" }]
}

{
  "id": "msg_01…", "type": "message", "role": "assistant", "model": "claude-sonnet-5",
  "content": [
    { "type": "text", "text": "Let me look that up." },
    { "type": "tool_use", "id": "toolu_01…", "name": "get_order", "input": { "order_id": "A-1042" } }
  ],
  "stop_reason": "tool_use", "stop_sequence": null, "stop_details": null,
  "usage": { "input_tokens": 812, "output_tokens": 57, "cache_creation_input_tokens": 0, "cache_read_input_tokens": 0 }
}

"messages": [
  { "role": "user", "content": "Where is order A-1042?" },
  { "role": "assistant", "content": [ { "type": "text", "text": "Let me look that up." },
                                      { "type": "tool_use", "id": "toolu_01…", "name": "get_order", "input": { "order_id": "A-1042" } } ] },
  { "role": "user", "content": [ { "type": "tool_result", "tool_use_id": "toolu_01…",
                                   "content": "{\"status\":\"in_transit\",\"eta\":\"2026-08-26\"}" } ] }
]

{
  "id": "msg_02…", "type": "message", "role": "assistant", "model": "claude-sonnet-5",
  "content": [ { "type": "text", "text": "Order A-1042 is in transit and should arrive by August 26." } ],
  "stop_reason": "end_turn", "stop_sequence": null, "stop_details": null,
  "usage": { "input_tokens": 96, "output_tokens": 23, "cache_creation_input_tokens": 0, "cache_read_input_tokens": 790 }
}

See it in code — dual knowledge

Every </> chip below (and the SOURCE row on every field card) points at Anthropic's cookbook — the canonical example of the field in use. Locally the chip opens the file in the running IntelliJ at that line; on the public site it opens GitHub, pinned to the exact commit the refs were resolved against, so the line numbers stay true.

⚠️ Field drift is real. Anthropic adds fields (stop_details, effort, compaction blocks) and retires others (budget_tokens, sampling knobs, prefill) between model generations. The shape on this page is stable; the exact set of optional fields is whatever the current API reference↗ says — read the response as an open object and branch only on the fields you know.