Eine Routine per API auslösen

Claude Code ist Anthropics agentisches Coding-Tool. Claude Code on the web führt Claude Code-Sessions auf von Anthropic verwalteter Cloud-Infrastruktur unter claude.ai/code aus, und eine Routine ist dort eine gespeicherte Konfiguration: ein Prompt, ein oder mehrere Repositories und Connectors, so verpackt, dass sie unbeaufsichtigt nach einem Zeitplan, als Reaktion auf GitHub-Events oder bei einem Aufruf über HTTP ausgeführt werden kann.

Dieser Endpunkt ist der HTTP-Einstiegspunkt. Ein POST an ihn startet einen neuen Durchlauf einer bestehenden Routine und gibt die resultierende Session-ID und URL zurück. Typische Aufrufer sind Alerting-Systeme, CI-Pipelines und interne Tools, die eine Claude Code-Session programmatisch starten müssen.

Der Aufruf dieses Endpunkts erfordert ein claude.ai-Konto mit einem Pro-, Max-, Team- oder Enterprise-Plan, bei dem Claude Code on the web aktiviert ist. Authentifiziere dich mit einem routinenspezifischen Bearer-Token, das in der Claude Code-Web-UI erstellt wurde, und nicht mit einem Claude-API-Key.



Unterschiede zur Claude Platform

Der Routine-Fire-Endpunkt gehört zur Claude Code-Produktoberfläche, die sich in einigen Punkten von den Claude Platform-APIs und -SDKs unterscheidet:



Bevor du beginnst

Um diesen Endpunkt aufzurufen, benötigst du:

1. Eine Routine, die unter claude.ai/code/routines erstellt wurde
2. Ein Bearer-Token, das für diese Routine generiert wurde: Öffne die Routine zum Bearbeiten, klicke unter Select a trigger auf Add another trigger, wähle API und klicke dann im Modal auf Generate token. Das Token wird einmalig angezeigt und kann später nicht mehr abgerufen werden.

Siehe Add an API trigger in der Claude Code-Dokumentation für die vollständige Einrichtungsanleitung.



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 diesen Header 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-Step, der die Routine bei einem CI-Fehler 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 Session erstellt wurde. Sie streamt keine Session-Ausgabe und wartet nicht auf den Abschluss der Session.



Header



Pfadparameter



Request-Body

Der Body ist optional. Unbekannte Felder im Body werden ignoriert.



Response

Eine erfolgreiche Anfrage gibt 200 OK mit den Details der neuen Session zurück:

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



Fehler

Fehler verwenden das standardmäßige Anthropic-Error-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 Tokens 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 Session. Es gibt keinen Idempotenz-Key. Wenn ein Webhook-Aufrufer einen Retry durchführt, erstellt der Endpunkt mehrere Sessions.



Ratenlimits

Routine-Durchläufe werden auf ein tägliches Kontingent pro Konto angerechnet, das je nach Plan variiert, und die resultierenden Sessions verbrauchen dieselbe Claude Code-Abonnementnutzung wie interaktive Sessions. Wenn eines der beiden Limits erreicht ist, gibt der Endpunkt 429 rate_limit_error mit einem Retry-After-Header zurück. Organisationen mit aktivierter zusätzlicher Nutzung überschreiten das enthaltene Kontingent mit nutzungsbasierter Abrechnung.

Deine verbleibenden täglichen Durchläufe werden unter claude.ai/code/routines angezeigt. Wie die Routine-Nutzung mit Abonnementlimits und der Abrechnung zusätzlicher Nutzung zusammenhängt, erfährst du unter 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

• Automate work with routines in der Claude Code-Dokumentation
• Beta-Header
• Fehler