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.

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

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

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

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

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

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 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
• Fehler