Migrating to API version 2026-10-21

This guide lists the code changes for moving from API version 2023-06-01 to 2026-10-21. The upgrade steps say what to do, in order.

Upgrade steps

1. 1

   Switch to 2026-10-21

   If you use an SDK, your requests use the API version that was current when your SDK's major version was released. The versions shown for your language are the first to use 2026-10-21, so upgrade to them. If you call the API without an SDK, set the anthropic-version header to 2026-10-21.

   cURLCLIPythonTypeScriptC#GoJavaPHPRuby

   Python

   Upgrade the anthropic package to version 2.0.0.

   Release the upgrade together with your fixes from the next step.

2. 2

   Update your code for the breaking changes

   Go through the breaking changes, and update your code for each one that affects you. Also make the code changes that the new SDK or CLI version needs.

3. 3

   Test against 2026-10-21

   Test your integration against 2026-10-21 before you release.

Breaking changes

Messages API

These changes apply to requests to the Messages API (POST /v1/messages), to token counting, and to each request in a Message Batch created with 2026-10-21.

Document blocks in assistant messages return an error

Affects you if you send document blocks directly in assistant messages.

In 2026-10-21, a request that places a document block directly in an assistant message returns a 400 error. Send documents in user messages instead. A document nested inside another block, such as a web fetch tool result that Claude returned, is still accepted.

Citations in user messages return an error

Affects you if you send citations on text blocks in user messages, including inside search_result blocks.

In 2026-10-21, a request that sends a text block with a non-empty citations array in a user message returns a 400 error. Remove citations from those blocks. Citations on text blocks in assistant messages, such as Claude's earlier replies that you send back, are still accepted, and so is the "citations": {"enabled": true} setting on documents and search results.

Sampling parameters are removed

Affects you if you send temperature, top_p, or top_k in Messages requests or Message Batch requests.

In 2026-10-21, a request that sends temperature, top_p, or top_k returns a 400 error, even at the parameter's default value.

Remove the three parameters from your requests.

As of the latest major versions, the SDK and the CLI no longer have the three parameters.

Without these parameters, a request samples with their defaults, including a temperature of 1.0, the same as a 2023-06-01 request that leaves them out. Models that already accept only the defaults, such as Claude 4.7 and later models, sample as before. On models that accept other values, such as Claude Sonnet 4.6, a request that lowered temperature for more consistent output loses that effect. No other setting replaces it. If a request relies on a non-default value, either stop sending the parameter, or keep that request on 2023-06-01.

Admin API and Claude Enterprise Analytics API

Affects you if your code reads the Admin API or Claude Enterprise Analytics API response fields in the following tables.

In 2026-10-21, responses from the Admin API and the Claude Enterprise Analytics API no longer include the old names of renamed fields. Use the new names instead.

Admin API:

Claude Enterprise Analytics API:

The group_type query parameter on the rate-limit list endpoints and the workspace_id filter on the API key list endpoint are unchanged.

workspace_id on API keys

Affects you if your code reads workspace_id on API keys.

In 2023-06-01, an API key's workspace_id is the ID of the workspace the key is bound to, or null for a key bound to the Default Workspace and for a key that isn't bound to one workspace (an all-workspaces key).

In 2026-10-21, workspace_id is removed. Read scope instead: for a key bound to a workspace, including the Default Workspace, scope.workspace_id is that workspace's real ID, and an all-workspaces key has a scope of {"type": "organization"}, with no workspace_id.

If your code treated a null workspace_id as the Default Workspace, compare scope.workspace_id with your Default Workspace's ID instead. To find that ID, call List Workspaces with include_default=true and take the workspace named "Default".

SDK and CLI changes

Earlier SDK and CLI versions sent anthropic-version: 2023-06-01 with every request. The versions under Switch to 2026-10-21 send 2026-10-21, including their Amazon Bedrock and Google Cloud clients. The changes in Breaking changes apply to them too: the removed parameters and the old field names are also gone from the SDK's types and from the CLI's flags and output.

MessageParam is a union with one type per role

In earlier versions, MessageParam was one type for every role. Each role now has a type of its own: UserMessageParam, AssistantMessageParam, and SystemMessageParam. BetaMessageParam is split the same way, into BetaUserMessageParam, BetaAssistantMessageParam, and BetaSystemMessageParam. The requests that the SDK sends have the same fields and values as before.

# Before
message = MessageParam(role="user", content="Hello")

# After
message: MessageParam = {"role": "user", "content": "Hello"}

# Before
def to_message(role: Literal["user", "assistant"], text: str) -> MessageParam:
    return {"role": role, "content": text}


# After
def to_message(role: Literal["user", "assistant"], text: str) -> MessageParam:
    if role == "user":
        return {"role": "user", "content": text}
    return {"role": "assistant", "content": text}

