Claude API 2026-10-21: Breaking Changes and SDK Migration

Q: What changed in Claude API version 2026-10-21?

`temperature`, `top_p` and `top_k` are removed and return a 400 even at defaults. `document` blocks in assistant messages and `citations` on user text blocks also return a 400. Several Admin and Enterprise Analytics API fields lose their old names.

Q: Why does my gateway reject requests after upgrading the SDK?

The new SDKs send the key as `Authorization: Bearer` instead of `X-Api-Key`. Change the gateway to read `Authorization`, or set `X-Api-Key` in `defaultHeaders` with `Authorization: null`.

Last updated: October 21, 2026

Anthropic released Claude API version 2026-10-21 today, the first new anthropic-version since 2023-06-01. The same day it released new major versions of every official SDK and the ant CLI that send it by default: TypeScript SDK 1.0.0, Python SDK 2.0.0, C# 13.0.0, Go 2.0.0, Java 3.0.0, PHP 1.0.0, Ruby 2.0.0 and ant 2.0.0 (release notes). Three things will break real code. temperature, top_p and top_k are gone, the SDKs now send your key as Authorization: Bearer, and the SDKs themselves have type-level breaking changes. The new SDKs are also licensed under Apache 2.0 instead of MIT.

Nothing forces you to move today. Your current SDK version keeps sending 2023-06-01. But the next npm update or pip install -U that crosses a major version will switch you over. Here is what changes, what we verified against the real packages, and the order to do it in. If you are also moving to a newer model, pair this with the Opus 5.5 developer guide, which covers that model's own API changes.

What breaks at the API level#

From the migration guide, for Messages API, token counting and Message Batch requests sent with 2026-10-21:

Change	What happens	What to do
`temperature`, `top_p`, `top_k` removed	400 error, "even at the parameter's default value"	Delete them. Requests sample with the defaults, including `temperature` 1.0
`document` block directly in an `assistant` message	400 error	Send documents in `user` messages
Non-empty `citations` on a `text` block in a `user` message	400 error	Remove them. Citations in `assistant` messages and `"citations": {"enabled": true}` still work

The sampling change is the one most code hits. Models that already accept only the defaults, such as Claude 4.7 and later, sample exactly as before. On a model that still accepts other values, such as Claude Sonnet 4.6, a request that lowered temperature for more consistent output loses that effect, and the guide is explicit that "no other setting replaces it". If you depend on a low temperature on an older model, keep that request on 2023-06-01 for now.

The Admin API and Claude Enterprise Analytics API drop the old names of renamed fields. RBAC groups return role_ids, not roles. Group members return rbac_group_id, not group_id. RBAC roles return display_name, not name. Rate limits return group.type, not group_type. Usage and cost reports return actor.email_address, not actor.email, and activity summaries return data, not summaries. API keys lose workspace_id in favor of scope. Code that treated a null workspace_id as the Default Workspace now needs to compare scope.workspace_id with that workspace's real ID.

Bedrock caveat: on Amazon Bedrock, 2026-10-21 only works with Claude 4.7 and later. If you still call an older model there, stay on your current SDK version.

Which API version a Claude request uses after this release

%% title: Which API version a Claude request uses after this release
flowchart TD
  A["Request"] --> B{"Using an official SDK?"}
  B -->|"Yes"| C{"SDK major version"}
  C -->|"TS 1.x, Python 2.x, Go 2.x, ..."| D["anthropic-version: 2026-10-21"]
  C -->|"TS 0.x, Python 1.x, Go 1.x, ..."| E["anthropic-version: 2023-06-01"]
  B -->|"No, raw HTTP"| F["Whatever you set in the anthropic-version header"]
  D --> G["temperature, top_p, top_k return 400"]

What breaks in the SDKs (TypeScript)#

We installed @anthropic-ai/sdk 1.1.0, the latest today (1.0.0 shipped this morning), and checked the migration guide's claims against it. These four "before" patterns now fail tsc --strict:

TypeScript

import Anthropic from "@anthropic-ai/sdk";
const client = new Anthropic();

// TS2769: temperature no longer exists on the params type
await client.messages.create({
  model: "claude-opus-5-5",
  max_tokens: 1024,
  temperature: 0.2,
  messages: [{ role: "user", content: "Hi" }]
});

