Claude API 2026-10-21: What Breaks and How to Upgrade

What changed on October 21?

Anthropic released API version 2026-10-21 on October 21, 2026, the first new version since 2023-06-01. Eight official SDK and CLI libraries released new major versions simultaneously to send 2026-10-21 by default. These releases include Python SDK 2.0.0, TypeScript SDK 1.0.0, C# SDK 13.0.0, Go SDK 2.0.0, Java SDK 3.0.0, PHP SDK 1.0.0, Ruby SDK 2.0.0, and CLI 2.0.0. The new versions are licensed under Apache 2.0 instead of MIT.

Direct API callers opt in explicitly by passing the header anthropic-version: 2026-10-21. Older SDK major releases remain functional and continue pinning requests to the 2023-06-01 version. On Amazon Bedrock, version 2026-10-21 is available only for Claude 4.7 and later models.

Which requests now return 400?

Sending temperature, top_p, or top_k to the Messages API, token counting endpoints, or Message Batches returns a 400 error under version 2026-10-21. The API rejects requests containing any of these three fields even if the payload sets them to their default values. Without them, requests sample with the defaults, including a temperature of 1.0. Before, this request worked; on 2026-10-21 it returns 400:

{
  "model": "claude-sonnet-4-6",
  "messages": [
    {
      "role": "user",
      "content": "Analyze these logs."
    }
  ],
  "temperature": 0.2,
  "max_tokens": 1024
}

After, the same request without the sampling parameter:

{
  "model": "claude-sonnet-4-6",
  "messages": [
    {
      "role": "user",
      "content": "Analyze these logs."
    }
  ],
  "max_tokens": 1024
}

Models that already accept only defaults, such as Claude 4.7 and later, sample exactly as before. On models that accept other values, such as Claude Sonnet 4.6, a request that lowered temperature loses that effect, and no other setting replaces it. Callers dependent on non-default values must stop sending them or keep those specific requests on 2023-06-01.

Placing a document block directly within an assistant message returns an HTTP 400 response. Client payloads must send document blocks inside user messages instead. The API still accepts document blocks nested inside another block in assistant messages, such as results returned by a web fetch tool.

Supplying a text block that contains a non-empty citations array inside a user message also generates a 400 error. This restriction applies whether the text block appears directly in a user message or inside a search_result block. The API continues to accept citation arrays inside assistant messages, as well as the setting "citations": {"enabled": true} on documents and search results.

What changes in the new SDKs?

API keys are now sent as Authorization: Bearer headers instead of X-Api-Key. The Claude API accepts either header format, so direct callers require no modifications. Any proxy or gateway that reads X-Api-Key must be updated to read Authorization, though AnthropicFoundry still sends x-api-key.

MessageParam in the Python SDK is now a union of UserMessageParam, AssistantMessageParam, and SystemMessageParam. Beta versions split following the identical design pattern. Calling MessageParam directly raises a TypeError at runtime, requiring Python developers to write messages as standard dictionaries.

# Before: Python SDK 1.x
from anthropic.types import MessageParam

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

# After: Python SDK 2.0.0
from anthropic.types import MessageParam

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

Text Completions is removed from the TypeScript, Go, Java, and Ruby SDKs, as well as the CLI where ant completions create has been removed. Applications calling legacy completion endpoints must migrate their payloads to the Messages API.

The non-beta Models methods no longer accept beta flags across SDK clients. To send beta headers, call the same methods on client.beta.models. In Python, this requires calling client.beta.models.list(betas=[beta]).

The TypeScript and Ruby SDK tool runners drop client-side compaction via compactionControl in favor of server-side compaction. Applications enable server-side compaction by providing betas: ["compact-2026-01-12"]. It is configured through context_management edits of type compact_20260112, with a trigger of at least 50,000 input tokens.

Which Admin API fields were renamed?

In 2026-10-21 the Admin API renames five response fields and the Claude Enterprise Analytics API renames two; the old names are gone. Role-based access control requests now reference role_ids instead of roles on RBAC groups. RBAC group members replace group_id with rbac_group_id, while RBAC roles rename name to display_name.

Organization and workspace rate-limit entries replace group_type with group.type. In the Claude Enterprise Analytics API, per-user usage and cost reports replace actor.email with actor.email_address. In addition, activity summaries responses rename summaries to data.

API key responses replace workspace_id with a scope field. Single-workspace API keys store the identifier under scope.workspace_id. An all-workspaces key returns a scope of {"type": "organization"} with no workspace_id.

How do you upgrade safely?

Upgrading to 2026-10-21 follows three steps from the official migration guide. First, switch to 2026-10-21 by updating your SDK dependency to the new major version or by adding the header. Second, fix breaking changes that affect your implementation, including removing sampling parameters and updating dictionary formats. Third, run your test suite against 2026-10-21 before releasing updates to production.

Updating SDK dependencies switches client calls to the new version header automatically. In Python environments, developers upgrade packages via standard package management.

pip install --upgrade "anthropic>=2.0.0"

Direct HTTP callers can test individual payloads by setting the anthropic-version header manually. This validates that request schemas comply with the new requirements before making code changes in production.

curl https://api.anthropic.com/v1/messages \
  -H "anthropic-version: 2026-10-21" \
  -H "Authorization: Bearer $ANTHROPIC_API_KEY" \
  -H "content-type: application/json" \
  -d '{
    "model": "claude-sonnet-4-6",
    "max_tokens": 1024,
    "messages": [{"role": "user", "content": "Ping"}]
  }'

Does this affect Claude Code or apps using Tokely?

Tokely's /v1/messages endpoint at base URL https://api.tokely.me accepts API keys sent via Authorization: Bearer or x-api-key. Because the gateway accepts both authentication schemas, new major SDKs authenticate without changes. Tokely forwards the anthropic-version header you send and defaults to 2023-06-01 when absent, so plan for the same 2026-10-21 rules when you upgrade your SDK.

To point Claude Code at Tokely, see the Claude Code guide.

Sources

This guide references the Anthropic release notes, the official migration document Migrating to API version `2026-10-21`, and the protocol documentation on API versions.