Technical Reference

Messages API POST /v1/messages

The interaction modes

A developer reaches Claude through a REST API, normally via an SDK. The choice of mode is settled with two questions: is someone waiting? and is it real time or offline volume?

The context window and its two ways of breaking

It is a fixed token budget that holds the entire request at once: system, history, tools, documents and the generation. It fails in two distinct ways, and the exam may ask you to tell them apart:

stop_reason values

Tool use

Defining a tool

{
  "name": "search_order",          // ^[a-zA-Z0-9_-]{1,64}$
  "description": "...",             // 3-4 sentences minimum, include when NOT to use it
  "input_schema": { ... },          // JSON Schema
  "input_examples": [ ... ]         // optional, useful on nested inputs
}

tool_choice values

With any or tool, the API prefills the turn: there will be no text before the tool_use. Parallelism comes enabled; it is turned off with disable_parallel_tool_use: true inside tool_choice.

Returning the result

{
  "role": "user",                   // there is no "tool" role
  "content": [
    { "type": "tool_result",
      "tool_use_id": "toolu_...",   // required
      "content": "...",             // optional
      "is_error": true },           // optional: model-readable failure
    { "type": "text", "text": "..." } // the text goes AFTER
  ]
}

Streaming stream: true

message_start
  content_block_start   // per block, with its index
  content_block_delta   // N times
  content_block_stop    // HERE the block is closed
message_delta           // cumulative usage
message_stop            // HERE the turn is confirmed

Message Batches

Prompt caching cache_control

{ "type": "text", "text": "...",
  "cache_control": { "type": "ephemeral", "ttl": "1h" } }
// "ephemeral" is the only type. ttl optional: 5 min by default

Reasoning and effort

Structured output

Two mechanisms: JSON outputs (schema in output_config.format, constrains the final response) and strict tool use (strict: true on a tool, validates the arguments). Both by constrained decoding.

Errors and retry strategy

Classifying failures

• First question on any failure: could waiting and retrying resolve it?
• If yes → exponential backoff with a cap and a retry budget. Never an immediate loop, which only makes the problem worse.
• If no → a named fallback. Without it, the unhandled exception becomes the default behaviour, and one bad response takes down the whole flow.
• Tool failure → back to the model with the error flag set, never hidden behind an empty result the model would mistake for data.

The official SDKs already retry with exponential backoff, 2 retries by default, respecting retry-after.

Evals: grading method by output shape

Official order of preference: code → LLM → human. On the human, the docs say literally "avoid it if you can". And the design principle: more cases with somewhat worse signal and automatic grading beats few hand-graded cases.

Test levels and what each one catches

The same instinct governs information retrieval: a single search for single-fact queries, search across several iterations when the question is genuinely multi-step.

Hooks

PreToolUse return shape

{ "permissionDecision": "deny",        // allow | deny | ask | defer
  "permissionDecisionReason": "...",
  "updatedInput": { ... } }            // optional

• Exit 2 = blocking error, not overridable even with an allow.
• Silence is not approval: a hook can deny, but staying quiet lets the normal permission flow continue.
• Hooks run in your process, outside the context window: they consume no tokens beyond what they return.

Agent SDK

A subagent's AgentDefinition

{ "description": "...",   // required
  "prompt": "...",        // required - the ONLY thing that crosses from the parent
  "tools": [...],         // if omitted, inherits all
  "model": "inherit",     // or a specific model
  "skills": [...] }       // subagents do NOT preload skills

MCP

Naming in Claude Code: tools mcp__server__tool · prompts /mcp__server__prompt · resources @server:proto://path.

Limits and counters