The Anthropic Messages API is one endpoint with a strict block grammar

Evidence status

Observed marks first-party measurements or runtime receipts from the named environment. Derived marks arithmetic calculated from cited inputs. Specified marks vendor or standards documentation. Implemented and deployed name code and live-state evidence, respectively. Reproduced means the stated procedure was rerun. Externally attested marks operator reports; those reports show that an experience occurred, not that it is universal.

One command proves the request envelope

Set the key in an environment variable. Do not put it in the JSON body, a URL, source control or a log.

export ANTHROPIC_API_KEY="<your Anthropic API key>"

curl -sS https://api.anthropic.com/v1/messages \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  --data '{
    "model":"claude-sonnet-4-5",
    "max_tokens":32,
    "system":"Answer with digits only.",
    "messages":[{"role":"user","content":"What is 7 times 6?"}]
  }' | jq '{type,role,content,stop_reason,usage}'

Expected shape:

{"type":"message","role":"assistant","content":[{"type":"text","text":"42"}],
 "stop_reason":"end_turn",
 "usage":{"input_tokens":"<integer>","cache_creation_input_tokens":"<integer>",
          "cache_read_input_tokens":"<integer>","output_tokens":"<integer>"}}

The token values vary with model and prompt. The invariant is the envelope: one assistant message, an array of typed content blocks, a non-null stop_reason, and one usage object.

Your key is checked before your version header, so a version mistake hides behind a 401

Three headers are mandatory: x-api-key, anthropic-version, content-type: application/json. The versioning reference: "When making API requests, you must send an anthropic-version request header. For example, anthropic-version: 2023-06-01." What it does not say is the order of checks. Three calls to api.anthropic.com on 2026-07-26, varying only headers:

Call C sends a version that does not exist and still gets the key error. Authentication runs first, so a missing anthropic-version is unreachable until the key is valid. Every response, including these, carried a request-id header — req_011CdQ3SLNGpKNvrJeV1DuDb on call A — which is the value Anthropic support asks for. The 401s also carried x-should-retry: false, which appears in none of the reference pages cited here; treat it as observed, not contracted.

Three required fields, and one field that looks like a message but is not

The system prompt is the field people get wrong, because every other major chat API carries it as a message. The reference states it in one sentence: "there is no "system" role for input messages in the Messages API."

{"model": "claude-sonnet-4-5", "max_tokens": 1024,
 "system": [{"type": "text", "text": "You are terse."}],
 "messages": [{"role": "user", "content": "What is 7 times 6?"}]}

{"role": "system", "content": "..."} inside messages is not a system prompt.

The same page nonetheless lists "system" among the accepted role values, and flattening that contradiction would be a lie. On Claude Fable 5, Mythos 5, Opus 4.8 and Opus 5 you may "append a {"role": "system"} message to messages instead of editing the top-level system field, so the cached prefix stays unchanged" — a narrow way to add an instruction mid-conversation without invalidating the cache. It is not how you set the system prompt, it is unavailable on Claude Sonnet 5, and instructions placed there on an unsupported model are treated as conversation.

Five content-block types carry everything in both directions

{"type": "text", "text": "What is 7 times 6?"}
{"type": "image", "source": {"type": "base64", "media_type": "image/png", "data": "iVBORw0KGgo..."}}
{"type": "tool_use", "id": "toolu_01A", "name": "get_weather", "input": {"city": "Dallas"}}
{"type": "tool_result", "tool_use_id": "toolu_01A", "content": "41C and clear"}
{"type": "thinking", "thinking": "...", "signature": "EqQBCgIYAhIM1gbcDa9GJwZA2b3hGgxBdjrkzLoky3dl1pki..."}

The tool_result row is what catches people migrating from other APIs: a tool's answer goes back inside a user turn, not a message with a dedicated tool role.

An unpaired tool_use does not fail one request, it kills every request after it

Three rules, all enforced:

1. Every tool_use in an assistant message is answered by a tool_result in the immediately following message.
2. That message has role: "user".
3. Each tool_result.tool_use_id matches a tool_use.id from that turn, and those ids are unique within it.

Break rule 1 and the 400 names the message index and the id. The real string, from an agent whose auto-compaction cut a turn in half:

messages.8: tool_use ids were found without tool_result blocks immediately after: toolu_01GJ.... Each tool_use block must have a corresponding tool_result block in the next message.

