Quick reference

1.1 - Messages API: Request Shape & stop_reason

Required top-level fields: model, max_tokens, messages. system is a sibling of messages, never a role inside it. messages entries alternate user/assistant only - no role: system turn.

• content is always an array of typed blocks (text, image, document, tool_use, tool_result, thinking) - never assume content[0] is the whole answer; dispatch by block.type.
• max_tokens is a hard cap, not a target - Claude doesn't try to fill it.
• Stateless API: no session/conversation id. Every call resends the full history needed, or Claude has no memory of it. The client owns (and may edit) history.

1.2 - Streaming: SSE Event Lifecycle & Deltas

Order: message_start -> (content_block_start -> deltas -> content_block_stop) per block -> message_delta -> message_stop. ping events can appear anywhere; ignore them.

Streaming changes delivery only - it does not change cost or what the model computes.

1.3 - Vision: Sending Images & Verifying Extraction

• Image source: base64 + media_type (image/jpeg, image/png, image/gif, image/webp), or a hosted URL Claude fetches itself.
• Multiple images allowed per turn, any order relative to text blocks. Oversized images are auto-downscaled.
• A separate document block type handles PDFs directly (page-by-page) - no need to pre-convert to page images.
• Image tokens scale with resolution and count as input_tokens - crop/downscale to the relevant region to cut cost and reduce attention dilution.

Pattern for a value that feeds a decision: force a tool call with a typed input_schema (not free text) + add a cross-check field (e.g. currency symbol) + a code-side sanity rule (threshold / mismatch -> flag for review) before auto-acting. Never let a single vision pass drive an automated payment or compliance action unverified.

1.4 - Prompt Caching: Breakpoint Placement & Economics

• cache_control: {type: "ephemeral"} goes on a content block, not as a top-level request field. Up to 4 breakpoints per request.
• Place the breakpoint after the large, stable, repeated content (system prompt, tool defs, shared document) and before the part that changes every call.
• Cache match is exact-prefix: any change anywhere before/at the breakpoint (reordered tools, one changed word) = full miss, not a partial hit.
• Default TTL ~5 minutes from last use, refreshed on each hit; a longer-lived option exists for bigger call gaps.
• In a growing agentic loop, move the breakpoint forward each turn so it always covers all but the newest one or two turns - a fixed breakpoint caches a shrinking fraction as the conversation grows.

Distractor to reject: caching speeds up output *generation*. It does not - it only cuts the cost/latency of reprocessing input already seen.

1.5 - Tool Use Loop: Contract & Failure Handling

