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). Experimente o Apidog hoje 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 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. Fixe a versão principal antiga do SDK. Por exemplo, anthropic