// TS2339: Text Completions is removed
await client.completions.create({ model: "x", max_tokens_to_sample: 1, prompt: "x" });

// TS2353: betas is gone from the non-beta Models methods
await client.models.list({ betas: ["b"] });

// TS2312: MessageParam is now a union, and an interface can't extend a union
interface Stored extends Anthropic.MessageParam { id: string }

And the migrated version, which type-checks cleanly against 1.1.0:

TypeScript

import Anthropic from "@anthropic-ai/sdk";

// v1 sends anthropic-version: 2026-10-21 and the key as Authorization: Bearer.
const client = new Anthropic();

// No temperature, top_p or top_k: they are gone from the types and the API.
const message = await client.messages.create({
  model: "claude-opus-5-5",
  max_tokens: 1024,
  messages: [{ role: "user", content: "Hello, Claude" }]
});
console.log(message.content);

// MessageParam is now UserMessageParam | AssistantMessageParam | SystemMessageParam.
function withBlocks(
  m: Anthropic.MessageParam,
  blocks: Anthropic.TextBlockParam[]
): Anthropic.MessageParam {
  return m.role === "system" ? m : { ...m, content: blocks };
}
type StoredMessage = Anthropic.MessageParam & { id: string };
const stored: StoredMessage = { id: "1", role: "user", content: "hi" };
console.log(withBlocks(stored, [{ type: "text", text: "x" }]));

// Beta headers on Models move to client.beta.models.
const page = await client.beta.models.list({ betas: ["some-beta-2026-01-01"] });
console.log(page.data.length);

// A gateway that still reads X-Api-Key.
const proxied = new Anthropic({
  apiKey: process.env.ANTHROPIC_API_KEY,
  defaultHeaders: { "X-Api-Key": process.env.ANTHROPIC_API_KEY ?? "", Authorization: null }
});
console.log(typeof proxied);

We also ran the client against a stub fetch to see what actually goes over the wire. A default client sent anthropic-version: 2026-10-21 and Authorization: Bearer ... with no x-api-key header. The client with the X-Api-Key workaround sent x-api-key and no Authorization. And new Anthropic({ apiKey, authToken }) threw a TypeError, which is the new "one credential per client" rule. These were not calls to the live API.

The rest of the TypeScript changes, per the guide:

Client-side compaction is gone from the tool runner. compactionControl and its module are removed. Use server-side compaction (betas: ["compact-2026-01-12"] plus a compact_20260112 edit in context_management), or call runner.compactBeforeNextTurn(). The trigger must be at least 50,000 tokens.
Platform packages move together. v1 of @anthropic-ai/bedrock-sdk, vertex-sdk, foundry-sdk, aws-sdk and google-cloud-sdk needs v1 of the core SDK. Upgrade them in the same change, or your package manager installs a second, older copy of @anthropic-ai/sdk.
Credential precedence changed. With nothing passed in code, the client uses the first of ANTHROPIC_API_KEY, ANTHROPIC_AUTH_TOKEN, the ANTHROPIC_PROFILE profile, workload identity federation variables, and the active profile on disk. It logs a warning once if both of the first two are set.

What breaks in the SDKs (Python and others)#

For Python 2.0.0, a message written as a dict literal needs no change. Calling MessageParam(...) as a constructor now raises TypeError; write a dict instead. A dict whose role is a variable spanning several roles no longer type-checks, so build one dict per role. Passing two of api_key, auth_token, credentials, config or profile raises ValueError. client.models.list(betas=...) moves to client.beta.models.list(...). Go moves to the /v2 module path (github.com/anthropics/anthropic-sdk-go/v2), and the CLI to github.com/anthropics/anthropic-cli/v2. The old go install path silently keeps installing v1. PHP needs composer require "anthropic-ai/sdk", because composer update stays inside your current constraint.

Upgrade order that will not page you#

Grep for the 400s first. Search your code for temperature, top_p, top_k, document blocks in assistant turns, and citations on user text. These fail at runtime, so fix them before switching versions.
Check your gateway. If LiteLLM, an internal proxy or an API gateway reads X-Api-Key, either change it to read Authorization or apply the defaultHeaders workaround above. This is the change most likely to cause a 401 after a routine dependency bump.
Bump the SDK and its platform packages together, then let the type checker list the rest.
Pin the major version in package.json or requirements.txt if you are not ready. A caret range like ^0.135.0 will not cross to 1.0.0, but an unpinned Python install will cross to 2.0.0.
Update license tracking for Apache 2.0. No code change, but your compliance tooling may flag it.

