Claude Platform Docs
Referencia de la APISoporte y configuración

Migración a la versión de API 2026-10-21

Actualiza una integración con la API de Claude de la versión de API 2023-06-01 a la 2026-10-21: la versión del SDK que debes instalar y los cambios de código que debes hacer.

Esta guía enumera los cambios de código necesarios para pasar de la versión de API 2023-06-01 a la 2026-10-21. Los pasos de actualización indican qué hacer, en orden.

Pasos de actualización

  1. Cambia a 2026-10-21

    Si usas un SDK, tus solicitudes usan la versión de API que estaba vigente cuando se publicó la versión principal de tu SDK. Las versiones que se muestran para tu lenguaje son las primeras que usan 2026-10-21, así que actualiza a ellas. Si llamas a la API sin un SDK, establece el encabezado anthropic-version en 2026-10-21.

    Actualiza el paquete anthropic a la versión 2.0.0.

    Publica la actualización junto con tus correcciones del siguiente paso.

  2. Actualiza tu código para los cambios incompatibles

    Revisa los cambios incompatibles y actualiza tu código para cada uno que te afecte. Haz también los cambios de código que necesita la nueva versión del SDK o de la CLI.

  3. Prueba con 2026-10-21

    Prueba tu integración con 2026-10-21 antes de publicarla.

Cambios incompatibles

Messages API

Estos cambios se aplican a las solicitudes a la Messages API (POST /v1/messages), al conteo de tokens y a cada solicitud de un Message Batch creado con 2026-10-21.

Los bloques de documento en mensajes del asistente devuelven un error

Te afecta si envías bloques document directamente en mensajes assistant.

En 2026-10-21, una solicitud que coloca un bloque document directamente en un mensaje assistant devuelve un error 400. Envía los documentos en mensajes user en su lugar. Un documento anidado dentro de otro bloque, como un resultado de la herramienta de web fetch que Claude devolvió, se sigue aceptando.

Las citas en mensajes del usuario devuelven un error

Te afecta si envías citations en bloques text dentro de mensajes user, incluso dentro de bloques search_result.

En 2026-10-21, una solicitud que envía un bloque text con un arreglo citations no vacío en un mensaje user devuelve un error 400. Quita citations de esos bloques. Las citas en bloques text de mensajes assistant, como las respuestas anteriores de Claude que vuelves a enviar, se siguen aceptando, al igual que la configuración "citations": {"enabled": true} en documentos y resultados de búsqueda.

Se eliminan los parámetros de muestreo

Te afecta si envías temperature, top_p o top_k en solicitudes de Messages o de Message Batch.

En 2026-10-21, una solicitud que envía temperature, top_p o top_k devuelve un error 400, incluso con el valor predeterminado del parámetro.

Quita los tres parámetros de tus solicitudes.

A partir de las últimas versiones principales, el SDK y la CLI ya no tienen los tres parámetros.

Sin estos parámetros, una solicitud realiza el muestreo con sus valores predeterminados, incluida una temperature de 1.0, igual que una solicitud 2023-06-01 que los omite. Los modelos que ya aceptan solo los valores predeterminados, como Claude 4.7 y los modelos posteriores, realizan el muestreo como antes. En los modelos que aceptan otros valores, como Claude Sonnet 4.6, una solicitud que reducía temperature para obtener una salida más consistente pierde ese efecto. Ninguna otra configuración lo reemplaza. Si una solicitud depende de un valor no predeterminado, deja de enviar el parámetro o mantén esa solicitud en 2023-06-01.

Admin API y Claude Enterprise Analytics API

Te afecta si tu código lee los campos de respuesta de la Admin API o de la Claude Enterprise Analytics API que aparecen en las siguientes tablas.

En 2026-10-21, las respuestas de la Admin API y de la Claude Enterprise Analytics API ya no incluyen los nombres antiguos de los campos renombrados. Usa los nombres nuevos en su lugar.

Admin API:

EndpointsNombre antiguoNombre nuevo
Grupos RBAC: crear, listar, recuperar y actualizarrolesrole_ids
Miembros de grupos RBAC: listar y agregar, y la respuesta a quitar un miembrogroup_idrbac_group_id
Roles RBAC: listar y recuperarnamedisplay_name
"Rate limits" (límites de velocidad) de la organización y del espacio de trabajo: listar, y la respuesta a establecer los límites de velocidad de un espacio de trabajogroup_typegroup.type
Claves de API: listar, recuperar y actualizarworkspace_idscope (valores diferentes; consulta workspace_id en las claves de API)

Claude Enterprise Analytics API:

EndpointsNombre antiguoNombre nuevo
Informes por usuario de uso y de costoactor.emailactor.email_address
Resúmenes de actividadsummariesdata

