--- title: Eine Routine über die API auslösen url: https://platform.claude.com/docs/de/api/claude-code/routines-fire description: Starte bei Bedarf eine Claude Code-Routine-Sitzung, indem du eine authentifizierte POST-Anfrage sendest. --- Dies ist eine experimentelle API. Anfrage- und Antwortformate, Ratenlimits und Token-Semantik können sich ändern. [Claude Code](https://code.claude.com/docs) ist Anthropics agentisches Coding-Tool. [Claude Code im Web](https://code.claude.com/docs/de/claude-code-on-the-web) führt Claude Code-Sitzungen auf von Anthropic verwalteter Cloud-Infrastruktur unter claude.ai/code aus, und eine [„routine“](https://code.claude.com/docs/de/routines) (Routine) ist dort eine gespeicherte Konfiguration: ein Prompt, ein oder mehrere Repositories und Konnektoren, so gebündelt, dass sie unbeaufsichtigt nach einem Zeitplan, als Reaktion auf GitHub-Ereignisse oder bei einem Aufruf über HTTP ausgeführt werden kann. Dieser Endpunkt ist der HTTP-Einstiegspunkt. Ein POST an ihn startet einen neuen Lauf einer bestehenden Routine und gibt die resultierende Sitzungs-ID und URL zurück. Typische Aufrufer sind Alerting-Systeme, CI-Pipelines und interne Tools, die programmatisch eine Claude Code-Sitzung starten müssen. Zum Aufrufen dieses Endpunkts benötigst du ein claude.ai-Konto mit einem Plan vom Typ Pro, Max, Team oder Enterprise, bei dem [Claude Code im Web](https://code.claude.com/docs/de/claude-code-on-the-web) aktiviert ist. Die Authentifizierung erfolgt mit einem routinespezifischen „bearer token" (Bearer-Token), das in der Claude Code-Web-UI erstellt wird, und nicht mit einem Claude API-Key. ## Unterschiede zur Claude Platform Der Endpunkt zum Auslösen von Routinen gehört zur Produktoberfläche von Claude Code, die sich in einigen Punkten von den APIs und SDKs der Claude Platform unterscheidet: | Aspekt | Dieser Endpunkt | Claude Platform-APIs | | --------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------- | | Authentifizierung | `Authorization: Bearer` mit einem routinespezifischen Token (`sk-ant-oat01-...`), erstellt unter [claude.ai/code/routines](https://claude.ai/code/routines) | `x-api-key` mit einem Claude API-Key aus der Claude Console | | Token-Geltungsbereich | Nur eine Routine; kein Lesezugriff | Workspace-Ebene | | SDK-Unterstützung | Keine | Verfügbar in allen [Client-SDKs](https://platform.claude.com/docs/de/cli-sdks-libraries/overview) | | Abrechnung | Claude Code-Abonnementnutzung auf claude.ai | Claude Platform-Nutzung | | Pfad-Namespace | `/v1/claude_code/...` | `/v1/...` | | Stabilität | Experimentell | Stabil oder Standard-Beta | ## Bevor du beginnst Um diesen Endpunkt aufzurufen, benötigst du: 1. Eine Routine, die unter [claude.ai/code/routines](https://claude.ai/code/routines) erstellt wurde. 2. Ein für diese Routine generiertes Bearer-Token: Öffne die Routine zum Bearbeiten, klicke unter **Select a trigger** auf **Add another trigger**, wähle **API** und klicke dann im modalen Fenster auf **Generate token**. Das Token wird nur einmal angezeigt und kann später nicht mehr abgerufen werden. Die vollständige Einrichtungsanleitung findest du unter [Einen API-Trigger hinzufügen](https://code.claude.com/docs/de/routines#add-an-api-trigger) in der Claude Code-Dokumentation. ## Eine Routine auslösen ```http POST https://api.anthropic.com/v1/claude_code/routines/{routine_id}/fire ``` Die Claude Code-Web-UI stellt die vollständige URL zusammen mit dem Token bereit, wenn du einen API-Trigger hinzufügst, sodass die meisten Integrationen beides als Secrets speichern und den Endpunkt direkt aufrufen. Die folgenden Beispiele zeigen einen Shell-Aufruf und einen GitHub Actions-Schritt, der die Routine bei einem CI-Fehlschlag auslöst. ```bash cURL curl -X POST https://api.anthropic.com/v1/claude_code/routines/$ROUTINE_ID/fire \ -H "Authorization: Bearer $ROUTINE_TOKEN" \ -H "anthropic-version: 2023-06-01" \ -H "Content-Type: application/json" \ -d '{"text": "Sentry alert SEN-4521 fired in prod. Stack trace attached."}' ``` ```yaml GitHub Actions - if: failure() env: ROUTINE_FIRE_URL: ${{ secrets.ROUTINE_FIRE_URL }} ROUTINE_FIRE_TOKEN: ${{ secrets.ROUTINE_FIRE_TOKEN }} run: | curl -X POST "$ROUTINE_FIRE_URL" \ -H "Authorization: Bearer $ROUTINE_FIRE_TOKEN" \ -H "anthropic-version: 2023-06-01" \ -H "Content-Type: application/json" \ -d "{\"text\": \"CI failed: $GITHUB_WORKFLOW run $GITHUB_RUN_ID on $GITHUB_REF\"}" ``` Die Anfrage kehrt zurück, sobald die Sitzung erstellt ist. Sie streamt keine Sitzungsausgabe und wartet nicht auf den Abschluss der Sitzung. ### Header | Name | Erforderlich | Beschreibung | | ------------------- | --------------------------- | --------------------------------------------------------------------------------------------------------------------- | | `Authorization` | Ja | `Bearer `. Das pro Routine in der Claude Code-Web-UI erstellte Token mit dem Präfix `sk-ant-oat01-`. | | `anthropic-version` | Ja | Die [API-Version](https://platform.claude.com/docs/de/api/versioning). `2023-06-01` ist der einzige akzeptierte Wert. | | `Content-Type` | Wenn ein Body vorhanden ist | `application/json`. | Ältere Integrationen, die einen `anthropic-beta: experimental-cc-routine-2026-04-01`-Header senden, sind nicht betroffen: Der Endpunkt akzeptiert Anfragen mit und ohne diesen Header. ### Pfadparameter | Name | Typ | Beschreibung | | ------------ | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `routine_id` | string | Die Kennung der Routine. Trotz des Parameternamens hat der Wert das Präfix `trig_` statt `routine_`. Enthalten in der URL, die das modale Fenster anzeigt, wenn du einen API-Trigger hinzufügst. | ### Request-Body | Feld | Typ | Erforderlich | Beschreibung | | ------ | ------ | ------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `text` | string | Nein | Anfänglicher Kontext für diesen Lauf, etwa der Text eines Alerts, eine fehlschlagende Log-Zeile oder ein Git-Diff. Der Wert ist Freitext und wird nicht geparst; wenn du JSON oder eine andere strukturierte Payload sendest, erhält die Routine sie als literalen String. Wird der Routine zusammen mit ihrem gespeicherten Prompt übergeben. Maximal 65.536 Zeichen. | Der Body ist optional. Unbekannte Felder im Body werden ignoriert. ### Antwort Eine erfolgreiche Anfrage gibt `200 OK` mit den Details der neuen Sitzung zurück: ```json { "type": "routine_fire", "claude_code_session_id": "session_01HJKLMNOPQRSTUVWXYZ", "claude_code_session_url": "https://claude.ai/code/session_01HJKLMNOPQRSTUVWXYZ" } ``` | Feld | Typ | Beschreibung | | ------------------------- | ------ | --------------------------------------------------------------------------------------------------------------------------------------------------- | | `type` | string | Immer `routine_fire`. | | `claude_code_session_id` | string | Die ID der für diesen Lauf erstellten Claude Code-Sitzung. | | `claude_code_session_url` | string | Ein Link zur Sitzung auf claude.ai. Öffne ihn in einem Browser, um den Lauf zu beobachten, Änderungen zu prüfen oder die Unterhaltung fortzusetzen. | ### Fehler Fehler verwenden den standardmäßigen Anthropic-[Fehler-Envelope](https://platform.claude.com/docs/de/api/errors): ```json { "type": "error", "error": { "type": "not_found_error", "message": "" } } ``` | HTTP-Status | Fehlertyp | Ursache | | ----------- | ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | 400 | `invalid_request_error` | Fehlender oder nicht unterstützter `anthropic-version`-Header, `text` überschreitet 65.536 Zeichen, oder die Routine ist pausiert (siehe [Routinen bearbeiten und steuern](https://code.claude.com/docs/de/routines#edit-and-control-routines)). | | 401 | `authentication_error` | Kein Bearer-Token im `Authorization`-Header, oder das Token passt nicht zu dieser Routine. | | 403 | `permission_error` | Das Konto oder die Organisation hat keinen Zugriff auf diesen Endpunkt. | | 404 | `not_found_error` | Die Routine existiert nicht. | | 429 | `rate_limit_error` | Ein stündliches Auslöselimit für die Routine oder das Konto wurde erreicht. Die Antwort enthält einen `Retry-After`-Header, der angibt, wann das Zeitfenster zurückgesetzt wird. | | 500 | `api_error` | Ein unerwarteter Serverfehler. Versuche es mit exponentiellem Backoff erneut; wenn der Fehler weiterhin auftritt, wende dich mit der Request-ID an den Support. | | 503 | `overloaded_error` | Der Dienst ist vorübergehend überlastet. Versuche es nach einer kurzen Wartezeit erneut. Die Claude Platform gibt für diesen Fehlertyp 529 zurück; dieser Endpunkt gibt 503 zurück. | ## Authentifizierung Das Bearer-Token ist auf eine einzelne Routine beschränkt. Ein kompromittiertes Token kann nur diese Routine auslösen; es gewährt keinen Lesezugriff, keinen Zugriff auf andere Routinen und keinen Zugriff auf Kontodaten. Generiere und widerrufe Token in den API-Trigger-Einstellungen der Routine unter [claude.ai/code/routines](https://claude.ai/code/routines). Es gibt keine öffentliche API für die Token-Verwaltung. Das Generieren eines neuen Tokens widerruft das vorherige. ## Idempotenz Jede erfolgreiche Anfrage erstellt eine neue Sitzung. Es gibt keinen Idempotenz-Schlüssel. Wenn ein Webhook-Aufrufer die Anfrage wiederholt, erstellt der Endpunkt mehrere Sitzungen. ## Ratenlimits API-Auslösungen sind pro Stunde begrenzt: Jede Routine akzeptiert bis zu 30 Auslösungen pro Stunde (gemeinsam genutzt von API-Auslösungen, der Schaltfläche **Run now** in der Web-UI und Neuaktivierungen einmaliger Trigger), und jedes Konto kann über alle Routinen hinweg bis zu 100 API-Auslösungen pro Stunde durchführen. Die resultierenden Sitzungen verbrauchen dasselbe Claude Code-Abonnementkontingent wie interaktive Sitzungen. Wenn ein Limit erreicht ist, gibt der Endpunkt `429 rate_limit_error` mit einem `Retry-After`-Header zurück. Wie sich die Nutzung von Routinen auf Abonnementlimits und die Abrechnung zusätzlicher Nutzung auswirkt, erfährst du unter [Nutzung und Limits](https://code.claude.com/docs/de/routines#usage-and-limits) in der Claude Code-Dokumentation. ## SDK-Unterstützung Dieser Endpunkt ist nicht in den Anthropic-SDKs enthalten. Sein Token-Modell unterscheidet sich von der API-Key-Authentifizierung, und typische Aufrufer wie CI-Jobs und Alerting-Webhooks senden die Anfrage direkt. ## Siehe auch * [Arbeit mit Routinen automatisieren](https://code.claude.com/docs/de/routines) in der Claude Code-Dokumentation * [Fehler](https://platform.claude.com/docs/de/api/errors)