Claude API Guide

Start With Messages

The Messages API is the core programmable interface for direct Claude model calls. The docs explain that it is stateless: you send the full conversational history each time rather than relying on server-side chat state. That design gives you control, but it also means you must manage context growth, summaries, retrieval, privacy, and cost.

Every robust integration should handle stop reasons, retries, refusals, truncation, tool calls, and fallbacks. Do not assume a successful HTTP response means the task is complete; inspect the model response and application-level criteria.

Tools And Server Capabilities

The feature overview separates server-side tools, client-side tools, tool infrastructure, and context management. Server-side web search gives Claude current web access with citations. Code execution can run Python in a sandbox for data analysis and file processing. Client-side tools let your application execute domain-specific actions.

MCP connector support lets the Messages API connect directly to remote MCP servers with a beta header, but the docs also list important limitations: only tool calls from the MCP spec are supported, the server must be publicly exposed over HTTP, and the feature is not Zero Data Retention eligible.

Citations, Files, And Search Results

Claude’s citations feature is useful when you need answer text tied to document passages. The docs say documents must have citations enabled, and currently only text citations are supported. PDFs, plain text, and custom content have different citation location formats.

The Files API is a create-once, use-many-times path for uploaded files and generated files, but the docs mark it beta and not eligible for Zero Data Retention. For RAG, the search-results feature can bring pre-fetched source snippets into responses with source attribution.

Model IDs And Context Budgets

The current API model IDs are `claude-fable-5-1`, `claude-opus-5`, `claude-sonnet-5`, and `claude-haiku-4-5` (with the dated alias `claude-haiku-4-5-20251001`). Anthropic’s guidance is to start with `claude-opus-5` and move to `claude-fable-5-1` when reasoning depth or agent horizon demands it.

Fable 5.1, Opus 5, and Sonnet 5 each document a 1M-token context window and 128K maximum output. That is a ceiling, not a target. Filling a million tokens is slow, expensive, and usually a sign that retrieval or compaction is missing; treat the large window as headroom for long agent transcripts rather than a reason to stop managing context.

Haiku 4.5 sits apart at 200K context and 64K output. If your integration assumes a uniform context budget across models, that assumption breaks at the Haiku tier.

Opus 5 Behavior And Betas

The Opus 5 launch added two behaviors worth designing around. The first is a beta that allows mid-conversation tool changes without invalidating the prompt cache — previously, altering the tool set forced a cache miss on the whole prefix. For agents that add or remove tools as a task progresses, this removes a real cost penalty.

The second is automatic fallback: when safety classifiers flag a request on Opus 5 or Fable 5, Anthropic can route the request to another model rather than failing it. Biology-related Fable blocks now route to Opus 5. Your integration should not assume the responding model is always the one you requested; log the model returned in the response.

Fable 5.1 adds its own set of additive betas — per-message effort, turn-scoped system messages, `display: "updates"` progress events, the lower cache-read rate, and content provenance. It also introduces breaking changes versus Fable 5: forced tool use now errors, earlier models cannot read its thinking blocks, and editing earlier turns invalidates thinking.

Cost And Latency Controls

Prompt caching is the first lever when a workload reuses long instructions, examples, documents, or conversation prefixes. The official docs explain automatic caching and explicit breakpoints, with a default five-minute cache lifetime and optional one-hour caching at higher write cost. Cache reads are 10% of base input on most models, but 2.5% on Fable 5.1 and Mythos 5.1 — $0.25 per million tokens.

Batch processing is the second lever when results do not need to stream immediately. The Message Batches API supports up to 100,000 requests or 256 MB per batch at 50% off, with most batches completing in less than one hour and results available after completion or after 24 hours, whichever comes first.

Opus 5 fast mode is a latency lever rather than a cost one: roughly 2.5x speed at 2x base price, billed against platform and Claude Code usage credits.

Reasoning And Effort

Current models use adaptive thinking and an `effort` control rather than manual thinking budgets. Fable 5.1, Opus 5, and Sonnet 5 all default to high effort on the platform, and Fable 5.1’s adaptive thinking is always on. Haiku 4.5 uses extended thinking rather than the effort control.

Effort defaults are surface-specific, which surprises people. Fable 5.1 defaults to High in Claude Code but Medium on Claude.ai and Cowork. If you are comparing API behavior against what you saw in the app, check the effort setting before concluding the model changed.

Set effort intentionally. Use low for simple, latency-sensitive work; high or above for complex reasoning, coding, tools, and tasks with expensive mistakes. Measure output quality and total cost, not token price alone.