One-value enums are constants

This affects the C#, Go, Java, PHP, and Ruby SDKs and one CLI flag. In earlier versions, a required field that can hold only one value had an enum type of its own with a single member. These fields are now constants, and the enum types are gone. The JSON that the SDK sends and reads is the same.

Client-side compaction is removed from the tool runner

This affects the TypeScript and Ruby SDKs. Client-side compaction in the tool runner has been removed in favor of server-side compaction, which summarizes the conversation inside the API instead of with an extra request from the client.

// Before
const runner = client.beta.messages.toolRunner({
  // ...
  compactionControl: { enabled: true, contextTokenThreshold: 100_000 }
});

// After
const runner = client.beta.messages.toolRunner({
  // ...
  betas: ["compact-2026-01-12"],
  context_management: {
    edits: [{ type: "compact_20260112", trigger: { type: "input_tokens", value: 100_000 } }]
  }
});

The trigger threshold must be at least 50,000 tokens. See compaction for the other options (pause_after_compaction, custom instructions).

Text Completions is removed

The legacy Text Completions API is removed from the TypeScript, Go, Java, and Ruby SDKs and from the CLI. Newer models and features don't support it. Use the Messages API instead.

# Before
ant completions create \
  --model "$MODEL" \
  --max-tokens-to-sample 1024 \
  --prompt $'\n\nHuman: Hello, Claude\n\nAssistant:'

# After
ant messages create \
  --model "$MODEL" \
  --max-tokens 1024 \
  --message '{role: user, content: "Hello, Claude"}'

betas is removed from the non-beta Models methods

The non-beta Models methods no longer take betas, and the ant models commands no longer take --beta. To send beta headers, call the same methods on client.beta.models, or ant beta:models in the CLI. In the SDK, those methods return BetaModelInfo where the non-beta ones return ModelInfo.

# Before
page = client.models.list(betas=[beta])

# After
page = client.beta.models.list(betas=[beta])

API keys are sent as Authorization: Bearer

The SDK and the CLI send your API key as Authorization: Bearer <key> instead of in the X-Api-Key header, so change any proxy or gateway that reads or sets X-Api-Key to use Authorization, or send the key in X-Api-Key yourself. The Claude API accepts a key in either header, so a program that talks to the API directly needs no change.

# Before
X-Api-Key: <key>

# After
Authorization: Bearer <key>

If a proxy or gateway reads X-Api-Key

import httpx2
from anthropic import Anthropic, DefaultHttpxClient


def send_x_api_key(request: httpx2.Request) -> httpx2.Request:
    if request.headers.get("Authorization") == f"Bearer {api_key}":
        del request.headers["Authorization"]
        request.headers["X-Api-Key"] = api_key
    return request


client = Anthropic(api_key=api_key, http_client=DefaultHttpxClient(auth=send_x_api_key))

If you set or removed X-Api-Key on a request

This affects the Python, TypeScript, Go, PHP, and Ruby SDKs.

If you removed X-Api-Key so that a request sent only an auth token, delete that code instead of changing it, because removing Authorization would remove the token. A client holds one credential, so make sure that it's the token: with none passed in code and both ANTHROPIC_API_KEY and ANTHROPIC_AUTH_TOKEN set, the client uses the key.

A client holds one credential

An API key and an auth token now share a header, so an SDK client holds one credential. With none passed in code, it follows the credential precedence order.

client = Anthropic(api_key=key, auth_token=token)

# Before: sent `X-Api-Key: <key>` and `Authorization: Bearer <token>`
# After:  raises `ValueError`

Changes in one SDK or the CLI

These changes each affect one SDK or the CLI.

# Before
ant --api-key "$KEY" models list

# After, from the environment
export ANTHROPIC_API_KEY="$KEY"
ant models list

# After, from a secret manager
op read op://vault/anthropic/api-key | ant --api-key-stdin models list

The license is Apache 2.0

Starting with these versions, the SDK and the CLI are licensed under the Apache License, Version 2.0. Earlier versions remain under the MIT License. No code changes are needed. If you track the licenses of your dependencies, update their entries.

• TypeScript: The platform packages (@anthropic-ai/bedrock-sdk, @anthropic-ai/vertex-sdk, @anthropic-ai/foundry-sdk, @anthropic-ai/aws-sdk, and @anthropic-ai/google-cloud-sdk) change license in their own 1.0.0 releases.
• C#: The other packages (Anthropic.Bedrock, Anthropic.Vertex, Anthropic.Foundry, Anthropic.Aws, Anthropic.GoogleCloud, and Anthropic.Mcp) change license in their own 1.0.0 releases.
• Java: The change covers every com.anthropic artifact.