• Tool def needs name, description (the primary signal Claude uses to decide when to call it - not decoration), input_schema with every genuinely-needed field marked required.
• tool_choice: auto (default, decide whether/which) | any (must call some tool) | tool + name (force one) | none (disable calling this turn, tools still defined).
• Every tool_use block needs exactly one matching tool_result, keyed by tool_use_id, inside a new user message (never appended to the assistant's own turn).
• Claude may return multiple tool_use blocks in parallel - always collect and answer *every* one, not just the first.
• A failed tool execution still returns a tool_result, with is_error: true and a description - never crash the loop or drop the result silently.
• Replay the assistant's turn exactly as received (full content array, including any preceding text block) - don't trim it to just the tool_use block.

1.6 - Extended Thinking: Budget, Signature, Replay

• Enabled via a thinking parameter with a token budget_tokens (or effort level) - separate from and additional to max_tokens for the visible answer.
• Helps: math, multi-constraint planning, subtle debugging, weighing evidence. Wastes cost/latency on: simple lookups, rewrites, obvious classifications.
• thinking blocks carry a cryptographic signature; redacted_thinking blocks arrive encrypted when a safety flag trips. Both must be replayed byte-for-byte, unmodified in later turns - never hand-edit, summarize, or drop either.
• On supported models, thinking can interleave with tool calls (think -> tool call -> result -> think again) within one extended turn.
• A too-small budget can truncate reasoning mid-thought (worse than no thinking); a too-large budget for an easy task just costs more - size to the task, not a global max.

1.7 - Choosing an Application Shape

Two decision questions: (1) Does a human need this result right now? (2) Does any step depend on what an earlier step returned?

• A batch request is an array of individually-parameterized items, each with its own custom_id used to match results back - not one shared prompt.
• One product commonly mixes shapes: sync chat + a background agentic task + a nightly batch job, each matched to its own requirements.
• Raw Messages API loop = full control, simple/custom needs. Claude Agent SDK = maintained loop + tool wiring + hooks, faster path to a production-grade loop.
• Distractor to reject: reaching for an agentic loop on thousands of independent, single-step classifications (over-engineering) - or using Batches for a live chat (unacceptable latency).

1.8 - Rate Limits, Retries, Idempotency

• Limits apply on multiple axes at once: requests/minute, input tokens/minute, output tokens/minute (tracked separately), plus a separate concurrent-connections cap - a large parallel batch can get throttled on concurrency even while under the per-minute ceilings.
• Read rate-limit response headers (limit, remaining, reset) proactively - slow down before hitting zero, don't just react to a 429.
• Backoff: delay roughly doubles each retry, capped at a max. Jitter (small random offset) prevents synchronized clients from retrying in lockstep (thundering herd).
• Idempotency key: reuse the *same* key across every retry of one logical operation (side-effecting calls) so a retry that duplicates a request the server already processed is recognized as a duplicate, not re-executed.
• Limits scale with account usage tier. A priority service tier trades cost for a stronger throughput guarantee - reduces *how often* throttling happens; backoff handles it *after* it happens.

1.9 - API Keys, Auth & Config Management

• API key = bearer credential sent as x-api-key header. Env vars / secrets manager only - never in source, never logged, never inside a prompt.
• A key that ever touched git history (even a deleted commit) is compromised - rotate it, don't just remove it from the latest file.
• Never call the Messages API directly from browser/mobile client code - the key is extractable from compiled/shipped code. Always route through your own backend proxy that holds the key server-side.
• Model name, max_tokens, temperature, enabled tools, thinking budget = config, not code - keeps behavior auditable, diffable across environments, and change-able without a redeploy.
• Scope keys narrowly: separate key per environment (dev/staging/prod); org -> workspaces boundary isolates teams' usage/billing. Admin-level keys (manage members, billing, other keys) get tighter access than a workspace call-only key.
• Rotate on a routine schedule, not just after a known leak - not every exposure (log aggregator, screen share, pasted debug output) gets detected.

1.10 - Testing Claude-Integrated Applications

• Trap: asserting response.content[0].text === "exact string" on live output in CI - flaky by construction.
• LLM-as-judge (a separate Claude call grading against a rubric) scales quality review, but the grading prompt itself needs validating against human judgment, and scores are trusted as a pass rate across many cases, not per-case.
• A useful golden eval dataset includes past regression cases, ambiguous judgment calls, and adversarial/malformed input - not just easy typical-case prompts.

1.11 - Versioning & Rolling Out Model Changes

• Pinned versions are eventually deprecated on a published timeline - track deprecation notices and migrate proactively; pinning ≠ 'set and forget'.
• Before rollout: test the new version against your own eval set, including format/schema-conformance cases specific to your feature, not just general quality - output-format habits can shift between versions even when overall quality improves.
• Staged rollout (a % of real traffic on the new version, compared against the old) catches long-tail regressions a curated offline eval set can miss.
• A user-visible behavior change from a version bump (tone, length, edge-case handling) is a product change, not just a backend deploy - needs the same change communication (support heads-up, rollback plan) as any product change.

Distractor to reject: "newer is presumably better, no need to validate." Aggregate benchmark improvement doesn't guarantee no regression on your specific feature's format requirements.