El parámetro de consulta group_type en los endpoints de listado de límites de velocidad y el filtro workspace_id en el endpoint de listado de claves de API no cambian.

workspace_id en las claves de API

Te afecta si tu código lee workspace_id en las claves de API.

En 2023-06-01, el workspace_id de una clave de API es el ID del espacio de trabajo al que está vinculada la clave, o null para una clave vinculada al Default Workspace y para una clave que no está vinculada a un solo espacio de trabajo (una clave para todos los espacios de trabajo).

En 2026-10-21, se elimina workspace_id. Lee scope en su lugar: para una clave vinculada a un espacio de trabajo, incluido el Default Workspace, scope.workspace_id es el ID real de ese espacio de trabajo, y una clave para todos los espacios de trabajo tiene un scope de {"type": "organization"}, sin workspace_id.

Si tu código trataba un workspace_id null como el Default Workspace, compara scope.workspace_id con el ID de tu Default Workspace en su lugar. Para encontrar ese ID, llama a List Workspaces con include_default=true y toma el espacio de trabajo llamado "Default".

Cambios en el SDK y la CLI

Las versiones anteriores del SDK y de la CLI enviaban anthropic-version: 2023-06-01 con cada solicitud. Las versiones indicadas en Cambia a 2026-10-21 envían 2026-10-21. Los cambios de Cambios incompatibles también se aplican a ellas: los parámetros eliminados y los nombres de campo antiguos también desaparecen de los tipos del SDK y de las flags y la salida de la CLI.

Versión de API en Amazon Bedrock y Google Cloud

El cliente del SDK para Google Cloud's Agent Platform indica la versión en el cuerpo de la solicitud en lugar de en un encabezado. Envía anthropic_version: 2026-10-21, donde las versiones anteriores enviaban vertex-2023-10-16, y ningún encabezado anthropic-version.

El cliente de Amazon Bedrock hace lo mismo. Envía anthropic_version: 2026-10-21, donde las versiones anteriores enviaban bedrock-2023-05-31, y ningún encabezado anthropic-version. Los modelos anteriores a Claude Opus 4.7 todavía no admiten la versión de API 2026-10-21 en Bedrock, y una solicitud que la indique podría recibir un error 400. Si usas uno de ellos, quédate por ahora en la versión anterior del SDK, o actualiza y envía bedrock-2023-05-31 tú mismo.

Esto se aplica a AnthropicVertex, AsyncAnthropicVertex, AnthropicBedrock y AsyncAnthropicBedrock.

Para enviar bedrock-2023-05-31, pasa extra_body={"anthropic_version": "bedrock-2023-05-31"} con cada solicitud.

MessageParam es una unión con un tipo por rol

En versiones anteriores, MessageParam era un solo tipo para todos los roles. Ahora cada rol tiene su propio tipo: UserMessageParam, AssistantMessageParam y SystemMessageParam. BetaMessageParam se divide de la misma manera, en BetaUserMessageParam, BetaAssistantMessageParam y BetaSystemMessageParam. Las solicitudes que envía el SDK tienen los mismos campos y valores que antes.

Un mensaje escrito como un literal de dict, como {"role": "user", "content": "Hello"}, no necesita cambios.

En v1, anthropic.types.MessageParam era un solo TypedDict. En v2 es una unión de los tres tipos, y anthropic.types.beta.BetaMessageParam es una unión de sus tres tipos. Ambos nombres siguen funcionando en anotaciones, como list[MessageParam].

Llamar a cualquiera de los dos nombres ahora genera un TypeError, y un verificador de tipos lo señala. Escribe el mensaje como un dict:

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

# Después
message: MessageParam = {"role": "user", "content": "Hello"}

Crear una subclase de cualquiera de los dos nombres también genera un TypeError. Crea una subclase del tipo del rol, como UserMessageParam.

Los cambios restantes solo afectan a la verificación de tipos. Un dict cuyo role es una variable que puede contener más de un rol no coincide con ningún tipo de la unión, así que construye el dict para un rol a la vez:

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


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

Dos más se aplican solo a BetaMessageParam:

  • clear_at y output_config son claves de BetaSystemMessageParam, por lo que un mensaje de usuario o de asistente no puede tenerlas.
  • content es opcional en BetaSystemMessageParam, por lo que pyright señala message["content"]. Léelo con message.get("content"), o comprueba primero que message["role"] no sea "system".

Los enums de un solo valor son constantes

Esto afecta a los SDK de C#, Go, Java, PHP y Ruby y a una opción de la CLI. En versiones anteriores, un campo obligatorio que solo puede contener un valor tenía su propio tipo enum con un único miembro. Estos campos ahora son constantes y los tipos enum ya no existen. El JSON que el SDK envía y lee es el mismo.