This is worse than an ordinary validation error because the endpoint is stateless: the client resends the whole history every turn. Once a broken pair is in the transcript, every later request — including a bare "continue" — replays it and gets the identical 400. The session is dead until the client edits its own history.

Rule 3 fails more quietly. A layer that invents missing ids from the tool name produces duplicates the moment the model calls one tool twice in a turn:

A duplicate id is sometimes a 400 and sometimes a silent mispairing, where one tool's output is handed back as another's. Generate ids per call, never per tool name.

The round trip working, captured live on 2026-07-26 — assistant tool_use, user tool_result, finished answer:

{"content": [{"type": "text", "text": "The weather in Dallas is currently 41°C and clear. It's quite warm with clear skies!"}],
 "stop_reason": "end_turn",
 "usage": {"input_tokens": 195, "output_tokens": 48, "cache_read_input_tokens": 0, "cache_creation_input_tokens": 0}}

Streaming is a nested event grammar, and tool arguments arrive as string fragments

With "stream": true the response is text/event-stream. Each event has an SSE name and a JSON payload repeating that name in type. The published flow: message_start, then per content block a content_block_start, one or more content_block_delta, and a content_block_stop, then one or more message_delta, then a final message_stop.

One rule has no event of its own: unknown types must be ignored, not treated as failures. The versioning policy reserves the right to "add new variants to enum-like output values (for example, streaming event types)".

Assembling a tool call is what third-party implementations get wrong. The argument object arrives as raw string pieces that are individually invalid JSON:

{"delta":{"type":"input_json_delta","partial_json":"{\"location\":"}}
{"delta":{"type":"input_json_delta","partial_json":" \"San"}}
{"delta":{"type":"input_json_delta","partial_json":" Francisc"}}
{"delta":{"type":"input_json_delta","partial_json":"o, CA\"}"}}

Concatenate every partial_json for one index in arrival order and parse once at content_block_stop, giving {"location": "San Francisco, CA"}. Parsing early throws. Keying the buffer on anything but index corrupts parallel calls.

A complete stream captured on 2026-07-26 from an endpoint answering this format. The argument object arrives in a single fragment here, which is legal — a client must handle both one and many:

event: message_start
data: {"type":"message_start","message":{"id":"msg_aig","type":"message","role":"assistant","model":"@cf/zai-org/glm-4.7-flash","content":[],"stop_reason":null,"stop_sequence":null,"usage":{"input_tokens":0,"output_tokens":0}}}

event: content_block_start
data: {"type":"content_block_start","index":0,"content_block":{"type":"tool_use","id":"chatcmpl-tool-b8d5b5cf4b01d725","name":"get_weather","input":{}}}

event: content_block_delta
data: {"type":"content_block_delta","index":0,"delta":{"type":"input_json_delta","partial_json":"{\"city\": \"Dallas\"}"}}

event: content_block_stop
data: {"type":"content_block_stop","index":0}

event: message_delta
data: {"type":"message_delta","delta":{"stop_reason":"tool_use","stop_sequence":null},"usage":{"output_tokens":64}}

event: message_stop
data: {"type":"message_stop"}

Streaming is a distinct transport and fails on its own. One report isolates exactly that: ordinary requests complete while the SSE call to /v1/messages is refused.

stop_reason is an instruction to the caller, not a status label

It is null in message_start and non-null everywhere else. Seven values, each implying a different next move.

Row two, captured live on 2026-07-26 with max_tokens set to 64:

{"content": [{"type": "text", "text": "1.  **Analyze the user's request:** The user is asking \"What is 7 times 6?\". The constraint is \"Answer with digits only\".\n\n2.  **Perform the calculation:** $7 \\times 6$.\n    $7 \\times 6 = 42$.\n\n3."}],
 "stop_reason": "max_tokens", "usage": {"input_tokens": 19, "output_tokens": 64}}

The answer is in there and the turn was cut at token 64. A client that renders only on end_turn shows nothing.

input_tokens counts what comes after your last cache breakpoint, not what you sent

The identity that always holds: total_input_tokens = cache_read_input_tokens + cache_creation_input_tokens + input_tokens.

The committed outputs of Anthropic's prompt-caching notebook make it concrete — the same 187,364-token prompt, three times:

input_tokens collapses from 187,364 to 3 once a breakpoint exists, because 187,361 tokens moved into the cache columns. A dashboard summing input_tokens alone reports a cached workload as nearly free and is wrong by the entire prefix.

