Claude API Versão 2026-10-21: O Que Mudou e Como Fazer o Upgrade com Segurança

A versão 2026-10-21 da API Claude é o primeiro novo valor de anthropic-version desde 2023-06-01. Ela introduz três mudanças de quebra na API de Mensagens: temperature, top_p e top_k agora retornam um erro 400, blocos document em mensagens de assistant retornam um 400, e citations em blocos text de mensagens de user retornam um 400. Ela também renomeia vários campos da Admin API e da Enterprise Analytics API. Você ativa a nova versão enviando anthropic-version: 2026-10-21 ou atualizando para as novas versões principais dos SDKs (Python 2.0.0, TypeScript 1.0.0, Go 2.0.0 e outros).

O problema: atualizar o SDK é justamente como a maioria das equipes vai migrar "acidentalmente" para a nova versão. Uma rotina pip install -U anthropic ou npm update que cruza uma versão principal faz com que todas as requisições passem para a 2026-10-21 de uma só vez. Este guia lista todas as mudanças documentadas pela Anthropic, mostra quais delas causam problemas em código real e apresenta uma ordem segura para fazer a atualização.

O que é o header anthropic-version?

O header anthropic-version é um cabeçalho obrigatório de requisição que fixa o formato da API Claude que você recebe. Dentro de uma mesma versão, a Anthropic mantém os parâmetros de entrada e saída existentes estáveis, mas pode adicionar entradas opcionais, novos valores de saída, novas variantes de enum, como tipos de eventos de streaming, e novas condições de erro. Mudanças de quebra só chegam com uma nova data de versão.

Segundo a página de versionamento, existem três versões:

Se você usa um SDK oficial, nunca define esse header por conta própria. Cada versão principal do SDK envia a versão que estava atual quando ela foi lançada. É por isso que, para a maioria das bases de código, a atualização do SDK e a atualização da versão da API são o mesmo evento.

Mudanças de quebra da Claude API 2026-10-21

Essas mudanças se aplicam a POST /v1/messages, à contagem de tokens e a todas as requisições dentro de um Message Batch criado com a versão 2026-10-21.

1. temperature, top_p e top_k foram removidos

Essa é a mudança que a maioria das pessoas vai encontrar. Qualquer requisição que envie temperature, top_p ou top_k retorna um erro 400, em todos os modelos, mesmo que você envie o valor padrão. Um temperature: 1.0 esquecido em um arquivo de configuração já é suficiente para quebrar a chamada.

O impacto na qualidade da saída depende do modelo:

• Claude 4.7 e posteriores já aceitam apenas os valores padrão de amostragem, então remover os parâmetros não altera nada na forma como eles geram resultados.
• Modelos mais antigos que aceitam outros valores, como o Claude Sonnet 4.6, perdem qualquer efeito obtido ao reduzir temperature. O guia de migração é direto sobre isso: nenhuma outra configuração o substitui.

Se uma requisição realmente depende de um valor não padrão, a Anthropic oferece duas opções: parar de enviar o parâmetro, ou manter aquela requisição específica na versão 2023-06-01.

2. Blocos document em mensagens de assistant retornam um 400

Alguns aplicativos reproduzem o histórico da conversa com um bloco document diretamente em um turno de assistant. Na versão 2026-10-21, isso é rejeitado. Mova os documentos para mensagens de user. Um documento aninhado dentro de outro bloco, como o resultado de uma ferramenta de web fetch retornada pelo Claude, ainda é aceito.

3. Citations em mensagens de user retornam um 400

Um bloco text com um array citations não vazio em uma mensagem de user agora falha, e isso inclui texto dentro de blocos search_result. Remova citations desses blocos. Citations nas respostas assistant do próprio Claude que você envia de volta continuam funcionando, assim como "citations": {"enabled": true} em documentos e resultados de busca.

4. Renomeações de campos na Admin API e na Enterprise Analytics

As respostas não incluem mais os nomes antigos dos campos:

A mudança nas chaves de API é a mais sutil. Na versão 2023-06-01, workspace_id era null tanto para chaves vinculadas ao Workspace Padrão quanto para chaves de todos os workspaces. Na versão 2026-10-21, scope.workspace_id contém o ID real do Workspace Padrão, e uma chave de todos os workspaces tem scope: {"type": "organization"} sem workspace_id. Se o seu dashboard tratava null como "Workspace Padrão", ele vai rotular incorretamente as chaves após a atualização.

Versões de SDK que enviam a 2026-10-21

A Anthropic lançou novas versões principais dos SDKs em 21 de outubro de 2026, e cada uma envia a 2026-10-21 por padrão, conforme as notas de versão:

As novas versões principais também trazem mudanças que não dependem da versão da API:

• As chaves de API são enviadas como Authorization: Bearer <key> em vez de X-Api-Key. A API Claude aceita ambas, mas um proxy, gateway, filtro de log ou stub de teste que lê X-Api-Key não verá mais a chave.
• Text Completions foi removida dos SDKs TypeScript, Go, Java e Ruby e da CLI. Use a API de Mensagens.
• betas foi removido dos métodos de Models não beta. Use client.beta.models em vez disso.
• MessageParam é uma união com um tipo por papel nos SDKs tipados, então algumas anotações de tipo precisam ser atualizadas.
• Go exige um novo caminho de importação terminando em /v2, e usuários de TypeScript nos pacotes Bedrock, Vertex, Foundry, AWS ou Google Cloud devem migrar esses pacotes para a v1 na mesma atualização, senão o gerenciador de pacotes instala uma segunda cópia mais antiga do SDK principal.
• A licença mudou de MIT para Apache 2.0.

Fixe sua versão principal atual antes de fazer qualquer outra coisa. Isso impede que um bot de dependências atualize seu projeto no meio de um sprint.

A exceção do Amazon Bedrock

No Amazon Bedrock, a versão 2026-10-21 funciona apenas com os modelos Claude 4.7 e posteriores. Se você ainda chama o Opus 4.6 ou um modelo mais antigo lá, mantenha sua versão atual do SDK ou continue enviando seu header atual, e troque o modelo primeiro.

Como atualizar para a versão 2026-10-21 da API Claude com segurança

A ordem sugerida pelo guia de migração é: trocar a versão, corrigir as mudanças de quebra e testar antes do lançamento. Veja como isso funciona na prática.

1. Fixe a versão principal antiga do SDK. Por exemplo, anthropic<2 no Python ou "@anthropic-ai/sdk": "^0" no npm.
2. Procure no seu código e configurações por temperature, top_p, top_k, X-Api-Key, completions.create e qualquer campo da Admin API da tabela acima.
3. Decida sobre a amostragem. No Claude 4.7 e posteriores, exclua os parâmetros. Em modelos mais antigos, aceite a amostragem padrão ou mantenha essas chamadas na 2023-06-01.
4. Corrija a construção das mensagens. Mova documentos do lado do assistant para turnos de user e remova citations dos blocos de texto de user.
5. Teste os mesmos payloads nas duas versões e compare os códigos de status e as formas das respostas.
6. Atualize o SDK e publique as correções de código juntas. A Anthropic recomenda lançar a atualização junto com suas correções, não antes.

Sem um SDK, a troca é feita com um único header:

curl https://api.anthropic.com/v1/messages \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2026-10-21" \
  -H "content-type: application/json" \
  -d '{
    "model": "claude-opus-5-5",
    "max_tokens": 1024,
    "messages": [{"role": "user", "content": "Hello, Claude"}]
  }'

Adicione "temperature": 0.2 a esse corpo e você receberá um 400. Envie o mesmo corpo com anthropic-version: 2023-06-01 e a requisição terá sucesso. Esse par de resultados é exatamente o que a etapa 5 deve capturar para cada payload que você envia em produção.

Deixe o Claude Code testar as duas versões com o Apidog CLI

A etapa 5 é tediosa manualmente: você tem dezenas de formatos de payload, e cada um precisa rodar duas vezes. Em vez disso, delegue a tarefa ao seu agente de programação. O Apidog CLI oferece ao Claude Code (ou Codex, Cursor e OpenCode) comandos para criar casos de teste e executá-los, de modo que o agente faz a comparação e você lê apenas o resumo.

