Claude Platform Docs
Referência da APISuporte e configuração

Migrando para a versão 2026-10-21 da API

Atualize uma integração com a Claude API da versão 2023-06-01 da API para a 2026-10-21: a versão do SDK a instalar e as alterações de código a fazer.

Este guia lista as alterações de código para migrar da versão 2023-06-01 da API para a 2026-10-21. As etapas de atualização dizem o que fazer, em ordem.

Etapas de atualização

  1. Mude para 2026-10-21

    Se você usa um SDK, suas requisições usam a versão da API que era a atual quando a versão principal do seu SDK foi lançada. As versões mostradas para a sua linguagem são as primeiras a usar 2026-10-21, então atualize para elas. Se você chama a API sem um SDK, defina o cabeçalho anthropic-version como 2026-10-21.

    Atualize o pacote anthropic para a versão 2.0.0.

    Lance a atualização junto com suas correções da próxima etapa.

  2. Atualize seu código para as alterações incompatíveis

    Percorra as alterações incompatíveis e atualize seu código para cada uma que afete você. Faça também as alterações de código de que a nova versão do SDK ou da CLI precisa.

  3. Teste com 2026-10-21

    Teste sua integração com 2026-10-21 antes de lançar.

Alterações incompatíveis

Messages API

Estas alterações se aplicam a requisições à Messages API (POST /v1/messages), à contagem de tokens e a cada requisição em um Message Batch criado com 2026-10-21.

Blocos de documento em mensagens do assistente retornam um erro

Afeta você se você envia blocos document diretamente em mensagens assistant.

Em 2026-10-21, uma requisição que coloca um bloco document diretamente em uma mensagem assistant retorna um erro 400. Envie documentos em mensagens user em vez disso. Um documento aninhado dentro de outro bloco, como um resultado da ferramenta de web fetch que Claude retornou, ainda é aceito.

Citações em mensagens do usuário retornam um erro

Afeta você se você envia citations em blocos text em mensagens user, inclusive dentro de blocos search_result.

Em 2026-10-21, uma requisição que envia um bloco text com um array citations não vazio em uma mensagem user retorna um erro 400. Remova citations desses blocos. Citações em blocos text em mensagens assistant, como respostas anteriores de Claude que você envia de volta, ainda são aceitas, assim como a configuração "citations": {"enabled": true} em documentos e resultados de pesquisa.

Os parâmetros de amostragem foram removidos

Afeta você se você envia temperature, top_p ou top_k em requisições de Messages ou de Message Batch.

Em 2026-10-21, uma requisição que envia temperature, top_p ou top_k retorna um erro 400, mesmo com o valor padrão do parâmetro.

Remova os três parâmetros das suas requisições.

A partir das versões principais mais recentes, o SDK e a CLI não têm mais os três parâmetros.

Sem esses parâmetros, uma requisição faz a amostragem com os valores padrão deles, incluindo uma temperature de 1.0, o mesmo que uma requisição 2023-06-01 que os omite. Modelos que já aceitam apenas os valores padrão, como Claude 4.7 e modelos posteriores, fazem a amostragem como antes. Em modelos que aceitam outros valores, como Claude Sonnet 4.6, uma requisição que reduzia temperature para obter uma saída mais consistente perde esse efeito. Nenhuma outra configuração o substitui. Se uma requisição depende de um valor não padrão, pare de enviar o parâmetro ou mantenha essa requisição em 2023-06-01.

Admin API e Claude Enterprise Analytics API

Afeta você se seu código lê os campos de resposta da Admin API ou da Claude Enterprise Analytics API nas tabelas a seguir.

Em 2026-10-21, as respostas da Admin API e da Claude Enterprise Analytics API não incluem mais os nomes antigos dos campos renomeados. Use os novos nomes em vez disso.

Admin API:

