Claude API Version 2026-10-21: Änderungen und sichere Upgrade-Anleitung

Claude API Version 2026-10-21 ist der erste neue anthropic-version-Wert seit 2023-06-01. Sie nimmt drei breaking changes an der Messages API vor: temperature, top_p und top_k geben jetzt einen 400-Fehler zurück, document-Blöcke in assistant-Nachrichten geben einen 400 zurück, und citations bei text-Blöcken in user-Nachrichten geben einen 400 zurück. Außerdem benennt sie mehrere Felder der Admin API und der Enterprise Analytics API um. Sie aktivieren sie, indem Sie anthropic-version: 2026-10-21 senden oder auf die neuen SDK-Hauptversionen aktualisieren (Python 2.0.0, TypeScript 1.0.0, Go 2.0.0 und andere).

Der Haken: Das Aktualisieren des SDK ist der Weg, auf dem die meisten Teams „versehentlich“ auf die neue Version wechseln. Ein routinemäßiges pip install -U anthropic oder npm update, das eine Hauptversion überschreitet, schaltet jede Anfrage auf einmal auf 2026-10-21 um. Dieser Leitfaden listet jede von Anthropic dokumentierte Änderung auf, zeigt, welche im echten Code wirklich wehtun, und gibt Ihnen eine sichere Reihenfolge für das Upgrade.

Was ist der anthropic-version-Header?

Der anthropic-version-Header ist ein erforderlicher Request-Header, der die Form der Claude API festlegt, die Sie zurückbekommen. Innerhalb einer Version hält Anthropic bestehende Eingabe- und Ausgabeparameter stabil, kann aber optionale Eingaben, neue Ausgabewerte, neue Enum-Varianten wie Streaming-Event-Typen und neue Fehlerbedingungen hinzufügen. Breaking changes kommen nur mit einem neuen Versionsdatum.

Von der Versioning-Seite existieren drei Versionen:

Wenn Sie ein offizielles SDK verwenden, setzen Sie den Header nie selbst. Jede SDK-Hauptversion sendet die Version, die zum Zeitpunkt der Veröffentlichung dieser Hauptversion aktuell war. Deshalb sind das SDK-Upgrade und das API-Versions-Upgrade für die meisten Codebasen dasselbe Ereignis.

Breaking changes der Claude API 2026-10-21

Diese Änderungen gelten für POST /v1/messages, für das Token-Counting und für jede Anfrage innerhalb eines Message Batches, der mit 2026-10-21 erstellt wurde.

1. temperature, top_p und top_k wurden entfernt

Das ist die Änderung, auf die die meisten stoßen werden. Jede Anfrage, die temperature, top_p oder top_k sendet, gibt einen 400-Fehler zurück – bei jedem Modell, selbst wenn Sie den Standardwert senden. Ein temperature: 1.0, das in einer Konfigurationsdatei übrig geblieben ist, reicht aus, um den Aufruf zu brechen.

Was mit der Ausgabequalität passiert, hängt vom Modell ab:

• Claude 4.7 und später akzeptieren bereits nur die Standard-Sampling-Werte, sodass das Entfernen der Parameter nichts daran ändert, wie sie samplen.
• Ältere Modelle, die andere Werte akzeptieren, wie Claude Sonnet 4.6, verlieren jede Wirkung, die Sie durch ein niedrigeres temperature erzielt haben. Der Migrationsleitfaden sagt es unverblümt: Keine andere Einstellung ersetzt sie.

Wenn eine Anfrage wirklich von einem Nicht-Standardwert abhängt, gibt Anthropic Ihnen zwei Möglichkeiten: Senden Sie ihn nicht mehr, oder halten Sie diese spezifische Anfrage auf 2023-06-01.

2. document-Blöcke in assistant-Nachrichten geben einen 400 zurück

Manche Apps spielen den Gesprächsverlauf mit einem document-Block direkt in einem assistant-Turn erneut ab. Unter 2026-10-21 wird das abgelehnt. Verschieben Sie Dokumente in user-Nachrichten. Ein Dokument, das in einen anderen Block eingebettet ist, wie etwa ein von Claude zurückgegebenes Web-Fetch-Tool-Ergebnis, wird weiterhin akzeptiert.

3. citations in user-Nachrichten geben einen 400 zurück

Ein text-Block mit einem nicht leeren citations-Array in einer user-Nachricht schlägt jetzt fehl, und das schließt Text innerhalb von search_result-Blöcken ein. Entfernen Sie citations aus diesen Blöcken. Citations bei Claudes eigenen assistant-Antworten, die Sie zurücksenden, sind weiterhin in Ordnung, ebenso wie "citations": {"enabled": true} bei Dokumenten und Suchergebnissen.

