Migration auf API-Version 2026-10-21

Dieser Leitfaden listet die Codeänderungen für den Wechsel von API-Version 2023-06-01 auf 2026-10-21 auf. Die Upgrade-Schritte beschreiben der Reihe nach, was zu tun ist.

Upgrade-Schritte

1. 1

   Auf 2026-10-21 wechseln

   Wenn du ein SDK verwendest, nutzen deine Anfragen die API-Version, die aktuell war, als die Hauptversion deines SDKs veröffentlicht wurde. Die für deine Sprache angegebenen Versionen sind die ersten, die 2026-10-21 verwenden, also aktualisiere auf diese. Wenn du die API ohne SDK aufrufst, setze den Header anthropic-version auf 2026-10-21.

   cURLCLIPythonTypeScriptC#GoJavaPHPRuby

   Python

   Aktualisiere das Paket anthropic auf Version 2.0.0.

   Veröffentliche das Upgrade zusammen mit deinen Korrekturen aus dem nächsten Schritt.

2. 2

   Deinen Code an die Breaking Changes anpassen

   Geh die Breaking Changes durch und passe deinen Code für jede an, die dich betrifft. Nimm außerdem die Codeänderungen vor, die die neue SDK- oder CLI-Version erfordert.

3. 3

   Gegen 2026-10-21 testen

   Teste deine Integration gegen 2026-10-21, bevor du sie veröffentlichst.

Breaking Changes

„Breaking changes" (inkompatible Änderungen) sind Änderungen, die bestehenden Code brechen können.

Messages API

Diese Änderungen gelten für Anfragen an die Messages API (POST /v1/messages), für das Token-Zählen und für jede Anfrage in einem Message Batch, der mit 2026-10-21 erstellt wurde.

Document-Blöcke in Assistant-Nachrichten geben einen Fehler zurück

Betrifft dich, wenn du document-Blöcke direkt in assistant-Nachrichten sendest.

In 2026-10-21 gibt eine Anfrage, die einen document-Block direkt in eine assistant-Nachricht setzt, einen 400-Fehler zurück. Sende Dokumente stattdessen in user-Nachrichten. Ein Dokument, das in einem anderen Block verschachtelt ist, etwa in einem von Claude zurückgegebenen Web-Fetch-Tool-Ergebnis, wird weiterhin akzeptiert.

Zitate in User-Nachrichten geben einen Fehler zurück

Betrifft dich, wenn du citations in text-Blöcken in user-Nachrichten sendest, auch innerhalb von search_result-Blöcken.

In 2026-10-21 gibt eine Anfrage, die einen text-Block mit einem nicht leeren citations-Array in einer user-Nachricht sendet, einen 400-Fehler zurück. Entferne citations aus diesen Blöcken. Zitate in text-Blöcken in assistant-Nachrichten, etwa in früheren Antworten von Claude, die du zurücksendest, werden weiterhin akzeptiert, ebenso die Einstellung "citations": {"enabled": true} bei Dokumenten und Suchergebnissen.

Sampling-Parameter werden entfernt

Betrifft dich, wenn du temperature, top_p oder top_k in Messages-Anfragen oder Message-Batch-Anfragen sendest.

In 2026-10-21 gibt eine Anfrage, die temperature, top_p oder top_k sendet, einen 400-Fehler zurück, selbst beim Standardwert des Parameters.

Entferne die drei Parameter aus deinen Anfragen.

Ab den neuesten Hauptversionen haben das SDK und die CLI die drei Parameter nicht mehr.

Ohne diese Parameter sampelt eine Anfrage mit deren Standardwerten, einschließlich einer temperature von 1.0, genau wie eine 2023-06-01-Anfrage, die sie weglässt. Modelle, die bereits nur die Standardwerte akzeptieren, wie Claude 4.7 und neuere Modelle, sampeln wie zuvor. Bei Modellen, die andere Werte akzeptieren, wie Claude Sonnet 4.6, verliert eine Anfrage, die temperature für konsistentere Ausgaben gesenkt hat, diesen Effekt. Keine andere Einstellung ersetzt ihn. Wenn eine Anfrage auf einen vom Standard abweichenden Wert angewiesen ist, sende den Parameter entweder nicht mehr oder belasse diese Anfrage auf 2023-06-01.

Admin API und Claude Enterprise Analytics API

Betrifft dich, wenn dein Code die Antwortfelder der Admin API oder der Claude Enterprise Analytics API aus den folgenden Tabellen liest.

In 2026-10-21 enthalten Antworten der Admin API und der Claude Enterprise Analytics API nicht mehr die alten Namen umbenannter Felder. Verwende stattdessen die neuen Namen.

Admin API:

Claude Enterprise Analytics API:

Der Query-Parameter group_type bei den Endpunkten zum Auflisten von Ratenlimits und der Filter workspace_id beim Endpunkt zum Auflisten von API-Keys bleiben unverändert.

workspace_id bei API-Keys

Betrifft dich, wenn dein Code workspace_id bei API-Keys liest.

In 2023-06-01 ist die workspace_id eines API-Keys die ID des Workspace, an den der Key gebunden ist, oder null für einen Key, der an den Default Workspace gebunden ist, und für einen Key, der nicht an einen einzelnen Workspace gebunden ist (ein Key für alle Workspaces).

In 2026-10-21 wird workspace_id entfernt. Lies stattdessen scope: Für einen an einen Workspace gebundenen Key, einschließlich des Default Workspace, ist scope.workspace_id die tatsächliche ID dieses Workspace, und ein Key für alle Workspaces hat einen scope von {"type": "organization"}, ohne workspace_id.

Wenn dein Code eine workspace_id mit dem Wert null als Default Workspace behandelt hat, vergleiche stattdessen scope.workspace_id mit der ID deines Default Workspace. Um diese ID zu finden, rufe List Workspaces mit include_default=true auf und nimm den Workspace mit dem Namen "Default".

SDK- und CLI-Änderungen

Frühere SDK- und CLI-Versionen haben bei jeder Anfrage anthropic-version: 2023-06-01 gesendet. Die Versionen unter Auf 2026-10-21 wechseln senden 2026-10-21. Die Änderungen unter Breaking Changes gelten auch für sie: Die entfernten Parameter und die alten Feldnamen sind auch aus den Typen des SDK sowie aus den Flags und der Ausgabe der CLI verschwunden.

API-Version auf Amazon Bedrock und Google Cloud

Der Client des SDK für Google Cloud's Agent Platform gibt die Version im Request-Body statt in einem Header an. Er sendet anthropic_version: 2026-10-21, wo frühere Versionen vertex-2023-10-16 gesendet haben, und keinen anthropic-version-Header.

Der Amazon Bedrock-Client macht dasselbe. Er sendet anthropic_version: 2026-10-21, wo frühere Versionen bedrock-2023-05-31 gesendet haben, und keinen anthropic-version-Header. Modelle, die älter als Claude Opus 4.7 sind, unterstützen API-Version 2026-10-21 auf Bedrock noch nicht, und eine Anfrage, die sie angibt, kann einen 400-Fehler erhalten. Wenn du eines davon verwendest, bleib vorerst bei der früheren SDK-Version oder aktualisiere und sende bedrock-2023-05-31 selbst.

MessageParam ist eine Union mit einem Typ pro Rolle

In früheren Versionen war MessageParam ein einziger Typ für jede Rolle. Jede Rolle hat jetzt einen eigenen Typ: UserMessageParam, AssistantMessageParam und SystemMessageParam. BetaMessageParam ist auf dieselbe Weise aufgeteilt, in BetaUserMessageParam, BetaAssistantMessageParam und BetaSystemMessageParam. Die Anfragen, die das SDK sendet, haben dieselben Felder und Werte wie zuvor.

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

# Nachher
message: MessageParam = {"role": "user", "content": "Hello"}

# Vorher
def to_message(role: Literal["user", "assistant"], text: str) -> MessageParam:
    return {"role": role, "content": text}


# Nachher
def to_message(role: Literal["user", "assistant"], text: str) -> MessageParam:
    if role == "user":
        return {"role": "user", "content": text}
    return {"role": "assistant", "content": text}

Enums mit nur einem Wert sind Konstanten

Dies betrifft die C#-, Go-, Java-, PHP- und Ruby-SDKs sowie ein CLI-Flag. In früheren Versionen hatte ein Pflichtfeld, das nur einen einzigen Wert annehmen kann, einen eigenen Enum-Typ mit einem einzigen Member. Diese Felder sind jetzt Konstanten, und die Enum-Typen sind entfallen. Das JSON, das das SDK sendet und liest, ist dasselbe.

Clientseitige Compaction wurde aus dem Tool-Runner entfernt

Dies betrifft die TypeScript- und Ruby-SDKs. Die clientseitige „compaction" (Komprimierung) im Tool-Runner wurde zugunsten der serverseitigen Compaction entfernt, die die Konversation innerhalb der API zusammenfasst statt mit einem zusätzlichen Request vom Client.

// Vorher
const runner = client.beta.messages.toolRunner({
  // ...
  compactionControl: { enabled: true, contextTokenThreshold: 100_000 }
});

// Nachher
const runner = client.beta.messages.toolRunner({
  // ...
  betas: ["compact-2026-01-12"],
  context_management: {
    edits: [{ type: "compact_20260112", trigger: { type: "input_tokens", value: 100_000 } }]
  }
});

