Claude API 2026-10-21 migration: what breaks and what to do first

Claude API 2026-10-21 is the first new API version Anthropic has released since 2023-06-01. It arrived on 21 October 2026 with new major versions of the seven official SDKs and the ant CLI, which send it by default.¹ You don’t have to move yet. Requests that send anthropic-version: 2023-06-01 keep the old behaviour, and Anthropic hasn’t announced an end date for that version.² Upgrading the SDK is what moves you, so start by pinning its major version.

Most teams will run into at least one of four changes. On 2026-10-21, a request that sends temperature, top_p or top_k returns a 400 error on every model, even at the default value.³ The new SDKs send the API key as Authorization: Bearer instead of X-Api-Key, which matters if a proxy or gateway reads the key. Each SDK client now accepts a single credential, so passing both a key and a token is an error. And MessageParam is now a union with one type per role, which breaks code that constructs or extends that type. Less often, a request fails because it puts a document block directly in an assistant message, or sends a user text block with citations.

We haven’t run this migration ourselves. Everything here comes from Anthropic’s Claude API migration guide, documentation and SDK repositories as of 26 October 2026. The order we recommend is to pin the SDK, ship the fixes that work under both versions, then upgrade the SDK and test the switch like a model change.

Do you have to move to Claude API 2026-10-21 yet?

You can stay on 2023-06-01 for now. Within an API version, Anthropic keeps existing input and output parameters, though it may add optional inputs, output values and enum variants.² The versions page lists 2023-06-01 with no end date, and the migration guide names it as one option for requests that depend on a non-default temperature.³ On 21 October, ClaudeDevs, the X account that posts official updates for Claude developers, added that 2023-06-01 is not deprecated.⁴

The SDK decides which version you send. Each major version of an official SDK sends one API version, and each new API version comes with a new major.⁵ Python 1.x, TypeScript 0.x and the earlier majors of the other SDKs send 2023-06-01. The majors released on 21 October send 2026-10-21, including their Amazon Bedrock and Google Cloud clients.³ A dependency bump across a major version therefore changes the API version and the SDK’s types in one step.

So far, new SDK features ship only on the new majors. Every Python and TypeScript release since 21 October has been on the new majors, up to Python 2.3.0 and TypeScript 1.3.0 as of 26 October, with message threads among the additions.⁵⁶⁷ ClaudeDevs also said that Anthropic plans to release API versions more often, so that developers can deal with breaking changes before a new model requires them.⁴

On Amazon Bedrock, 2026-10-21 covers only Claude 4.7 and later models, and the other platforms on the versions page have no such limit.² For older models on Bedrock, Anthropic advises keeping your current SDK version, or the version header you already send, until those calls move to Claude 4.7 or later.³

Claude API breaking changes in 2026-10-21

The request changes apply to the Messages API, token counting and each request in a Message Batch created with 2026-10-21, so a batch created under 2023-06-01 keeps the old rules.³ The table covers every API-level change in the migration guide, as of 26 October 2026.

A 400 here is the API’s invalid_request_error, raised as BadRequestError in the Python and TypeScript SDKs.⁸⁹¹⁰ The guide doesn’t publish the error messages, so match on status code and error type in your monitoring.

The workspace_id rename also changes meaning. Under 2023-06-01 it is null for keys bound to the Default Workspace and for all-workspaces keys. Under 2026-10-21, the first kind gets the workspace’s real ID in scope.workspace_id, and the second a scope of type organization. Code that read null as the Default Workspace should compare against the ID that List Workspaces returns with include_default=true.³

What changed in Anthropic Python SDK 2.0 and TypeScript SDK 1.0

The new majors also carry breaking changes that don’t depend on the API version.³ These are the ones to check in Python and TypeScript.

