Déclencher une routine via l'API

Claude Code est l'outil de codage agentique d'Anthropic. Claude Code sur le web exécute des sessions Claude Code sur une infrastructure cloud gérée par Anthropic à l'adresse claude.ai/code, et une routine est une configuration enregistrée à cet endroit : un prompt, un ou plusieurs dépôts et des connecteurs, regroupés de manière à pouvoir s'exécuter sans surveillance selon un calendrier, en réponse à des événements GitHub ou lorsqu'elle est appelée via HTTP.

Ce point de terminaison est le point d'entrée HTTP. Envoyer une requête POST à ce point de terminaison démarre une nouvelle exécution d'une routine existante et renvoie l'ID et l'URL de la session résultante. Les appelants typiques sont des systèmes d'alerte, des pipelines CI et des outils internes qui doivent démarrer une session Claude Code de manière programmatique.

L'appel de ce point de terminaison nécessite un compte claude.ai sur un forfait Pro, Max, Team ou Enterprise avec Claude Code sur le web activé. Authentifiez-vous avec un jeton « bearer » propre à chaque routine, créé dans l'interface web de Claude Code, plutôt qu'avec une clé API Claude.



Différences avec la Claude Platform

Le point de terminaison de déclenchement de routine appartient à la surface produit Claude Code, qui diffère des API et SDK de la Claude Platform à plusieurs égards :



Avant de commencer

Pour appeler ce point de terminaison, vous avez besoin de :

1. Une routine créée sur claude.ai/code/routines
2. Un jeton bearer généré pour cette routine : ouvrez la routine pour la modifier, cliquez sur Add another trigger sous Select a trigger, choisissez API, puis cliquez sur Generate token dans la fenêtre modale. Le jeton n'est affiché qu'une seule fois et ne peut pas être récupéré ultérieurement.

Consultez Ajouter un déclencheur API dans la documentation Claude Code pour la procédure de configuration complète.



Déclencher une routine

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

Chaque requête doit inclure l'en-tête anthropic-beta: experimental-cc-routine-2026-04-01. Les requêtes sans cet en-tête renvoient 400 invalid_request_error.

L'interface web de Claude Code fournit l'URL complète avec le jeton lorsque vous ajoutez un déclencheur API, de sorte que la plupart des intégrations stockent les deux en tant que secrets et appellent directement le point de terminaison. Les exemples ci-dessous montrent un appel shell et une étape GitHub Actions qui déclenche la routine en cas d'échec de la CI.

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\"}"

La requête retourne une fois la session créée. Elle ne diffuse pas la sortie de la session en streaming et n'attend pas que la session se termine.



En-têtes



Paramètres de chemin



Corps de la requête

Le corps est facultatif. Les champs inconnus dans le corps sont ignorés.



Réponse

Une requête réussie renvoie 200 OK avec les détails de la nouvelle session :

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



Erreurs

Les erreurs utilisent l'enveloppe d'erreur standard d'Anthropic :

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



Authentification

Le jeton bearer est limité à une seule routine. Un jeton compromis ne peut déclencher que cette routine ; il n'accorde aucun accès en lecture, aucun accès aux autres routines et aucun accès aux données du compte.

Générez et révoquez des jetons depuis les paramètres de déclencheur API de la routine sur claude.ai/code/routines. Il n'existe pas d'API publique pour la gestion des jetons. La génération d'un nouveau jeton révoque le précédent.



Idempotence

Chaque requête réussie crée une nouvelle session. Il n'y a pas de clé d'idempotence. Si un appelant webhook effectue de nouvelles tentatives, le point de terminaison crée plusieurs sessions.



Limites de débit

Les exécutions de routines sont décomptées d'une allocation quotidienne par compte qui varie selon le forfait, et les sessions résultantes consomment la même utilisation d'abonnement Claude Code que les sessions interactives. Lorsque l'une ou l'autre limite est atteinte, le point de terminaison renvoie 429 rate_limit_error avec un en-tête Retry-After. Les organisations ayant activé l'utilisation supplémentaire continuent au-delà de l'allocation incluse avec une facturation au dépassement mesuré.

Vos exécutions quotidiennes restantes sont affichées sur claude.ai/code/routines. Pour comprendre comment l'utilisation des routines interagit avec les limites d'abonnement et la facturation de l'utilisation supplémentaire, consultez Utilisation et limites dans la documentation Claude Code.



Prise en charge SDK

Ce point de terminaison n'est pas inclus dans les SDK Anthropic. Son modèle de jeton diffère de l'authentification par clé API, et les appelants typiques tels que les tâches CI et les webhooks d'alerte envoient la requête directement.



Voir aussi

• Automatiser le travail avec des routines dans la documentation Claude Code
• En-têtes bêta
• Erreurs