EndpointsNome antigoNome novo
Grupos RBAC: criar, listar, recuperar e atualizarrolesrole_ids
Membros de grupos RBAC: listar e adicionar, e a resposta à remoção de um membrogroup_idrbac_group_id
Funções RBAC: listar e recuperarnamedisplay_name
Limites de taxa da organização e do workspace: listar, e a resposta à definição dos limites de taxa de um workspacegroup_typegroup.type
Chaves de API: listar, recuperar e atualizarworkspace_idscope (valores diferentes; consulte workspace_id em chaves de API)

Claude Enterprise Analytics API:

EndpointsNome antigoNome novo
Relatórios de uso e de custo por usuárioactor.emailactor.email_address
Resumos de atividadesummariesdata

O parâmetro de consulta group_type nos endpoints de listagem de limites de taxa e o filtro workspace_id no endpoint de listagem de chaves de API não mudaram.

workspace_id em chaves de API

Afeta você se seu código lê workspace_id em chaves de API.

Em 2023-06-01, o workspace_id de uma chave de API é o ID do workspace ao qual a chave está vinculada, ou null para uma chave vinculada ao Default Workspace e para uma chave que não está vinculada a um único workspace (uma chave de todos os workspaces).

Em 2026-10-21, workspace_id foi removido. Leia scope em vez disso: para uma chave vinculada a um workspace, incluindo o Default Workspace, scope.workspace_id é o ID real desse workspace, e uma chave de todos os workspaces tem um scope de {"type": "organization"}, sem workspace_id.

Se seu código tratava um workspace_id null como o Default Workspace, compare scope.workspace_id com o ID do seu Default Workspace em vez disso. Para encontrar esse ID, chame List Workspaces com include_default=true e pegue o workspace chamado "Default".

Alterações no SDK e na CLI

As versões anteriores do SDK e da CLI enviavam anthropic-version: 2023-06-01 em cada requisição. As versões em Mude para 2026-10-21 enviam 2026-10-21. As alterações em Alterações incompatíveis também se aplicam a elas: os parâmetros removidos e os nomes de campos antigos também deixaram de existir nos tipos do SDK e nas flags e na saída da CLI.

Versão da API no Amazon Bedrock e no Google Cloud

O cliente do SDK para o Google Cloud's Agent Platform indica a versão no corpo da requisição em vez de em um cabeçalho. Ele envia anthropic_version: 2026-10-21, onde as versões anteriores enviavam vertex-2023-10-16, e nenhum cabeçalho anthropic-version.

O cliente do Amazon Bedrock faz o mesmo. Ele envia anthropic_version: 2026-10-21, onde as versões anteriores enviavam bedrock-2023-05-31, e nenhum cabeçalho anthropic-version. Modelos mais antigos que o Claude Opus 4.7 ainda não suportam a versão 2026-10-21 da API no Bedrock, e uma requisição que a indique pode receber um erro 400. Se você usa um deles, permaneça na versão anterior do SDK por enquanto, ou atualize e envie bedrock-2023-05-31 você mesmo.

Isso se aplica a AnthropicVertex, AsyncAnthropicVertex, AnthropicBedrock e AsyncAnthropicBedrock.

Para enviar bedrock-2023-05-31, passe extra_body={"anthropic_version": "bedrock-2023-05-31"} em cada requisição.

MessageParam é uma união com um tipo por função

Nas versões anteriores, MessageParam era um único tipo para todas as funções. Cada função agora tem um tipo próprio: UserMessageParam, AssistantMessageParam e SystemMessageParam. BetaMessageParam é dividido da mesma forma, em BetaUserMessageParam, BetaAssistantMessageParam e BetaSystemMessageParam. As requisições que o SDK envia têm os mesmos campos e valores de antes.

Uma mensagem escrita como um literal de dict, como {"role": "user", "content": "Hello"}, não precisa de alteração.

Na v1, anthropic.types.MessageParam era um único TypedDict. Na v2 é uma união dos três tipos, e anthropic.types.beta.BetaMessageParam é uma união dos seus três. Ambos os nomes ainda funcionam em anotações, como list[MessageParam].

Chamar qualquer um dos nomes agora gera um TypeError, e um verificador de tipos o sinaliza. Escreva a mensagem como um dict:

# Antes
message = MessageParam(role="user", content="Hello")

