Claude API Version 2026-10-21: What Changed and How to Upgrade Safely

Claude API version 2026-10-21 is the first new anthropic-version value since 2023-06-01. It makes three breaking changes to the Messages API: temperature, top_p and top_k now return a 400 error, document blocks in assistant messages return a 400, and citations on text blocks in user messages return a 400. It also renames several Admin API and Enterprise Analytics API fields. You opt in by sending anthropic-version: 2026-10-21 or by upgrading to the new SDK majors (Python 2.0.0, TypeScript 1.0.0, Go 2.0.0 and others).

The catch: upgrading the SDK is how most teams will “accidentally” move to the new version. A routine pip install -U anthropic or npm update that crosses a major version flips every request to 2026-10-21 at once. This guide lists every change Anthropic documents, shows which ones bite in real code, and gives you a safe order to upgrade in.

What is the anthropic-version header?

The anthropic-version header is a required request header that pins the shape of the Claude API you get back. Within one version, Anthropic keeps existing input and output parameters stable, but may add optional inputs, new output values, new enum variants such as streaming event types, and new error conditions. Breaking changes only arrive with a new version date.

From the versioning page, three versions exist:

If you use an official SDK, you never set the header yourself. Each SDK major sends the version that was current when that major shipped. That’s why the SDK upgrade and the API version upgrade are the same event for most codebases.

Claude API 2026-10-21 breaking changes

These changes apply to POST /v1/messages, to token counting, and to every request inside a Message Batch created with 2026-10-21.

1. temperature, top_p and top_k are removed

This is the change most people will hit. Any request that sends temperature, top_p or top_k returns a 400 error, on every model, even if you send the default value. A temperature: 1.0 left in a config file is enough to break the call.

What happens to output quality depends on the model:

• Claude 4.7 and later already accept only the default sampling values, so removing the parameters changes nothing about how they sample.
• Older models that accept other values, such as Claude Sonnet 4.6, lose any effect you got from lowering temperature. The migration guide is blunt about it: no other setting replaces it.

If a request truly depends on a non-default value, Anthropic gives you two choices: stop sending it, or keep that specific request on 2023-06-01.

2. document blocks in assistant messages return a 400

Some apps replay conversation history with a document block sitting directly in an assistant turn. Under 2026-10-21 that’s rejected. Move documents into user messages. A document nested inside another block, such as a web fetch tool result that Claude returned, is still accepted.

3. citations in user messages return a 400

A text block with a non-empty citations array in a user message now fails, and that includes text inside search_result blocks. Strip citations from those blocks. Citations on Claude’s own assistant replies that you send back are still fine, and so is "citations": {"enabled": true} on documents and search results.

4. Admin API and Enterprise Analytics field renames

Responses no longer include the old field names:

The API key change is the subtle one. Under 2023-06-01, workspace_id was null both for keys bound to the Default Workspace and for all-workspaces keys. Under 2026-10-21, scope.workspace_id holds the Default Workspace’s real ID, and an all-workspaces key has scope: {"type": "organization"} with no workspace_id. If your dashboard treated null as “Default Workspace”, it will mislabel keys after the upgrade.

SDK versions that send 2026-10-21

Anthropic shipped new SDK majors on October 21, 2026, and each one sends 2026-10-21 by default, per the release notes:

The new majors also bring changes that don’t depend on the API version at all:

• API keys go out as Authorization: Bearer <key> instead of X-Api-Key. The Claude API accepts either, but a proxy, gateway, log filter or test stub that reads X-Api-Key won’t see the key anymore.
• Text Completions is removed from the TypeScript, Go, Java and Ruby SDKs and from the CLI. Use the Messages API.
• betas is gone from the non-beta Models methods. Call client.beta.models instead.
• MessageParam is a union with one type per role in the typed SDKs, so some type annotations need updating.
• Go needs a new import path ending in /v2, and TypeScript users on the Bedrock, Vertex, Foundry, AWS or Google Cloud packages must move those to v1 in the same upgrade, or the package manager installs a second, older copy of the core SDK.
• The license changed from MIT to Apache 2.0.

Pin your current major before you do anything else. That stops a dependency bot from upgrading you mid-sprint.

The Amazon Bedrock exception

On Amazon Bedrock, 2026-10-21 works only with Claude 4.7 and later models. If you still call Opus 4.6 or an older model there, stay on your current SDK version or keep sending your current header, and switch the model first.

How to upgrade to Claude API version 2026-10-21 safely

The migration guide’s order is: switch the version, fix the breaking changes, test before release. Here’s how that looks in practice.

