Guides

Anthropic's API version 2026-10-21: how to upgrade, and what will break

Anthropic released a new Claude API version on 21 October 2026, with new major SDK releases that send it by default. Sampling parameters are removed and API keys move to a Bearer header. A step-by-step guide.

Abstract illustration of a dotted route through waypoints over a contour map, in teal and orange.
Abstract illustration of a dotted route through waypoints over a contour map, in teal and orange.

Anthropic released a new version of its Claude API, 2026-10-21, on 21 October 2026. It is the first new value for the anthropic-version request header since 2023-06-01, and it ships alongside new major versions of every official Anthropic SDK and the ant command-line tool, all of which send the new version by default. Some requests that work today will return errors under it, so this SDK upgrade is more than a routine dependency bump. This guide walks through the changes using Anthropic’s official migration documentation.

Step 1: know which releases switch you over

If you call the API through an SDK, the API version is set by the SDK’s major version. According to Anthropic’s release notes, these are the first releases that send 2026-10-21:

SDK or tool First version on 2026-10-21
Python (anthropic) 2.0.0
TypeScript (@anthropic-ai/sdk) 1.0.0
C# (Anthropic) 13.0.0
Go (anthropic-sdk-go) 2.0.0
Java (anthropic-java) 3.0.0
PHP (anthropic-ai/sdk) 1.0.0
Ruby (anthropic) 2.0.0
ant CLI 2.0.0

A few packaging details from the migration guide are easy to miss:

  • TypeScript: the Bedrock, Vertex, Foundry, AWS and Google Cloud companion packages must move to their own v1 at the same time, or your package manager will install a second, older copy of the core SDK.
  • Go: the module path gains a /v2 suffix, so every import changes, followed by go get github.com/anthropics/anthropic-sdk-go/v2.
  • PHP: run composer require "anthropic-ai/sdk"; Anthropic notes that composer update alone stays within your existing version constraint.
  • Raw HTTP: set the header anthropic-version: 2026-10-21 yourself.

Anthropic’s guide says to release the SDK upgrade together with the code fixes below, and to test against the new version first.

Amazon Bedrock users: on Bedrock, 2026-10-21 is available only for Claude 4.7 and later models. If you call a model numbered 4.6 or lower there, Anthropic’s advice is to stay on your current SDK version or keep sending your current API version until you move to a newer model.

Step 2: fix the three Messages API breaking changes

These apply to POST /v1/messages, token counting and Message Batches created under the new version.

1. temperature, top_p and top_k are removed. Sending any of them returns a 400 error, even at the default value. Without them, requests sample with the defaults, including a temperature of 1.0. Anthropic says Claude 4.7 and later models already accept only the defaults, so they behave as before. On older models that accepted other values, such as Claude Sonnet 4.6, a request that lowered the temperature for more consistent output loses that effect, and the documentation says no other setting replaces it. If a request depends on a non-default value, the guide’s options are to drop the parameter or keep that request on 2023-06-01.

2. Document blocks in assistant messages are rejected. A document block placed directly in an assistant message now returns a 400 error. Move documents into user messages. Documents nested inside other blocks, such as a web fetch result returned by Claude, are still accepted.

3. Citations in user messages are rejected. A text block with a non-empty citations array in a user message, including inside a search_result block, returns a 400 error. Citations in assistant messages, and the "citations": {"enabled": true} setting on documents, are unaffected.

Step 3: handle the SDK changes

The new SDK majors also carry changes that do not depend on the API version:

  • API keys are sent as Authorization: Bearer instead of in the X-Api-Key header. Anthropic says the API accepts either, but any proxy, gateway, log filter or test stub that reads X-Api-Key needs updating. The guide shows how to send X-Api-Key yourself if you cannot change the proxy.
  • One credential per client. In Python, passing more than one of api_key, auth_token, credentials, config or profile now raises a ValueError.
  • MessageParam is split by role into user, assistant and system types. Dict and object literals that name their role mostly need no change, but in Python calling MessageParam(...) directly now raises a TypeError; write the message as a dict instead.
  • Text Completions is removed from the TypeScript, Go, Java and Ruby SDKs and from the CLI. Use the Messages API.
  • The CLI drops --api-key and --auth-token. Anthropic says values on the command line are visible in shell history and process listings.
  • The licence changes from MIT to Apache 2.0 for the new SDK and CLI versions. No code changes are needed, but dependency licence records may need updating.

Step 4: Admin API and analytics users

Responses no longer include the old names of renamed fields. For example, RBAC groups return role_ids instead of roles, rate-limit entries return group.type instead of group_type, and the Enterprise Analytics per-user reports return actor.email_address instead of actor.email. API keys no longer return workspace_id; read scope instead, where a key bound to any workspace, including the Default Workspace, has a real scope.workspace_id, and an all-workspaces key has a scope type of organization. Code that treated a null workspace_id as the Default Workspace needs rewriting.

What it means

For many applications on current Claude models, the core work is likely to be the SDK upgrade and removing the three sampling parameters, which newer models already restricted to their defaults. The changes more likely to cause surprises sit outside application code: the move to a Bearer header affects proxies and logging, and the Go module path and TypeScript companion packages affect build tooling. Anthropic recommends using the latest API version whenever possible; teams relying on lower temperatures with older models should weigh that against the option the guide gives of keeping those requests on 2023-06-01 while they plan a model change.

Sources

See All

More on Anthropic

See All

Type to search. ↑ ↓ to navigate, ↵ to open.