https://docs.claude.com/en/docs/about-claude/models/overview

https://docs.claude.com/en/docs/about-claude/models/choosing-a-model

https://docs.claude.com/en/docs/about-claude/model-deprecations

https://docs.claude.com/en/docs/build-with-claude/token-counting

https://docs.claude.com/en/docs/about-claude/pricing

https://docs.claude.com/en/docs/build-with-claude/prompt-engineering/overview

https://docs.claude.com/en/docs/build-with-claude/prompt-engineering/be-clear-and-direct

https://docs.claude.com/en/docs/build-with-claude/prompt-engineering/multishot-prompting

https://docs.claude.com/en/docs/build-with-claude/prompt-engineering/use-xml-tags

https://docs.claude.com/en/docs/build-with-claude/prompt-engineering/system-prompts

https://docs.claude.com/en/docs/build-with-claude/extended-thinking

https://docs.claude.com/en/docs/build-with-claude/prompt-engineering/chain-of-thought

https://docs.claude.com/en/docs/build-with-claude/effort

https://docs.claude.com/en/docs/build-with-claude/context-windows

https://docs.claude.com/en/docs/build-with-claude/prompt-engineering/long-context-tips

https://docs.claude.com/en/docs/build-with-claude/context-editing

https://www.anthropic.com/engineering/effective-context-engineering-for-ai-agents

https://academy.claude.com/courses/claude-platform-101

https://platform.claude.com/workbench

https://github.com/anthropics/prompt-eng-interactive-tutorial

Current lineup (Sep 2026): Claude Fable 5.1 claude-fable-5-1 (1M context, 128K max output, adaptive thinking always on, $10/$50); Claude Opus 5 claude-opus-5 (1M, 128K, adaptive, $5/$25); Claude Sonnet 5 claude-sonnet-5 (1M, 128K, adaptive, $2/$10, fast); Claude Haiku 4.5 claude-haiku-4-5-20251001 (200K, 64K, manual extended thinking, $1/$5, fastest).

Recommendations: Opus 5 for most workloads; Fable 5.1 for the hardest reasoning/agentic work; Sonnet 5 for speed/cost balance; Haiku 4.5 for budget and speed. Default effort is high on the 5-series; effort is not supported on Haiku 4.5.

ID formats: 4.6 and later are dateless and pinned (claude-sonnet-4-6, claude-opus-5) — they are snapshots, not evergreen aliases. Pre-4.6: dated IDs (claude-sonnet-4-5-20250929) plus rolling aliases (claude-sonnet-4-5). Bedrock: anthropic.claude-opus-5; Vertex: same as API.

Weights never change for a given ID. GET /v1/models returns max_input_tokens, max_tokens and capabilities.

Same models on Amazon Bedrock, Google Vertex AI, Microsoft Foundry with platform-specific IDs and SDK clients.

USD per million tokens — input / 5-min cache write / 1-h cache write / cache read / output: Fable 5.1 $10 / 12.50 / 20 / 0.25 / 50 · Opus 5 (and 4.5–4.8) $5 / 6.25 / 10 / 0.50 / 25 · Sonnet 5 $2 / 2.50 / 4 / 0.20 / 10 · Sonnet 4.5–4.6 $3 / 3.75 / 6 / 0.30 / 15 · Haiku 4.5 $1 / 1.25 / 2 / 0.10 / 5.

Multipliers: 5-min cache write 1.25×, 1-hour write 2×, cache read 0.1× (0.025× on Fable/Mythos 5.1). Batch API: 50% off input AND output (Opus 5 $2.50/$12.50; Sonnet 5 $1/$5; Haiku 4.5 $0.50/$2.50).

No long-context premium above 200K — the full 1M window is billed at standard rates. Data residency inference_geo 'us' = 1.1×.

Server tools: web search $10 per 1,000 searches (+ tokens, errors free); web fetch free beyond tokens; code execution free alongside web search/fetch, otherwise 1,550 free container-hours/month then $0.05/hour (5-min minimum).

Tool-use system prompt overhead: Opus 5 286 tokens (auto/none) / 406 (any/tool); Sonnet 5 354/474; Haiku 4.5 496/588.

Minimum 60 days' notice before retiring a publicly released model; email to orgs with active usage plus docs updates.

States: Active → Legacy (no updates) → Deprecated (still serves, retirement date set) → Retired (requests fail).

All Claude 3.x models are retired (3.5 Haiku and 3.7 Sonnet retired Feb 2026; 3 Haiku Apr 2026); Opus 4 / Sonnet 4 retired Jun 2026; Opus 4.1 retired Aug 2026. Oldest still-active: Sonnet 4.5 and Haiku 4.5.

