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

Ogni richiesta deve includere l'header anthropic-beta: experimental-cc-routine-2026-04-01. Le richieste che ne sono prive 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 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 "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 restituisce una risposta non appena la sessione viene creata. Non trasmette in streaming l'output della sessione né attende il completamento della sessione.

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 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 viene raggiunto uno dei due limiti, l'endpoint restituisce 429 rate_limit_error con un header Retry-After. Le organizzazioni con utilizzo extra abilitato proseguono oltre la quota inclusa con eccedenza a consumo.

Visualizza le esecuzioni giornaliere rimanenti su claude.ai/code/routines. Per scoprire come l'utilizzo delle routine interagisce con i limiti dell'abbonamento e 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
• Header beta
• Errori