Claude Code users get a shortcut: Claude Code 2.1.307 added /claude-api api-version to "move Claude API code to API version 2026-10-21".

Gotchas and limits#

Default temperature is now the only temperature. This is the substantive change hiding in a version bump. Evaluation harnesses and classification prompts that pinned temperature: 0 for repeatability on older models will get more varied output after migrating, and there is no replacement setting. Re-run your evals after the upgrade, not just your type checker.

Both versions are live. Old SDKs keep working, and no end date for 2023-06-01 is announced in the docs. That makes it easy to run mixed versions across services without noticing. Log the anthropic-version you send.

Raw HTTP callers opt in explicitly. If you call the API without an SDK, nothing changes until you set anthropic-version: 2026-10-21 yourself.

What people are actually saying#

The release is hours old. We found no Hacker News or Reddit thread yet, only vendor recaps such as CellCog's write-up, which leads with the sampling-parameter removal, the same change we expect to cause the most friction.
We will update this post with practitioner reports, especially on gateway breakage and eval drift, once they exist.

FAQ#

What changed in Claude API version 2026-10-21?#

temperature, top_p and top_k are removed and return a 400 even at defaults. document blocks in assistant messages and citations on user text blocks also return a 400. Several Admin and Enterprise Analytics API fields lose their old names.

Which SDK versions use API version 2026-10-21?#

Python 2.0.0, TypeScript 1.0.0, C# 13.0.0, Go 2.0.0, Java 3.0.0, PHP 1.0.0, Ruby 2.0.0 and ant CLI 2.0.0. Earlier versions keep sending 2023-06-01.

Do I have to migrate now?#

No deadline is announced. Earlier SDK versions keep sending 2023-06-01, and Anthropic recommends the latest version whenever possible. If a request needs a non-default temperature, keep it on 2023-06-01.

Why does my gateway reject requests after upgrading the SDK?#

The new SDKs send the key as Authorization: Bearer instead of X-Api-Key. Change the gateway to read Authorization, or set X-Api-Key in defaultHeaders with Authorization: null.

Continue Reading#

Claude Opus 5.5 Developer Guide: Pricing, API, Claude Code - the model-level API changes to handle alongside the version bump
Prompt Caching in the Claude API: A Production Guide - re-check cache behavior after a major SDK bump
Claude API OpenTelemetry Tracing: How to Set It Up (Beta) - trace requests to confirm which version each service sends

Sources#

Last updated: October 21, 2026

What breaks at the API level#

From the migration guide, for Messages API, token counting and Message Batch requests sent with 2026-10-21:

Change	What happens	What to do
`temperature`, `top_p`, `top_k` removed	400 error, "even at the parameter's default value"	Delete them. Requests sample with the defaults, including `temperature` 1.0
`document` block directly in an `assistant` message	400 error	Send documents in `user` messages
Non-empty `citations` on a `text` block in a `user` message	400 error	Remove them. Citations in `assistant` messages and `"citations": {"enabled": true}` still work

Bedrock caveat: on Amazon Bedrock, 2026-10-21 only works with Claude 4.7 and later. If you still call an older model there, stay on your current SDK version.

Which API version a Claude request uses after this release

%% title: Which API version a Claude request uses after this release
flowchart TD
  A["Request"] --> B{"Using an official SDK?"}
  B -->|"Yes"| C{"SDK major version"}
  C -->|"TS 1.x, Python 2.x, Go 2.x, ..."| D["anthropic-version: 2026-10-21"]
  C -->|"TS 0.x, Python 1.x, Go 1.x, ..."| E["anthropic-version: 2023-06-01"]
  B -->|"No, raw HTTP"| F["Whatever you set in the anthropic-version header"]
  D --> G["temperature, top_p, top_k return 400"]

What breaks in the SDKs (TypeScript)#

We installed @anthropic-ai/sdk 1.1.0, the latest today (1.0.0 shipped this morning), and checked the migration guide's claims against it. These four "before" patterns now fail tsc --strict:

TypeScript

import Anthropic from "@anthropic-ai/sdk";
const client = new Anthropic();

