Eine Routine über die API auslösen

Claude Code ist Anthropics agentisches Coding-Tool. Claude Code im Web führt Claude Code-Sitzungen auf von Anthropic verwalteter Cloud-Infrastruktur unter claude.ai/code aus, und eine „routine“ (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.

Der Aufruf dieses Endpunkts erfordert ein claude.ai-Konto mit einem Pro-, Max-, Team- oder Enterprise-Plan, bei dem Claude Code im Web aktiviert ist. Authentifiziere dich mit einem pro Routine erstellten „bearer token“ (Bearer-Token), das in der Claude Code-Web-UI erzeugt wird, statt 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:

Bevor du beginnst

Um diesen Endpunkt aufzurufen, benötigst du:

1. Eine Routine, die unter 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 in der Claude Code-Dokumentation.

Eine Routine auslösen

POST https://api.anthropic.com/v1/claude_code/routines/{routine_id}/fire

Jede Anfrage muss den Header anthropic-beta: experimental-cc-routine-2026-04-01 enthalten. Anfragen ohne ihn geben 400 invalid_request_error zurück.

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.

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 "anthropic-beta: experimental-cc-routine-2026-04-01" \
  -H "Content-Type: application/json" \
  -d '{"text": "Sentry alert SEN-4521 fired in prod. Stack trace attached."}'

- 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 "anthropic-beta: experimental-cc-routine-2026-04-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

Pfadparameter

Request-Body

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:

{
  "type": "routine_fire",
  "claude_code_session_id": "session_01HJKLMNOPQRSTUVWXYZ",
  "claude_code_session_url": "https://claude.ai/code/session_01HJKLMNOPQRSTUVWXYZ"
}

Fehler

Fehler verwenden den standardmäßigen Anthropic-Fehler-Envelope:

{
  "type": "error",
  "error": {
    "type": "not_found_error",
    "message": "<string>"
  }
}

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. 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

Routine-Läufe werden auf ein tägliches Kontingent pro Konto angerechnet, das je nach Plan variiert, und die resultierenden Sitzungen verbrauchen dieselbe Claude Code-Abonnementnutzung wie interaktive Sitzungen. Wenn eines der beiden Limits erreicht ist, gibt der Endpunkt 429 rate_limit_error mit einem Retry-After-Header zurück. Organisationen mit aktivierter Zusatznutzung fahren über das enthaltene Kontingent hinaus mit nutzungsbasiert abgerechneter Mehrnutzung fort.

Deine verbleibenden täglichen Läufe siehst du unter claude.ai/code/routines. Wie die Routine-Nutzung mit Abonnementlimits und der Abrechnung von Zusatznutzung zusammenspielt, erfährst du unter Nutzung und 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 in der Claude Code-Dokumentation
• Beta-Header
• Fehler