Version 2026-10-21 de l’API Claude : ce qui change et comment migrer en toute sécurité

La version 2026-10-21 de l'API Claude est la première nouvelle valeur d'anthropic-version depuis 2023-06-01. Elle introduit trois changements cassants dans l'API Messages : temperature, top_p et top_k renvoient désormais une erreur 400, les blocs document dans les messages assistant renvoient une 400, et les citations sur les blocs text dans les messages user renvoient une 400. Elle renomme également plusieurs champs de l'Admin API et de l'Enterprise Analytics API. Vous optez pour cette version en envoyant anthropic-version: 2026-10-21 ou en mettant à niveau vers les nouvelles versions majeures des SDK (Python 2.0.0, TypeScript 1.0.0, Go 2.0.0 et autres).

Le piège : la mise à niveau du SDK est la façon dont la plupart des équipes vont « accidentellement » passer à la nouvelle version. Un simple pip install -U anthropic ou npm update qui franchit une version majeure bascule d'un coup toutes les requêtes vers 2026-10-21. Ce guide liste chaque changement documenté par Anthropic, montre lesquels mordent dans du code réel, et vous donne un ordre sûr pour effectuer la mise à niveau.

Qu'est-ce que l'en-tête anthropic-version ?

L'en-tête anthropic-version est un en-tête de requête obligatoire qui fixe la forme de l'API Claude que vous recevez en retour. Au sein d'une même version, Anthropic maintient stables les paramètres d'entrée et de sortie existants, mais peut ajouter des entrées optionnelles, de nouvelles valeurs de sortie, de nouvelles variantes d'énumération telles que les types d'événements de streaming, ainsi que de nouvelles conditions d'erreur. Les changements cassants n'arrivent qu'avec une nouvelle date de version.

D'après la page de versioning, trois versions existent :

Si vous utilisez un SDK officiel, vous ne définissez jamais l'en-tête vous-même. Chaque version majeure de SDK envoie la version qui était en vigueur au moment de sa publication. C'est pourquoi la mise à niveau du SDK et la mise à niveau de la version de l'API constituent le même événement pour la plupart des bases de code.

Changements cassants de l'API Claude 2026-10-21

Ces changements s'appliquent à POST /v1/messages, au comptage de tokens, et à chaque requête au sein d'un Message Batch créé avec 2026-10-21.

1. temperature, top_p et top_k sont supprimés

C'est le changement que la plupart des gens vont rencontrer. Toute requête qui envoie temperature, top_p ou top_k renvoie une erreur 400, sur tous les modèles, même si vous envoyez la valeur par défaut. Un temperature: 1.0 laissé dans un fichier de configuration suffit à casser l'appel.

Ce qui arrive à la qualité de la sortie dépend du modèle :

• Claude 4.7 et versions ultérieures n'acceptent déjà que les valeurs d'échantillonnage par défaut, donc retirer les paramètres ne change rien à leur façon d'échantillonner.
• Les modèles plus anciens qui acceptent d'autres valeurs, comme Claude Sonnet 4.6, perdent tout effet que vous obteniez en abaissant temperature. Le guide de migration est sans détour à ce sujet : aucun autre réglage ne le remplace.

Si une requête dépend réellement d'une valeur non par défaut, Anthropic vous donne deux choix : arrêter de l'envoyer, ou maintenir cette requête spécifique sur 2023-06-01.

2. Les blocs document dans les messages assistant renvoient une 400

Certaines applications rejouent l'historique de conversation avec un bloc document placé directement dans un tour assistant. Sous 2026-10-21, cela est rejeté. Déplacez les documents dans les messages user. Un document imbriqué dans un autre bloc, comme un résultat d'outil de récupération web renvoyé par Claude, est toujours accepté.

3. Les citations dans les messages user renvoient une 400

Un bloc text avec un tableau citations non vide dans un message user échoue désormais, et cela inclut le texte à l'intérieur des blocs search_result. Supprimez citations de ces blocs. Les citations sur les réponses assistant de Claude que vous renvoyez restent acceptées, tout comme "citations": {"enabled": true} sur les documents et les résultats de recherche.