Der Auslöse-Schwellenwert muss mindestens 50.000 Token betragen. Siehe Compaction für die weiteren Optionen (pause_after_compaction, benutzerdefinierte instructions).

Text Completions wurde entfernt

Die veraltete Text Completions API wurde aus den TypeScript-, Go-, Java- und Ruby-SDKs sowie aus der CLI entfernt. Neuere Modelle und Funktionen unterstützen sie nicht. Verwende stattdessen die Messages API.

# Vorher
ant completions create \
  --model "$MODEL" \
  --max-tokens-to-sample 1024 \
  --prompt $'\n\nHuman: Hello, Claude\n\nAssistant:'

# Nachher
ant messages create \
  --model "$MODEL" \
  --max-tokens 1024 \
  --message '{role: user, content: "Hello, Claude"}'

betas wurde aus den Nicht-Beta-Models-Methoden entfernt

Die Nicht-Beta-Models-Methoden nehmen kein betas mehr entgegen, und die ant models-Befehle nehmen kein --beta mehr entgegen. Um Beta-Header zu senden, rufe dieselben Methoden auf client.beta.models auf, oder ant beta:models in der CLI. Im SDK geben diese Methoden BetaModelInfo zurück, wo die Nicht-Beta-Methoden ModelInfo zurückgeben.

# Vorher
page = client.models.list(betas=[beta])

# Nachher
page = client.beta.models.list(betas=[beta])

API-Keys werden als Authorization: Bearer gesendet

Das SDK und die CLI senden deinen API-Key als Authorization: Bearer <key> statt im X-Api-Key-Header. Ändere daher jeden Proxy oder jedes Gateway, das X-Api-Key liest oder setzt, so, dass Authorization verwendet wird, oder sende den Key selbst in X-Api-Key. Die Claude API akzeptiert einen Key in beiden Headern, daher benötigt ein Programm, das direkt mit der API kommuniziert, keine Änderung.

# Before
X-Api-Key: <key>

# After
Authorization: Bearer <key>

Wenn ein Proxy oder Gateway X-Api-Key liest

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

Wenn du X-Api-Key bei einem Request gesetzt oder entfernt hast

Dies betrifft die Python-, TypeScript-, Go-, PHP- und Ruby-SDKs.

Wenn du X-Api-Key entfernt hast, damit ein Request nur ein Auth-Token sendet, lösche diesen Code, statt ihn zu ändern, denn das Entfernen von Authorization würde das Token entfernen. Ein Client hält genau eine Anmeldeinformation, stelle also sicher, dass es das Token ist: Wenn im Code keine übergeben wird und sowohl ANTHROPIC_API_KEY als auch ANTHROPIC_AUTH_TOKEN gesetzt sind, verwendet der Client den Key.

Ein Client hält eine Anmeldeinformation

Ein API-Key und ein Auth-Token teilen sich jetzt einen Header, daher hält ein SDK-Client eine einzige Anmeldeinformation. Wird im Code keine übergeben, folgt er der Reihenfolge der Vorrangregeln für Anmeldeinformationen.

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

# Vorher: sendete `X-Api-Key: <key>` und `Authorization: Bearer <token>`
# Nachher: löst `ValueError` aus

Änderungen in einem SDK oder der CLI

Diese Änderungen betreffen jeweils ein SDK oder die CLI.

# Vorher
ant --api-key "$KEY" models list

# Nachher, aus der Umgebung
export ANTHROPIC_API_KEY="$KEY"
ant models list

# Nachher, aus einem Secret-Manager
op read op://vault/anthropic/api-key | ant --api-key-stdin models list

Die Lizenz ist Apache 2.0

Ab diesen Versionen stehen das SDK und die CLI unter der Apache License, Version 2.0. Frühere Versionen bleiben unter der MIT License. Es sind keine Codeänderungen erforderlich. Wenn du die Lizenzen deiner Abhängigkeiten nachverfolgst, aktualisiere deren Einträge.

• TypeScript: Die Plattform-Pakete (@anthropic-ai/bedrock-sdk, @anthropic-ai/vertex-sdk, @anthropic-ai/foundry-sdk, @anthropic-ai/aws-sdk und @anthropic-ai/google-cloud-sdk) wechseln die Lizenz in ihren eigenen 1.0.0-Releases.
• C#: Die anderen Pakete (Anthropic.Bedrock, Anthropic.Vertex, Anthropic.Foundry, Anthropic.Aws, Anthropic.GoogleCloud und Anthropic.Mcp) wechseln die Lizenz in ihren eigenen 1.0.0-Releases.
• Java: Die Änderung umfasst jedes com.anthropic-Artefakt.