Anthropic API version 2026-10-21: what breaks and how to migrate

Anthropic's API version 2026-10-21 makes three kinds of request that used to work return a 400: any request that sends temperature, top_p or top_k; a document block placed directly in an assistant message; and a text block with a non-empty citations array in a user message¹. You get the new version when you send anthropic-version: 2026-10-21 yourself, or when you upgrade to one of the new SDK majors, which send it by default. Nothing forces the move: 2023-06-01 still works, and the migration guide tells you to keep a request on it if that request relies on a non-default temperature¹.

This guide is for the developer who has to bump the SDK and the lead who has to approve it: what changed, where the affected calls hide, what to use instead, and how to test before release.

What changes on 2026-10-21

The Messages API changes apply to POST /v1/messages, to token counting, and to every request inside a Message Batch created with the new version¹. Anthropic's versions page lists the same three rules and adds that the sampling parameters return a 400 "on every model"².

The Admin API and the Claude Enterprise Analytics API also drop old field names on the new version: roles becomes role_ids, group_id becomes rbac_group_id, an RBAC role's name becomes display_name, rate-limit entries lose group_type for group.type, and API keys lose workspace_id in favour of scope¹. If you have an internal tool that lists keys or workspaces, it is in scope too. The workspace_id change has a trap: on 2023-06-01 a null meant the Default Workspace or an all-workspaces key; on the new version a key bound to the Default Workspace carries the workspace's real id in scope.workspace_id, and an all-workspaces key has scope {"type": "organization"}¹.

What it means for sampling on each model

Removing the three parameters is not the same change on every model. Anthropic is explicit: without them a request samples at the defaults, including a temperature of 1.0, exactly like a 2023-06-01 request that leaves them out. Claude 4.7 and later models already accept only the defaults, so they "sample as before". On a model that accepts other values, such as Claude Sonnet 4.6, a request that lowered temperature for more consistent output loses that effect, and "no other setting replaces it"¹.

The current lineup (Claude Fable 5.1, Opus 5.5, Sonnet 5.5 and Haiku 5.5) is all on the 4.7-and-later side³. For traffic on those models, the version change is mostly about deleting parameters that were already doing nothing beyond their defaults. The risk sits with older models still in use and with code paths you forgot send a temperature at all.

What the new SDKs change besides the header

Each SDK's first release on 2026-10-21 is a new major version: anthropic 2.0.0 for Python, @anthropic-ai/sdk 1.0.0 for TypeScript, Go 2.0.0 (module path ending in /v2), anthropic-java 3.0.0, the C# package 13.0.0, PHP 1.0.0, Ruby 2.0.0, and the ant CLI 2.0.0¹. Three of the accompanying changes catch teams that only expected the API rules.

• The sampling parameters are gone from the SDK. As of the new majors, the SDKs and the CLI "no longer have the three parameters"¹. In a typed codebase that is useful: the compiler finds the call sites for you. Code that passes extra fields through an untyped dictionary or an extra-body escape hatch is not caught that way and fails at the API instead.
• The key moves to Authorization: Bearer. The SDKs and the CLI now send the API key as a bearer token instead of X-Api-Key. Any proxy, gateway, middleware, log filter or test stub that reads X-Api-Key must read Authorization instead, or you set X-Api-Key yourself. The Claude API itself accepts either header¹.
• Companion packages move together. In TypeScript, v1 of the Bedrock, Vertex, Foundry, AWS and Google Cloud packages needs v1 of @anthropic-ai/sdk; upgrade one without the others and the package manager installs a second, older copy¹.

The guide also lists SDK-only changes: per-role message types, removal of the legacy Text Completions API from several SDKs, and removal of client-side compaction in the TypeScript and Ruby tool runners in favour of server-side compaction¹. Read the section for your language before you open the pull request.

On Amazon Bedrock, 2026-10-21 exists only for Claude 4.7 and later. Calls to older Claude models on Bedrock should stay on the SDK version or header they use today until they move to a newer model¹.

Find every affected call site

The calls that fail after an SDK bump are rarely the ones in your main service. They are in a helper that sets temperature=0 "for determinism", a batch job, an eval harness, or a framework adapter that fills in a default you never wrote.

Search the code

Start with a literal search across every repository, including notebooks and infrastructure code:

# Sampling parameters near Anthropic calls (review each hit by hand).
rg -n --hidden -g '!node_modules' -g '!*.lock' \
  -e '\b(temperature|top_p|top_k|topP|topK)\b' \
  -e 'anthropic-version' \
  -e '(x-api-key|X-Api-Key)'

# Documents in assistant turns and citations sent back in user turns.
rg -n --hidden -g '!node_modules' -e '"type":\s*"document"' -e 'citations'

Then look where the values are not literals: shared client wrappers, prompt-template files and stored prompt configurations, feature flags and remote config that carry model settings, and the configuration of any agent or LLM framework you call Claude through. Many frameworks expose temperature as a model setting; check whether yours sends one when you leave it unset, in the version you run, by reading its request logging or source rather than assuming.