4. Renommages de champs de l'Admin API et de l'Enterprise Analytics

Les réponses n'incluent plus les anciens noms de champs :

Le changement des clés API est le plus subtil. Sous 2023-06-01, workspace_id valait null à la fois pour les clés liées à l'espace de travail par défaut et pour les clés couvrant tous les espaces de travail. Sous 2026-10-21, scope.workspace_id contient l'ID réel de l'espace de travail par défaut, et une clé couvrant tous les espaces de travail possède scope: {"type": "organization"} sans workspace_id. Si votre tableau de bord traitait null comme « espace de travail par défaut », il étiquettera mal les clés après la mise à niveau.

Les versions de SDK qui envoient 2026-10-21

Anthropic a publié de nouvelles versions majeures de SDK le 21 octobre 2026, et chacune envoie 2026-10-21 par défaut, d'après les notes de version :

Les nouvelles versions majeures apportent aussi des changements qui ne dépendent pas du tout de la version de l'API :

• Les clés API sont envoyées sous la forme Authorization: Bearer <key> au lieu de X-Api-Key. L'API Claude accepte les deux, mais un proxy, une passerelle, un filtre de logs ou un stub de test qui lit X-Api-Key ne verra plus la clé.
• Text Completions est supprimé des SDK TypeScript, Go, Java et Ruby ainsi que du CLI. Utilisez l'API Messages.
• betas a disparu des méthodes Models non bêta. Appelez plutôt client.beta.models.
• MessageParam est une union avec un type par rôle dans les SDK typés, donc certaines annotations de type doivent être mises à jour.
• Go nécessite un nouveau chemin d'import se terminant par /v2, et les utilisateurs TypeScript des packages Bedrock, Vertex, Foundry, AWS ou Google Cloud doivent les faire passer à la v1 dans la même mise à niveau, sinon le gestionnaire de paquets installe une seconde copie plus ancienne du SDK principal.
• La licence a changé de MIT à Apache 2.0.

Épinglez votre version majeure actuelle avant toute autre chose. Cela empêche un bot de dépendances de vous mettre à niveau en pleine sprint.

L'exception Amazon Bedrock

Sur Amazon Bedrock, 2026-10-21 ne fonctionne qu'avec les modèles Claude 4.7 et versions ultérieures. Si vous appelez encore Opus 4.6 ou un modèle plus ancien à cet endroit, restez sur votre version actuelle de SDK ou continuez d'envoyer votre en-tête actuel, et changez d'abord de modèle.

Comment mettre à niveau vers la version 2026-10-21 de l'API Claude en toute sécurité

L'ordre indiqué dans le guide de migration est : changer la version, corriger les changements cassants, tester avant la mise en production. Voici à quoi cela ressemble en pratique.

1. Épinglez l'ancienne version majeure du SDK. Par exemple anthropic<2 en Python ou "@anthropic-ai/sdk": "^0" dans npm.
2. Recherchez dans votre code et vos configurations les occurrences de temperature, top_p, top_k, X-Api-Key, completions.create, et tout champ de l'Admin API du tableau ci-dessus.
3. Décidez du paramétrage d'échantillonnage. Sur Claude 4.7 et versions ultérieures, supprimez les paramètres. Sur les modèles plus anciens, acceptez l'échantillonnage par défaut ou maintenez ces appels sur 2023-06-01.
4. Corrigez la construction des messages. Déplacez les documents côté assistant vers les tours user et supprimez citations des blocs de texte user.
5. Testez les mêmes charges utiles sous les deux versions et comparez les codes de statut et les formes de réponse.
6. Mettez à niveau le SDK et livrez les correctifs de code ensemble. Anthropic recommande de publier la mise à niveau avec vos correctifs, pas avant.

Sans SDK, le basculement se fait avec un seul en-tête :

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

Ajoutez "temperature": 0.2 à ce corps de requête et vous obtiendrez une 400. Envoyez le même corps avec anthropic-version: 2023-06-01 et cela réussit. Cette paire de résultats est exactement ce que l'étape 5 devrait détecter pour chaque charge utile que vous envoyez en production.

Laissez Claude Code tester les deux versions avec Apidog CLI