Both cache fields at 0 means nothing was cached, most often because the prompt was under the model's minimum — and no error is returned. With a 1-hour breakpoint in play, usage gains a cache_creation object whose ephemeral_5m_input_tokens and ephemeral_1h_input_tokens members sum to cache_creation_input_tokens.

Caching is a field you have to send, and it pays back on the second request

Nothing caches by default. A breakpoint is one field on one block:

{"type": "text", "text": "<20,000 tokens of instructions>", "cache_control": {"type": "ephemeral"}}

ephemeral is the only type. Default lifetime is five minutes, refreshed free on every hit. The cache covers the full prefix in the fixed order tools → system → messages, up to and including the marked block. Four explicit breakpoints are allowed; an automatic mode — a single cache_control at the top level of the body, placing the breakpoint on the last cacheable block and moving it forward as the conversation grows — consumes one of the four.

Below the model minimum the marker does nothing and says nothing: 512 tokens on Claude Opus 5 and Fable 5; 1,024 on Opus 4.8, Sonnet 5, Sonnet 4.6 and Sonnet 4.5; 2,048 on Opus 4.7; 4,096 on Opus 4.6, Opus 4.5 and Haiku 4.5.

The multipliers, quoted: "5-minute cache write tokens are 1.25 times the base input tokens price"; "1-hour cache write tokens are 2 times the base input tokens price"; "Cache read tokens are 0.1 times the base input tokens price."

Worked on a real prompt: a 20,000-token static prefix of tool definitions plus a long system prompt, on Claude Sonnet 4.5 at $3.00/MTok input, $3.75/MTok 5-minute writes, $6.00/MTok 1-hour writes and $0.30/MTok reads, sent fifty times inside one five-minute window:

The five-minute cache removes $2.6310 of $3.0000, or 87.7 percent. Break-even is the second request: two uncached requests cost 2.00 units of base price, a write plus one read costs 1.25 + 0.10 = 1.35.

The one-hour cache looks worse there and wins the moment the gap between requests exceeds five minutes. Same prefix, one request every six minutes for an hour — eleven requests, five-minute entry expired between every pair:

Asking for the longer lifetime is one more key: "cache_control": {"type": "ephemeral", "ttl": "1h"}. Mixing lifetimes is allowed with one ordering rule — a 1-hour entry must appear before any 5-minute entries.

Three ways caching silently does nothing

The field is never sent. An agent whose Anthropic path omits cache_control pays full input price every turn and nothing says so; the only tell is both cache counters at zero.

A proxy strips it. Anything in the path can drop unrecognised keys. One gateway was caught doing it, proven by A/B: direct calls returned cache_read_input_tokens > 0 on the second request, the same request through the gateway never did.

The same failure shows up as a routing bug when markers are injected on only one code path:

Something in the prefix moves per request. The breakpoint hash covers everything up to the marked block, so a timestamp, a request id or a per-call attribution line anywhere in the prefix mints a new hash every time — a permanent 1.25x write and never a read. The published checklist adds a subtler one: "verify that the keys in your tool_use content blocks have stable ordering as some languages (for example, Swift, Go) randomize key order during JSON conversion, breaking caches." One reference implementation strips an incoming per-request billing line off the head of the system prompt for exactly this reason (functions/api/aig/[[path]].js, lines 116–130).

The one-hour lifetime is also not reachable from every client. One operator reading the wire found the marker present and the lifetime absent:

Because placement is manual, proxies exist purely to insert breakpoints for integrations that never expose the request body:

The shape teams converge on afterwards is worth copying: one tool for structured output, parsed tool_use, cache_control: ephemeral on system and context, exponential backoff on 429.

count_tokens is free, and the estimators that replace it drift

POST /v1/messages/count_tokens takes the same body minus max_tokens and returns one integer:

curl -s https://api.anthropic.com/v1/messages/count_tokens \
  -H "x-api-key: $ANTHROPIC_API_KEY" -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{"model":"claude-sonnet-4-5","system":[{"type":"text","text":"Answer with digits only."}],
       "messages":[{"role":"user","content":"What is 7 times 6?"}]}'   # -> {"input_tokens": 18}

It is "free to use but subject to requests per minute rate limits based on your usage tier", and those limits are independent: "Token counting and message creation have separate and independent rate limits. Usage of one does not count against the limits of the other." Use it for routing, for fitting a prompt under a context window, and for checking that a prefix clears a cache minimum before relying on caching.