--type es opcional en ant beta:sessions:resources add. file es el único valor que --type puede tomar ahí, así que v2 lo envía por ti. Los comandos que todavía pasan --type file siguen funcionando, así que no hay nada que cambiar.

La compactación del lado del cliente se eliminó del tool runner

Esto afecta a los SDK de TypeScript y Ruby. La "client-side compaction" (compactación del lado del cliente) en el "tool runner" (ejecutor de herramientas) se eliminó en favor de la compactación del lado del servidor, que resume la conversación dentro de la API en lugar de hacerlo con una solicitud adicional desde el cliente.

La opción compactionControl y el módulo @anthropic-ai/sdk/lib/tools/CompactionControl ya no existen. La opción dejó de funcionar en v0.129.0, donde pasarla lanzaba un AnthropicError. No está en el tipo de parámetros, así que TypeScript la reporta como una propiedad desconocida.

Para seguir compactando automáticamente al alcanzar un umbral de tokens:

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

// Después
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 tú mismo cuándo se compacta la conversación, llama a runner.compactBeforeNextTurn().

El umbral de activación debe ser de al menos 50,000 tokens. Consulta compactación para ver las demás opciones (pause_after_compaction, instructions personalizadas).

Text Completions se eliminó

La API heredada de Text Completions se eliminó de los SDK de TypeScript, Go, Java y Ruby y de la CLI. Los modelos y funciones más recientes no la admiten. Usa la API de Messages en su lugar.

El comando ant completions create ya no existe.

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

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

El texto de la respuesta pasa del campo completion a content.0.text, así que un script que pasaba --transform completion ahora pasa --transform content.0.text.

ant messages create también acepta --stream, pero sus eventos tienen otra forma: el texto llega en delta.text de los eventos content_block_delta, así que --transform content.0.text no se aplica a un stream.

betas se eliminó de los métodos de Models que no son beta

Los métodos de Models que no son beta ya no aceptan betas, y los comandos ant models ya no aceptan --beta. Para enviar encabezados beta, llama a los mismos métodos en client.beta.models, o a ant beta:models en la CLI. En el SDK, esos métodos devuelven BetaModelInfo donde los que no son beta devuelven ModelInfo.

client.models.retrieve() y client.models.list() ya no aceptan betas (pasarlo produce un TypeError, y un verificador de tipos lo señala), y anthropic.types.ModelListParams ya no tiene una clave betas.

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

# Después
page = client.beta.models.list(betas=[beta])

Las claves de API se envían como Authorization: Bearer

El SDK y la CLI envían tu clave de API como Authorization: Bearer <key> en lugar de en el encabezado X-Api-Key, así que cambia cualquier proxy o gateway que lea o establezca X-Api-Key para que use Authorization, o envía tú mismo la clave en X-Api-Key. La API de Claude acepta una clave en cualquiera de los dos encabezados, así que un programa que se comunica directamente con la API no necesita cambios.

# Before
X-Api-Key: <key>

# After
Authorization: Bearer <key>

Authorization es el encabezado que auth_token ya usa.

Esto se aplica al argumento api_key y a la variable de entorno ANTHROPIC_API_KEY de Anthropic y AsyncAnthropic, y a api_key y ANTHROPIC_AWS_API_KEY de AnthropicAWS. AnthropicFoundry sigue enviando su clave como x-api-key, y AnthropicBedrockMantle ya enviaba un token bearer.

Si un proxy o gateway lee X-Api-Key

Vuelve a mover la clave con una función auth en el cliente HTTP. Se ejecuta en cada solicitud que envía el cliente, incluidos los reintentos:

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 acepta la misma función, en http_client=DefaultAsyncHttpxClient(auth=send_x_api_key).

Si establecías o eliminabas X-Api-Key en una solicitud

Esto afecta a los SDK de Python, TypeScript, Go, PHP y Ruby.

Si eliminabas X-Api-Key para que una solicitud enviara solo un token de autenticación, borra ese código en lugar de cambiarlo, porque eliminar Authorization eliminaría el token. Un cliente contiene una sola credencial, así que asegúrate de que sea el token: si no se pasa ninguna en el código y están definidas tanto ANTHROPIC_API_KEY como ANTHROPIC_AUTH_TOKEN, el cliente usa la clave.

El código que pasa extra_headers={"X-Api-Key": omit} para mantener la clave fuera de una solicitud ya no lo consigue. Pasa extra_headers={"Authorization": omit} en su lugar.

extra_headers={"X-Api-Key": other_key} ya no reemplaza la clave del cliente: se envían ambas claves. Para enviar otra clave con una solicitud, pasa extra_headers={"Authorization": f"Bearer {other_key}"}.

Un cliente tiene una sola credencial

