--- title: "Anthropic SDK upgrade: what API version 2026-10-21 breaks" description: "Anthropic TypeScript SDK 1.0.0 and Python SDK 2.0.0 send API version 2026-10-21: temperature now returns a 400, keys go as Bearer. What to change first." canonical_url: "https://www.outofplace.space/blog/claude-api-2026-10-21-sdk-migration" language: "en" last_updated: "2026-10-24" alternates: pl: "https://www.outofplace.space/pl/blog/anthropic-sdk-migracja-api-2026-10-21.md" --- # Anthropic SDK upgrade: what API version 2026-10-21 breaks > Anthropic TypeScript SDK 1.0.0 and Python SDK 2.0.0 send API version 2026-10-21: temperature now returns a 400, keys go as Bearer. What to change first. Published 2026-10-24 · Category: Web development · Tags: Claude, TypeScript, Python 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](https://platform.claude.com/docs/en/api/migration-2026-10-21), the release notes, GitHub and the npm and PyPI registries on 24 October 2026; we did not run the new SDKs against the API. - TypeScript SDK 1.0.0 and Python SDK 2.0.0 were published on 21 October 2026; on 24 October the latest are 1.3.0 and 2.3.0. - API version `2026-10-21` returns a 400 for `temperature`, `top_p` and `top_k`, at any value, on every model. - The SDKs send the API key as `Authorization: Bearer`; a client now holds exactly one credential. - On Amazon Bedrock, `2026-10-21` works only with Claude 4.7 and later models, so older Bedrock models stay on the old SDK. - The new majors are licensed under Apache 2.0 instead of MIT. ## What changed on 21 October 2026 The [release notes of 21 October 2026](https://platform.claude.com/docs/en/release-notes/overview) list eight new versions that send `2026-10-21` by default, all under the Apache License 2.0 where earlier versions were MIT: | SDK or tool | Package | First version on `2026-10-21` | | ----------- | -------------------------------------- | ----------------------------: | | TypeScript | `@anthropic-ai/sdk` | 1.0.0 | | Python | `anthropic` | 2.0.0 | | Go | `github.com/anthropics/anthropic-sdk-go/v2` | 2.0.0 | | Java | `com.anthropic:anthropic-java` | 3.0.0 | | C# | `Anthropic` | 13.0.0 | | PHP | `anthropic-ai/sdk` | 1.0.0 | | Ruby | `anthropic` gem | 2.0.0 | | CLI | `ant` | 2.0.0 | 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](https://www.outofplace.space/blog/dev-digest-2026-10-18); 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](https://registry.npmjs.org/@anthropic-ai/sdk) gives every version's publish time and licence; PyPI's JSON API gives the upload times of [every release](https://pypi.org/pypi/anthropic/json) and the licence of [1.17.0](https://pypi.org/pypi/anthropic/1.17.0/json) and [2.0.0](https://pypi.org/pypi/anthropic/2.0.0/json). Here are the last version on the old API version, the first major and what is current on 24 October 2026: | Package | Last on `2023-06-01` | First on `2026-10-21` | Latest on 24 Oct 2026 | | ------------------- | ----------------------- | ------------------------ | ---------------------- | | `@anthropic-ai/sdk` | 0.137.0, 20 Oct, MIT | 1.0.0, 21 Oct 16:00 UTC | 1.3.0, 23 Oct | | `anthropic` (PyPI) | 1.17.0, 20 Oct, MIT | 2.0.0, 21 Oct 15:51 UTC | 2.3.0, 23 Oct | The GitHub releases ([TypeScript sdk-v1.0.0](https://github.com/anthropics/anthropic-sdk-typescript/releases/tag/sdk-v1.0.0), [Python v2.0.0](https://github.com/anthropics/anthropic-sdk-python/releases/tag/v2.0.0)) 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](https://platform.claude.com/docs/en/api/migration-2026-10-21#breaking-changes) section: | Request | `2023-06-01` | `2026-10-21` | | ----------------------------------------------------------- | ------------ | ------------------------------------------------------- | | `temperature`, `top_p` or `top_k`, any value | Accepted | 400 error | | `document` block directly in an `assistant` message | Accepted | 400 error; send documents in `user` messages | | `text` block with non-empty `citations` in a `user` message | Accepted | 400 error, also inside `search_result` blocks | 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](https://platform.claude.com/docs/en/api/versioning) 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](https://platform.claude.com/docs/en/api/migration-2026-10-21#sdk-changes) don't depend on the API version. For TypeScript and Python side by side: | Change | TypeScript 1.0.0 | Python 2.0.0 | | --------------------------------- | ----------------------------------------------------------------------- | ------------------------------------------------------------------------- | | API key header | `Authorization: Bearer`, from `apiKey` and `ANTHROPIC_API_KEY` | `Authorization: Bearer`, from `api_key` and `ANTHROPIC_API_KEY` | | Two credentials on one client | Throws `TypeError` | Raises `ValueError` | | `MessageParam` | Union of `UserMessageParam`, `AssistantMessageParam`, `SystemMessageParam`; types only | Same union; calling or subclassing `MessageParam` raises `TypeError` | | `betas` on `models.list`/`retrieve` | Removed from the params types; use `client.beta.models` | Passing it is a `TypeError`; use `client.beta.models` | | Tool runner `compactionControl` | Removed (it stopped working in 0.129.0); use server-side compaction | Not listed | | Text Completions | Removed | Not listed | | Platform packages | Bedrock, Vertex, Foundry, AWS and Google Cloud packages need their own 1.0.0 | Not listed | | Licence | Apache-2.0 (0.137.0 was MIT) | Apache-2.0 (1.17.0 was MIT) | 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: | Search your code and config for | If you find it | | -------------------------------------------------- | ------------------------------------------------------------------------------- | | `temperature`, `top_p`, `top_k` in Messages calls | Remove them, or keep that request on the old SDK | | `X-Api-Key` (any case) in proxies, middleware, mocks | Read `Authorization` instead, or send `X-Api-Key` yourself | | `apiKey` and `authToken` (or `api_key` and `auth_token`) on one client | Pass one; the other throws or raises | | `models.list(` or `models.retrieve(` with `betas` | Call `client.beta.models` instead | | `MessageParam(` (Python) or `extends MessageParam` (TypeScript) | Write a dict literal, or use a type alias with `&` | | `compactionControl` (TypeScript) | Move to `context_management` with `compact_20260112` | | Bedrock with Claude Opus 4.6 or earlier | Stay on your current SDK until you move to a 4.7 or later model | | `ant --api-key` or `ant --auth-token` in scripts and CI | `ant` 2.0.0 removes both flags: use `ANTHROPIC_API_KEY`, `--api-key-stdin` or `ant auth login` (`ANTHROPIC_AUTH_TOKEN` or `--auth-token-stdin` for a token) | 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](https://platform.claude.com/docs/en/api/migration-2026-10-21#upgrade) says to stay on the SDK version you use today. In TypeScript that holds the whole tree back: in the [npm registry](https://registry.npmjs.org/@anthropic-ai/bedrock-sdk), `@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 `. 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): ```ts title="migrate.ts" // 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](https://platform.claude.com/docs/en/api/errors) 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](https://github.com/anthropics/anthropic-sdk-typescript/releases/tag/sdk-v1.2.0) and [Python 2.2.0](https://github.com/anthropics/anthropic-sdk-python/releases/tag/v2.2.0), 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 - [Migrating to API version 2026-10-21](https://platform.claude.com/docs/en/api/migration-2026-10-21): Every breaking change with before and after code for all eight SDKs and the CLI. - [Claude API versions](https://platform.claude.com/docs/en/api/versioning): What each API version changed and where 2026-10-21 is available, Bedrock included. - [Claude Platform release notes](https://platform.claude.com/docs/en/release-notes/overview): The 21 October 2026 entry with the eight SDK and CLI versions and the licence change. - [anthropic-sdk-typescript sdk-v1.0.0](https://github.com/anthropics/anthropic-sdk-typescript/releases/tag/sdk-v1.0.0): The TypeScript release on GitHub; later 1.x releases are listed beside it. - [anthropic-sdk-python v2.0.0](https://github.com/anthropics/anthropic-sdk-python/releases/tag/v2.0.0): The Python release on GitHub, with 2.1.0 to 2.3.0 after it. - [@anthropic-ai/sdk on the npm registry](https://registry.npmjs.org/@anthropic-ai/sdk): Every version with its publish time and licence.