Because it is optional, gateways often substitute a character estimate. Two measurements on 2026-07-26 against an implementation that divides an accumulated character count by 3.7 (functions/api/aig/[[path]].js, lines 445–457). The body above returned 18; sent to /v1/messages, it reported usage.input_tokens of 19 — low by one, 5.3 percent.

The second shows the error is not stable. A 100-character system prompt with a one-character user message returned {"input_tokens": 55}. Counting the system prompt once gives ceil((100 + 1) / 3.7) = 28. Fifty-five is ceil((100 + 100 + 1) / 3.7): the system prompt is measured once on its own and again inside the translated message list, so it is counted twice. Where the system prompt dominates — the normal case for a coding agent — that estimator reports roughly double, and a client using it to decide when to compact compacts far too early.

The error catalogue, by symptom

Every error body is JSON with a top-level error carrying type and message, plus a request_id:

{"type": "error",
 "error": {"type": "not_found_error", "message": "The requested resource could not be found."},
 "request_id": "req_011CSHoEeqs5C35K2UUqR7Fy"}

Match on the SDK's typed exception classes, not on message text — the reference is explicit that "the values within these objects may expand".

Three other vendors answer this exact shape, and each drops different fields

The same credential-free request body reached all three Anthropic-shaped routes on 2026-07-26 and all returned HTTP 401: DeepSeek returned Authentication Fails (governor); Z.ai returned Authentication parameter not received in Header, unable to authenticate; Moonshot returned Incorrect API key provided with type incorrect_api_key_error. These are route-existence receipts, not compatibility claims.

Because the format is one endpoint with a documented body, other providers implement it and inherit any client that speaks it. DeepSeek documents https://api.deepseek.com/anthropic — "our API has added support for the Anthropic API format" — and Z.ai documents https://api.z.ai/api/anthropic. Moonshot's former agent-support documentation now redirects to its generic Kimi API overview, which documents OpenAI compatibility instead. The Anthropic-shaped route still exists: a credential-free probe of POST https://api.moonshot.ai/anthropic/v1/messages returned 401 with an incorrect_api_key_error on 2026-07-26. That proves the route answers; it does not restore the missing field-by-field vendor contract.

Compatible is a range, not a boolean. DeepSeek publishes a field-by-field support matrix, and reading it is the fastest way to see which parts of the format are load-bearing:

Two rows carry the whole caching story from the other side. anthropic-version ignored means the version header buys nothing. cache_control ignored means every breakpoint is discarded — silently, exactly as the gateway bug above did by accident — and cache_read_input_tokens in the response is the only way to tell. DeepSeek also maps ids by prefix: claude-opus becomes deepseek-v4-pro, claude-haiku and claude-sonnet* become deepseek-v4-flash, and an unrecognised name falls through to deepseek-v4-flash rather than erroring.

A working configuration that routes an Anthropic-format client to a non-Anthropic model, with a test suite over these behaviours, is in Claude Code on Kimi, GLM or Grok through your own Cloudflare account. The account setup behind it is in the AI Gateway setup page and the credit accounting in Cloudflare Unified Billing.

Fresh wire checks reproduce the contract

The complete harness is the same sequence printed below, run at 05:15–05:16 UTC on 2026-07-26. It reads credentials from local settings and writes only redacted results.

The exact local commands were node /private/tmp/codex-messages-api/measure.mjs and node /private/tmp/codex-messages-api/measure-headers.mjs. Neither prints a credential.

Method for the six measurements above

All six were captured on 2026-07-26. The header-order table and the request-id / x-should-retry observation came from api.anthropic.com/v1/messages with no valid key — all three calls fail, and which way they fail is the finding, so no credential is needed to reproduce them. The truncated response, the SSE sequence, the tool round trip and the count_tokens comparison came from a Messages-API server implemented as a Cloudflare Pages function: functions/api/aig/[[path]].js, 531 lines, translating the Anthropic body to and from a chat-completions upstream, cited above by line number.

To rerun any of them, point BASE at https://api.anthropic.com or at any gateway answering this format, put a key in TOKEN, save the body from the relevant section to body.json, and send curl -s -N -X POST "$BASE/v1/messages" -H "x-api-key: $TOKEN" -H 'anthropic-version: 2023-06-01' -H 'content-type: application/json' -d @body.json.