L'étape 5 est fastidieuse à la main : vous avez des dizaines de formes de charges utiles, et chacune doit être exécutée deux fois. Confiez-la plutôt à votre agent de codage. Apidog CLI fournit à Claude Code (ou Codex, Cursor et OpenCode) des commandes pour créer des cas de test et les exécuter, afin que l'agent fasse la comparaison et que vous lisiez le résumé.

Configurez-le une fois :

npm install -g apidog-cli@latest
apidog login --with-token <YOUR_TOKEN>
npx -y skills add https://apidog.com   # pick Claude Code when prompted

Ensuite, donnez un seul prompt à Claude Code :

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.

L'agent vérifie le schéma de chaque charge utile avant d'écrire quoi que ce soit, puis exécute les cas :

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

L'option --env-var permute la valeur de l'en-tête sans toucher au cas de test, de sorte que la différence tient à une seule variable. Ajoutez --upload-report pour consulter les deux exécutions dans l'application Apidog, ou placez l'exécution 2026-10-21 dans la CI avec -r junit afin qu'une mise à jour de dépendance ne puisse pas livrer un champ temperature en production. Le guide d'Apidog CLI dans Claude Code détaille la configuration, et la référence de apidog run liste toutes les options. Le plan gratuit d'Apidog couvre jusqu'à 4 utilisateurs.

2023-06-01 est-elle obsolète ?

Aucune date de retrait n'a été publiée. La page de versioning liste 2023-06-01 sans avis de dépréciation, et le guide de migration lui-même vous indique de maintenir sur 2023-06-01 les requêtes qui nécessitent une temperature non par défaut. Anthropic recommande toujours la dernière version « dans la mesure du possible ».

Cela compte pour la planification. La mise à niveau d'aujourd'hui est facultative, mais 2026-10-21 est la première nouvelle version en plus de trois ans, et les futurs changements cassants arriveront de la même manière, donc traiter le test de version comme une tâche de CI routinière dès maintenant coûte moins cher qu'une migration précipitée plus tard. Si vous ajustez déjà vos appels autour des limites de débit de l'API Claude ou du coût de l'API Claude, ajoutez la vérification de version au même pipeline. Notre guide des bonnes pratiques de versioning d'API explique pourquoi les versions basées sur des dates comme celle-ci les facilitent.

FAQ

Dois-je passer dès maintenant à la version 2026-10-21 de l'API Claude ?

Non. 2023-06-01 fonctionne toujours et n'a aucune date de retrait publiée. Vous effectuez la mise à niveau lorsque vous envoyez le nouvel en-tête ou installez une version majeure du SDK qui l'utilise par défaut.

Pourquoi ma requête renvoie-t-elle une 400 après une mise à niveau du SDK ?

Les nouvelles versions majeures du SDK envoient 2026-10-21, qui rejette temperature, top_p et top_k, les blocs document côté assistant et les citations sur les blocs de texte user. Vérifiez d'abord votre charge utile pour ces éléments.

Puis-je conserver temperature sur certaines requêtes ?

Oui, en maintenant ces requêtes spécifiques sur 2023-06-01. Sous 2026-10-21, il n'existe aucun réglage de remplacement, et les modèles Claude 4.7 et versions ultérieures n'échantillonnent de toute façon qu'avec les valeurs par défaut.

2026-10-21 fonctionne-t-elle sur Amazon Bedrock ?

Uniquement pour les modèles Claude 4.7 et versions ultérieures. Les modèles Bedrock plus anciens nécessitent votre version de SDK ou en-tête actuel jusqu'à ce que vous changiez de modèle.

Mon proxy verra-t-il encore ma clé API ?

Non, s'il lit X-Api-Key. Les nouveaux SDK envoient la clé sous la forme Authorization: Bearer. Mettez à jour le proxy pour lire Authorization, ou configurez le SDK pour envoyer X-Api-Key vous-même.

La nouvelle version modifie-t-elle les événements de streaming ?

Anthropic ne liste aucun changement de format de streaming pour 2026-10-21. Le format de streaming que vous utilisez aujourd'hui vient de 2023-06-01.