Recent development · Practical technical guide · 23 October 2026
Anthropic published API version 2026-10-21 and the Python SDK 2.0.0 that defaults to it on 21 October 2026. This reads the migration guide, shows which changes break code versus proxies, and records what the 1.17.0 and 2.0.0 Python SDKs actually send, checked locally against a mock transport.
A dated version, and an SDK that defaults to it
Anthropic identifies API versions by date through the anthropic-version header, and on 21 October 2026 it published version 2026-10-21. The same day it released anthropic-sdk-python 2.0.0, whose requests default to the new version; earlier 1.x SDKs send 2023-06-01. So you adopt the new version either by upgrading the SDK or, for raw HTTP callers, by setting the header. The migration is small in code but touches a few things that are easy to get wrong, and some of the breaking changes affect your proxy or gateway rather than your application. The facts below are from the migration guide; the SDK behaviour is what two local installs actually sent.
The breaking changes that matter most
Three Messages API changes and one transport change account for most real migrations.
| Change | Who it affects | What to do |
|---|---|---|
| temperature, top_p, top_k removed | Requests that send any sampling parameter | Remove them; a request that sends one returns 400 on every model |
| Document blocks in assistant messages | Code that puts a document in an assistant turn | Send documents in user messages; 400 otherwise |
| Citations in user messages | Text blocks with a citations array in user turns | Remove those citations; 400 otherwise |
| API key sent as Authorization: Bearer | Proxies or code that read x-api-key | Read Authorization instead, or re-add x-api-key yourself |
The sampling-parameter removal is the one most likely to surprise. In 2026-10-21 a request that sends temperature, top_p or top_k returns a 400 even at the parameter default. Without them a request samples at the model defaults, the same as a 2023-06-01 request that omitted them; the effect is only felt by code that lowered temperature for more consistent output on a model that accepted other values, which loses that effect and has no replacement. A request that depends on a non-default value must either drop the parameter or stay on 2023-06-01.
What the SDKs actually send
To separate documentation from behaviour I installed anthropic 1.17.0 and 2.0.0 in isolated virtualenvs and sent one request through each against an in-memory mock transport, so no call reached Anthropic. The outgoing request differs exactly as the guide describes.
| Observed with mock transport | anthropic 1.17.0 | anthropic 2.0.0 |
|---|---|---|
| anthropic-version header | 2023-06-01 | 2026-10-21 |
| Auth header sent | x-api-key | Authorization: Bearer |
| MessageParam(role=..., content=...) | constructs | raises TypeError (now a union) |
| models.list(betas=[...]) | accepted | raises TypeError |
Two things are worth flagging. First, the Python SDK has not accepted a temperature keyword on messages.create for several major versions, so the risk for Python users is not the keyword but raw HTTP bodies and anything passed through extra_body, which the SDK forwards unchanged; I confirmed a temperature placed in extra_body is sent on the wire under both SDKs. Second, MessageParam is now a union of UserMessageParam, AssistantMessageParam and SystemMessageParam, so calling or subclassing it raises; a plain dict literal still works.
Illustrative python, checked for syntax; adapt names and storage to your system.
# After 2026-10-21: write messages as dicts, not MessageParam(...).
message = {"role": "user", "content": "Hello"} # unchanged, still correct
# If a proxy still reads x-api-key, move the key back on every request:
import httpx2
from anthropic import Anthropic, DefaultHttpxClient
def send_x_api_key(request: httpx2.Request) -> httpx2.Request:
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))The proxy change people forget
The quietest breakage is the auth header. The 2.0.0 SDK and the current CLI send the API key as Authorization: Bearer <key> instead of X-Api-Key. The Claude API accepts either, so a direct caller notices nothing, but a proxy, gateway, log filter or test stub that reads or sets X-Api-Key stops seeing the key. If your gateway authenticates on that header, either update it to read Authorization or re-add X-Api-Key on each request as above. There is a related subtlety for anyone who previously stripped X-Api-Key to send only a bearer token: a client holds one credential, so with nothing passed in code and both ANTHROPIC_API_KEY and ANTHROPIC_AUTH_TOKEN set, the SDK uses the key.
Upgrade steps
- Upgrade the SDK (Python to 2.0.0 or later) or, for raw HTTP, set anthropic-version: 2026-10-21, and release it together with the code fixes below.
- Remove temperature, top_p and top_k from every request, including any in extra_body or a raw body; decide whether any request that relied on a non-default value should stay on 2023-06-01.
- Move documents out of assistant messages and remove citations from user-message text blocks.
- Update any proxy, gateway or test that reads X-Api-Key to read Authorization, or re-add the header on each request.
- If you read renamed Admin or Analytics fields (roles, group_id, workspace_id on keys, actor.email), switch to the new names.
- Test against 2026-10-21 before release.
When to stay on the old version
If a request genuinely depends on a lowered temperature on a model that honoured it, the migration guide itself says to keep that request on 2023-06-01 rather than lose the effect. On Amazon Bedrock, 2026-10-21 is available only for Claude 4.7 and later; older Bedrock models should stay on the SDK version they use today. For everyone else the new version is the recommended default, and the work is mechanical. Treat the version as what it is, a dated contract: pin it explicitly in a config value rather than inheriting it from whichever SDK version happens to be installed, so an unrelated dependency bump cannot move you across a breaking boundary without a code review.
Failure modes
- Leaving a temperature in a raw body or extra_body after upgrading, so every request returns 400.
- A gateway that authenticates on X-Api-Key and now sees no key, rejecting all traffic after an SDK bump.
- Calling or subclassing MessageParam in typed code, which now raises; use a dict or the role-specific type.
- Reading removed Admin or Analytics field names and getting nulls or key errors after the cutover.
- Assuming a Python temperature keyword was the risk; the SDK dropped it long ago, so audit raw bodies instead.
Verification
Reproduce the SDK check locally: install the old and new SDK in separate environments, send one request each through a mock transport, and assert the version header and auth header flip as above with no network call. Add a contract test that sends a request with temperature against 2026-10-21 and asserts a 400, so a stray parameter fails your tests before production. If you run a gateway, add a test that it still authenticates when the key arrives as a bearer token. Finally, grep your code and any stored request templates for temperature, top_p, top_k and x-api-key before the cutover.
Sources and scope
Checked against these sources on 23 October 2026. Event: Anthropic API versions page and the 2026-10-21 migration guide, 21 October 2026; recheck it before acting. Examples and figures are illustrative, not measurements.
Remove temperature, top_p and top_k from every request including raw bodies and extra_body, update any proxy that reads x-api-key to read Authorization, write messages as dicts rather than MessageParam, switch to the renamed Admin fields, and keep a request on 2023-06-01 only if it truly needs a non-default sampling value.