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:
| Versão | O que introduziu |
|---|---|
2023-01-01 |
Lançamento inicial |
2023-06-01 |
Eventos de streaming server-sent incrementais e nomeados; removeu o evento data: [DONE] e os valores legados exception e truncated
|
2026-10-21 |
Removeu parâmetros de amostragem, regras mais rígidas para conteúdo de mensagens e renomeou campos de Admin e Analytics |
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:
| Endpoint | Campo antigo | Novo campo |
|---|---|---|
| Grupos RBAC | roles |
role_ids |
| Membros de grupos RBAC | group_id |
rbac_group_id |
| Papéis RBAC | name |
display_name |
| Limites de taxa de organização e workspace | group_type |
group.type |
| Chaves de API | workspace_id |
scope.workspace_id |
| Relatórios de uso e custo por usuário do Analytics | actor.email |
actor.email_address |
| Resumos de atividade do Analytics | summaries |
data |
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:
| SDK | Primeira versão na 2026-10-21 |
|---|---|
Python (anthropic) |
2.0.0 |
TypeScript (@anthropic-ai/sdk) |
1.0.0 |
Go (anthropic-sdk-go/v2) |
2.0.0 |
Java (anthropic-java) |
3.0.0 |
C# (Anthropic) |
13.0.0 |
PHP (anthropic-ai/sdk) |
1.0.0 |
Ruby (anthropic) |
2.0.0 |
CLI ant
|
2.0.0 |
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 deX-Api-Key. A API Claude aceita ambas, mas um proxy, gateway, filtro de log ou stub de teste que lêX-Api-Keynão verá mais a chave. - Text Completions foi removida dos SDKs TypeScript, Go, Java e Ruby e da CLI. Use a API de Mensagens.
-
betasfoi removido dos métodos de Models não beta. Useclient.beta.modelsem 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.
-
Fixe a versão principal antiga do SDK. Por exemplo,
anthropic<2no Python ou"@anthropic-ai/sdk": "^0"no npm. -
Procure no seu código e configurações por
temperature,top_p,top_k,X-Api-Key,completions.createe qualquer campo da Admin API da tabela acima. - 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.
-
Corrija a construção das mensagens. Mova documentos do lado do assistant para turnos de user e remova
citationsdos blocos de texto de user. - Teste os mesmos payloads nas duas versões e compare os códigos de status e as formas das respostas.
- 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-[REDACTED CREDENTIAL] \
-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 [REDACTED PROMPT]
In Apidog project , 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:
bash
apidog environment create claude-api --project --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 --file case.json
apidog run --test-case --project -e --env-var "anthropic_version=2023-06-01" -r cli,json
apidog run --test-case --project -e --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](https://apidog.com/pt/blog/apidog-cli-in-claude-code?utm_source=dev.to&utm_medium=wanda&utm_content=n8n-post-automation) aborda a configuração com mais detalhes, e a [referência do `apidog run`](https://apidog.com/pt/blog/apidog-run-command-reference?utm_source=dev.to&utm_medium=wanda&utm_content=n8n-post-automation) 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](https://apidog.com/pt/blog/claude-api-rate-limits?utm_source=dev.to&utm_medium=wanda&utm_content=n8n-post-automation) ou de [custo da API Claude](https://apidog.com/pt/blog/claude-api-cost?utm_source=dev.to&utm_medium=wanda&utm_content=n8n-post-automation), adicione a verificação de versão ao mesmo pipeline. Nosso guia sobre [melhores práticas de versionamento de APIs](https://apidog.com/pt/blog/api-versioning-best-practices?utm_source=dev.to&utm_medium=wanda&utm_content=n8n-post-automation) 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 `[REDACTED CREDENTIAL] 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.
Top comments (0)