# What to check before upgrading the Anthropic SDK

> Upgrading the Anthropic SDK changes the API version your app sends. Check sampling parameters, authentication, message history, and output before you ship.

Author: [Flavio Copes](https://flaviocopes.com/about/) | Published: 2026-10-23 | Topics: [AI](https://flaviocopes.com/tags/ai/) | Canonical: https://flaviocopes.com/anthropic-sdk-upgrade/

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](https://platform.claude.com/docs/en/release-notes/overview) list the versions for each language.

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

```mermaid
flowchart TD
  accTitle: An SDK upgrade can change the API contract
  accDescr: Application code sends a request through the SDK. Upgrading the SDK changes the API version header, so the API can reject a request before the unchanged model runs.
  A[Your application and prompt] --> B[New major SDK version]
  B --> C[API version 2026-10-21]
  C --> D{Request meets new contract?}
  D -->|No| E[HTTP 400]
  D -->|Yes| F[Same model as before]
```

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](https://platform.claude.com/docs/en/api/migration-2026-10-21) 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:

```bash
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](https://platform.claude.com/docs/en/api/migration-2026-10-21#sampling-parameters-are-removed).

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](https://flaviocopes.com/vercel-ai-sdk/), inspect the provider integration too.

For example, this old request fragment needs changing:

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

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

```js
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:

| What your request contains | What to change |
| --- | --- |
| A `document` block directly in an `assistant` message | Send the document in a `user` message |
| A non-empty `citations` array on a user `text` block, including inside `search_result` | Remove that array from the user text block |
| Citations on assistant text from an earlier reply | Keep them; they are still accepted |
| `citations: { enabled: true }` on a document or search result | Keep it; enabling citations is still supported |

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](https://platform.claude.com/docs/en/api/migration-2026-10-21#sdk-and-cli-changes) 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:

```bash
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:

```js
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:

```bash
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](https://platform.claude.com/docs/en/cli-sdks-libraries/sdks/typescript#default-headers) 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.