• Sampling parameters are gone from the SDKs. TypeScript 1.0 removes temperature, top_p and top_k from its types. Python dropped them from its method signatures in 1.0.0, on 20 August 2026, and its v1 guide told teams on older models to pass them in extra_body.¹¹¹ Python 2.0 sends 2026-10-21, so that route now ends in a 400 unless the request stays on 2023-06-01.
• The API key travels as Authorization: Bearer. The Claude API accepts a key in either header, but a proxy, gateway, log filter or test stub that reads X-Api-Key won’t find it. The Foundry clients still send X-Api-Key. If a gateway needs the old header, TypeScript can set it in defaultHeaders with Authorization: null, and Python can move it back with an auth function on the HTTP client.³
• A client holds one credential. Passing two of api_key, auth_token, credentials, config and profile raises ValueError in Python, and doing the same in new Anthropic() throws TypeError in TypeScript. With none passed, it prefers an API key over an auth token and warns once if it finds both.³
• MessageParam is a union of UserMessageParam, AssistantMessageParam and SystemMessageParam. Messages written as dict or object literals need no change. In Python, calling or subclassing MessageParam raises TypeError. In TypeScript, an interface can’t extend the union.³
• betas left the non-beta Models methods. Send beta headers through client.beta.models.
• In TypeScript only, compactionControl and the legacy Text Completions API are gone. The Bedrock, Vertex, Foundry, AWS and Google Cloud packages must move to 1.0 in the same upgrade, or the package manager installs a second, older copy of the core SDK for them.³

Anthropic’s guide shows the TypeScript fix for an interface that extended MessageParam.

// Before
interface StoredMessage extends Anthropic.MessageParam {
  id: string;
}

// After
type StoredMessage = Anthropic.MessageParam & { id: string };

Python teams still on 0.x take both steps at once, so work through the v1 guide first. Version 1.0 raised the minimum to Python 3.10 and moved the HTTP layer to httpx2, and tracing or mocking tools that patch httpx can silently miss the SDK’s requests until they’re pointed at httpx2.¹¹

Other SDKs, the ant CLI and the Apache 2.0 licence

The other SDKs get the same MessageParam split, credential rules and Authorization header. In C#, Go, Java, PHP and Ruby, single-value enum types also become constants.³ The table lists what else to check, as of 26 October 2026.⁵

From these versions on, the SDKs and the CLI are licensed under Apache 2.0, while earlier versions stay under the MIT License. No code changes are needed, though Anthropic asks teams that track licences to update their records. The TypeScript and C# platform packages switch in their own 1.0.0 releases, and in Java the change covers every com.anthropic artifact.³ The Python and TypeScript READMEs add that earlier third-party contributions stay under MIT.¹²

Pin anthropic-version first, then upgrade

Without an SDK, your code sets the anthropic-version header, so keep it in one place. Moving means sending anthropic-version: 2026-10-21 on every request.³

With an SDK, pin the major version first, since it decides the header. Python’s v1 guide installs with pip install --upgrade "anthropic>=1,<2", a range that keeps you on 2023-06-01.¹¹ In TypeScript, keep @anthropic-ai/sdk below 1.0. In Go the import path is the pin, because 2.0.0 lives under a module path ending in /v2.

Only the Python and TypeScript SDK pages document overriding the header itself, and both warn that it can lead to incorrect types or other unexpected behaviour.⁹¹⁰ A 2.x or 1.x client’s types follow 2026-10-21, so we’d keep the dependency as the main pin and use the override only for a short list of named calls. Python takes default_headers on the client or extra_headers on a request. Here the override keeps one call to an older model, which still needs a lower temperature, on 2023-06-01.

# Before: SDK 1.x sends 2023-06-01, and the v1 guide's extra_body route works
message = client.messages.create(
    model="claude-sonnet-4-6",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Hello, Claude"}],
    extra_body={"temperature": 0.2},
)

# After: SDK 2.x sends 2026-10-21, which rejects temperature.
# Delete extra_body, or keep this one call on 2023-06-01:
message = client.messages.create(
    model="claude-sonnet-4-6",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Hello, Claude"}],
    extra_body={"temperature": 0.2},
    extra_headers={"anthropic-version": "2023-06-01"},
)

TypeScript documents the override per request only.

// Before: SDK 0.x sends 2023-06-01 on every request
const message = await client.messages.create({
  max_tokens: 1024,
  messages: [{ role: "user", content: "Hello, Claude" }],
  model: "claude-opus-5-5"
});

// After: SDK 1.x sends 2026-10-21 unless a request overrides the header
const pinned = await client.messages.create(
  {
    max_tokens: 1024,
    messages: [{ role: "user", content: "Hello, Claude" }],
    model: "claude-opus-5-5"
  },
  { headers: { "anthropic-version": "2023-06-01" } }
);

The C#, Go, Java, PHP and Ruby pages say each major sends one API version and show no override, so in those languages the dependency is the only documented pin.¹³ The same goes for the CLI. Its quickstart doesn’t mention the API version, and the migration guide says ant can’t add a header of your own.³

With the pin in place, we’d work in this order.

