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 y est une configuration enregistrée : 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 lors d'un appel via HTTP.

Ce point de terminaison est le point d'entrée HTTP. Y envoyer une requête POST 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 par programmation.

L'appel de ce point de terminaison nécessite un compte claude.ai avec un forfait Pro, Max, Team ou Enterprise sur lequel Claude Code sur le web est activé. Authentifiez-vous avec un « bearer token » (jeton porteur) 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 sur plusieurs points :

Avant de commencer

Pour appeler ce point de terminaison, vous avez besoin :

1. D'une routine créée sur claude.ai/code/routines.
2. D'un jeton porteur généré pour cette routine : ouvrez la routine en mode édition, 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

L'interface web de Claude Code fournit l'URL complète en même temps que le jeton lorsque vous ajoutez un déclencheur API ; la plupart des intégrations stockent donc les deux en tant que secrets et appellent directement le point de terminaison. Les exemples suivants 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 "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\"}"

La requête renvoie une réponse dès que la session est 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

Les intégrations plus anciennes qui envoient un en-tête anthropic-beta: experimental-cc-routine-2026-04-01 ne sont pas affectées : le point de terminaison accepte les requêtes avec ou sans cet en-tête.

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 porteur 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 les jetons depuis les paramètres du 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 déclenchements via l'API sont limités par heure. Chaque routine accepte jusqu'à 30 déclenchements par heure, partagés entre les déclenchements via l'API, le bouton Run now de l'interface web et les réarmements ponctuels. Chaque compte peut effectuer jusqu'à 100 déclenchements via l'API par heure sur l'ensemble de ses routines. Les sessions résultantes consomment l'utilisation de l'abonnement Claude Code de la même manière que les sessions interactives. Lorsqu'une limite est atteinte, le point de terminaison renvoie 429 rate_limit_error avec un en-tête Retry-After.

Pour savoir 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 de Claude Code.

Prise en charge SDK

Ce point de terminaison ne figure pas 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 les routines dans la documentation de Claude Code
• Erreurs