POST /v1/messages/count_tokens; SDK client.messages.count_tokens(...) → {input_tokens: N}. Free, but rate-limited separately (Start 5,000 RPM, Build 10,000, Scale 20,000).

Counts system, messages, tools, images, PDFs and thinking blocks — it is not text-only; input tokens only, no output estimate.

Claude 4.7+ uses a new tokenizer yielding ~30% more tokens for the same text — don't reuse older counts.

Prerequisites before prompt engineering: clear success criteria, empirical evals against them, a first-draft prompt.

Prompt engineering beats fine-tuning for most needs: faster, cheaper, preserves general knowledge, transparent, easy to iterate.

Technique order (broad → specialised): be clear and direct → examples (few-shot) → XML structure → role via system prompt → let Claude think → chain prompts → long-context tips.

Resources: prompt generator/improver in the Console Workbench, the interactive GitHub tutorial, model-specific best-practice pages.

Golden rule: show the prompt to a colleague with minimal context — if they'd be confused, so will Claude. Treat Claude as a brilliant new employee who lacks your context.

Be specific about output format and constraints; use numbered lists when order matters; explain WHY ('a text-to-speech engine will read this, so no ellipses' beats 'NEVER use ellipses'). Tell Claude what to do rather than what not to do.

Examples: 3–5, relevant and diverse, wrapped in <example> inside <examples>; include <thinking> inside examples to demonstrate reasoning style.

XML: consistent descriptive tag names; nest for hierarchy (<documents> → <document index='n'>); separate <instructions>, <context>, <input>.

Role: set it in the system parameter — even one sentence makes a difference; put task-specific data in the user turn.

Thinking: prefer general instructions ('think thoroughly') over prescriptive steps; adaptive thinking on 4.6+ (always on for Fable/Mythos 5.x); when thinking is off, use manual chain of thought with <thinking> and <answer> tags.

Long context (20k+ tokens): documents at the TOP, query at the END — up to 30% better; wrap each in <document> with <source> and <document_content>; ask Claude to quote relevant parts first.

Prefill on the last assistant turn is unsupported from Claude 4.6 (400 error); use explicit format instructions, XML output tags or structured outputs.

Prompt chaining remains useful when you must inspect intermediate outputs or enforce a pipeline (draft → review → refine).

Tool-use prompting: be explicit ('Change this function' vs 'Can you suggest'); require confirmation before destructive or irreversible actions.

Manual mode: thinking={type:'enabled', budget_tokens:N} — N ≥ 1,024 and < max_tokens; budget is a target, max_tokens the hard ceiling. Adaptive mode: thinking={type:'adaptive'} plus output_config.effort.

Support: manual only on 4.5 and earlier (and Haiku 4.5); deprecated on 4.6; rejected (400) on 4.7+, Opus 5, Sonnet 5, Fable 5.1 — those are adaptive-only.

Response: thinking block (summarised) then text; redacted_thinking may appear; blocks carry a signature and must be passed back unmodified with tool results.

Interleaved thinking (thinking between tool calls) is automatic in adaptive mode (beta header in manual mode).

Incompatible with prefill and with max_tokens:0 cache pre-warm; changing thinking config between requests misses the cache. Claude 4.6+ keeps prior-turn thinking in context (billed as input); 4.5 and earlier strip it.

output_config={effort: low | medium | high | xhigh | max}; default high. Supported on Opus 4.5+, Sonnet 4.6+, Fable/Mythos; not Haiku 4.5.

Effort shapes all output — text length, number of tool calls, thinking depth; it is a behavioural signal, not a strict budget. thinking controls whether thinking happens; effort controls how much.

Lower effort → fewer/combined tool calls, terse output; xhigh for long-horizon work; max unconstrained. On Opus 5, xhigh/max require thinking enabled.

Changing top-level effort between requests invalidates the message cache; a per-message effort via a system turn (beta) preserves it. No separate pricing — cost changes only through tokens.

1M-token window with 128K max output on the 5-series and 4.6+ Opus/Sonnet; 200K on Sonnet 4.5 and older, and Haiku 4.5. 1M is the default (no beta header, no surcharge).

Everything counts: system, all messages, tool definitions, tool results, images/documents, generated output; cached tokens still count.

Input alone > window → 400 'prompt is too long'. Input + max_tokens > window → generation stops with stop_reason 'model_context_window_exceeded' (Claude 4.5+).

