Claude API 2026-10-21: Migrate to Python SDK 2.0 and TS 1.0

If you call the Claude API from a backend, the dependency bot has probably opened a pull request by now that bumps anthropic to 2.x or @anthropic-ai/sdk to 1.x. Merge it without reading the notes and some requests will start failing with a 400. On 21 October 2026 Anthropic released Claude API version 2026-10-21, the first new anthropic-version since 2023-06-01, and the new SDK majors send it by default. This guide covers what actually changes, how I migrated Python and TypeScript code, and the questions people search alongside "claude api": keys, pricing and whether it is free.

What changed in Claude API version 2026-10-21

The release notes for 21 October list two things that arrived together: the new API version, and new SDK majors that send it. The SDK versions that switch you over are:

The last-version column for Python and TypeScript comes from the PyPI and npm release history (1.17.0 and 0.137.0 both shipped on 20 October). The changes fall into three groups:

1. API changes that apply to any client sending anthropic-version: 2026-10-21, including raw HTTP.
2. SDK changes that come with the new majors whatever version you send: the key header, message types and credential rules.
3. Licence: the new SDK and CLI versions are Apache 2.0. Earlier versions stay MIT.

Breaking changes in the Messages API

These apply to POST /v1/messages, token counting, and each request inside a Message Batch created with the new version.

temperature, top_p and top_k return a 400

This is the one most people will hit. Under 2026-10-21, sending temperature, top_p or top_k returns a 400 error, even at the parameter's default value. The new SDKs no longer have the three parameters at all.

What you lose depends on the model. Claude 4.7 and later models already accept only the default values, so removing the parameters changes nothing for them. On older models that accept other values, such as Claude Sonnet 4.6, a request that lowered temperature for more consistent output loses that effect, and Anthropic says no other setting replaces it. Your two options are to drop the parameter or keep that specific request on 2023-06-01.

Documents and citations in the wrong role

Two smaller rules. A document block placed directly in an assistant message now returns a 400; send documents in user messages. And a text block with a non-empty citations array in a user message returns a 400. Citations on Claude's earlier assistant replies that you send back are still accepted, and so is "citations": {"enabled": true} on documents.

Admin API field names

If you read the Admin API or the Claude Enterprise Analytics API, the old names of renamed fields are gone in the new version. For example roles is now role_ids on RBAC groups, and API keys report scope instead of workspace_id. The migration guide has the full table.

Migrating to Python SDK 2.0

Install the new major and pin it:

pip install "anthropic>=2.3,<3"

A message written as a dict needs no change. What breaks is code that calls the type. In 2.x, MessageParam is a union of UserMessageParam, AssistantMessageParam and SystemMessageParam, so calling it raises TypeError: Cannot instantiate typing.Union:

# Before (anthropic 1.x)
message = MessageParam(role="user", content="Hello")

# After (anthropic 2.x)
message: MessageParam = {"role": "user", "content": "Hello"}

A helper that builds a dict with a variable role still runs, but mypy now rejects it because the dict matches no single member of the union. Build one role at a time:

from typing import Literal

from anthropic.types import MessageParam


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

The full request after the upgrade looks like this:

from anthropic import Anthropic
from anthropic.types import MessageParam

# Reads ANTHROPIC_API_KEY from the environment. Never hard-code the key.
client = Anthropic()

history: list[MessageParam] = [
    {"role": "user", "content": "Summarise this support ticket in two lines: ..."},
]

message = client.messages.create(
    model="claude-sonnet-5-5",
    max_tokens=512,
    system="You are a concise support assistant. Answer in plain English.",
    messages=history,
)

for block in message.content:
    if block.type == "text":
        print(block.text)

Two more Python changes: client.models.list(betas=...) is now client.beta.models.list(betas=...), and passing two credentials such as api_key and auth_token raises ValueError. Note that Python SDK 1.0 (20 August) had already removed temperature, top_p and top_k from the method signatures, so on Python the sampling change mostly bites code that sends them through extra_body or raw HTTP.

Migrating to TypeScript SDK 1.0

npm install @anthropic-ai/sdk@^1.3.0

If you use @anthropic-ai/bedrock-sdk, vertex-sdk, foundry-sdk, aws-sdk or google-cloud-sdk, move them to v1 in the same commit. Otherwise npm installs a second, older copy of @anthropic-ai/sdk for them.

The two compile errors I hit were temperature (now an unknown property) and an interface extending MessageParam, which is now a union:

// Before (@anthropic-ai/sdk 0.x)
interface StoredMessage extends Anthropic.MessageParam {
  id: string;
}
await client.messages.create({ model, max_tokens: 512, temperature: 0.2, messages });

// After (@anthropic-ai/sdk 1.x)
type StoredMessage = Anthropic.MessageParam & { id: string };
await client.messages.create({ model, max_tokens: 512, messages });

A complete, type-checked version:

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

// Reads ANTHROPIC_API_KEY from the environment. Server-side only.
const client = new Anthropic();

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

const history: StoredMessage[] = [
  { id: "m1", role: "user", content: "Summarise this support ticket in two lines: ..." },
];

