Claude API's first new version in three years: temperature/top_p/top_k removed — your migration checklist

On October 21, 2026, Anthropic released a new Claude API version: 2026-10-21. This deserves its own article for one simple reason — the previous official version, 2023-06-01, was released in June 2023. After more than three years, the Claude API version number has finally moved. At the same time, the official SDKs in all seven languages jumped major versions (Python 2.0.0, TypeScript 1.0.0, C# 13.0.0, Go 2.0.0, Java 3.0.0, PHP 1.0.0, Ruby 2.0.0), the ant CLI reached 2.0.0, and the new SDKs and CLI send 2026-10-21 by default.

A version bump means breaking changes. The headline this time: the Messages API has removed the three sampling parameters temperature, top_p, and top_k — sending any of them returns a 400 error, even at their default values. Beyond that: a batch of Admin API fields renamed, SDKs switching to the Authorization: Bearer auth header, the license changing from MIT to Apache 2.0, and several easy-to-miss details. This article walks through the official migration guide item by item: who gets hit, who can stay put, and a migration checklist you can execute directly.

The core changes at a glance

Change	Details
New API version	2026-10-21, the first official version since June 2023; the old 2023-06-01 is not deprecated yet
New SDKs (send the new version by default)	Python 2.0.0, TypeScript 1.0.0, C# 13.0.0, Go 2.0.0, Java 3.0.0, PHP 1.0.0, Ruby 2.0.0, and ant CLI 2.0.0
Most-watched breaking change	Messages API removes temperature, top_p, top_k — sending them returns 400
Other request-level changes	400 for document blocks placed directly in assistant messages; 400 for non-empty citations arrays on text blocks in user messages
Admin surface changes	A batch of Admin API and Enterprise Analytics API fields renamed (e.g. roles→role_ids)
Version-independent SDK changes	Auth header becomes Authorization: Bearer; Text Completions removed from TS/Go/Java/Ruby; client-side compaction removed from TS/Ruby
License	New SDK and CLI versions move from MIT to Apache 2.0, no code changes needed

Breaking changes, item by item

1. Sampling parameters removed: temperature, top_p, top_k

This is the highest-impact item in the whole migration guide. Under 2026-10-21, any Messages API request (including token counting and every request inside a Message Batch) that includes temperature, top_p, or top_k returns a 400 — even at the parameter's default value. The guide's wording is "even at the parameter's default value": no exceptions, no grace period.

Without the parameters, requests sample at the defaults — equivalent to a request that never sent them, i.e. temperature=1.0. The key dividing line: Claude 4.7 and later models only ever accepted the defaults, so nothing changes for them behaviorally. But on models that still accept other values, such as Claude Sonnet 4.6, if you lowered temperature for more consistent output, that effect is gone — the guide states plainly that "no other setting replaces it."

Anthropic offers two ways out: remove the parameters and accept default sampling, or keep requests that rely on non-default values on 2023-06-01. Note this is not the first move: the Claude Haiku 5.5 migration guide published on October 7 already documented that sampling parameters and assistant prefill return 400 on the new model. The direction is clear — Anthropic is systematically taking back developer control over the sampling process.

2. Document blocks directly in assistant messages: 400

If you place document blocks directly in assistant messages when assembling conversation history, the new version returns 400. Put documents in user messages instead. One exception: a document nested inside another block is still accepted, such as one inside a web fetch tool result that Claude returned. This mainly hits code that fabricates assistant turns or hand-assembles history.

3. Non-empty citations arrays on text blocks in user messages: 400

Sending a text block with a non-empty citations array in a user message (including inside search_result blocks) also returns 400. Three exemptions to note: citations on text blocks in assistant messages remain legal (e.g. echoing Claude's earlier replies back); the "citations": {"enabled": true} setting on documents and search results is unaffected. This one targets RAG pipelines that manage citation round-tripping themselves.

4. Admin API and Enterprise Analytics field renames

The admin-surface breaking changes follow a "old names are gone, no compatibility period" approach. RBAC: roles→role_ids, group_id→rbac_group_id, name→display_name; rate limits: group_type→group.type; usage and cost reports: actor.email→actor.email_address, and summaries→data on activity summaries.

The trickiest is workspace_id on API keys: in the old version it was the ID of the workspace the key is bound to (null for Default Workspace keys and all-workspace keys); in the new version the field is removed in favor of scope — a workspace-bound key reports its real ID in scope.workspace_id (no more ambiguous null), and an all-workspaces key has {"type": "organization"}. Code that treated workspace_id == null as "Default Workspace" must be rewritten: call List Workspaces with include_default=true, find the workspace named "Default", and compare IDs.

5. SDKs switch to the Authorization: Bearer auth header

New SDK versions no longer send the key in the X-Api-Key header — they use Authorization: Bearer <key>. The good news: the Claude API accepts either header, so there is no hard server-side cutover. The bad news: every link in your chain that reads X-Api-Key must change — homegrown API gateways, proxies, log-scrubbing middleware, test stubs. Grep them all. If you set headers by hand, you can keep using X-Api-Key; the API still accepts it.

A related design change: API keys and auth tokens now share one header, so an SDK client holds a single credential. With neither passed in code, the client follows the credential precedence order. If you ever wrote code that removed X-Api-Key so a request carried only a token, delete that logic — removing Authorization would now remove the token too.

The ant CLI 2.0.0 removes the --api-key and --auth-token flags outright (they printed deprecation warnings since v1.27.0), for a very practical reason: command-line values linger in shell history and process listings. Use the ANTHROPIC_API_KEY / ANTHROPIC_AUTH_TOKEN environment variables, --api-key-stdin / --auth-token-stdin, or ant auth login instead.

6. SDK/CLI breaking changes independent of the API version

This group hits you as soon as you upgrade the SDK major version, regardless of which API version you send:

• Text Completions removed: gone from the TypeScript, Go, Java, and Ruby SDKs and from the CLI. The rationale: newer models and features don't support it — use the Messages API.
• TypeScript and Ruby SDKs drop client-side compaction: the client-side compaction logic in the tool runner is removed in favor of server-side compaction — conversation summarization now happens inside the API instead of via an extra client request. Note the trigger threshold must be at least 50,000 tokens; pause_after_compaction and custom instructions are among the other options.
• MessageParam split by role: previously one type for all roles, now UserMessageParam, AssistantMessageParam, and SystemMessageParam (beta variants split the same way). The JSON the SDK actually sends is unchanged — this mostly affects TypeScript users' type gymnastics.
• One-value enums become constants: affects the C#, Go, Java, PHP, and Ruby SDKs plus one CLI flag. Required fields that can hold only one value previously had their own single-member enum types; now they are constants, the enum types are gone, and the JSON sent and received is unchanged.
• Non-beta Models methods no longer take betas: to send beta headers, call the same methods on client.beta.models (ant beta:models in the CLI), which return BetaModelInfo instead of ModelInfo; the --beta flag on ant models is removed in sync.

7. License: MIT → Apache 2.0

Starting with these versions, all SDKs and the CLI — including the TypeScript platform packages, the C# Bedrock/Vertex/etc. packages, and every Java com.anthropic artifact — move to the Apache License 2.0. Earlier versions remain MIT. The guide is explicit: no code changes are needed; the only action item is updating your dependency license inventory if you keep one. For enterprise users, Apache 2.0's explicit patent grant usually clears compliance review more easily than MIT, so this change is most likely a net positive.

Who gets hit by a 400, and who can sleep well

Situation	Verdict
Requests carrying temperature / top_p / top_k (any value)	400 — remove the parameters
Relying on lowered temperature for stable output (Sonnet 4.6-era models)	Behavior changes, no replacement setting; can stay on 2023-06-01 for now
Only using Claude 4.7 and later models with default sampling	No behavior change; just remove the parameters
Placing document blocks directly in assistant messages	400 — move them to user messages
Citations on user-message text blocks (common in RAG round-tripping)	400 when non-empty — drop the array
Internal tools reading Admin API / Analytics field names	Old names are gone — update per the rename table
Homegrown gateways/proxies reading X-Api-Key for auth or log scrubbing	Switch to the Authorization header (API accepts both, migrate gradually)
Scripts passing keys via ant --api-key	2.0.0 errors out — use env vars or stdin
Simple Messages API Q&A, never touching sampling parameters	Barely affected — upgrade the SDK and move on

The migration checklist: just follow it

The official recommended upgrade order has three steps: switch to 2026-10-21 first (upgrade the SDK major version, or set the anthropic-version header to 2026-10-21 for raw calls), then fix each breaking change, then test fully against the new version before releasing. The diagram above, in text form:

• Remove temperature / top_p / top_k: search the codebase for all three names and delete them. Remember that even default values return 400 — there is no "pass 1.0 to be safe" option.
• Move document blocks out of assistant messages into user messages: audit the code that assembles conversation history.
• Remove citations arrays from user-message text blocks: RAG pipelines should prioritize their citation round-trip logic.
• Update Admin API field names: roles→role_ids, group_id→rbac_group_id, name→display_name, group_type→group.type, actor.email→actor.email_address, summaries→data; read API key scope via scope.
• Point gateways and middleware at the Authorization header: grep for X-Api-Key — auth, log scrubbing, test stubs, miss none.
• Upgrade SDK majors and fix removed APIs: Text Completions, client-side compaction, the MessageParam type split, one-value enums as constants, the betas parameter on Models methods — go through them one by one.
• Update SDK license entries to Apache 2.0: no code changes, pure bookkeeping.

The other item in the same day's release notes that's easy to miss

The October 21 release-notes entry actually has three paragraphs, and so far we've only covered the first (API version and SDKs). The second deserves attention from anyone running a platform or gateway: user profiles gained enforcement_status and enforcement_actions fields, letting you see whether Anthropic has restricted or banned one of your end customers, plus a new enforcement_status[] filter to list profiles with open restrictions or bans.

This is built for the API-resale scenario: if you operate a platform or gateway, or resell Claude access to downstream customers, a safety enforcement action against one end user used to risk hitting your whole organization; with user profiles, enforcement can target a single end customer. The October 20 entry added a matching piece — organization webhooks (beta): your servers get event notifications when an end customer is restricted or the restriction ends. This is an Admin-surface feature, not in the 2026-10-21 migration guide's breaking-change list, but gateway teams should handle it in the same upgrade window as the auth-header change — you're touching the gateway code anyway.

Why is Anthropic so determined to kill the sampling parameters?

Removing temperature looks like "three fewer parameters" on the surface; underneath, it's Anthropic stating an API design philosophy. Three pieces of evidence point the same way.

First, newer models never really honored them. The migration guide states it plainly: Claude 4.7 and later models only accepted the defaults. For the latest models, these parameters have been decorative for years — and per the October 7 Haiku 5.5 migration guide, sending non-default values returns a 400. The API-level removal simply ratifies at platform level what was already true at model level.

Second, sampling knobs are losing relevance in the reasoning era. The last two years of model capability gains came mostly from reasoning (thinking / chain-of-thought), while temperature-style parameters control token-sampling randomness — a concept born in the "completion" era. When a model's main job becomes "think first, then answer," tuning output quality with a 0-to-1 dial is increasingly crude. Anthropic's choice: take the dial away and put the responsibility for "stable and controllable" on the model and on prompt engineering.

Third, Anthropic is pushing developers toward the "right" way to get determinism. temperature=0 used to be the de facto standard answer, but it was never a real determinism guarantee — the same prompt could still drift across runs, and low-temperature sampling degrades output quality. Anthropic is telling you: want structure, use schema constraints; want stability, write sharper instructions; want robustness, add validation and retries. These engineering measures cost more than tweaking a parameter, but they actually work.

There will be pushback, of course: removing the parameters takes some control away from developers, and for scenarios that genuinely want high randomness (brainstorming, creative copy), whether the default temperature=1.0 suffices remains to be tested in practice. But one thing is certain — in the 2026-10-21 world, "tuning parameters" no longer exists as an action. What's left is prompts and engineering.

SDK major upgrades: one note per language

With all seven SDKs jumping majors at once, the rule from the guide's "Switch to 2026-10-21" section is: upgrade to the first listed version for your language — its default anthropic-version is 2026-10-21. One thing worth flagging per language:

• Python (2.0.0): if you wrote code that stripped X-Api-Key to leave only a token, delete that logic now; verify the credential precedence behaves as expected when both ANTHROPIC_API_KEY and ANTHROPIC_AUTH_TOKEN are set.
• TypeScript (1.0.0): the most churn — MessageParam split into three per-role types, client-side compaction removed in favor of server-side, Text Completions deleted, and the platform packages (bedrock-sdk, vertex-sdk, etc.) each shipping their own 1.0.0 with the Apache 2.0 license switch.
• C# (13.0.0): the one-value-enums-to-constants change has the widest blast radius — any wrapper code defining matching enum types needs edits; the companion packages (Anthropic.Bedrock, Anthropic.Vertex, etc.) each ship 1.0.0 with the license change.
• Go (2.0.0): watch the enum-to-constant change and the Text Completions removal; the Amazon Bedrock and Google Cloud clients also send the new version by default.
• Java (3.0.0): the license change covers every com.anthropic artifact — enterprise users updating license inventories shouldn't miss transitive dependencies.
• PHP (1.0.0): jumping from 0.x straight to 1.0.0 — semantically this is the "first stable release," so read the changelog from 0.53.0 onward in full when upgrading.
• Ruby (2.0.0): like TypeScript, it takes both the client-side compaction removal and the Text Completions deletion — prioritize regression testing around the tool runner.

Raw API callers (no SDK) have it simplest: set the anthropic-version request header to 2026-10-21, then fix request bodies item by item from the checklist. The official advice is to ship the version switch and the breaking-change fixes together in one release, avoiding an in-between state.

Four judgments for vibe developers

Judgment 1: Removing temperature ends the "reproducibility" playbook

Many vibe coding projects carry a line of "ancestral config": temperature=0, hoping for stable, reproducible model output. Anthropic just flipped the table: sampling is no longer yours to control. Combined with Haiku 5.5 also 400-ing on assistant prefill, the message is unambiguous — output stability should be guaranteed by the model itself, not tuned by callers with sampling knobs.

For vibe developers, only three routes remain: write constraints into the prompt ("output JSON only, no explanations" beats temperature); use structured output plus schema validation to block uncertainty at the gate; add multi-sample voting on critical steps. The engineering discipline that temperature let you skip now has to be built for real. That's not bad news — temperature was never a determinism guarantee anyway, just a psychological comfort blanket.

Judgment 2: The auth-header unification means gateway authors grep before upgrading

The change most likely to blow up in production isn't temperature — it's X-Api-Key → Authorization. Because the API accepts both, the server won't error; your own gateway logic will: auth middleware that can't find the key fails open or closed, log-scrubbing rules go stale and keys land in logs in plaintext. Before upgrading the SDK, grep X-Api-Key across your gateway, proxy, and middleware code. This step should rank above removing temperature.

Judgment 3: Apache 2.0 is a compliance plus, but update the books

MIT → Apache 2.0 has zero practical impact for most individual developers and users — no code changes. But if you ship company projects, the dependency license-audit gate cares: Apache 2.0's explicit patent grant usually sails through compliance review more smoothly than MIT. Conversely, the license entries for these SDKs in your company's compliance inventory must be updated, or the next audit will flag them. Old versions stay MIT; nothing is retroactive.

Judgment 4: "Not deprecated yet" is a grace period, not a long-term plan

Anthropic gave no deprecation timeline for 2023-06-01, so requests depending on non-default temperature can stay put for now. But don't architect around "two versions forever": the new SDKs' type definitions have already dropped the old fields, so your code will need changes sooner or later — and Anthropic's new models only recognize the new behavior anyway. The old version just buys you a few months. Recommended strategy: build new integrations directly on 2026-10-21, and schedule old ones for migration in "remove parameters → rename fields → switch version" order. Don't wait for the deprecation announcement — by cloud-industry convention, the window from deprecation notice to actual shutdown is usually only 6 to 12 months.

Three years for one official version — Anthropic's move this time is no small thing: removing sampling parameters is a philosophical stance, changing the auth header is engineering hygiene, and switching the license is compliance maturity. Bundling all three into one release signals that the Claude API has moved past its "move fast" phase and is now designed for long-term stability. The best response from developers is to migrate early per the checklist — the sooner, the less to worry about. After all, if the version number only moves once every three years, the next move may not come with such a gentle grace period.