Thinking: models that strip prior thinking (Opus <4.5, Sonnet <4.6, all Haiku) bill it once as output; models that keep it (Opus 4.5+, Sonnet 4.6+, 5.x) count prior thinking as input each turn — clear with context editing.

Context awareness: Sonnet 4.5+/Haiku 4.5 receive token-budget warnings after tool calls; server-side compaction (beta, 4.6+) summarises earlier turns to continue past the limit. 'Context rot' degrades accuracy as tokens grow even below the limit.

Beta header context-management-2025-06-27; request param context_management={edits:[…]}; use client.beta.messages.create.

Strategy clear_tool_uses_20250919: clears old tool results (replaced by a placeholder) once context grows. Fields: trigger (default input_tokens 100,000; or tool_uses N), keep (default tool_uses 3), clear_at_least (input_tokens N), exclude_tools, clear_tool_inputs (default false).

Strategy clear_thinking_20251015: keep {thinking_turns: N} or 'all'. When combining, list clear_thinking first.

Response includes context_management.applied_edits (type, cleared_tool_uses, cleared_input_tokens). Edits are server-side; your stored history is untouched.

Clearing tool results invalidates the prompt cache from that point — use clear_at_least to make it worthwhile. Pair with the memory tool to persist critical facts before clearing; count_tokens accepts context_management to preview.

Context engineering = curating the whole context state (system prompt, tools, external data, history) — a superset of prompt engineering.

Context rot: performance degrades as tokens grow; attention is a finite budget (n² pairwise); a gradient, not a cliff.

System prompt at the right altitude: not brittle if/else rules, not vague; specific heuristics in organised sections; minimal high-signal tokens.

Tools: self-contained, non-overlapping, token-efficient — 'if a human engineer can't say which tool to use, an agent can't either'.

Just-in-time context: lightweight references (paths, URLs, queries) loaded at runtime; hybrid with upfront context (Claude Code loads CLAUDE.md then greps).

Long-horizon techniques: compaction (summarise history — maximise recall first, then precision), structured note-taking (persistent notes outside context, e.g. Claude Code memory), sub-agent architectures (clean context per subagent, 1–2k-token summaries back).

Interface interpretation: read a Messages request/response like a contract — which blocks are present (text, tool_use, thinking), what stop_reason implies, what usage costs; never assume content[0] is text.

Schema design for tools and outputs: small, flat objects; explicit enums instead of free text; required vs optional deliberate; descriptions on every property; unambiguous names (user_id); avoid deeply nested or union-heavy schemas (structured outputs has limits on unions/optionals); version schemas when you change them.

Session hygiene: the API is stateless — your app owns the history. Store it server-side keyed by session id; cap history length; summarise or drop old turns; keep the system prompt stable (cacheable) and put per-request data last; never leak one user's context into another's; clear or rephrase after a refusal; strip tool results that are no longer needed (context editing).

Conversation state vs application state: the model sees only what you send — keep authoritative state (orders, balances) in your database and pass snapshots, not the other way round.

Defensive parsing (blueprint 'Output Handling'): check stop_reason first; validate JSON against a schema; handle max_tokens truncation; retry once with the error message; fail closed on unparsable output; log the raw response with request id.

Multi-tenant design: one workspace/key per tenant for Files and spend isolation; opaque metadata.user_id for abuse tracking; per-tenant rate-limit budgets.

Configuration management (blueprint 4.1%): model ID, max_tokens, effort, tool list and prompt versions live in config (not scattered in code); CLAUDE.md and settings.json versioned with the repo; environment-specific settings (dev/staging/prod keys and models).

Transport reality: the Messages API is HTTPS request/response; streaming uses server-sent events (SSE) over that same HTTP response — one-way, text/event-stream, reconnect by resending. There is no WebSocket endpoint on the Messages API; WebSockets appear in YOUR app tier (browser ↔ your server) to relay SSE tokens to a UI, or in voice/realtime products.

Pattern: browser ⇄ (WebSocket or SSE) ⇄ your backend ⇄ (SSE) ⇄ Claude. Keep the API key on the backend only; never call the API from the browser.

SDK integration: sync client for scripts/batch, async client for servers; configure max_retries and timeout; use with_options per call; catch typed exceptions; use messages.stream() helper for token streaming; read _request_id for support.

Timeouts: non-streaming calls have a ~10-minute limit; stream long outputs; use Batches for long offline work; set TCP keep-alive on long connections.

Idempotency and retries: the SDK retries transient errors (408/409/429/5xx); design tool side effects to be safe under retry.

Environment: ANTHROPIC_API_KEY from env/secret manager; separate keys per environment; spend limits per workspace; region/data residency via inference_geo where required.