async function main(): Promise<void> {
  const message = await client.messages.create({
    model: "claude-sonnet-5-5",
    max_tokens: 512,
    system: "You are a concise support assistant. Answer in plain English.",
    messages: history.map(({ id: _id, ...m }) => m),
  });
  for (const block of message.content) {
    if (block.type === "text") console.log(block.text);
  }
}

main().catch((err: unknown) => {
  console.error(err);
  process.exit(1);
});

Also in 1.x: client.models.list({ betas }) moves to client.beta.models.list, the legacy Text Completions API is gone, the tool runner's compactionControl option is removed in favour of server-side compaction (trigger of at least 50,000 tokens), and new Anthropic({ apiKey, authToken }) throws a TypeError.

The auth header change: X-Api-Key becomes Authorization: Bearer

The new SDKs and CLI send your API key as Authorization: Bearer <key> instead of X-Api-Key. The Claude API accepts either header, so direct calls keep working. What breaks is anything in between that reads X-Api-Key: an API gateway, a reverse proxy, a log filter that redacts that header, or a test stub that asserts on it.

The cleanest fix is to change the gateway to read Authorization. If you can't do that yet, the migration guide shows how to move the key back. Both of these sent only X-Api-Key in my mock test:

import os

import httpx2
from anthropic import Anthropic, DefaultHttpxClient

api_key = os.environ["ANTHROPIC_API_KEY"]


def send_x_api_key(request: httpx2.Request) -> httpx2.Request:
    # Only for gateways that still read X-Api-Key.
    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))

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

const apiKey = process.env["ANTHROPIC_API_KEY"] ?? "";

// Only for gateways that still read X-Api-Key.
const client = new Anthropic({
  apiKey,
  defaultHeaders: { "X-Api-Key": apiKey, Authorization: null },
});

Platform clients differ: the Foundry clients still send x-api-key, and the Bedrock and Bedrock Mantle clients already used a bearer token.

Getting and using a Claude API key safely

You create API keys in the Claude Console at platform.claude.com. Since July 2026 you can set an expiry when you create one, and since August keys can be personal or tied to a service account and scoped to a workspace. For workloads that already have an identity (GitHub Actions, Kubernetes, cloud IAM), Workload Identity Federation lets the SDK use short-lived tokens instead of a static key.

The rules I follow on every client project:

• Keep the key in ANTHROPIC_API_KEY on the server or in a secret manager. Both SDKs read it automatically.
• Never ship it in a Flutter, React Native or browser bundle. Anyone can pull it out of the binary. Put a small backend in front, as I describe in securing API keys in Flutter apps.
• One key per service and environment, with an expiry, so you can revoke one without taking everything down.
• Set only one credential per client. Under the new SDKs, if both ANTHROPIC_API_KEY and ANTHROPIC_AUTH_TOKEN are set and you pass nothing in code, the client uses the key and logs a warning once.

Claude API pricing for the current models

Prices from Anthropic's pricing page on 1 November 2026, in USD per million tokens:

The API version change does not change prices. For choosing between Haiku, Sonnet and Opus 5.5 and the model-level migration, see my Claude Sonnet 5.5 vs Opus and Haiku 5.5 guide, and for cost per task across vendors, the LLM API pricing comparison.

Is the Claude API free?

Not as an ongoing tier. Anthropic's pricing FAQ says new users receive a small amount of free credits to test the API, and since 7 October 2026 the Claude Max, Ultra and Team plans include monthly API credits. After that, billing is per token on actual monthly usage.

Claude API key vs Claude Code

They are easy to mix up because they share a name. A Claude API key is a credential for your own applications, billed per token through the Console. Claude Code is Anthropic's coding tool. You can sign in to it with a Pro, Max, Ultra, Team or Enterprise subscription, or with a Console account, and it can also use an ANTHROPIC_API_KEY from the environment after you approve it, according to the Claude Code authentication docs. Upgrading your app's SDK does not change how Claude Code signs in.

Upgrade checklist

• Search the codebase for temperature, top_p, top_k, extra_body and raw calls to /v1/messages.
• Decide per request: drop the sampling parameter, or keep that request on 2023-06-01 and the old SDK for now.
• Move document blocks out of assistant messages and remove citations from user text blocks.
• Bump anthropic to 2.x or @anthropic-ai/sdk to 1.x, plus every @anthropic-ai/*-sdk platform package in the same commit.
• Fix the type errors: MessageParam(...) calls, interfaces extending MessageParam, models.list(betas=...).
• Update gateways, proxies, log redaction and test stubs that read X-Api-Key.
• Make sure each client gets exactly one credential.
• On Bedrock with Opus 4.6 or earlier, stay on the old SDK until you move to a Claude 4.7 or later model.
• Update your licence inventory from MIT to Apache 2.0.
• Run your evaluation set and integration tests against 2026-10-21 before release.

The upgrade itself is mostly mechanical. The two parts worth slowing down for are lost sampling control on older models and anything in your infrastructure that watches the X-Api-Key header.