CONCEPT One endpoint underneath everything
Every agent, workflow, tool call, chain-of-thought, and structured output you build on Claude bottoms
out at a single HTTP endpoint: POST /v1/messages. There is no separate
"tools API", "thinking API", or "agents API". Tool use, extended thinking, structured output, streaming —
these are all features expressed through the same request/response shape, toggled
by fields you pass and blocks you get back.
/v1/messages — with a tools field added.The endpoint is stateless. It holds no memory between calls. Each request must carry
the full system prompt and the entire messages[] history; the server reads it,
produces one response, and forgets everything (see 1.4).
| You might think it's… | It's actually… |
|---|---|
| A "tools API" | /v1/messages + a tools field → tool_use blocks back |
| A "thinking API" | /v1/messages + a thinking config → thinking blocks back |
| A "structured-output API" | /v1/messages steered by tools / prompt → text or tool_use you parse |
| A stateful "chat session" | Stateless replay: you resend system + all messages[] each turn |
DIAGRAM Request → endpoint → response anatomy
STATELESS · one shot"] EP --> RESP subgraph RESP["📥 Response = Message"] P1["content[] blocks
text · thinking · tool_use"] P2["stop_reason"] P3["usage
input/output tokens"] end classDef req fill:#d1ecf1,stroke:#17a2b8,color:#0c5460; classDef ep fill:#e2d4f0,stroke:#764ba2,color:#3d1a5b; classDef res fill:#d4edda,stroke:#28a745,color:#155724; class R1,R2,R3,R4,R5 req; class EP ep; class P1,P2,P3 res;
CONCEPT Request anatomy
Five fields carry almost everything. system and tools are optional; the rest
define a valid request.
| Field | Role | Notes |
|---|---|---|
model | Which model runs the request | Exact IDs: claude-opus-4-8, claude-sonnet-4-6, claude-haiku-4-5 |
max_tokens | Cap on output tokens | Required. Hitting it → stop_reason="max_tokens" (output truncated, not the context window). Default ~16000 for non-streaming. |
system | The system prompt (persona, rules) | Top-level field, not a message role. Resent every call. |
messages | The full conversation so far | List of {role, content}; roles alternate user/assistant; first is user. |
tools | Tool schemas the model may call | Presence enables tool use; model may emit tool_use blocks. |
CONCEPT Response anatomy
The response is a Message object. Three parts matter for orchestration:
response.content— a list of blocks, not a string. Each block has atype(text,thinking,tool_use). Checkblock.typebefore touching.text(see 1.5).response.stop_reason— why generation stopped. Your loop branches on this (see 1.3).response.usage—input_tokens,output_tokens,cache_read_input_tokens, etc. Your cost & budget signal.
CODE Basic call + iterating content by block type
# The one call that underlies everything: POST /v1/messages via the SDK. import anthropic client = anthropic.Anthropic() # reads ANTHROPIC_API_KEY from env response = client.messages.create( model="claude-opus-4-8", max_tokens=1024, system="You are a concise assistant.", # top-level field, NOT a message messages=[ {"role": "user", "content": "Summarize the CAP theorem in one line."}, ], ) # response.content is a LIST of blocks — never assume it's a string. for block in response.content: if block.type == "text": print(block.text) elif block.type == "thinking": print("[thinking]", block.thinking) elif block.type == "tool_use": print("[wants tool]", block.name, block.input) # Orchestration signals live outside content: print(response.stop_reason) # e.g. "end_turn" or "tool_use" print(response.usage.input_tokens, response.usage.output_tokens)
TRADE-OFFS Stateless single-endpoint design
✅ Why it's designed this way
- One shape to learn — tools/thinking/output are just fields & blocks
- Statelessness scales horizontally; any server can handle any request
- You own the full context → total control over what the model sees
⚠️ What it costs you
- You must resend
system+ full history every call (tokens) - No server memory — you build conversation state yourself (1.4)
- Growing history → growing cost; you own pruning/compaction (see 7.5)
EXAM TRAPS
POST /v1/messages. There is no separate tools/thinking API;
they're features toggled by request fields.system as a message with role:"system". →
In the Messages API, system is a top-level field, not an entry in messages[].
Message roles are only user and assistant.response.content[0].text as the whole answer. →
content is a list of typed blocks; a call using tools or thinking may put a non-text
block first. Iterate and check block.type (see 1.5).max_tokens refers to the context window. → It caps the
output. Hitting it yields stop_reason="max_tokens" with truncated output — a distinct
thing from a context-window overflow.PRACTICE
Q1 · A teammate asks "what's the URL for the Claude tools API?" What do you tell them?
There isn't a separate one. Tool use rides on POST /v1/messages — you add a
tools field to the normal request and the model may return tool_use blocks. Tools,
thinking, and structured output are all features of the single Messages endpoint.
Q2 · Your code does print(response.content) and gets a list of objects, not text. Bug?
Not a bug — that's the contract. response.content is a list of content blocks.
Iterate them and check block.type, reading block.text only for text
blocks. Assuming a string is the classic mistake (see 1.5).
Q3 · Which top-level request fields are required vs optional in a basic call?
Required: model, max_tokens, and messages. Optional:
system and tools (add them to enable a persona or tool use). All of them are resent
every call because the endpoint is stateless.