4. Umbenennungen von Feldern der Admin API und Enterprise Analytics

Antworten enthalten die alten Feldnamen nicht mehr:

Die Änderung bei den API-Schlüsseln ist die subtile. Unter 2023-06-01 war workspace_id sowohl für Schlüssel, die an den Default Workspace gebunden sind, als auch für All-Workspaces-Schlüssel null. Unter 2026-10-21 enthält scope.workspace_id die echte ID des Default Workspace, und ein All-Workspaces-Schlüssel hat scope: {"type": "organization"} ohne workspace_id. Wenn Ihr Dashboard null als „Default Workspace“ behandelte, wird es Schlüssel nach dem Upgrade falsch beschriften.

SDK-Versionen, die 2026-10-21 senden

Anthropic hat am 21. Oktober 2026 neue SDK-Hauptversionen veröffentlicht, und jede sendet standardmäßig 2026-10-21, gemäß den Release Notes:

Die neuen Hauptversionen bringen außerdem Änderungen mit sich, die überhaupt nicht von der API-Version abhängen:

• API-Schlüssel gehen als Authorization: Bearer <key> raus statt als X-Api-Key. Die Claude API akzeptiert beides, aber ein Proxy, Gateway, Log-Filter oder Test-Stub, der X-Api-Key liest, sieht den Schlüssel nicht mehr.
• Text Completions wurde entfernt aus den TypeScript-, Go-, Java- und Ruby-SDKs und aus der CLI. Verwenden Sie die Messages API.
• betas ist aus den Nicht-Beta-Models-Methoden verschwunden. Rufen Sie stattdessen client.beta.models auf.
• MessageParam ist eine Union mit einem Typ pro Rolle in den typisierten SDKs, sodass einige Typannotationen aktualisiert werden müssen.
• Go braucht einen neuen Importpfad, der auf /v2 endet, und TypeScript-Nutzer der Bedrock-, Vertex-, Foundry-, AWS- oder Google-Cloud-Pakete müssen diese im selben Upgrade auf v1 umstellen, sonst installiert der Paketmanager eine zweite, ältere Kopie des Core-SDKs.
• Die Lizenz hat sich geändert von MIT zu Apache 2.0.

Pinnen Sie Ihre aktuelle Hauptversion, bevor Sie irgendetwas anderes tun. Das hindert einen Dependency-Bot daran, Sie mitten im Sprint zu aktualisieren.

Die Amazon-Bedrock-Ausnahme

Auf Amazon Bedrock funktioniert 2026-10-21 nur mit Claude 4.7 und späteren Modellen. Wenn Sie dort noch Opus 4.6 oder ein älteres Modell aufrufen, bleiben Sie bei Ihrer aktuellen SDK-Version oder senden Sie weiterhin Ihren aktuellen Header, und wechseln Sie zuerst das Modell.

So aktualisieren Sie sicher auf Claude API Version 2026-10-21

Die Reihenfolge des Migrationsleitfadens ist: Version umschalten, Breaking Changes beheben, vor dem Release testen. So sieht das in der Praxis aus.

1. Pinnen Sie die alte SDK-Hauptversion. Zum Beispiel anthropic<2 in Python oder "@anthropic-ai/sdk": "^0" in npm.
2. Durchsuchen Sie Ihren Code und Ihre Konfigurationen nach temperature, top_p, top_k, X-Api-Key, completions.create und jedem Admin-API-Feld aus der Tabelle oben.
3. Entscheiden Sie sich beim Sampling. Bei Claude 4.7 und später löschen Sie die Parameter. Bei älteren Modellen akzeptieren Sie entweder das Standard-Sampling oder behalten diese Aufrufe auf 2023-06-01.
4. Korrigieren Sie die Nachrichtenkonstruktion. Verschieben Sie assistentenseitige Dokumente in User-Turns und entfernen Sie citations aus User-Text-Blöcken.
5. Testen Sie dieselben Payloads unter beiden Versionen und vergleichen Sie Statuscodes und Antwortformen.
6. Aktualisieren Sie das SDK und liefern Sie die Code-Fixes gemeinsam aus. Anthropic sagt, Sie sollen das Upgrade mit Ihren Fixes veröffentlichen, nicht davor.

Ohne SDK ist der Wechsel ein einziger Header:

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

