Choosing a Claude Model
The Opus/Sonnet/Haiku tradeoff and how to pick — without guessing.
Tokens, Context & Pricing
Count tokens correctly, max_tokens vs context window, and estimating cost.
Your First API Call
Install the SDK, authenticate, and make a real call to Claude in Python, TypeScript, or cURL.
API Version 2026-10-21 — The First Breaking Version in Three Years
Claude's anthropic-version header moved for the first time since 2023. What breaks, why your package manager decides when you adopt it, and the exact upgrade order.
Streaming & Multi-Turn Conversations
Stream responses and manage history on a stateless API.
Tool Use / Function Calling
Define tools, run the agentic loop, and handle results — including the three message-shape rules that cause 400s, and why tool_choice "any" and "tool" now error on the newest Claude models.
Code Execution Tool — Sandboxed Bash, Files, and Python
Anthropic's server-side sandbox lets Claude run Bash, edit files, and execute Python — with 5 GiB of RAM, 30-day container reuse, and a 1,550-hour monthly free tier. The three tool versions, what each adds, when it's free, and the file-capture gotcha nobody documents.
Vision, PDF & File Input
Send images and documents, and reuse uploads by file_id.
Structured Output
Get schema-conforming JSON you can rely on — not prompt-and-pray.
Extended Thinking & Effort
Adaptive reasoning and the effort control — choosing depth by workload.
Effort tuning: 5 levels, model defaults, and the cache trap
The July 2026 effort parameter has five levels — low, medium, high, xhigh, max — and lives inside output_config, not at the top level. It affects tool calls (not just thinking), invalidates prompt cache when changed mid-conversation, and each model has a different recommended starting point. The practical tuning guide.
The advisor tool: Sonnet does the work, Fable does the thinking
The advisor server-tool (beta advisor-tool-2026-03-01) lets a fast executor model consult a stronger model mid-turn. Full field reference, the token-accounting trap most integrators miss, the model pairing matrix, and the exact prompts Anthropic ships in production.
Task Budgets — Advisory Token Caps That Make Agents Finish Gracefully
The March 2026 Messages-API beta gives Claude a token budget for the whole agentic loop — thinking, tool calls, tool results, output — so long-running agents self-regulate and wrap up cleanly instead of running away. How the countdown works, why it's advisory not enforced, and how to size it so it doesn't cause refusal-like behavior.
Prompt Caching & Cost Optimization
Reuse a stable prompt prefix to cut cost and latency — and the gotcha that breaks it.
Cache Diagnostics — Find Out Exactly Why Your Cache Missed
Stop guessing why cache_read_input_tokens is zero. The API will tell you which part of your prompt diverged, and by how many tokens.
Message Batches — Async Jobs at 50% Off
Cut cost in half and lift throughput by moving bulk work to the async Batches API — with the gotchas that trip people up.
Mid-Conversation System Messages
Steer a long agent session without blowing up the prompt cache — the new system role you can append after any user turn.
Mid-Conversation Tool Changes
Add and retire tools between turns without invalidating the prompt cache — the Opus 5 beta that fixes the biggest hidden tax on long agent sessions.
Building Agents on the API
Single call vs workflow vs custom agent — the decision test and loop design.
Managed Agents
Anthropic-hosted agent loop: agents vs sessions, environments, memory, vaults, and scheduled deployments (cron).
Managed Agents Memory Stores
The July 2026 beta — server-side persistent memory that mounts into a Managed Agents sandbox, with versioning, audit trail, and redaction.
Managed Agents Session Budgets
The August 2026 beta — hard dollar caps on a Managed Agents session, enforced at public list rates, with the budget_reached stop reason, the one-request overshoot, and the pause-and-resume model.
Managed Agents Domain Restrictions
The August 26, 2026 beta — allowed_domains, blocked_domains, max_content_tokens, and user_location on web_search and web_fetch inside Managed Agents. Format rules, multiagent semantics, mid-session updates, and the url_not_allowed error.
Cowork & Agent Teams
The agentic desktop workspace and multi-agent collaboration as products.
MCP & Connecting to Tools
Call remote MCP servers straight from the Messages API — the request shape, allowlists and denylists, deferred loading, and the limits that bite in production.
MCP 2026-07-28: The Stateless Spec
The biggest MCP revision since launch: the session is gone, every request self-describes, and any server instance can answer any call. What actually changed on July 28, 2026, and how to migrate without breaking today's servers.
MCP Apps: Interactive UIs Inside a Tool Call
MCP Apps (SEP-1865) lets an MCP server ship an HTML UI that the client renders inside a sandboxed iframe — with every action still routed through the standard JSON-RPC audit path. What the spec actually says, what to build with it, and what to refuse to build.
MCP Tasks: Long-Running Work Without the Session
The 2026-07-28 stateless MCP spec killed the session — so how do you model a 20-minute CI job, a batch import, or a human approval gate? With the official Tasks extension (SEP-2663). Full lifecycle, wire protocol, migration from the old experimental Tasks API, and the polling/notification patterns that actually work in production.
Playwright MCP: The Deep Practical Guide (2026)
Microsoft's Playwright MCP is now the #1 MCP server in the world — ahead of GitHub and Figma. The bit almost nobody teaches: the default accessibility-snapshot mode is not just faster than vision, it's a completely different automation paradigm. Profiles, opt-in caps, browser-extension mode that attaches to your real Chrome, the token-cost fight against Playwright-as-a-Skill, and the security line you must not cross.
Safety, Refusals & Fallbacks
Handle refusals gracefully and distinguish them from classifier blocks.
Server-Side Fallbacks & Fallback Credit
The Opus 5 beta that turns a Fable 5 / Opus 5 refusal into a normal answer inside one API call — plus the credit token that stops you from paying the prompt cache twice on the retry.
Errors, Rate Limits & Reliability
The error map, retries with backoff, rate-limit tiers, and model migration.
Memory & Context Editing
Give agents persistent memory and auto-pruned context — the client-side memory tool plus context editing that clears stale tool results to survive long runs.
Conversation Compaction — Summarize History Server-Side and Keep Going
The Messages API can summarize a conversation into one signed block you send back in place of the messages it replaces. The four flavors (on-demand, keep-tail, background, threshold), the swap rules, the two mistakes that fail silently with HTTP 200, and what a summary can never carry.
Tool Search & Deferred Loading
Scale to thousands of tools without context bloat: how defer_loading and the tool search tool actually work, the five 400s they produce, and why your request body does not get smaller.
Message Threads — Send Only the New Turn
The Messages API can keep your conversation on the server and let each turn send only the new messages. What it actually saves (bytes and latency, not tokens), the replay path you must build before you ship, the three field groups, and the 4-breakpoint cache limit.
Programmatic Tool Calling
Let Claude call your tools from Python inside the code-execution sandbox — cutting round-trips and keeping intermediate results out of context.
The Admin API: automate your Claude org
The operator's guide to Anthropic's Admin API — list members, invite users, run RBAC groups, offboard cleanly. Console + Claude Enterprise, with the seat-pool and SSO gotchas that trip real teams.
Agent Observability: Tracing an Agent You Can't Reproduce
An agent run is a non-deterministic distributed trace, so you cannot debug it by re-running it — you have to have recorded it. This page covers what to record: the OpenTelemetry GenAI span shapes (and why every gen_ai.* attribute is still 'Development'), Claude Code's exact metric and event names, the request-id that links your trace to Anthropic support, and the three privacy traps in agent telemetry.
First-Party OpenTelemetry Tracing: Two Paths, One Trace
Since October 2026 the Claude API and the Claude SDK emit OpenTelemetry spans themselves — no hand-rolled instrumentation. But the two paths overlap, and summing both will double your token numbers. This page covers the setup for each, the one rule that keeps token counts honest, the traceparent flag that silently deletes your traces, and the delivery rules that disable a destination after 24 hours.
The Usage & Cost Analytics API: Attribute Every Dollar
The practical guide to Claude's Usage and Cost Analytics API — the beta that replaced the legacy usage_report and cost_report endpoints. Row shape, the five-dimension limit, actor semantics, the 100x cents footgun, data-freshness rules that break naive dashboards, and the legacy migration table.
Inference Hooks: inline DLP for Claude Enterprise
The operator's guide to Claude Enterprise Inference Hooks — the HTTPS webhook that lets your DLP server allow or deny every prompt across chat, Claude Code, and Cowork, before the model sees it. Full spec, verdict schema, signing, rollout playbook.
User Profiles & Enforcement: Don't Let One Customer Ban Your Whole Org
The operator's guide to Claude API user profiles — attribute every request to an end customer so a safety restriction or ban lands on one profile instead of your entire organization. Full field reference, the four enforcement_status values, the enac_ action schema, organization webhooks, and the polling loop you need because event delivery isn't live yet.