La versión 2026-10-21 de la API de Claude es el primer valor nuevo de anthropic-version desde 2023-06-01. Introduce tres cambios que rompen la compatibilidad en la API de Messages: temperature, top_p y top_k ahora devuelven un error 400, los bloques document en mensajes assistant devuelven un 400, y las citations en bloques text de mensajes user devuelven un 400. También cambia el nombre de varios campos de la Admin API y de la Enterprise Analytics API. Te suscribes a ella enviando anthropic-version: 2026-10-21 o actualizando a las nuevas versiones mayores del SDK (Python 2.0.0, TypeScript 1.0.0, Go 2.0.0 y otras).
La trampa: actualizar el SDK es la forma en que la mayoría de los equipos pasará a la nueva versión "sin querer". Un rutinario pip install -U anthropic o npm update que cruce una versión mayor cambia todas las solicitudes a 2026-10-21 de golpe. Esta guía enumera todos los cambios que documenta Anthropic, muestra cuáles duelen en código real y te da un orden seguro para actualizar.
¿Qué es la cabecera anthropic-version?
La cabecera anthropic-version es una cabecera de solicitud obligatoria que fija la forma de la API de Claude que recibes. Dentro de una misma versión, Anthropic mantiene estables los parámetros de entrada y salida existentes, pero puede añadir entradas opcionales, nuevos valores de salida, nuevas variantes de enumeración, como los tipos de eventos de streaming, y nuevas condiciones de error. Los cambios que rompen la compatibilidad solo llegan con una nueva fecha de versión.
Según la página de versionado, existen tres versiones:
| Versión | Qué introdujo |
|---|---|
2023-01-01 |
Lanzamiento inicial |
2023-06-01 |
Eventos enviados por el servidor (server-sent events) incrementales y con nombre para streaming; se eliminaron el evento exception y truncated |
2026-10-21 |
Eliminación de los parámetros de muestreo, reglas más estrictas sobre el contenido de los mensajes, cambio de nombre de campos de Admin y Analytics |
Si usas un SDK oficial, nunca configuras la cabecera tú mismo. Cada versión mayor del SDK envía la versión que estaba vigente cuando se publicó esa versión mayor. Por eso, para la mayoría de las bases de código, la actualización del SDK y la actualización de la versión de la API son el mismo evento.
Cambios que rompen la compatibilidad en la API de Claude 2026-10-21
Estos cambios se aplican a POST /v1/messages, al conteo de tokens y a todas las solicitudes dentro de un Message Batch creado con 2026-10-21.
1. Se eliminan temperature, top_p y top_k
Este es el cambio con el que se topará la mayoría. Cualquier solicitud que envíe temperature, top_p o top_k devuelve un error 400, en todos los modelos, incluso si envías el valor predeterminado. Basta con que quede un temperature: 1.0 en un archivo de configuración para romper la llamada.
Lo que ocurre con la calidad de la salida depende del modelo:
- Claude 4.7 y posteriores ya solo aceptan los valores de muestreo predeterminados, así que eliminar los parámetros no cambia nada en su forma de muestrear.
- Los modelos más antiguos que aceptan otros valores, como Claude Sonnet 4.6, pierden cualquier efecto que obtuvieras al reducir
temperature. La guía de migración es tajante al respecto: ninguna otra configuración lo sustituye.
Si una solicitud realmente depende de un valor distinto del predeterminado, Anthropic te da dos opciones: dejar de enviarlo o mantener esa solicitud concreta en 2023-06-01.
2. Los bloques document en mensajes assistant devuelven un 400
Algunas aplicaciones reproducen el historial de conversación con un bloque document situado directamente en un turno de assistant. Con 2026-10-21 eso se rechaza. Mueve los documentos a mensajes de user. Un documento anidado dentro de otro bloque, como el resultado de una herramienta de obtención web que devolvió Claude, sigue aceptándose.
3. Las citations en mensajes user devuelven un 400
Un bloque text con un array citations no vacío en un mensaje de user ahora falla, y eso incluye el texto dentro de bloques search_result. Elimina citations de esos bloques. Las citas en las propias respuestas de assistant de Claude que devuelves siguen estando bien, y también lo está "citations": {"enabled": true} en documentos y resultados de búsqueda.
4. Cambios de nombre de campos en la Admin API y Enterprise Analytics
Las respuestas ya no incluyen los nombres de campo antiguos:
| Endpoint | Campo antiguo | Campo nuevo |
|---|---|---|
| Grupos RBAC | roles |
role_ids |
| Miembros de grupos RBAC | group_id |
rbac_group_id |
| Roles RBAC | name |
display_name |
| Límites de velocidad de organización y workspace | group_type |
group.type |
| Claves de API | workspace_id |
scope.workspace_id |
| Informes de uso y coste por usuario de Analytics | actor.email |
actor.email_address |
| Resúmenes de actividad de Analytics | summaries |
data |
El cambio de las claves de API es el más sutil. Con 2023-06-01, workspace_id era null tanto para las claves vinculadas al Workspace predeterminado como para las claves de todos los workspaces. Con 2026-10-21, scope.workspace_id contiene el ID real del Workspace predeterminado, y una clave de todos los workspaces tiene scope: {"type": "organization"} sin workspace_id. Si tu panel trataba null como "Workspace predeterminado", etiquetará mal las claves después de la actualización.
Versiones del SDK que envían 2026-10-21
Anthropic publicó nuevas versiones mayores del SDK el 21 de octubre de 2026, y cada una envía 2026-10-21 de forma predeterminada, según las notas de la versión:
| SDK | Primera versión con 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 de ant |
2.0.0 |
Las nuevas versiones mayores también traen cambios que no dependen en absoluto de la versión de la API:
- Las claves de API se envían como
Authorization: Bearer <key>en lugar deX-Api-Key. La API de Claude acepta cualquiera de las dos, pero un proxy, gateway, filtro de logs o stub de pruebas que leaX-Api-Keyya no verá la clave. - Se elimina Text Completions de los SDK de TypeScript, Go, Java y Ruby y de la CLI. Usa la API de Messages.
betasdesaparece de los métodos de Models que no son beta. Llama aclient.beta.modelsen su lugar.MessageParames una unión con un tipo por rol en los SDK tipados, así que algunas anotaciones de tipo tendrán que actualizarse.- Go necesita una nueva ruta de importación que termina en
/v2, y los usuarios de TypeScript que usan los paquetes de Bedrock, Vertex, Foundry, AWS o Google Cloud deben pasarlos a v1 en la misma actualización, o el gestor de paquetes instalará una segunda copia, más antigua, del SDK principal. - La licencia cambió de MIT a Apache 2.0.
Fija tu versión mayor actual antes de hacer cualquier otra cosa. Eso evita que un bot de dependencias te actualice a mitad de sprint.
La excepción de Amazon Bedrock
En Amazon Bedrock, 2026-10-21 solo funciona con los modelos Claude 4.7 y posteriores. Si todavía llamas allí a Opus 4.6 o a un modelo más antiguo, quédate con tu versión actual del SDK o sigue enviando tu cabecera actual, y cambia primero el modelo.
Cómo actualizar a la versión 2026-10-21 de la API de Claude de forma segura
El orden que indica la guía de migración es: cambiar la versión, corregir los cambios que rompen la compatibilidad y probar antes de publicar. Así es como se ve en la práctica.
- Fija la versión mayor antigua del SDK. Por ejemplo,
anthropic<2en Python o"@anthropic-ai/sdk": "^0"en npm. - Busca en tu código y tus configuraciones
temperature,top_p,top_k,X-Api-Key,completions.createy cualquier campo de la Admin API de la tabla anterior. - Decide sobre el muestreo. En Claude 4.7 y posteriores, elimina los parámetros. En modelos más antiguos, acepta el muestreo predeterminado o mantén esas llamadas en 2023-06-01.
- Corrige la construcción de los mensajes. Mueve los documentos del lado de assistant a turnos de user y elimina
citationsde los bloques de texto de user. - Prueba los mismos payloads con ambas versiones y compara los códigos de estado y las formas de las respuestas.
- Actualiza el SDK y publica las correcciones de código a la vez. Anthropic dice que publiques la actualización junto con tus correcciones, no antes.
Sin SDK, el cambio es una sola cabecera:
curl https://api.anthropic.com/v1/messages \
-H "x-api-key: $ANTHROPIC_API_KEY" \
-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"}]
}'
Añade "temperature": 0.2 a ese body y obtendrás un 400. Envía el mismo body con anthropic-version: 2023-06-01 y funcionará. Ese par de resultados es exactamente lo que el paso 5 debería detectar para cada payload que envíes en producción.
Deja que Claude Code pruebe ambas versiones con Apidog CLI
El paso 5 es tedioso a mano: tienes decenas de formas de payload y cada una debe ejecutarse dos veces. Delégalo en tu agente de programación. Apidog CLI ofrece a Claude Code (o a Codex, Cursor y OpenCode) comandos para crear casos de prueba y ejecutarlos, de modo que el agente hace la comparación y tú lees el resumen.
Configúralo una 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
Después, dale a Claude Code un único prompt:
In Apidog project <id>, 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.
El agente comprueba el esquema de cada payload antes de escribir nada y luego ejecuta los casos:
apidog environment create claude-api --project <id> --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 <id> --file case.json
apidog run --test-case <caseId> --project <id> -e <envId> --env-var "anthropic_version=2023-06-01" -r cli,json
apidog run --test-case <caseId> --project <id> -e <envId> --env-var "anthropic_version=2026-10-21" -r cli,json
El flag --env-var cambia el valor de la cabecera sin tocar el caso de prueba, así que la diferencia es una sola variable. Añade --upload-report para ver ambas ejecuciones en la aplicación de Apidog, o pon la ejecución de 2026-10-21 en CI con -r junit para que una actualización de dependencias no pueda enviar a producción un campo temperature. La guía de Apidog CLI en Claude Code explica la configuración con más detalle, y la referencia de apidog run enumera todos los flags. El plan gratuito de Apidog cubre hasta 4 usuarios.
¿Está obsoleta la versión 2023-06-01?
No se ha publicado ninguna fecha de retirada. La página de versionado incluye 2023-06-01 sin aviso de obsolescencia, y la propia guía de migración indica que mantengas en 2023-06-01 las solicitudes que necesiten un temperature distinto del predeterminado. Anthropic sigue recomendando la última versión "siempre que sea posible".
Eso importa a la hora de planificar. La actualización de hoy es opcional, pero 2026-10-21 es la primera versión nueva en más de tres años, y los futuros cambios que rompan la compatibilidad llegarán de la misma forma, así que tratar las pruebas de versiones como una tarea rutinaria de CI ahora es más barato que una migración precipitada más adelante. Si ya estás ajustando en torno a los límites de velocidad de la API de Claude o al coste de la API de Claude, añade la comprobación de versión al mismo pipeline. Nuestra guía sobre buenas prácticas de versionado de API explica por qué las versiones basadas en fechas como esta lo facilitan.
Preguntas frecuentes
¿Tengo que actualizar ahora a la versión 2026-10-21 de la API de Claude?
No. 2023-06-01 sigue funcionando y no tiene fecha de retirada publicada. Actualizas cuando envías la nueva cabecera o instalas una versión mayor del SDK que la use de forma predeterminada.
¿Por qué mi solicitud devuelve 400 después de actualizar el SDK?
Las nuevas versiones mayores del SDK envían 2026-10-21, que rechaza temperature, top_p y top_k, los bloques document del lado de assistant y las citations en bloques de texto de user. Revisa primero si tu payload contiene eso.
¿Puedo mantener temperature en algunas solicitudes?
Sí, manteniendo esas solicitudes concretas en 2023-06-01. En 2026-10-21 no hay ninguna configuración que lo sustituya, y los modelos Claude 4.7 y posteriores solo muestrean con los valores predeterminados de todos modos.
¿Funciona 2026-10-21 en Amazon Bedrock?
Solo para los modelos Claude 4.7 y posteriores. Los modelos más antiguos de Bedrock necesitan tu versión actual del SDK o tu cabecera actual hasta que cambies de modelo.
¿Seguirá viendo mi proxy mi clave de API?
No, si lee X-Api-Key. Los nuevos SDK envían la clave como Authorization: Bearer. Actualiza el proxy para que lea Authorization, o configura el SDK para que envíe X-Api-Key tú mismo.
¿Cambia la nueva versión los eventos de streaming?
Anthropic no indica ningún cambio en el formato de streaming para 2026-10-21. El formato de streaming que usas hoy llegó con 2023-06-01.