Configure uma única vez:

npm install -g apidog-cli@latest
apidog login --with-token <YOUR_TOKEN>
npx -y skills add https://apidog.com   # pick Claude Code when prompted

Depois, dê ao Claude Code um único prompt:

In Apidog project <id>, create an environment "claude-api" with base URL
https://api.anthropic.com. For each JSON payload in ./fixtures/claude/, add a
POST /v1/messages test case that sends the header anthropic-version: {{anthropic_version}}
and asserts status 200 and a non-empty content array. Run every case twice, once with
anthropic_version=2023-06-01 and once with 2026-10-21, and list each case that passes
on the old version but fails on the new one, with the error message.

O agente verifica o schema de cada payload antes de escrever qualquer coisa e, em seguida, executa os casos:

apidog environment create claude-api --project <id> --base-url https://api.anthropic.com
apidog cli-schema get test-case-create
apidog cli-schema validate test-case-create --file case.json
apidog test-case create --project <id> --file case.json
apidog run --test-case <caseId> --project <id> -e <envId> --env-var "anthropic_version=2023-06-01" -r cli,json
apidog run --test-case <caseId> --project <id> -e <envId> --env-var "anthropic_version=2026-10-21" -r cli,json

A flag --env-var troca o valor do header sem tocar no caso de teste, então o diff é uma única variável. Adicione --upload-report para visualizar ambas as execuções no aplicativo Apidog, ou coloque a execução da 2026-10-21 no CI com -r junit para que uma atualização de dependência não envie um campo temperature para produção. O guia do Apidog CLI no Claude Code aborda a configuração com mais detalhes, e a referência do apidog run lista todas as flags. O plano gratuito do Apidog cobre até 4 usuários.

A 2023-06-01 está descontinuada?

Nenhuma data de aposentadoria foi publicada. A página de versionamento lista a 2023-06-01 sem aviso de descontinuação, e o próprio guia de migração orienta a manter as requisições que precisam de um temperature não padrão na 2023-06-01. A Anthropic ainda recomenda a versão mais recente "sempre que possível".

Isso importa para o planejamento. A atualização de hoje é opcional, mas a 2026-10-21 é a primeira nova versão em mais de três anos, e futuras mudanças de quebra chegarão da mesma forma, então tratar testes de versão como uma rotina de CI agora é mais barato do que uma migração apressada depois. Se você já está ajustando seus limites de rate limits da API Claude ou de custo da API Claude, adicione a verificação de versão ao mesmo pipeline. Nosso guia sobre melhores práticas de versionamento de APIs explica por que versões baseadas em data, como esta, facilitam esse processo.

FAQ

Preciso atualizar para a versão 2026-10-21 da API Claude agora?

Não. A 2023-06-01 ainda funciona e não tem data de aposentadoria publicada. A atualização acontece quando você envia o novo header ou instala uma versão principal de SDK que a usa por padrão.

Por que minha requisição retorna 400 após uma atualização de SDK?

As novas versões principais dos SDKs enviam a 2026-10-21, que rejeita temperature, top_p e top_k, blocos document do lado do assistant e citations em blocos de texto de user. Verifique primeiro se há esses itens no seu payload.

Posso manter temperature em algumas requisições?

Sim, mantendo essas requisições específicas na 2023-06-01. Na versão 2026-10-21 não há nenhuma configuração substituta, e os modelos Claude 4.7 e posteriores só geram resultados com os valores padrão de qualquer forma.

A 2026-10-21 funciona no Amazon Bedrock?

Apenas para os modelos Claude 4.7 e posteriores. Modelos mais antigos no Bedrock exigem sua versão ou header atual do SDK até que você troque de modelo.

Meu proxy ainda verá minha chave de API?

Não, se ele lê X-Api-Key. Os novos SDKs enviam a chave como Authorization: Bearer. Atualize o proxy para ler Authorization, ou configure o SDK para enviar X-Api-Key você mesmo.

A nova versão altera os eventos de streaming?

A Anthropic não lista nenhuma mudança no formato de streaming para a 2026-10-21. O formato de streaming que você usa hoje veio com a 2023-06-01.