Calling the Anthropic (Claude) API

The Messages API takes a model name, a required max_tokens budget, optional generation controls, optional top-level system instructions, and a messages array. Each message has a role of user or assistant and content that can be a string or an explicit list of content blocks.

The response mirrors this structured design. It includes an id, type, role, model, a content list, stop_reason, optional stop_sequence, and a usage object. Production code should read these fields instead of scraping plain text from the response. The shape gives the application enough metadata to decide whether the answer is complete, truncated, waiting for a tool result, or failed upstream.

Anthropic separates durable instructions from conversation turns. The system prompt is provided as a top-level system field, not as a message with role system. The messages array contains only user and assistant turns: the current user request, prior user messages, and prior assistant outputs that define conversation state.

This distinction matters in migrations from other chat APIs. If you put a fake system message into messages, you are not using the Anthropic schema correctly. A clean integration keeps policy, tone, source-of-truth rules, and tool rules in system, while user data and previous assistant answers remain in messages.

A message can contain content as a simple string for basic text, but serious integrations should understand the block model. A content list can hold text blocks, image blocks, assistant tool_use blocks, and user tool_result blocks. The response is also a content list, so the first item is not guaranteed to be the only meaningful item.

The list design lets one message carry multiple modalities and multiple actions. A user message can include text plus an image. An assistant message can include explanatory text plus one or more tool_use requests. A later user message can include tool_result blocks that connect server-side execution back to Claude. Treating content as blocks keeps the protocol extensible and avoids brittle string conventions.

Anthropic requires max_tokens on Messages API calls. It is the maximum number of output tokens Claude may produce, not the total context window and not a guarantee that the model will use all of them. Set it high enough for the desired answer and low enough to protect latency and cost.

After a response, stop_reason tells you why generation stopped. end_turn means Claude naturally finished the turn. max_tokens means the output hit the requested budget and may be incomplete. stop_sequence means a caller-provided stop sequence was encountered. tool_use means Claude is asking the application to run a tool and return tool_result content in a follow-up message.

Sampling parameters affect how predictable the output is. temperature controls randomness directly: lower values are better for extraction, classification, and support workflows, while higher values can help brainstorming. top_p nucleus sampling limits choices to a cumulative probability mass. top_k limits the next-token candidates to a fixed count.

In production, change one sampling control at a time. For most beginner integrations, use low temperature and leave top_p and top_k at provider defaults unless you have evaluation data. Over-tuning all three can make behavior harder to reason about and harder to reproduce during an incident.

Every successful response includes a usage object with input_tokens and output_tokens. Log these values with the model, prompt version, cache behavior, request id, latency, and stop_reason. That data is how teams explain cost spikes, truncation, and quality regressions.

Prompt caching adds more token accounting fields in supported responses, such as cache creation and cache read token counts. Those fields are important because cached reads and cache writes are priced differently. The application should treat usage as billing and performance telemetry, not as a debugging afterthought.

The top-level system field makes the request contract explicit. Conversation turns are the transcript; system is the application instruction layer. That separation improves portability across turns and makes it clear which text is durable policy versus user-provided content.

This also helps with prompt caching and prompt management. Stable system context can be authored, versioned, and cached separately from the rapidly changing user message. In an interview, call out that role priority is not just style. It affects security, maintainability, and debugging.

Content blocks are the protocol surface for multimodal and agentic behavior. A text block carries ordinary language. An image block carries visual input. A tool_use block is Claude asking the application to call a named tool with JSON input. A tool_result block is the application returning the result in a later user turn.

This model avoids fragile instructions such as write TOOL_CALL followed by JSON. The application can inspect a typed block and route it deterministically. It also lets one response mix text and tool calls, so client code should iterate through the whole content array rather than assuming content at index zero is all that matters.

Prompt caching is useful when a large part of the prompt is stable across requests: policy manuals, product documentation, long examples, or tool definitions. Add cache_control with type ephemeral to supported content blocks near the end of the reusable prefix. Anthropic can cache that prefix so later calls avoid reprocessing the same tokens.

The default ephemeral cache has a 5-minute TTL. Cache writes and cache reads are billed differently: writing cached tokens has its own creation price, while reading cached tokens is much cheaper than sending the same uncached input again. The break-even point depends on model pricing and reuse frequency, but the rule is simple: cache long stable context that will be reused soon, not tiny one-off prompts.

When streaming is enabled, Anthropic sends server-sent events over one HTTP response. The client receives lifecycle events such as message_start, content_block_start, content_block_delta, content_block_stop, message_delta, and message_stop. Text usually arrives in delta events, while final usage and stop information arrive later in the stream.

A robust streaming client separates transport handling from UI rendering. It should buffer deltas, handle ping events, surface stream errors, and still reconcile the final stop_reason. The user sees faster first-token latency, but the application still needs a complete final state for logging and safety checks.

Retrying every failure is dangerous. Validation errors, missing max_tokens, unknown model names, and authentication failures are permanent until the request changes. Retrying them only adds load and hides the real bug. Transient failures are different: 429 rate_limit_error, connection resets, timeouts, overloaded responses, and selected 5xx errors can succeed after a delay.

Use exponential backoff with jitter, respect retry-after, cap attempts, and make idempotency decisions deliberately. For user-facing chat, show progress or a graceful fallback instead of freezing the UI. For background jobs, put failed work on a queue with a retry budget and dead-letter path.

Log the model, prompt version, max_tokens, sampling parameters, stop_reason, latency, input_tokens, output_tokens, cache read and write token counts, and provider request id. Without these fields, debugging cost, truncation, and model changes becomes guesswork.

Design for 429 responses before launch. Use client-side concurrency limits, per-tenant quotas, exponential backoff, and fallback behavior for non-critical features. If a chat UI streams, handle both HTTP errors before the stream starts and error events inside the stream.

Set max_tokens intentionally, trim stale conversation history, summarize old turns when appropriate, and cache long stable context with ephemeral cache_control. Monitor cache write and cache read tokens separately so you can prove the cache is actually saving money.

Keep API keys server-side, never expose them in browser code, and avoid logging sensitive prompt content by default. For tool_use, authorize every tool call on your server. Claude can request a tool, but your application decides whether that tool may run for the current user and tenant.

This Python example uses the Anthropic SDK from a server-side process. It keeps the system prompt top-level, sends the user content as a text block, sets max_tokens explicitly, and prints stop_reason plus usage.

The SDK hides most server-sent event parsing, but the underlying transport is still a stream. The important application behavior is to display deltas quickly while preserving final response handling for logs and safety checks.

This example marks a long stable policy block as ephemeral cacheable context, then retries rate limits and transient provider failures with exponential backoff and jitter. Real systems should also add concurrency limits and request tracing.