Attivare una routine tramite API

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

Questo endpoint è il punto di ingresso HTTP. Inviare una POST ad esso avvia una nuova esecuzione di una routine esistente e restituisce l'ID e l'URL della sessione risultante. I chiamanti tipici sono sistemi di alerting, 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 on the web abilitato. Autenticati con un bearer token specifico per routine creato nell'interfaccia web di Claude Code anziché con una chiave API di Claude.



Differenze rispetto alla Claude Platform

L'endpoint di attivazione della 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 Add an API trigger nella documentazione di Claude Code per la procedura completa di configurazione.



Attivare una routine

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

Ogni richiesta deve includere l'header anthropic-beta: experimental-cc-routine-2026-04-01. Le richieste senza di esso restituiscono 400 invalid_request_error.

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 secret e chiama l'endpoint direttamente. 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 "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 richiesta ritorna una volta che la sessione è stata creata. Non trasmette in streaming l'output della sessione né attende il completamento della sessione.



Header



Parametri del percorso



Body della richiesta

Il body è opzionale. 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 l'envelope di errore standard di Anthropic:

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



Autenticazione

Il bearer token è limitato a una singola routine. Un token compromesso può solo attivare quella routine; non concede 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. Generare 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 esecuzioni delle routine vengono conteggiate rispetto a una quota giornaliera per account che varia in base al piano, e le sessioni risultanti consumano lo stesso utilizzo dell'abbonamento Claude Code delle sessioni interattive. Quando uno dei due limiti viene raggiunto, l'endpoint restituisce 429 rate_limit_error con un header Retry-After. Le organizzazioni con l'utilizzo extra abilitato continuano oltre la quota inclusa con addebito a consumo per l'eccedenza.

Le esecuzioni giornaliere rimanenti sono mostrate su claude.ai/code/routines. Per sapere come l'utilizzo delle routine interagisce con i limiti dell'abbonamento e la fatturazione dell'utilizzo extra, consulta Usage and limits 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 i job CI e i webhook di alerting inviano la richiesta direttamente.



Vedi anche

• Automate work with routines nella documentazione di Claude Code
• Header beta
• Errori