Una clave de API y un token de autenticación ahora comparten un encabezado, por lo que un cliente del SDK tiene una sola credencial. Si no se pasa ninguna en el código, sigue el orden de precedencia de credenciales.

v1 enviaba tanto una clave de API como un token de autenticación cuando el cliente tenía ambos, cada uno en su propio encabezado. La credencial es una de api_key, auth_token, credentials, config o profile.

  • Pasa como máximo una. Dos o más en el constructor, o en una sola llamada a copy() o with_options(), generan ValueError. None no cuenta. v1 generaba TypeError, y solo para dos de credentials, config y profile.
  • La que pasas es la única. Como en v1, el cliente no busca otra en el entorno ni en el disco.
  • Si no pasas ninguna, solo se usa la primera de estas que esté definida: ANTHROPIC_API_KEY, ANTHROPIC_AUTH_TOKEN, el perfil que nombra ANTHROPIC_PROFILE, las variables de federación de identidad de cargas de trabajo, el perfil activo en el disco (el que nombra el archivo active_config, o en su defecto default). Cuando las dos primeras están definidas, el cliente registra una advertencia una vez. v1 usaba el perfil activo antes que las variables de federación cuando ANTHROPIC_CONFIG_DIR estaba definida o existía un archivo active_config; define ANTHROPIC_PROFILE para seguir usándolo.
  • copy() y with_options() reemplazan. Una credencial que pasas reemplaza la del cliente, sea del tipo que sea cualquiera de las dos. Una URL base y encabezados que provenían de la configuración o el perfil de la credencial anterior se van con ella, y se usan los de la nueva credencial. Una URL base que pasaste se mantiene.
client = Anthropic(api_key=key, auth_token=token)

# Antes: enviaba `X-Api-Key: <key>` y `Authorization: Bearer <token>`
# Después:  genera `ValueError`

Los clientes de plataforma mantienen sus propias reglas. AnthropicAWS acepta auth_token junto a api_key sin error, y envía la clave.

Los docstrings de Anthropic.__init__ y Anthropic.copy en _client.py tienen los detalles.

Si dependías de enviar ambos, por ejemplo un token para un gateway y una clave para la API detrás de él, pasa el token como auth_token y define X-Api-Key en default_headers. Haz que el gateway elimine su encabezado Authorization antes de reenviar la solicitud. La API de Claude espera una credencial por solicitud.

Cambios en un SDK o en la CLI

Cada uno de estos cambios afecta a un SDK o a la CLI.

Se eliminan --api-key y --auth-token. ant ya no acepta una clave de API ni un token de autenticación como valor de un flag, porque un valor en la línea de comandos es visible en el historial del shell y en los listados de procesos. Ambos flags han mostrado una advertencia de obsolescencia desde v1.27.0. Un comando que todavía pase uno se detiene con flag provided but not defined.

EliminadoUsa en su lugar
--api-key <key>ANTHROPIC_API_KEY, --api-key-stdin o ant auth login
--auth-token <token>ANTHROPIC_AUTH_TOKEN o --auth-token-stdin
# Antes
ant --api-key "$KEY" models list

# Después, desde el entorno
export ANTHROPIC_API_KEY="$KEY"
ant models list

# Después, desde un gestor de secretos
op read op://vault/anthropic/api-key | ant --api-key-stdin models list

--api-key-stdin y --auth-token-stdin leen toda la entrada estándar, por lo que un comando que use uno de ellos toma el cuerpo de su solicitud de los flags.

ant auth status, el aviso de primera ejecución de ant apply y la nota sobre múltiples fuentes de autenticación ahora llaman a estas credenciales ANTHROPIC_API_KEY y ANTHROPIC_AUTH_TOKEN, donde antes mostraban --api-key / ANTHROPIC_API_KEY y --auth-token / ANTHROPIC_AUTH_TOKEN.

La licencia es Apache 2.0

A partir de estas versiones, el SDK y la CLI tienen licencia Apache License, Version 2.0. Las versiones anteriores siguen bajo la MIT License. No se necesitan cambios en el código. Si llevas un registro de las licencias de tus dependencias, actualiza sus entradas.

  • TypeScript: Los paquetes de plataforma (@anthropic-ai/bedrock-sdk, @anthropic-ai/vertex-sdk, @anthropic-ai/foundry-sdk, @anthropic-ai/aws-sdk y @anthropic-ai/google-cloud-sdk) cambian de licencia en sus propias versiones 1.0.0.
  • C#: Los demás paquetes (Anthropic.Bedrock, Anthropic.Vertex, Anthropic.Foundry, Anthropic.Aws, Anthropic.GoogleCloud y Anthropic.Mcp) cambian de licencia en sus propias versiones 1.0.0.
  • Java: El cambio abarca todos los artefactos de com.anthropic.

Was this page helpful?