Fügen Sie "temperature": 0.2 zu diesem Body hinzu, und Sie bekommen einen 400. Senden Sie denselben Body mit anthropic-version: 2023-06-01, und er gelingt. Genau dieses Ergebnispaar sollte Schritt 5 für jede Payload abfangen, die Sie in der Produktion senden.

Lassen Sie Claude Code beide Versionen mit Apidog CLI testen

Schritt 5 ist von Hand mühsam: Sie haben Dutzende von Payload-Formen, und jede muss zweimal laufen. Übergeben Sie das stattdessen Ihrem Coding-Agenten. Apidog CLI gibt Claude Code (oder Codex, Cursor und OpenCode) Befehle zum Erstellen und Ausführen von Testfällen, sodass der Agent den Vergleich durchführt und Sie die Zusammenfassung lesen.

Richten Sie es einmal ein:

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

Geben Sie dann Claude Code einen 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.

Der Agent prüft jedes Payload-Schema, bevor er etwas schreibt, und führt dann die Fälle aus:

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

Das --env-var-Flag tauscht den Header-Wert aus, ohne den Testfall anzufassen, sodass der Diff aus einer einzigen Variable besteht. Fügen Sie --upload-report hinzu, um beide Läufe in der Apidog-App anzuzeigen, oder legen Sie den 2026-10-21-Lauf mit -r junit in CI, damit ein Dependency-Bump kein temperature-Feld in die Produktion ausliefern kann. Der Leitfaden zu Apidog CLI in Claude Code behandelt die Einrichtung ausführlicher, und die apidog run-Referenz listet jedes Flag auf. Der Free-Plan von Apidog deckt bis zu 4 Benutzer ab.

Ist 2023-06-01 veraltet?

Es wurde kein Abschaltdatum veröffentlicht. Die Versioning-Seite listet 2023-06-01 ohne Deprecation-Hinweis auf, und der Migrationsleitfaden selbst sagt Ihnen, Anfragen, die ein Nicht-Standard-temperature benötigen, auf 2023-06-01 zu belassen. Anthropic empfiehlt weiterhin die neueste Version „wann immer möglich“.

Das ist wichtig für die Planung. Das heutige Upgrade ist optional, aber 2026-10-21 ist die erste neue Version seit mehr als drei Jahren, und zukünftige Breaking Changes werden auf dieselbe Weise kommen. Versionstests schon jetzt als routinemäßigen CI-Job zu behandeln, ist also günstiger als eine überstürzte Migration später. Wenn Sie bereits rund um Claude API Rate Limits oder Claude API Kosten optimieren, fügen Sie die Versionsprüfung derselben Pipeline hinzu. Unser Leitfaden zu Best Practices für API-Versionierung erklärt, warum datumsbasierte Versionen wie diese es einfacher machen.

FAQ

Muss ich jetzt auf Claude API Version 2026-10-21 aktualisieren?

Nein. 2023-06-01 funktioniert weiterhin und hat kein veröffentlichtes Abschaltdatum. Sie aktualisieren, wenn Sie den neuen Header senden oder eine SDK-Hauptversion installieren, die ihn standardmäßig verwendet.

Warum gibt meine Anfrage nach einem SDK-Upgrade einen 400 zurück?

Die neuen SDK-Hauptversionen senden 2026-10-21, was temperature, top_p und top_k, assistentenseitige document-Blöcke und citations bei User-Text-Blöcken ablehnt. Prüfen Sie zuerst Ihre Payload auf diese.

Kann ich temperature bei einigen Anfragen behalten?

Ja, indem Sie diese spezifischen Anfragen auf 2023-06-01 belassen. Unter 2026-10-21 gibt es keine Ersatzeinstellung, und Claude 4.7 und spätere Modelle samplen ohnehin nur mit den Standardwerten.

Funktioniert 2026-10-21 auf Amazon Bedrock?

Nur für Claude 4.7 und spätere Modelle. Ältere Bedrock-Modelle benötigen Ihre aktuelle SDK-Version oder Ihren aktuellen Header, bis Sie das Modell wechseln.

Wird mein Proxy meinen API-Schlüssel noch sehen?

Nicht, wenn er X-Api-Key liest. Die neuen SDKs senden den Schlüssel als Authorization: Bearer. Aktualisieren Sie den Proxy so, dass er Authorization liest, oder konfigurieren Sie das SDK so, dass es selbst X-Api-Key sendet.

Ändert die neue Version die Streaming-Events?

Anthropic listet keine Änderung des Streaming-Formats für 2026-10-21 auf. Das Streaming-Format, das Sie heute verwenden, kam mit 2023-06-01.