# Depois
message: MessageParam = {"role": "user", "content": "Hello"}

Criar uma subclasse de qualquer um dos nomes também gera um TypeError. Crie uma subclasse do tipo da função, como UserMessageParam.

As alterações restantes afetam apenas a verificação de tipos. Um dict cujo role é uma variável que pode conter mais de uma função não corresponde a nenhum tipo da união, então construa o dict para uma função de cada vez:

# Antes
def to_message(role: Literal["user", "assistant"], text: str) -> MessageParam:
    return {"role": role, "content": text}


# Depois
def to_message(role: Literal["user", "assistant"], text: str) -> MessageParam:
    if role == "user":
        return {"role": "user", "content": text}
    return {"role": "assistant", "content": text}

Mais duas se aplicam apenas a BetaMessageParam:

  • clear_at e output_config são chaves de BetaSystemMessageParam, então uma mensagem de usuário ou de assistente não pode tê-las.
  • content é opcional em BetaSystemMessageParam, então o pyright reporta message["content"]. Leia-o com message.get("content"), ou verifique primeiro que message["role"] não é "system".

Enums de um único valor são constantes

Isso afeta os SDKs de C#, Go, Java, PHP e Ruby e uma flag da CLI. Em versões anteriores, um campo obrigatório que só pode conter um valor tinha um tipo "enum" (enumeração) próprio com um único membro. Esses campos agora são constantes, e os tipos enum deixaram de existir. O JSON que o SDK envia e lê é o mesmo.

--type é opcional em ant beta:sessions:resources add. file é o único valor que --type pode assumir ali, então a v2 o envia por você. Comandos que ainda passam --type file continuam funcionando, então não há nada a mudar.

A compactação do lado do cliente foi removida do tool runner

Isso afeta os SDKs de TypeScript e Ruby. A "client-side compaction" (compactação do lado do cliente) no "tool runner" (executor de ferramentas) foi removida em favor da compactação do lado do servidor, que resume a conversa dentro da API em vez de com uma requisição extra do cliente.

A opção compactionControl e o módulo @anthropic-ai/sdk/lib/tools/CompactionControl deixaram de existir. A opção parou de funcionar na v0.129.0, em que passá-la lançava um AnthropicError. Ela não está no tipo de parâmetros, então o TypeScript a reporta como uma propriedade desconhecida.

Para continuar compactando automaticamente em um limite de tokens:

// Antes
const runner = client.beta.messages.toolRunner({
  // ...
  compactionControl: { enabled: true, contextTokenThreshold: 100_000 }
});

// Depois
const runner = client.beta.messages.toolRunner({
  // ...
  betas: ["compact-2026-01-12"],
  context_management: {
    edits: [{ type: "compact_20260112", trigger: { type: "input_tokens", value: 100_000 } }]
  }
});

Para decidir você mesmo quando a conversa é compactada, chame runner.compactBeforeNextTurn().

O limite de acionamento deve ser de pelo menos 50.000 tokens. Consulte compactação para as outras opções (pause_after_compaction, instructions personalizadas).

Text Completions foi removida

A API legado de Text Completions foi removida dos SDKs de TypeScript, Go, Java e Ruby e da CLI. Modelos e recursos mais recentes não a suportam. Use a Messages API em vez disso.

O comando ant completions create deixou de existir.

# Antes
ant completions create \
  --model "$MODEL" \
  --max-tokens-to-sample 1024 \
  --prompt $'\n\nHuman: Hello, Claude\n\nAssistant:'

# Depois
ant messages create \
  --model "$MODEL" \
  --max-tokens 1024 \
  --message '{role: user, content: "Hello, Claude"}'

O texto da resposta passa do campo completion para content.0.text, então um script que passava --transform completion passa --transform content.0.text em vez disso.

ant messages create também aceita --stream, mas seus eventos têm outro formato: o texto chega em delta.text de eventos content_block_delta, então --transform content.0.text não se aplica a um stream.

betas foi removido dos métodos não beta de Models

