Anthropic Messages API guide

Messages API structure

Anthropic represents conversation, images, and tools with top-level system, messages, and typed content[]. Input roles are user and assistant; do not encode a system prompt as a role=system message. The API is stateless by default, so clients resend the complete protocol-valid history for multi-turn work.

Make a minimal call through this site

Direct Anthropic REST requires both x-api-key and anthropic-version. This site recommends a unified Bearer token and also accepts the site key as x-api-key on /v1/messages; explicitly send a supported version header to pin semantics. max_tokens is required by Messages, and the model ID comes from the model marketplace.

Copycurl "$BASE_URL/v1/messages" \
  -H "Authorization: Bearer $API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "Content-Type: application/json" \
  -d '{"model":"MODEL_NAME","max_tokens":512,"messages":[{"role":"user","content":"Reply only: connected"}]}'

Successful text is in content[] blocks whose type is text. Also read stop_reason, usage.input_tokens, usage.output_tokens, and request ID. Do not assume the first block is text because tools, thinking, and other types can be interleaved.

Close client tool calls correctly

For a client tool, the model emits tool_use, the application validates its name and JSON, performs a controlled action, and returns tool_result with the same ID. Database, file, network, and side-effect permissions belong to the application. Anthropic also offers server tools such as Web Search that the platform executes and bills differently; the two categories are not interchangeable.

Streaming is not OpenAI choices

Messages streams include message/content-block start, delta, and stop events, plus possible ping, new unknown events, and an in-stream error after HTTP 200. Parse complete SSE events, tolerate unknown types, accumulate tool JSON and usage, and keep the operation incomplete until message_stop.

Errors and request IDs

Official statuses include 400 request, 401 authentication, 402 billing, 403 permission, 404 resource, 413 body size, 429 rate, 500 internal, 504 timeout, and 529 overload. Error objects include type, message, and request_id. Retry only connection errors, transient 429, and 5xx confirmed to be transient with bounded backoff; official SDKs can also retry automatically.

Context, stop reasons, and long work

An input beyond the context window can return 400 invalid_request_error. Selected newer models can instead return a successful message with model_context_window_exceeded when generation reaches the window. Estimate before sending with Token Counting or an equivalent. Prefer streaming for long responses and asynchronous batches for offline work rather than only increasing a client timeout.

Security, cost, and compatibility boundary

Separate keys by workspace and environment, set expiration, and store them in secret management; production can evaluate Workload Identity Federation. Cost includes more than visible text: tool schemas, results, thinking, and server tools can contribute. This gateway does not guarantee extended thinking, caching, batches, citations, or vision on every channel; contract-test system placement, content blocks, tool results, stop reasons, and usage.