1. Pin the old SDK major. For example anthropic<2 in Python or "@anthropic-ai/sdk": "^0" in npm.
2. Search your code and configs for temperature, top_p, top_k, X-Api-Key, completions.create, and any Admin API field from the table above.
3. Decide on sampling. On Claude 4.7 and later, delete the parameters. On older models, either accept default sampling or keep those calls on 2023-06-01.
4. Fix message construction. Move assistant-side documents to user turns and strip citations from user text blocks.
5. Test the same payloads under both versions and compare status codes and response shapes.
6. Upgrade the SDK and ship the code fixes together. Anthropic says to release the upgrade with your fixes, not before.

Without an SDK, the switch is one header:

curl https://api.anthropic.com/v1/messages \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2026-10-21" \
  -H "content-type: application/json" \
  -d '{
    "model": "claude-opus-5-5",
    "max_tokens": 1024,
    "messages": [{"role": "user", "content": "Hello, Claude"}]
  }'

Add "temperature": 0.2 to that body and you’ll get a 400. Send the same body with anthropic-version: 2023-06-01 and it succeeds. That pair of results is exactly what step 5 should catch for every payload you send in production.

Let Claude Code test both versions with Apidog CLI

Step 5 is tedious by hand: you have dozens of payload shapes, and each needs to run twice. Hand it to your coding agent instead. Apidog CLI gives Claude Code (or Codex, Cursor and OpenCode) commands to create test cases and run them, so the agent does the comparison and you read the summary.

Set it up once:

npm install -g apidog-cli@latest
apidog login --with-token <YOUR_TOKEN>
npx -y skills add https://apidog.com   # pick Claude Code when prompted

Then give Claude Code one prompt:

In Apidog project <id>, create an environment "claude-api" with base URL
https://api.anthropic.com. For each JSON payload in ./fixtures/claude/, add a
POST /v1/messages test case that sends the header anthropic-version: {{anthropic_version}}
and asserts status 200 and a non-empty content array. Run every case twice, once with
anthropic_version=2023-06-01 and once with 2026-10-21, and list each case that passes
on the old version but fails on the new one, with the error message.

The agent checks each payload schema before it writes anything, then runs the cases:

apidog environment create claude-api --project <id> --base-url https://api.anthropic.com
apidog cli-schema get test-case-create
apidog cli-schema validate test-case-create --file case.json
apidog test-case create --project <id> --file case.json
apidog run --test-case <caseId> --project <id> -e <envId> --env-var "anthropic_version=2023-06-01" -r cli,json
apidog run --test-case <caseId> --project <id> -e <envId> --env-var "anthropic_version=2026-10-21" -r cli,json

The --env-var flag swaps the header value without touching the test case, so the diff is one variable. Add --upload-report to view both runs in the Apidog app, or put the 2026-10-21 run in CI with -r junit so a dependency bump can’t ship a temperature field to production. The Apidog CLI in Claude Code guide covers setup in more detail, and the apidog run reference lists every flag. Apidog’s Free plan covers up to 4 users.

Is 2023-06-01 deprecated?

No retirement date has been published. The versioning page lists 2023-06-01 with no deprecation notice, and the migration guide itself tells you to keep requests that need a non-default temperature on 2023-06-01. Anthropic still recommends the latest version “whenever possible”.

That matters for planning. Today’s upgrade is optional, but 2026-10-21 is the first new version in more than three years, and future breaking changes will arrive the same way, so treating version testing as a routine CI job now is cheaper than a rushed migration later. If you’re already tuning around Claude API rate limits or Claude API cost, add the version check to the same pipeline. Our guide to API versioning best practices explains why date-based versions like this one make it easier.

FAQ

Do I have to upgrade to Claude API version 2026-10-21 now?

No. 2023-06-01 still works and has no published retirement date. You upgrade when you send the new header or install an SDK major that defaults to it.

Why does my request return 400 after an SDK upgrade?

The new SDK majors send 2026-10-21, which rejects temperature, top_p and top_k, assistant-side document blocks and citations on user text blocks. Check your payload for those first.

Can I keep temperature on some requests?

Yes, by keeping those specific requests on 2023-06-01. Under 2026-10-21 there is no replacement setting, and Claude 4.7 and later models only sample with the defaults anyway.

Does 2026-10-21 work on Amazon Bedrock?

Only for Claude 4.7 and later models. Older Bedrock models need your current SDK version or header until you switch models.

Will my proxy still see my API key?

Not if it reads X-Api-Key. The new SDKs send the key as Authorization: Bearer. Update the proxy to read Authorization, or configure the SDK to send X-Api-Key yourself.

Does the new version change streaming events?

Anthropic lists no streaming format change for 2026-10-21. The streaming format you use today came with 2023-06-01.