What to check before upgrading the Anthropic SDK

Upgrading the Anthropic SDK can change which requests the Claude API accepts, even when you keep the same model and prompt.

On October 21, 2026, Anthropic released API version 2026-10-21, Python SDK 2.0.0, TypeScript SDK 1.0.0, and new major versions of its other SDKs and the ant CLI. These versions use the new API contract by default. The release notes list the versions for each language.

If you call Claude from your own application, treat this as a migration, not a routine package update.

If you use Amazon Bedrock with a model older than Claude 4.7, Anthropic says to stay on your existing SDK version. The new API version is available there only for Claude 4.7 and later models. See the migration guide before upgrading those integrations.

Save a working baseline

Before changing the package, run your existing tests and save a few representative inputs and outputs. Include a conversation with history, not just a single question.

Record the model ID, SDK version, and API version alongside those results. The API version is sent in the anthropic-version request header. It chooses the request and response contract; it doesn’t choose the model.

For a Node.js app using npm, check the installed SDK with:

npm ls @anthropic-ai/sdk

Commit your working dependency files before upgrading. Keep the model ID and prompt unchanged while you make the migration, so you can tell which changes came from the upgrade.

Sampling parameters are gone

Under the new API version, sending temperature, top_p, or top_k returns HTTP 400, even with default values. Remove them. The SDK also removes these arguments, so it may reject your code before sending a request.

There is no replacement for non-default sampling. Requests that need it can stay on 2023-06-01, according to Anthropic’s migration guide.

This is easy to miss if you have a shared wrapper around several providers. A helper might add temperature: 0 to every request, even when the application code never mentions it. If you use a framework such as the Vercel AI SDK, inspect the provider integration too.

For example, this old request fragment needs changing:

const request = {
  model,
  max_tokens: 256,
  messages,
  temperature: 0,
}

Keep the same model and messages, and omit the sampling field entirely:

const request = {
  model,
  max_tokens: 256,
  messages,
}

Setting temperature to its default value still fails. In TypeScript, fix the type error rather than hiding it with a cast: extra fields can still reach the API at runtime.

I’d check the wrapper first. Then I’d test the result, not just whether the request succeeds. Removing a setting can fix an error without preserving the behavior your application depended on.

Check authentication around the SDK

For direct Claude API calls, the SDK now sends API keys through Authorization: Bearer instead of X-Api-Key. The Claude API accepts either header, but your proxy, middleware, mocks, and log filters may expect the old one.

For example, a test that checks for X-Api-Key may fail even though authentication works. More importantly, a custom logger that only hides that header may need updating.

Check the request path between your application and Anthropic, not just the API call itself. Never print a real key while debugging this.

Use a fake key in tests that inspect outgoing headers. Check that your logger hides both Authorization and X-Api-Key, regardless of header casing. A gateway may still use the older header elsewhere.

Check message construction too

The role attached to a block now matters in a few places:

Don’t strip citations from every message to make a failing request pass. Fix the block and role combination that the API rejects. A document nested inside a tool result, such as a web fetch result returned by Claude, is still accepted.

In Python, MessageParam becomes a union: use a dictionary rather than calling MessageParam(...) as a constructor. The migration guide covers this and the remaining language-specific changes.

Pay particular attention to stored conversations. A simple new chat might pass while replaying an older thread fails.

Upgrade and test the request

Make the upgrade on a branch. In an npm project, install the reviewed SDK release and commit the resulting package.json and package-lock.json together. The first TypeScript release using the new API version is 1.0.0; review later release notes too if you install a newer release.

Search your application code for the places that may need changes:

rg -n 'temperature|top_p|top_k|MessageParam\(|X-Api-Key|x-api-key' src tests

Replace src and tests with your project’s directories. These matches are places to inspect, not instructions to delete every occurrence. Other providers may still need those settings.

After fixing them, try a small request outside your application’s wrappers. Save this as sdk-smoke.mjs in the project:

import Anthropic from '@anthropic-ai/sdk'

const model = process.env.ANTHROPIC_MODEL
if (!model) throw new Error('Set ANTHROPIC_MODEL to your existing model ID')

const client = new Anthropic()

const message = await client.messages.create({
  model,
  max_tokens: 256,
  messages: [{ role: 'user', content: 'What is a dependency lockfile?' }],
})

for (const block of message.content) {
  if (block.type === 'text') console.log(block.text)
}

Run it on the server with ANTHROPIC_API_KEY and ANTHROPIC_MODEL set in your environment:

node sdk-smoke.mjs

This makes a billable API request. Use the model ID your app already uses. The client reads the API key from the environment; keep this file out of browser code.

If this works but the application fails, compare what its wrapper and gateway send. If TypeScript compilation fails before you can run anything, start with the SDK’s changed types.

Next, exercise the paths a basic smoke test might miss:

• Start a conversation, then continue it with saved history.
• Send a document through the actual application workflow.
• Run a tool call and return its result.
• Pass through any proxy or gateway you use.
• Check that logs still hide credentials.

Finally, run a small set of representative inputs and compare whether the answers still meet your requirements.

For example, if the app extracts invoice fields, check the fields and amounts against known invoices. If it calls a tool, check the selected tool and its arguments. You don’t need identical wording, but you do need the behavior your app relies on.

Check the rest of the migration guide

These are the common request checks, but they aren’t the whole release. The new SDKs also change features independently of the API version. In TypeScript, check for the removed legacy Text Completions API and the old tool-runner compactionControl option. Applications using the Admin or Enterprise Analytics APIs need to review renamed response fields too.

Changing only the anthropic-version header back doesn’t restore removed SDK methods or types. The TypeScript SDK docs warn that overriding the header can leave the SDK’s types out of sync with the API.

If you need to roll back, restore the working application code and its dependency files together. In an npm project, npm ci then installs the versions recorded in that restored lockfile. Keep your baseline inputs so you can rerun the same checks before trying the migration again.

Want me to talk about your product? You can sponsor this site.