That Claude SDK bump comes with a side of 400s: migrating to API version 2026-10-21

🛠️ Deep dive · Oct 23, 2026 · ~6 min read

The short version

Claude SDK users, check before you upgrade: a routine dependency bump now moves every request to API version 2026-10-21, where temperature, top_p and top_k return a 400 error even at their defaults.

The same majors send your API key in a different header, hold one credential per client and change some response fields. A request can stay on 2023-06-01 while you fix it, so you can move one call at a time.

Source: Claude docs: migrate to API version 2026-10-21

What shipped

On Oct 21, 2026, Anthropic released Claude API version 2026-10-21, plus new major versions of the Python, TypeScript, C#, Go, Java, PHP and Ruby SDKs and the ant CLI, all of which send the new version by default (Claude Platform release notes, Oct 21, 2026).

Those SDK and CLI versions also carry breaking changes of their own and switch from the MIT License to Apache 2.0.

Anthropic recommends the latest API version whenever possible. It is available on the Claude API, Claude Platform on AWS, Claude Models on Google Cloud and Microsoft Foundry; on Amazon Bedrock it covers Claude 4.7 and later models only (Claude docs: API versions).

Why a version bump is the trigger

Your SDK quietly chooses the API version for you. Per the migration guide, requests use the API version that was current when your SDK’s major version came out, and earlier SDK and CLI versions sent anthropic-version: 2023-06-01 with every request (Claude docs: migrate to API version 2026-10-21).

So the risky moment is the pull request where a bot or a teammate moves anthropic or @anthropic-ai/sdk up a major.

If you call the API with raw HTTP, nothing changes until you set the anthropic-version header to 2026-10-21 yourself.

The breaking change isn’t a date on the calendar. It’s the dependency bump you merge on autopilot.

What breaks on the new version

These apply to the Messages API, token counting and each request in a Message Batch (Claude docs: migrate to API version 2026-10-21):

Sampling knobs are gone. Sending temperature, top_p or top_k returns a 400 error, even at the default value. Without them, requests sample at the defaults, including a temperature of 1.0. Models that already accept only the defaults, such as Claude 4.7 and later, sample as before. On a model like Claude Sonnet 4.6, a lowered temperature loses its effect, and no other setting replaces it.
Documents in assistant turns fail. A document block placed directly in an assistant message returns a 400. A document nested inside another block, such as a web fetch tool result Claude returned, is still accepted.
Citations in user turns fail. A text block with a non-empty citations array in a user message returns a 400, including inside search_result blocks. Citations on Claude’s own earlier replies that you send back still work.

The Admin API and Claude Enterprise Analytics API drop old field names (roles becomes role_ids, actor.email becomes actor.email_address), and API keys swap workspace_id for a scope object, where a Default Workspace key now carries that workspace’s real ID.

Blast radius for teams

Surface	What breaks	What to check
App code tuned with `temperature`	Every request that sends it returns a 400	Grep for `temperature`, `top_p`, `top_k`; decide per call
Proxies, gateways, log filters	API key now arrives as `Authorization: Bearer`	Anything that reads or sets `X-Api-Key`
Clients built with both a key and a token	Python raises `ValueError` when you pass both	Constructor calls and env vars
Admin and analytics scripts	Old field names vanish from responses	Code that treated a null `workspace_id` as Default
Bedrock calls to older models	`2026-10-21` covers Claude 4.7 and later only	Model IDs before you bump
License tracking	SDK and CLI move to Apache 2.0	Your dependency license inventory

Downstream effects nobody greps for

Auth moves headers. The new SDKs and CLI send your API key as Authorization: Bearer <key>, not X-Api-Key. The Claude API accepts a key in either header, but the guide says to update any proxy, gateway, middleware, log filter or test stub that reads X-Api-Key.

One credential per client. An API key and an auth token now share a header, so a client holds one credential.

In Python, passing two or more in the constructor raises ValueError, and with both ANTHROPIC_API_KEY and ANTHROPIC_AUTH_TOKEN set and none passed in code, the client uses the key and logs a warning once.

SDK code changes. MessageParam becomes a union with one type per role, client-side compaction leaves the TypeScript and Ruby tool runners in favor of server-side compaction, and Text Completions is removed from the TypeScript, Go, Java and Ruby SDKs and the CLI.

The CLI drops its --api-key and --auth-token flags, so scripts that pass a key on the command line stop with flag provided but not defined.

We are not claiming any change in your output quality or bill. Whether losing a lowered temperature matters depends on your model and prompts, so compare on your own evals.

Migration notes, in order

Built from the guide’s upgrade steps, with the first versions that send 2026-10-21 from the release notes:

Inventory first. List every service that calls Claude, its SDK and its model. Bedrock calls to Opus 4.6 and earlier stay on today’s SDK until they move to a Claude 4.7 or later model.
Fix the breaking changes in code before or with the bump, not after: sampling parameters, document and citation placement, renamed admin fields.
Upgrade to the first versions on the new API version: Python SDK 2.0.0, TypeScript SDK 1.0.0, C# SDK 13.0.0, Go SDK 2.0.0, Java SDK 3.0.0, PHP SDK 1.0.0, Ruby SDK 2.0.0 and ant CLI 2.0.0.
Fix your edges: gateways that read X-Api-Key, clients that pass two credentials, CLI scripts using the removed flags.
Test against 2026-10-21 before you release, then ship the upgrade together with your fixes.
Update the license entry if you track dependency licenses. No code change is needed for that.

Controls and escape hatches

From the same guide:

Keep a request that relies on a non-default temperature on 2023-06-01, or stop sending the parameter.
Raw HTTP users stay on the old version until they change the anthropic-version header.
If a gateway reads X-Api-Key, move the key back with an auth function on the HTTP client, or send X-Api-Key yourself.

Oct 20, 2026: user profiles tell Anthropic which end customer each request is for, and org admins can turn off web fetch (Claude Platform release notes, Oct 20, 2026).
Oct 22, 2026: Claude Models on Google Cloud (Anthropic managed) launched, reached through your Google Cloud project (Claude Platform release notes, Oct 22, 2026).

Chef’s pick: pin the SDK major you run today, grep for temperature and X-Api-Key, then move one service at a time with tests on 2026-10-21. Leave any call that truly needs a low temperature on 2023-06-01 until you’ve compared outputs.