Search the traffic

Code search shows what could be sent; traffic shows what was. If you log outgoing request bodies, or a gateway records them, count Claude requests in the last 30 days that carry any of the three parameters, grouped by service and model. Do the same for request bodies that send a document block in an assistant turn. A conversation store that replays Claude's earlier replies with their citations is fine; a pipeline that copies cited text into the next user message is not.

Check the auth path

List every hop between your code and Anthropic: corporate egress proxies, API gateways, logging middleware, mock servers in tests. Any of them that keys on X-Api-Key needs a change before the SDK upgrade ships.

What to use instead

Drop the parameters on Claude 4.7 and later. They were already pinned to the defaults there, so removing them changes nothing about sampling¹.

Use structured outputs for consistent shape. Much of the temperature=0 in production code exists to stop a parser from breaking. Claude's structured outputs constrain the response to a JSON schema with output_config.format set to {"type": "json_schema", "schema": {...}}, and strict tool use sets "strict": true on a tool definition; the feature is generally available on the current models⁴. A schema guarantees the shape, not the content, so keep validating values.

Use effort for spend and depth, not randomness. output_config.effort (low, medium, high, xhigh, max) controls how many tokens Claude spends on a response, thinking and tool calls included. Claude Opus 5.5 and Haiku 5.5 default to medium, other models to high⁵. It is a useful setting to make explicit during the same migration, but it is not a replacement for a lowered temperature, and Anthropic does not present it as one.

Keep a request on 2023-06-01 when it truly needs the parameter. On a model such as Claude Sonnet 4.6, if a lower temperature measurably matters to a task, the documented option is to keep that request on the old version¹. Treat that as a pin with an owner and a review date, and plan the model move that makes it unnecessary.

# Before: anthropic 1.x, anthropic-version 2023-06-01
client.messages.create(
    model="claude-sonnet-5-5",
    max_tokens=2048,
    temperature=0,          # removed in 2.0.0; a 400 on 2026-10-21
    messages=messages,
)

# After: anthropic 2.0.0, anthropic-version 2026-10-21
client.messages.create(
    model="claude-sonnet-5-5",
    max_tokens=2048,
    output_config={
        "effort": "medium",  # explicit spend and depth, not randomness
        "format": {"type": "json_schema", "schema": TICKET_SCHEMA},
    },
    messages=messages,
)

A test plan before release

1. Inventory. Run the code, config and traffic searches above. Give every hit an owner.
2. Upgrade in a branch. Move the SDK and every companion package in one change, fix compile errors, and remove the three parameters everywhere.
3. Replay recorded requests. Send a few hundred recorded requests per workload through the new SDK against a staging key. Any 400 names a call site the searches missed.
4. Compare outputs where sampling changed. For calls to models older than 4.7 that used a non-default temperature, compare task success, parse failures and output tokens per request before and after. On 4.7 and later models expect no difference.
5. Test the auth path end to end. Through every proxy and in CI, not only from a laptop that talks to Anthropic directly.
6. Release with the fixes. Anthropic's own guide says to release the SDK upgrade together with the code fixes¹; a staged SDK bump without them is a staged outage.
7. Watch for a week. Alert on Anthropic 400 errors by service and on any change in output tokens per request.

Running Claude through INFRO during the change

INFRO is a control plane that sits between your applications and the provider accounts you already hold; you connect your own Anthropic account and Anthropic bills you directly. Two of its paths matter here, and they behave differently.

OpenAI-compatible chat (/v1/chat/completions). When the model that serves a request refuses a sampling parameter, INFRO does not send it. For Claude 4.7 and later (Opus 4.7 and 4.8, the Claude 5 family, Fable) it drops temperature, top_p and top_k, and for Claude 4.5 and 4.6 it keeps temperature and drops top_p when both are sent. The response lists what was dropped in the X-INFRO-Params-Dropped header, for example X-INFRO-Params-Dropped: temperature, top_p, so you can find callers still sending them without a 400. Only sampling parameters are ever dropped; a refused stop, tools or response_format reaches you as the provider's 400. See chat completions.

Anthropic's own shape (/v1/messages). For Claude Code, the Agent SDK and code written against Anthropic's SDK, INFRO accepts the key as x-api-key or Authorization: Bearer, so the new SDK majors authenticate without a change. On an Anthropic connection the body reaches Anthropic as written, so INFRO does not strip parameters on this path. INFRO accepts the anthropic-version header and pins the version it sends to Anthropic itself (2023-06-01 when this was written), so a request through this path is evaluated under that version, not the one your SDK sent. INFRO therefore does not give you 2026-10-21 behaviour today, and a non-default temperature sent to a Claude 4.7 or later model is still refused by Anthropic. See coding agents.

Either way, the request log records each request with its model, key and status, which gives you the traffic inventory in step 1 for whatever goes through INFRO. Calls made straight to Anthropic do not appear there.