The Claude API Surface: Messages, Batches, Files

Almost everything on the Claude platform is reached through one endpoint. Tools, structured outputs, thinking, citations and server-side tools are all features of a Messages request, not separate products. A small set of supporting endpoints handles asynchronous volume, file reuse, token counting, model discovery and organisation administration. Knowing this map lets you design integrations that use the platform as intended instead of rebuilding its features.

Anatomy of a Messages request

Field	Purpose	Architect's note
model	Which model serves the request	Keep in configuration; pin versions in production
max_tokens	Hard cap on output tokens for this response	Do not lowball; truncated output needs a retry
system	Operator instructions; string or array of blocks	Array form allows cache breakpoints
messages	Alternating user and assistant turns with content blocks	First must be user; the API is stateless so send full history
tools	Custom tool schemas, Anthropic-defined tools, server tools, MCP toolsets	Rendered first for caching; keep order stable
tool_choice	auto, none, or forced	Forced modes are not supported on some current models
output_config	Structured output format, effort, task budget	Preferred to deprecated top-level alternatives
thinking	Reasoning configuration	Adaptive on current models; see per-model docs
stream	Server-sent events instead of a single response	Required in practice for long outputs
metadata, stop_sequences	Request tagging; custom stop strings	Metadata user ID helps abuse detection

Content blocks are typed: text, image, document, tool_use, tool_result, thinking, and result blocks for server tools. Responses carry a stop_reason (end_turn, max_tokens, stop_sequence, tool_use, pause_turn, refusal) and a usage object with input, output and cache token counts. Always branch on stop_reason before reading content; a refusal carries structured stop_details, and pause_turn means a long server-tool turn should be continued by sending the response back.

Requests carry an anthropic-version header; beta features are opted into with an anthropic-beta header or the SDK's beta namespace. Treat beta features as architecture risks: they may change or require migration.

Supporting endpoints

• Token counting returns the input token count for a prospective request. Use it for budgeting, for deciding whether a document fits, and for re-baselining when a model's tokenizer changes.
• Models API lists models with their context window, output limit and capabilities. Use it to validate configuration at deployment and to drive dashboards.
• Admin API manages organisation members, workspaces, API keys and related resources, and exposes usage and cost reporting. It requires an admin credential distinct from ordinary API keys.

Message Batches

The Batches API accepts many Messages requests in one submission, processes them asynchronously within a service window measured in hours, and returns results at a substantial discount. Each request carries a custom_id; results arrive in any order and must be keyed by that ID, never by position. Statuses move through in-progress to ended; individual results may succeed, error, be cancelled or expire, so handle each outcome.

Use batches when nothing is waiting on the answer: nightly document processing, backfills, evaluation runs, dataset labelling, periodic report generation. Combine with prompt caching where many requests share a prefix, but do not depend on hit rates in batch; processing order is not guaranteed. Batch limits on request count and payload size are in the docs.

Files API

The Files API lets you upload a file once and reference it by ID in document or image blocks across many requests, instead of resending base64 content. It also carries files produced by server-side code execution back to you. Use it for reference documents shared across users, for large PDFs used in many sessions, and for any workflow where the same content appears in repeated requests. The content block type must match the file's media type.

Choosing the surface

Scenario	Surface	Reason
User waiting for an answer	Messages, streaming	Latency and UX
Agent loop with tools	Messages with tools, or the SDK tool runner	Model decides next step turn by turn
50,000 documents to classify by morning	Batches	Cost and throughput; nobody waits
Same 300-page manual in every session	Files API plus caching	Upload once, cache the prefix
Weekly eval over 2,000 cases	Batches	Cheap, parallel, results keyed by case ID
Need the model's context limit at startup	Models API	Discover rather than assume

Reliability behaviour you must design for

The official SDKs retry a bounded number of times on connection errors, rate limits and server errors with exponential backoff, and apply a default request timeout that scales for large outputs in some SDKs. Make your own timeouts explicit and consistent with the SDK's, prefer streaming for anything that may take long, and add idempotency around side effects so that a retried request cannot duplicate an action. Rate limits are enforced per organisation and workspace on requests and tokens per minute; the reliability lesson in the evaluation domain covers handling, but the design consequence is that workspaces are how you isolate one team's traffic from another's.

Exam focus

• The Messages API is the single endpoint; tools, structured outputs, thinking and server tools are request features, not separate APIs.
• Know the request fields and the stop reasons, including pause_turn and refusal with stop_details.
• Batches are asynchronous, discounted, hours-scale, and return results in arbitrary order keyed by custom_id.
• The Files API avoids resending content and returns code-execution outputs; block type must match media type.
• Token counting and the Models API support budgeting and configuration validation; the Admin API manages the organisation.
• Beta headers signal change risk; SDK retries and timeouts must be matched by idempotent side effects in your design.