D1 · Agentic Architecture › Cluster 1 · Foundations

1.2 · The Messages API as Substrate

One endpoint — everything else is a feature of it

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.

🔑 Architect framing: the Messages API is a substrate, not a menu of endpoints. When the exam says "which API do you call to use tools?", the answer is the same one you always call — /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

flowchart LR subgraph REQ["📤 Request body"] R1["model"] R2["max_tokens"] R3["system (prompt)"] R4["messages[] (full history)"] R5["tools (optional)"] end REQ --> EP["🟣 POST /v1/messages
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.

FieldRoleNotes
modelWhich model runs the requestExact IDs: claude-opus-4-8, claude-sonnet-4-6, claude-haiku-4-5
max_tokensCap on output tokensRequired. Hitting it → stop_reason="max_tokens" (output truncated, not the context window). Default ~16000 for non-streaming.
systemThe system prompt (persona, rules)Top-level field, not a message role. Resent every call.
messagesThe full conversation so farList of {role, content}; roles alternate user/assistant; first is user.
toolsTool schemas the model may callPresence enables tool use; model may emit tool_use blocks.

CONCEPT Response anatomy

The response is a Message object. Three parts matter for orchestration:

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)
Because the endpoint is uniform, the same parsing loop above works whether the call used tools, thinking, or neither. You add features by adding fields — not by switching APIs.

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

Trap: "Which endpoint / API do you call to use tools (or thinking, or structured output)?" → Always the same one: POST /v1/messages. There is no separate tools/thinking API; they're features toggled by request fields.
Trap: Treating 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.
Trap: Reading 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).
Trap: Assuming 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.