// TS2769: temperature no longer exists on the params type
await client.messages.create({
  model: "claude-opus-5-5",
  max_tokens: 1024,
  temperature: 0.2,
  messages: [{ role: "user", content: "Hi" }]
});

// TS2339: Text Completions is removed
await client.completions.create({ model: "x", max_tokens_to_sample: 1, prompt: "x" });

// TS2353: betas is gone from the non-beta Models methods
await client.models.list({ betas: ["b"] });

// TS2312: MessageParam is now a union, and an interface can't extend a union
interface Stored extends Anthropic.MessageParam { id: string }

And the migrated version, which type-checks cleanly against 1.1.0:

TypeScript

import Anthropic from "@anthropic-ai/sdk";

// v1 sends anthropic-version: 2026-10-21 and the key as Authorization: Bearer.
const client = new Anthropic();

// No temperature, top_p or top_k: they are gone from the types and the API.
const message = await client.messages.create({
  model: "claude-opus-5-5",
  max_tokens: 1024,
  messages: [{ role: "user", content: "Hello, Claude" }]
});
console.log(message.content);

// MessageParam is now UserMessageParam | AssistantMessageParam | SystemMessageParam.
function withBlocks(
  m: Anthropic.MessageParam,
  blocks: Anthropic.TextBlockParam[]
): Anthropic.MessageParam {
  return m.role === "system" ? m : { ...m, content: blocks };
}
type StoredMessage = Anthropic.MessageParam & { id: string };
const stored: StoredMessage = { id: "1", role: "user", content: "hi" };
console.log(withBlocks(stored, [{ type: "text", text: "x" }]));

// Beta headers on Models move to client.beta.models.
const page = await client.beta.models.list({ betas: ["some-beta-2026-01-01"] });
console.log(page.data.length);

// A gateway that still reads X-Api-Key.
const proxied = new Anthropic({
  apiKey: process.env.ANTHROPIC_API_KEY,
  defaultHeaders: { "X-Api-Key": process.env.ANTHROPIC_API_KEY ?? "", Authorization: null }
});
console.log(typeof proxied);

The rest of the TypeScript changes, per the guide:

Client-side compaction is gone from the tool runner. compactionControl and its module are removed. Use server-side compaction (betas: ["compact-2026-01-12"] plus a compact_20260112 edit in context_management), or call runner.compactBeforeNextTurn(). The trigger must be at least 50,000 tokens.
Platform packages move together. v1 of @anthropic-ai/bedrock-sdk, vertex-sdk, foundry-sdk, aws-sdk and google-cloud-sdk needs v1 of the core SDK. Upgrade them in the same change, or your package manager installs a second, older copy of @anthropic-ai/sdk.
Credential precedence changed. With nothing passed in code, the client uses the first of ANTHROPIC_API_KEY, ANTHROPIC_AUTH_TOKEN, the ANTHROPIC_PROFILE profile, workload identity federation variables, and the active profile on disk. It logs a warning once if both of the first two are set.

What breaks in the SDKs (Python and others)#

Upgrade order that will not page you#

Grep for the 400s first. Search your code for temperature, top_p, top_k, document blocks in assistant turns, and citations on user text. These fail at runtime, so fix them before switching versions.
Check your gateway. If LiteLLM, an internal proxy or an API gateway reads X-Api-Key, either change it to read Authorization or apply the defaultHeaders workaround above. This is the change most likely to cause a 401 after a routine dependency bump.
Bump the SDK and its platform packages together, then let the type checker list the rest.
Pin the major version in package.json or requirements.txt if you are not ready. A caret range like ^0.135.0 will not cross to 1.0.0, but an unpinned Python install will cross to 2.0.0.
Update license tracking for Apache 2.0. No code change, but your compliance tooling may flag it.

Claude Code users get a shortcut: Claude Code 2.1.307 added /claude-api api-version to "move Claude API code to API version 2026-10-21".

Gotchas and limits#

Raw HTTP callers opt in explicitly. If you call the API without an SDK, nothing changes until you set anthropic-version: 2026-10-21 yourself.

What people are actually saying#

The release is hours old. We found no Hacker News or Reddit thread yet, only vendor recaps such as CellCog's write-up, which leads with the sampling-parameter removal, the same change we expect to cause the most friction.
We will update this post with practitioner reports, especially on gateway breakage and eval drift, once they exist.