Os métodos não beta de Models não recebem mais betas, e os comandos ant models não aceitam mais --beta. Para enviar cabeçalhos beta, chame os mesmos métodos em client.beta.models, ou ant beta:models na CLI. No SDK, esses métodos retornam BetaModelInfo onde os não beta retornam ModelInfo.

client.models.retrieve() e client.models.list() não recebem mais betas (passá-lo gera um TypeError, e um verificador de tipos o sinaliza), e anthropic.types.ModelListParams não tem mais uma chave betas.

# Antes
page = client.models.list(betas=[beta])

# Depois
page = client.beta.models.list(betas=[beta])

Chaves de API são enviadas como Authorization: Bearer

O SDK e a CLI enviam sua chave de API como Authorization: Bearer <key> em vez de no cabeçalho X-Api-Key, então altere qualquer proxy ou gateway que leia ou defina X-Api-Key para usar Authorization, ou envie você mesmo a chave em X-Api-Key. A Claude API aceita uma chave em qualquer um dos cabeçalhos, então um programa que se comunica diretamente com a API não precisa de nenhuma alteração.

# Before
X-Api-Key: <key>

# After
Authorization: Bearer <key>

Authorization é o cabeçalho que auth_token já usa.

Isso se aplica ao argumento api_key e à variável de ambiente ANTHROPIC_API_KEY de Anthropic e AsyncAnthropic, e a api_key e ANTHROPIC_AWS_API_KEY de AnthropicAWS. AnthropicFoundry ainda envia sua chave como x-api-key, e AnthropicBedrockMantle já enviava um bearer token.

Se um proxy ou gateway lê X-Api-Key

Mova a chave de volta com uma função auth no cliente HTTP. Ela é executada em toda requisição que o cliente envia, incluindo novas tentativas:

import httpx2
from anthropic import Anthropic, DefaultHttpxClient


def send_x_api_key(request: httpx2.Request) -> httpx2.Request:
    if request.headers.get("Authorization") == f"Bearer {api_key}":
        del request.headers["Authorization"]
        request.headers["X-Api-Key"] = api_key
    return request


client = Anthropic(api_key=api_key, http_client=DefaultHttpxClient(auth=send_x_api_key))

AsyncAnthropic recebe a mesma função, em http_client=DefaultAsyncHttpxClient(auth=send_x_api_key).

Se você definia ou removia X-Api-Key em uma requisição

Isso afeta os SDKs de Python, TypeScript, Go, PHP e Ruby.

Se você removia X-Api-Key para que uma requisição enviasse apenas um token de autenticação, exclua esse código em vez de alterá-lo, porque remover Authorization removeria o token. Um cliente mantém uma única credencial, então certifique-se de que seja o token: sem nenhuma passada no código e com ANTHROPIC_API_KEY e ANTHROPIC_AUTH_TOKEN ambas definidas, o cliente usa a chave.

Código que passa extra_headers={"X-Api-Key": omit} para manter a chave fora de uma requisição não faz mais isso. Passe extra_headers={"Authorization": omit} em vez disso.

extra_headers={"X-Api-Key": other_key} não substitui mais a chave do cliente: ambas as chaves são enviadas. Para enviar outra chave com uma requisição, passe extra_headers={"Authorization": f"Bearer {other_key}"}.

Um cliente mantém uma credencial

Uma chave de API e um token de autenticação agora compartilham um cabeçalho, então um cliente do SDK mantém uma credencial. Sem nenhuma passada no código, ele segue a ordem de precedência de credenciais.

