Anthropic SDK upgrade: what API version 2026-10-21 breaks

On 21 October 2026 Anthropic released Claude API version 2026-10-21 and a new major of every SDK that sends it by default: TypeScript SDK 1.0.0, Python SDK 2.0.0, five more SDKs and the ant CLI. Upgrading breaks two things at once. The API version rejects temperature, top_p and top_k with a 400 error, even at their defaults, and rejects document blocks in assistant messages and citations in user messages. The SDKs send your API key as Authorization: Bearer instead of X-Api-Key, which breaks any proxy, gateway or test stub that reads the old header. Change those first: remove the three sampling parameters, then point anything that reads X-Api-Key at Authorization. Old SDK majors keep sending 2023-06-01, which still works and has no published end date, so nothing breaks until you upgrade. We checked every claim below against the migration guide (opens in a new tab), the release notes, GitHub and the npm and PyPI registries on 24 October 2026; we did not run the new SDKs against the API.

What changed on 21 October 2026

The release notes of 21 October 2026 (opens in a new tab) list eight new versions that send 2026-10-21 by default, all under the Apache License 2.0 where earlier versions were MIT:

The same release notes recorded fast mode for Claude Opus 5.5 leaving research preview on 15 October, one of the items in our web dev digest of 18 October; this release asks more of your code. For the two SDKs most web teams use, the registries give the exact times. The npm registry document (opens in a new tab) gives every version's publish time and licence; PyPI's JSON API gives the upload times of every release (opens in a new tab) and the licence of 1.17.0 (opens in a new tab) and 2.0.0 (opens in a new tab). Here are the last version on the old API version, the first major and what is current on 24 October 2026:

The GitHub releases (TypeScript sdk-v1.0.0 (opens in a new tab), Python v2.0.0 (opens in a new tab)) name a single breaking change, "add support for new API version 2026-10-21". The list of what that means is in the migration guide, in two groups.

What the API version rejects

These apply to POST /v1/messages, token counting and every request in a Message Batch created with 2026-10-21, per the breaking changes (opens in a new tab) section:

Two things stay accepted: citations on text blocks in assistant messages (Claude's earlier replies you send back), and the "citations": {"enabled": true} setting on documents and search results. A document nested inside another block, such as a web fetch result Claude returned, is fine too.

The sampling change matters most. The versioning page (opens in a new tab) says the 400 comes "on every model". On Claude 4.7 and later models, which already accept only the defaults, removing the parameters changes nothing. On a model that accepts other values, such as Claude Sonnet 4.6, a request that set a low temperature for more consistent output loses that effect, and the guide says no other setting replaces it.

The Admin API and the Claude Enterprise Analytics API also drop old field names: roles becomes role_ids, group_id becomes rbac_group_id, name on RBAC roles becomes display_name, group_type becomes group.type, actor.email becomes actor.email_address and summaries becomes data. API keys lose workspace_id for scope, which has different values: a key bound to the Default Workspace now carries that workspace's real ID, where it used to be null.

What the SDKs change on their own

The SDK and CLI changes (opens in a new tab) don't depend on the API version. For TypeScript and Python side by side:

The header switch is the change most likely to break something outside your code. Anything between your app and the API that reads X-Api-Key stops seeing the key: a corporate proxy, an API gateway, middleware that checks it, a log filter that redacts it, a test stub that asserts on it. The API itself accepts a key in either header, the migration guide says. Not every client changes: in TypeScript, apiKey in @anthropic-ai/foundry-sdk still goes out as X-Api-Key and apiKey in @anthropic-ai/bedrock-sdk was already a bearer token; in Python, AnthropicFoundry still sends x-api-key and AnthropicBedrockMantle already sent a bearer token.

The one-credential rule catches setups that sent a gateway token and an API key together. With none passed in code and both ANTHROPIC_API_KEY and ANTHROPIC_AUTH_TOKEN set, the client uses the key and logs a warning once.

Who is affected and how to tell

You are affected the day you install a new major, not before. A repository search shows how much work it is:

The Bedrock line needs care. The new SDKs send 2026-10-21 from their Amazon Bedrock and Google Cloud clients too, and on Bedrock that version exists only for Claude 4.7 and later models. If you call an older model there, the upgrade step (opens in a new tab) says to stay on the SDK version you use today. In TypeScript that holds the whole tree back: in the npm registry (opens in a new tab), @anthropic-ai/bedrock-sdk 1.0.0 requires @anthropic-ai/sdk >=1.0.0 <2, and 0.36.0 requires >=0.115.1 <1. The versioning page also lists 2026-10-21 on Claude Platform on AWS, both Google Cloud offerings and Microsoft Foundry, and names a model limit only for Bedrock.

How to upgrade the Anthropic SDK to API version 2026-10-21

1. Pin the last old version and record a baseline

   Note what you run today (for example @anthropic-ai/sdk 0.137.0 or anthropic 1.17.0) and run your tests against it, so you can tell a migration failure from an old one and roll back to a known version.

2. Remove temperature, top_p and top_k

   Delete the three parameters from every Messages and Batch request. For a request that depends on a low temperature on a model that accepts it, decide now: accept the default, or keep that code path on the old SDK for the time being.

3. Move every reader of X-Api-Key to Authorization

   Update proxies, gateways, middleware, log redaction and test stubs to read Authorization: Bearer <key>. If a gateway can't change yet, set the header yourself: in TypeScript defaultHeaders: { "X-Api-Key": apiKey, Authorization: null }, in Python an auth function on the HTTP client that the guide shows.

4. Install the latest new major, with its platform packages

   Install @anthropic-ai/sdk@^1 (1.3.0 on 24 October) or anthropic>=2,<3 (2.3.0), not exactly 1.0.0 or 2.0.0: 1.2.0 and 2.2.0 fixed the tool runner. In TypeScript, move any @anthropic-ai/bedrock-sdk, vertex-sdk, foundry-sdk, aws-sdk or google-cloud-sdk to 1.x in the same change, or the package manager installs a second, older copy of the SDK for it.

5. Fix what the compiler and the tests report

   Pass one credential per client, move betas calls to client.beta.models, rewrite MessageParam constructors and interfaces, drop document blocks from assistant messages and citations from user messages. Then run the suite against 2026-10-21, including one real request per code path, before you release.

In TypeScript, the two code changes most apps need look like this (the second is the migration guide's own example):

// 0.x: accepted on 2023-06-01
await client.messages.create({ model, max_tokens: 1024, temperature: 0.2, messages });
// 1.x: temperature is gone from the types, and the API returns a 400 for it
await client.messages.create({ model, max_tokens: 1024, messages });
 
// 0.x
const page = await client.models.list({ betas: [beta] });
// 1.x
const page = await client.beta.models.list({ betas: [beta] });

What to watch out for

• No end date for 2023-06-01. As of 24 October 2026, neither the release notes nor the versioning page gives one, and the versioning page recommends the latest version whenever possible. Treat staying on the old major as a decision with a review date, not as a plan.
• No replacement for low temperature. The guide's only options are to stop sending it or to keep that request on 2023-06-01. If output consistency matters, write an evaluation before you switch a model that honoured your temperature.
• No documented error text. The guide says these requests return a 400 and does not quote the message. The errors page (opens in a new tab) maps a 400 to invalid_request_error, and the SDKs raise a typed exception for it, so a test that asserts on the status or the type is safer than one that matches a string.
• Tool runner fixes after 1.0.0. TypeScript 1.2.0 (opens in a new tab) and Python 2.2.0 (opens in a new tab), both of 23 October, fix the tool runner: the TypeScript release around setMessagesParams() and pushMessages(), the Python one around set_messages_params() and append_messages(). Start from the latest version.
• Libraries built on the SDK. A framework that wraps @anthropic-ai/sdk or anthropic declares its own version range and its own types. Check that it supports the new major before you upgrade; the migration guide covers only Anthropic's packages.
• Licence records. Apache 2.0 needs no code change, but if you track dependency licences, update the entry.

We read every source on 24 October 2026; check the release notes for anything newer before you plan the upgrade. Earlier Claude news, including fast mode for Opus 5.5 leaving research preview, is in the web dev digest of 18 October linked above.

Further reading