Attivare una routine tramite l'API

Claude Code è lo strumento di coding agentico di Anthropic. Claude Code sul web esegue sessioni di Claude Code su infrastruttura cloud gestita da Anthropic all'indirizzo claude.ai/code, e una routine è una configurazione salvata in quell'ambiente: un prompt, uno o più repository e connettori, impacchettati in modo da poter essere eseguiti senza supervisione secondo una pianificazione, in risposta a eventi GitHub o quando richiamati tramite HTTP.

Questo endpoint è il punto di ingresso HTTP. Inviare una richiesta POST a questo endpoint avvia una nuova esecuzione di una routine esistente e restituisce l'ID e l'URL della sessione risultante. I chiamanti tipici sono sistemi di allerta, pipeline CI e strumenti interni che devono avviare una sessione di Claude Code in modo programmatico.

Chiamare questo endpoint richiede un account claude.ai con un piano Pro, Max, Team o Enterprise con Claude Code sul web abilitato. Autenticati con un "bearer token" (token di tipo bearer) per singola routine creato nell'interfaccia web di Claude Code anziché con una chiave API di Claude.

Differenze rispetto alla Claude Platform

L'endpoint di attivazione delle routine appartiene alla superficie di prodotto di Claude Code, che differisce dalle API e dagli SDK della Claude Platform in alcuni aspetti:

Prima di iniziare

Per chiamare questo endpoint, hai bisogno di:

1. Una routine creata su claude.ai/code/routines.
2. Un bearer token generato per quella routine: apri la routine per modificarla, fai clic su Add another trigger sotto Select a trigger, scegli API, quindi fai clic su Generate token nella finestra modale. Il token viene mostrato una sola volta e non può essere recuperato in seguito.

Consulta Aggiungere un trigger API nella documentazione di Claude Code per la procedura di configurazione completa.

Attivare una routine

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

L'interfaccia web di Claude Code fornisce l'URL completo insieme al token quando aggiungi un trigger API, quindi la maggior parte delle integrazioni memorizza entrambi come segreti e chiama direttamente l'endpoint. Gli esempi seguenti mostrano una chiamata da shell e uno step di GitHub Actions che attiva la routine in caso di fallimento della 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 richiesta restituisce una risposta non appena la sessione viene creata. Non trasmette in streaming l'output della sessione né attende il completamento della sessione.

Header

Le integrazioni meno recenti che inviano un header anthropic-beta: experimental-cc-routine-2026-04-01 non sono interessate: l'endpoint accetta richieste sia con sia senza questo header.

Parametri di percorso

Body della richiesta

Il body è facoltativo. I campi sconosciuti nel body vengono ignorati.

Risposta

Una richiesta riuscita restituisce 200 OK con i dettagli della nuova sessione:

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

Errori

Gli errori utilizzano la struttura di errore standard di Anthropic:

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

Autenticazione

Il bearer token ha un ambito limitato a una singola routine. Un token compromesso può solo attivare quella routine; non concede alcun accesso in lettura, nessun accesso ad altre routine e nessun accesso ai dati dell'account.

Genera e revoca i token dalle impostazioni del trigger API della routine su claude.ai/code/routines. Non esiste un'API pubblica per la gestione dei token. La generazione di un nuovo token revoca quello precedente.

Idempotenza

Ogni richiesta riuscita crea una nuova sessione. Non esiste una chiave di idempotenza. Se un chiamante webhook riprova, l'endpoint crea più sessioni.

Limiti di velocità

Le attivazioni tramite API sono soggette a un "rate limit" (limite di velocità) orario: ogni routine accetta fino a 30 attivazioni all'ora (condivise tra attivazioni tramite API, il pulsante Run now nell'interfaccia web e le riattivazioni una tantum), e ogni account può effettuare fino a 100 attivazioni tramite API all'ora su tutte le routine. Le sessioni risultanti consumano lo stesso utilizzo dell'abbonamento Claude Code delle sessioni interattive. Quando viene raggiunto un limite, l'endpoint restituisce 429 rate_limit_error con un header Retry-After.

Per scoprire come l'utilizzo delle routine interagisce con i limiti dell'abbonamento e con la fatturazione dell'utilizzo extra, consulta Utilizzo e limiti nella documentazione di Claude Code.

Supporto SDK

Questo endpoint non è presente negli SDK di Anthropic. Il suo modello di token differisce dall'autenticazione tramite chiave API, e i chiamanti tipici come job CI e webhook di allerta inviano la richiesta direttamente.

Vedi anche

• Automatizzare il lavoro con le routine nella documentazione di Claude Code
• Errori