Claude API 2026-10-21 Migration: Sampling and Bearer Auth

The first new API version in three years

Every Claude API request carries an anthropic-version header. Most code has been sending 2023-06-01, and on October 21, 2026 the next version, 2026-10-21, was released. The official versioning page recommends the latest version, but it doesn't announce an end date for 2023-06-01.

New major SDK versions shipped the same day, and they send 2026-10-21 by default. So you can hit a 400 just by bumping a package, without ever touching the version header yourself.

C# (13.0.0), PHP (1.0.0), and Ruby (2.0.0) moved too. The new SDKs and CLI are licensed under Apache 2.0 instead of MIT, so update your dependency license inventory if you keep one.

If you call the API over plain HTTP, you only change the header value.

curl https://api.anthropic.com/v1/messages \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2026-10-21" \
  -H "content-type: application/json" \
  -d '{"model":"claude-haiku-5-5","max_tokens":512,
       "messages":[{"role":"user","content":"Hello"}]}'

The change most teams will hit: sampling parameters are gone

On the new version, sending temperature, top_p, or top_k returns a 400 on every model. The migration guide states plainly that this happens even at the parameter's default value. Code that kept temperature: 1 "just to be safe" breaks too.

Without these parameters, requests sample with the defaults (temperature 1.0). Claude 4.7 and later models already accepted only the defaults, so their output doesn't change. But if you lowered temperature on a model that allowed it, such as Claude Sonnet 4.6, that effect is lost and no other setting replaces it. The official advice is to drop the parameter, or keep that specific request on 2023-06-01.

Start by finding every place that sends them. Message Batch requests and token counting follow the same rule.

# Find sampling parameters (snake_case and camelCase)
git grep -nE '\b(temperature|top_p|top_k|topP|topK)\b' -- '*.ts' '*.tsx' '*.py' '*.java' '*.kt'

If you relied on low temperature for stable output, solve it with structure instead. For classification, constraining the output to an enum schema removes most of the room for drift without any sampling knob.

SDK major upgrade: Bearer auth and proxies

Separately from the API version, the new SDKs and CLI send your key differently. They used to put it in X-Api-Key; now they send Authorization: Bearer <key>. The Claude API itself accepts either header.

The risk is whatever sits in between. If an internal gateway (a server that receives requests and forwards them) or proxy reads X-Api-Key to meter usage or swap keys, authentication can break right after the upgrade. Log filters that redact the key and test stubs need the same check.

If you can't change the gateway yet, you can send the old header from the client. This is for TypeScript SDK v1.

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

// Gateway reads only X-Api-Key: drop Authorization, send the old header
const client = new Anthropic({
  apiKey,
  defaultHeaders: { "X-Api-Key": apiKey, Authorization: null },
});

A few behaviors changed along with it. A client now holds one credential, and adding X-Api-Key in per-request options sends both keys instead of replacing one. The ant CLI dropped its --api-key and --auth-token flags, because values on the command line end up in shell history and process listings.

Other changes: documents, citations, and Admin API fields

Two more Messages API rules changed. A document block placed directly in an assistant message returns a 400, so send documents in user messages. A text block with a non-empty citations array in a user message also returns a 400. Sending Claude's earlier cited replies back as assistant messages is still fine.

If you have ops tooling on the Admin API, rename fields. RBAC groups return role_ids instead of roles, roles return display_name instead of name, and rate-limit entries return group.type instead of group_type. API keys no longer return workspace_id; use scope.workspace_id.

SDK types were cleaned up as well. MessageParam is now a union of per-role types such as UserMessageParam and AssistantMessageParam, and the legacy Text Completions API is gone from the TypeScript, Go, Java, and Ruby SDKs and the CLI. Code that builds messages as plain dicts or object literals mostly keeps working.

An upgrade checklist

Here is the official order, translated into day-to-day steps.

1. Map your dependencies: do you call the Claude SDK directly, or through a framework? Wrappers often send their own version header.
2. Remove sampling parameters: delete what the search finds, then re-check quality against your eval set.
3. Audit the auth path: confirm which header your gateway, log filters, and test stubs read.
4. Ship it in one release: bundle the SDK upgrade with the code fixes, as the guide recommends.
5. Check Bedrock: on Amazon Bedrock, only Claude 4.7 and later models support the new version. For older models, stay on your current SDK version.

If you use TypeScript platform packages such as the Bedrock or Vertex SDKs, move them to 1.0 in the same upgrade. Otherwise your package manager installs a second, older copy of the core SDK.

On our stack: the AI SDK and Haiku 5.5

The chatbot on the IntentCode homepage calls Claude Haiku 5.5 through the Vercel AI SDK (ai v4 with @ai-sdk/anthropic 1.2). When we opened the installed package, we found the wrapper attaches anthropic-version: 2023-06-01 and x-api-key on its own. So the official SDK's major release doesn't change our requests today.

Our code does, however, set temperature to 1 explicitly in three places. Haiku 5.5 rejects non-default temperatures with a 400, and AI SDK v4 sends 0 when you leave it unset, so we pinned it. Once the wrapper moves to 2026-10-21, those same lines would cause a 400. We've added "remove those three lines" to the checklist for the day we upgrade the wrapper.

In short, this version simplifies the API for an era of models that only use default sampling. Migrating ahead of time keeps a model swap and an API change from landing in the same release.