FAQ#

What changed in Claude API version 2026-10-21?#

Which SDK versions use API version 2026-10-21?#

Python 2.0.0, TypeScript 1.0.0, C# 13.0.0, Go 2.0.0, Java 3.0.0, PHP 1.0.0, Ruby 2.0.0 and ant CLI 2.0.0. Earlier versions keep sending 2023-06-01.

Do I have to migrate now?#

Why does my gateway reject requests after upgrading the SDK?#

The new SDKs send the key as Authorization: Bearer instead of X-Api-Key. Change the gateway to read Authorization, or set X-Api-Key in defaultHeaders with Authorization: null.

Continue Reading#

Claude Opus 5.5 Developer Guide: Pricing, API, Claude Code - the model-level API changes to handle alongside the version bump
Prompt Caching in the Claude API: A Production Guide - re-check cache behavior after a major SDK bump
Claude API OpenTelemetry Tracing: How to Set It Up (Beta) - trace requests to confirm which version each service sends

What breaks at the API level#

What breaks in the SDKs (TypeScript)#

What breaks in the SDKs (Python and others)#

Upgrade order that will not page you#

Gotchas and limits#

What people are actually saying#

FAQ#

What changed in Claude API version 2026-10-21?#

Which SDK versions use API version 2026-10-21?#

Do I have to migrate now?#

Why does my gateway reject requests after upgrading the SDK?#

Continue Reading#

Sources#

Get the next deep dive like this in your inbox

Claude Opus 5.5 Developer Guide: Pricing, API, Claude Code

Prompt Caching in the Claude API: A Production Guide

Claude API OpenTelemetry Tracing: How to Set It Up (Beta)

Related Tools

Claude Agent SDK

Claude Code

Vercel AI SDK

OpenAI Agents SDK

Apps from Developers Digest

Pricing Experiment Lab

Related Guides

MCP Servers Explained

Plan Mode - Claude Code

Live Skill Discovery - Claude Code

Related Videos

Anthropic's Cowork: Claude Code for the Rest of Your Work

Anthropic's Claude Opus 4.5 in 5 Minutes

Anthropic’s Claude Haiku 4.5 in 6 Minutes

Related Posts

Claude Opus 5.5 Developer Guide: Pricing, API, Claude Code

Prompt Caching in the Claude API: A Production Guide

Claude API OpenTelemetry Tracing: How to Set It Up (Beta)

Anthropic Python SDK 1.0: How to Migrate to httpx2

Claude Advisor Tool vs a Bigger Model: When the Pairing Pays

Claude Code Review Levels: Quick, Standard and Deep Explained

Build with the member tools

What breaks at the API level#

What breaks in the SDKs (TypeScript)#

What breaks in the SDKs (Python and others)#

Upgrade order that will not page you#

Gotchas and limits#

What people are actually saying#

FAQ#

What changed in Claude API version 2026-10-21?#

Which SDK versions use API version 2026-10-21?#

Do I have to migrate now?#

Why does my gateway reject requests after upgrading the SDK?#

Continue Reading#

Sources#

Get the next deep dive like this in your inbox

Claude Opus 5.5 Developer Guide: Pricing, API, Claude Code

Prompt Caching in the Claude API: A Production Guide

Claude API OpenTelemetry Tracing: How to Set It Up (Beta)

Related Tools

Claude Agent SDK

Claude Code

Vercel AI SDK

OpenAI Agents SDK

Apps from Developers Digest

Pricing Experiment Lab

Related Guides

MCP Servers Explained

Plan Mode - Claude Code

Live Skill Discovery - Claude Code

Related Videos

Anthropic's Cowork: Claude Code for the Rest of Your Work

Anthropic's Claude Opus 4.5 in 5 Minutes

Anthropic’s Claude Haiku 4.5 in 6 Minutes

Related Posts

Claude Opus 5.5 Developer Guide: Pricing, API, Claude Code

Prompt Caching in the Claude API: A Production Guide

Claude API OpenTelemetry Tracing: How to Set It Up (Beta)

Anthropic Python SDK 1.0: How to Migrate to httpx2

Claude Advisor Tool vs a Bigger Model: When the Pairing Pays

Claude Code Review Levels: Quick, Standard and Deep Explained

Build with the member tools