Contents
If your Anthropic integration goes through an official SDK, you have never had to think about the anthropic-version header. The SDK sent it for you. That convenience is now the risk: the migration guide for API version 2026-10-21 says an SDK uses the API version that was current when its major version was released, and the new majors (Python 2.0.0, TypeScript 1.0.0, Go 2.0.0, Java 3.0.0, Ruby 2.0.0, PHP 1.0.0, C# 13.0.0, ant CLI 2.0.0) all send 2026-10-21. A dependency bump is therefore also a server-side contract change, and the two failures that matter most look very different: one is a loud 400, the other is a header that your own infrastructure silently stops seeing.
The loud change: sampling parameters return 400
In 2026-10-21, a Messages or Message Batches request that includes temperature, top_p or top_k returns a 400, even when the value equals the default. The SDKs and CLI drop the three parameters entirely, so typed code that sets them stops compiling or raises, depending on the language.
The detail worth reading twice is what the guide says about behavior, not syntax. Without the parameters a request samples at the defaults, including temperature of 1.0. Models that already accept only the defaults, which the guide names as Claude 4.7 and later, behave as before. On a model that still accepts other values, such as Claude Sonnet 4.6, a request that lowered temperature for more consistent output loses that effect, and “no other setting replaces it”. The guide’s two options are to stop sending the parameter or to keep that specific request on 2023-06-01.
That second option is the real decision. If a pipeline on an older model uses temperature: 0 for extraction or classification and you have no regression suite measuring output variance, removing the parameter is not a no-op. Treat it as a behavior change and decide per call site whether it stays pinned to the old version.
This is also a loud failure only if the code path runs. A rarely used branch that sets top_p will pass your tests and 400 in production, so search the codebase for all three names before the bump, not after.
The quiet change: the key moves to Authorization
The SDKs and CLI now send the API key as Authorization: Bearer <key> instead of X-Api-Key. The guide states that the Claude API accepts a key in either header, so requests still authenticate. What changes is everything between your code and the API that looked for the old header:
- a proxy or gateway that reads
X-Api-Keyto identify the caller, rate limit, or inject its own credential; - a log filter that redacts
X-Api-Keybut has no rule forAuthorization, which is a secrets-in-logs risk rather than an outage; - middleware or test stubs that assert on the header.
Nothing returns an error in these cases, which is why they are worth auditing first. The guide’s CLI note shows the shape of the change: --debug output now prints Authorization: Bearer <REDACTED> where it printed X-Api-Key: <REDACTED>. If your own redaction is a header allowlist, check it.
For gateways you cannot change yet, the guide gives per-language ways to keep sending X-Api-Key. In TypeScript:
const client = new Anthropic({
apiKey,
defaultHeaders: { "X-Api-Key": apiKey, Authorization: null }
});
In Go it is option.WithHeader("X-Api-Key", apiKey) plus option.WithHeaderDel("Authorization"). The Authorization: null and WithHeaderDel parts matter, because without them the SDK still sends the bearer header as well.
One client, one credential
Because a key and an auth token now share the Authorization header, a client holds a single credential. In Python, passing two of api_key, auth_token, credentials, config or profile to a constructor, copy() or with_options() raises ValueError. Version 1 sent both, each in its own header.
The pattern this breaks is a gateway that wants a token and an upstream that wants a key, both set on one client. The guide’s answer is to pass the token as auth_token, put X-Api-Key in default_headers, and have the gateway strip its own Authorization before forwarding, since “the Claude API expects one credential for each request”.
Credential discovery also changed when nothing is passed in code: only the first of ANTHROPIC_API_KEY, ANTHROPIC_AUTH_TOKEN, the named profile, the workload identity federation variables, and the active profile on disk is used, and the Python client logs a warning once if the first two are both set. A CI runner that happens to carry both variables now behaves by a precedence rule you should know.
Admin API consumers: renamed fields, not deprecations
For the Admin API and Claude Enterprise Analytics API, responses under 2026-10-21 no longer contain the old field names. Examples from the guide’s tables: RBAC groups roles becomes role_ids, RBAC group members group_id becomes rbac_group_id, RBAC roles name becomes display_name, rate limits group_type becomes group.type, and analytics actor.email becomes actor.email_address.
The one with semantics attached is API keys. workspace_id is removed in favor of scope. Previously workspace_id was null for both a key bound to the Default Workspace and an all-workspaces key, so those were indistinguishable. Now a workspace-bound key, including Default, has scope.workspace_id set to the real ID, and an all-workspaces key has scope of {"type": "organization"}. Any audit script that read null as “Default workspace” will now misclassify, and the guide’s fix is to look up the Default workspace ID with List Workspaces and include_default=true and compare against that.
Two smaller 400s
Placing a document block directly in an assistant message now returns 400, and so does a text block with non-empty citations in a user message, including inside search_result blocks. Documents nested in tool results that Claude returned, and citations on assistant text you replay, are still accepted. These mostly hit code that rebuilds conversation history by hand.
How I would sequence the upgrade
The mechanism gives you two independent levers, and the guide supports using them separately: the SDK version, and the anthropic-version header you set yourself if you call the API without an SDK. So:
- Grep for
temperature,top_p,top_k,X-Api-Keyandx-api-keyacross application code, gateway config, log redaction rules and test fixtures. - For each sampling parameter on a model that honors it, decide whether the call stays on
2023-06-01or you accept default sampling and re-run your evals. - Fix gateways and redaction before the SDK bump, since those fail silently.
- Bump the SDK in a separate release from unrelated dependency changes, so a 400 or a missing header is attributable.
One platform caveat from the guide: on Amazon Bedrock, 2026-10-21 is available only for Claude 4.7 and later models, so calls to older Bedrock models should stay on the SDK version you run today.
I have not run the new SDKs against a gateway for this post. Everything above comes from Anthropic’s release notes and migration guide, so the specifics of your proxy’s behavior are still yours to test.