A v1 enviava tanto uma chave de API quanto um token de autenticação quando o cliente tinha ambos, cada um em seu próprio cabeçalho. A credencial é uma de api_key, auth_token, credentials, config ou profile.

  • Passe no máximo uma. Duas ou mais no construtor, ou em uma chamada de copy() ou with_options(), geram ValueError. None não conta. A v1 gerava TypeError, e apenas para duas de credentials, config e profile.
  • A que você passa é a única. Como na v1, o cliente não procura outra no ambiente ou no disco.
  • Sem nenhuma passada, apenas a primeira destas que estiver definida é usada: ANTHROPIC_API_KEY, ANTHROPIC_AUTH_TOKEN, o perfil que ANTHROPIC_PROFILE nomeia, as variáveis de federação de identidade de carga de trabalho, o perfil ativo no disco (aquele que o arquivo active_config nomeia, caso contrário default). Quando as duas primeiras estão definidas, o cliente registra um aviso uma vez. A v1 usava o perfil ativo antes das variáveis de federação quando ANTHROPIC_CONFIG_DIR estava definida ou um arquivo active_config existia; defina ANTHROPIC_PROFILE para continuar usando-o.
  • copy() e with_options() substituem. Uma credencial que você passa substitui a do próprio cliente, seja qual for o tipo de cada uma. Uma URL base e cabeçalhos que vieram da config ou do perfil da credencial antiga vão junto com ela, e os da nova credencial são usados. Uma URL base que você passou permanece.
client = Anthropic(api_key=key, auth_token=token)

# Antes: enviava `X-Api-Key: <key>` e `Authorization: Bearer <token>`
# Depois: lança `ValueError`

Os clientes de plataforma mantêm suas próprias regras. AnthropicAWS aceita auth_token junto com api_key sem erro, e envia a chave.

As docstrings de Anthropic.__init__ e Anthropic.copy em _client.py têm os detalhes.

Se você dependia de enviar ambos, por exemplo um token para um gateway e uma chave para a API por trás dele, passe o token como auth_token e defina X-Api-Key em default_headers. Faça o gateway remover seu cabeçalho Authorization antes de encaminhar a requisição. A Claude API espera uma credencial por requisição.

Mudanças em um SDK ou na CLI

Cada uma destas mudanças afeta um SDK ou a CLI.

--api-key e --auth-token foram removidos. ant não aceita mais uma chave de API ou token de autenticação como valor de flag, porque um valor na linha de comando fica visível no histórico do shell e nas listagens de processos. Ambas as flags exibem um aviso de descontinuação desde a v1.27.0. Um comando que ainda passa uma delas para com flag provided but not defined.

RemovidoUse em vez disso
--api-key <key>ANTHROPIC_API_KEY, --api-key-stdin ou ant auth login
--auth-token <token>ANTHROPIC_AUTH_TOKEN ou --auth-token-stdin
# Antes
ant --api-key "$KEY" models list

# Depois, a partir do ambiente
export ANTHROPIC_API_KEY="$KEY"
ant models list

# Depois, a partir de um gerenciador de segredos
op read op://vault/anthropic/api-key | ant --api-key-stdin models list

--api-key-stdin e --auth-token-stdin leem toda a entrada padrão, então um comando que usa uma delas obtém o corpo da requisição a partir de flags.

ant auth status, o prompt de primeira execução de ant apply e a nota sobre múltiplas fontes de autenticação agora chamam essas credenciais de ANTHROPIC_API_KEY e ANTHROPIC_AUTH_TOKEN, onde antes exibiam --api-key / ANTHROPIC_API_KEY e --auth-token / ANTHROPIC_AUTH_TOKEN.

A licença é Apache 2.0

A partir destas versões, o SDK e a CLI são licenciados sob a Apache License, Version 2.0. Versões anteriores permanecem sob a MIT License. Nenhuma alteração de código é necessária. Se você acompanha as licenças de suas dependências, atualize as entradas delas.

  • TypeScript: Os pacotes de plataforma (@anthropic-ai/bedrock-sdk, @anthropic-ai/vertex-sdk, @anthropic-ai/foundry-sdk, @anthropic-ai/aws-sdk e @anthropic-ai/google-cloud-sdk) mudam de licença em suas próprias versões 1.0.0.
  • C#: Os outros pacotes (Anthropic.Bedrock, Anthropic.Vertex, Anthropic.Foundry, Anthropic.Aws, Anthropic.GoogleCloud e Anthropic.Mcp) mudam de licença em suas próprias versões 1.0.0.
  • Java: A mudança abrange todos os artefatos com.anthropic.

Was this page helpful?