1. While still on 2023-06-01, ship the fixes that work under both versions. Drop sampling parameters from calls to Claude 4.7 and later models, send documents in user messages, and remove citations from user text blocks.
2. Make Admin and Analytics API code read the new field names, falling back to the old ones until the switch.
3. Upgrade the SDK in a branch and let the type checker find MessageParam, credential and betas problems.
4. Test as described below, then release the upgrade with its remaining fixes, as Anthropic’s guide recommends.³

The Claude temperature error and what to use instead

After the switch, a request that sends temperature, top_p or top_k gets a 400 whatever the value. Leave them out and the request samples with the defaults, including a temperature of 1.0, as a 2023-06-01 request without them did.³

How much you lose depends on the model. Claude 4.7 and later models already rejected non-default values under earlier API versions, so any working call to them was sending defaults, and removing those changes nothing.¹⁴ Models that still accept other values, such as Claude Sonnet 4.6, lose the effect of a lowered temperature. Anthropic says no other setting replaces it. That rules out effort too, which Anthropic describes as the control for thinking depth, latency and cost.³¹⁵ The guide’s two options are to stop sending the parameter or to keep the request on 2023-06-01. As of 26 October 2026, Claude Sonnet 4.6 is active, with retirement not sooner than 17 February 2027.¹⁴

Anthropic recommends prompting in place of sampling parameters, in its parameter deprecation table and in the Claude Opus 5.5 migration guide.¹⁴¹⁶ Where output must be consistent, its consistency guide suggests these techniques.¹⁷

• Structured outputs, where you need guaranteed JSON schema conformance.
• A precisely defined output format in JSON, XML or a template.
• Examples of the output you want.
• Retrieval from a fixed set of information.
• Chained prompts, each covering one subtask.

If you set temperature to 0 for repeatable results, Anthropic notes that it never guaranteed identical outputs on earlier models.¹⁶ Repeatability has to come from your own system. Store the outputs you must reproduce, check their structure in code, and run the same inputs several times to see how much answers vary. Our post on measuring model drift shows how to put error bars on that variation.

If a framework or wrapper sits between your code and the API, log one outgoing request body to see whether it sets any of the three for you.

Testing the switch before you release it

Test the switch as you would a model upgrade. Run a frozen set of production requests through the old SDK on 2023-06-01 and the new SDK on 2026-10-21, and compare the results item by item. Our one-week routine for model upgrades covers building that set and setting pass rules. Add these checks for this migration.

• Calls that used to lower temperature. On models before Claude 4.7 their outputs will change, so run those items several times on each version and compare the spread as well as the pass rate.
• Every 400 in staging. Group them by endpoint and error type. A new 400 after the switch points to a leftover sampling parameter, a document in an assistant turn or a citation in a user turn.
• The version each client sends. TypeScript’s debug log level logs request headers, and ant --debug prints the request log.¹⁰³ The TypeScript log includes bodies too, so keep it to staging. Check every service, Bedrock and Google Cloud clients included.
• The real gateway. Send staging traffic through the same proxy configuration as production, since the key now travels in Authorization.
• Admin and analytics jobs. Run them once against 2026-10-21 and check the renamed fields.
• Rollback. Keep the previous lockfile so that rolling back is a dependency revert. Batches created before the switch keep the 2023-06-01 rules, so they don’t need draining first.

A Claude API migration checklist

1. List each service that calls Claude, with its SDK and major version, or the header value it sends.
2. Pin the SDK major in every lockfile, and pin the ant CLI.
3. Find temperature, top_p and top_k in code, configuration and framework settings, and remove them now from calls to Claude 4.7 and later models.
4. For older models that use a non-default value, test without it, or keep those calls on 2023-06-01 with the documented header override.
5. Move document blocks out of assistant messages, and remove citations from user text blocks.
6. Read the new Admin and Analytics API field names, falling back to the old ones until the switch.
7. On Bedrock, leave calls to models older than Claude 4.7 on the current SDK until they move to a newer model.
8. Upgrade the SDK in a branch, with TypeScript’s platform packages, Go’s /v2 imports and PHP’s composer require.
9. Fix MessageParam type errors, pass one credential per client, and point proxies, log filters and test stubs at Authorization.
10. Run the regression set on both versions, review every 400 in staging and confirm the version each client sends.
11. Update your dependency licence records from MIT to Apache 2.0.
12. Release the upgrade with its fixes, and keep the old lockfile for rollback.

Frequently asked questions