La version d'API 2026-10-21 et les nouveaux SDK

Chaque requête à l’API Claude porte un en-tête anthropic-version. Pendant plus de trois ans, sa valeur n’a pas bougé : 2023-06-01. Le 21 octobre 2026, Anthropic a publié une nouvelle version, 2026-10-21, avec une nouvelle génération de SDK qui l’utilisent par défaut. C’est un changement qui ne se voit pas dans les annonces de modèles et qui peut pourtant casser une intégration au moment d’une simple mise à jour de dépendances.

Ce qu’est une version d’API

La version d’API fige un contrat : la forme des requêtes acceptées et des réponses renvoyées. Tant que vous envoyez 2023-06-01, ce contrat ne change pas. Les SDK, eux, envoient la version qui était courante à la sortie de leur version majeure. Autrement dit, ce n’est pas votre code qui décide de basculer, c’est la mise à jour de votre SDK : d’où l’intérêt de savoir quelles versions sont concernées.

Ces nouvelles versions passent aussi de la licence MIT à la licence Apache 2.0. Dans les langages où Bedrock, Vertex, Foundry, AWS et Google Cloud ont leur propre paquet (TypeScript, C#, Java), ces paquets changent aussi de version majeure : mettez-les à jour en même temps que le SDK. Si vous appelez l’API sans SDK, il vous suffit de changer l’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": "Bonjour Claude"}]
  }'

Les trois ruptures de l’API Messages

La nouvelle version change trois comportements de l’API Messages, et chacun provoque une erreur 400. Ils valent aussi pour le comptage de tokens et pour chaque requête d’un lot Message Batches.

• Paramètres d’échantillonnage : temperature, top_p et top_k sont refusés, même à leur valeur par défaut. Sur les modèles Claude 4.7 et suivants, qui n’acceptaient déjà que les valeurs par défaut, rien ne change en pratique ; sur un modèle plus ancien comme Sonnet 4.6, une requête qui baissait la température perd cet effet, et aucun autre réglage ne le remplace. La documentation conseille de passer par le prompt.
• Documents dans un message assistant : un bloc document placé directement dans un message assistant est refusé ; envoyez vos documents dans les messages user.
• Citations dans un message utilisateur : un bloc text portant un tableau citations non vide dans un message user est refusé. Les citations restent acceptées dans les messages assistant, ainsi que le réglage "citations": {"enabled": true} sur les documents.

Si vous utilisez l’API Admin ou l’API Analytics de Claude Enterprise, une quatrième rupture vous concerne : leurs réponses ne contiennent plus les anciens noms de champs renommés (par exemple workspace_id sur les clés d’API, remplacé par scope).

Les changements propres aux SDK

Les nouvelles versions majeures apportent aussi des changements qui ne dépendent pas de l’API. Le plus discret est le plus susceptible de surprendre une équipe d’exploitation : les SDK envoient désormais la clé d’API dans l’en-tête Authorization: Bearer au lieu de X-Api-Key (le client Foundry excepté). L’API accepte les deux, mais un proxy, une passerelle ou un filtre de journaux qui lisait X-Api-Key ne verra plus rien passer. Autres changements :

• un client ne porte plus qu’un seul identifiant : en passer deux au constructeur lève une erreur ;
• MessageParam devient une union d’un type par rôle (les messages écrits comme de simples dictionnaires ne changent pas) ;
• l’ancienne API Text Completions disparaît des SDK qui la gardaient encore, et la compaction côté client du Tool Runner cède la place à la compaction côté serveur ;
• les méthodes non bêta de l’API Models n’acceptent plus d’en-têtes bêta : passez par client.beta.models.

Pour Python, une étape intermédiaire avait déjà eu lieu le 20 août 2026 avec le SDK 1.0 : passage de httpx à httpx2, Python 3.10 minimum, et retrait de temperature, top_p et top_k des méthodes Messages.

Le cas d’Amazon Bedrock

Si vous passez par Bedrock, la version 2026-10-21 n’y est disponible que pour les modèles Claude 4.7 et suivants. Si vous appelez un modèle plus ancien sur Bedrock, restez sur votre version actuelle du SDK, ou basculez d’abord ces appels vers un modèle récent.

La méthode de migration

La documentation propose trois étapes, dans cet ordre. D’abord, passer à la version de SDK qui envoie 2026-10-21, ou changer l’en-tête si vous n’utilisez pas de SDK. Ensuite, corriger votre code pour chacune des ruptures qui vous concernent, y compris celles propres au SDK. Enfin, tester l’intégration contre 2026-10-21 avant de livrer, et livrer la mise à jour du SDK en même temps que vos corrections, pas séparément. Une recherche dans votre dépôt sur temperature, top_p, top_k, X-Api-Key et citations couvre l’essentiel du risque. Dans Claude Code, la commande /claude-api api-version déroule cette migration pour vous.

À vous de jouer

Une migration à blanc. Dans une branche de votre projet, passez le SDK à la version qui envoie 2026-10-21, puis lancez vos tests. Pour chaque échec, rattachez-le à l’une des ruptures de cette leçon. Vérifiez enfin, dans les journaux de votre proxy ou de votre passerelle, que la clé d’API arrive bien dans Authorization et que rien n’en dépendait sous X-Api-Key.

Sources officielles : Migrating to API version 2026-10-21 (documentation Claude : étapes, ruptures, changements des SDK) · Model deprecations (paramètres dépréciés) · Release notes

Points clés à retenir

• La version d’API 2026-10-21 succède à 2023-06-01 ; ce sont les nouvelles versions majeures des SDK qui la déclenchent
• Trois ruptures de l’API Messages : paramètres d’échantillonnage, documents dans un message assistant, citations dans un message utilisateur
• Les SDK envoient la clé en Authorization: Bearer : vérifiez vos proxys et vos filtres de journaux
• Un seul identifiant par client, MessageParam par rôle, plus de Text Completions
• Sur Bedrock, 2026-10-21 exige un modèle Claude 4.7 ou plus récent