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

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. 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.

   cURLCLIPythonTypeScriptC#GoJavaPHPRuby

   Python

   Actualiza el paquete anthropic a la versión 2.0.0.

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

2. 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. 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 obtención web 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. Elimina citations de esos bloques. Las citas en bloques text de mensajes assistant, como las respuestas anteriores de Claude que reenvías, 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.

Elimina 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 muestrea 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, muestrean 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:

Claude Enterprise Analytics API:

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 de 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 de 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, incluidos sus clientes de Amazon Bedrock y Google Cloud. 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 opciones y la salida de la CLI.

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.

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

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

# 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}

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 desaparecen. El JSON que el SDK envía y lee es el mismo.

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.

// 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 } }]
  }
});

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 las funciones más recientes no la admiten. Usa la API de Messages en su lugar.

# 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"}'

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.

# 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" (puerta de enlace) que lea o establezca X-Api-Key para que use Authorization, o envía tú mismo la clave en X-Api-Key. La Claude API 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>

Si un proxy o gateway lee X-Api-Key

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))

Si estableciste o eliminaste X-Api-Key en una solicitud

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

Si eliminaste 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 establecidas tanto ANTHROPIC_API_KEY como ANTHROPIC_AUTH_TOKEN, el cliente usa la clave.

Un cliente contiene una sola credencial

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

client = Anthropic(api_key=key, auth_token=token)

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

Cambios en un SDK o en la CLI

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

# 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

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.