--- title: Attivare una routine tramite l'API url: https://platform.claude.com/docs/it/api/claude-code/routines-fire description: Avvia una sessione di routine di Claude Code su richiesta inviando una richiesta POST autenticata. --- Questa è un'API sperimentale. La struttura di richieste e risposte, i limiti di velocità e la semantica dei token potrebbero cambiare. [Claude Code](https://code.claude.com/docs) è lo strumento di coding agentico di Anthropic. [Claude Code sul web](https://code.claude.com/docs/en/claude-code-on-the-web) esegue sessioni di Claude Code su infrastruttura cloud gestita da Anthropic all'indirizzo claude.ai/code, e una [routine](https://code.claude.com/docs/en/routines) è 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. Per chiamare questo endpoint è necessario un account claude.ai con un piano Pro, Max, Team o Enterprise con [Claude Code sul web](https://code.claude.com/docs/en/claude-code-on-the-web) abilitato. Autenticati con un "bearer token" (token di autenticazione) specifico per ogni 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: | Aspetto | Questo endpoint | API della Claude Platform | | ---------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------ | | Autenticazione | `Authorization: Bearer` con un token per singola routine (`sk-ant-oat01-...`) creato su [claude.ai/code/routines](https://claude.ai/code/routines) | `x-api-key` con una chiave API di Claude ottenuta dalla Claude Console | | Ambito del token | Una sola routine; nessun accesso in lettura | A livello di workspace | | Supporto SDK | Nessuno | Disponibile in tutti gli [SDK client](https://platform.claude.com/docs/it/cli-sdks-libraries/overview) | | Fatturazione | Utilizzo dell'abbonamento Claude Code su claude.ai | Utilizzo della Claude Platform | | Namespace del percorso | `/v1/claude_code/...` | `/v1/...` | | Stabilità | Sperimentale | Stabile o beta standard | ## Prima di iniziare Per chiamare questo endpoint, hai bisogno di: 1. Una routine creata su [claude.ai/code/routines](https://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](https://code.claude.com/docs/en/routines#add-an-api-trigger) nella documentazione di Claude Code per la procedura di configurazione completa. ## Attivare una routine ```http 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. ```bash cURL 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."}' ``` ```yaml GitHub Actions - 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 | Nome | Obbligatorio | Descrizione | | ------------------- | ------------------------- | ------------------------------------------------------------------------------------------------------------------------ | | `Authorization` | Sì | `Bearer `. Il token per singola routine creato nell'interfaccia web di Claude Code, con prefisso `sk-ant-oat01-`. | | `anthropic-version` | Sì | La [versione dell'API](https://platform.claude.com/docs/it/api/versioning). `2023-06-01` è l'unico valore accettato. | | `Content-Type` | Quando è presente un body | `application/json`. | 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 | Nome | Tipo | Descrizione | | ------------ | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `routine_id` | string | L'identificatore della routine. Nonostante il nome del parametro, il valore ha il prefisso `trig_` anziché `routine_`. Incluso nell'URL mostrato dalla finestra modale quando aggiungi un trigger API. | ### Body della richiesta | Campo | Tipo | Obbligatorio | Descrizione | | ------ | ------ | ------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `text` | string | No | Contesto iniziale per questa esecuzione, come il corpo di un avviso, una riga di log in errore o un git diff. Il valore è testo libero e non viene analizzato; se invii JSON o un altro payload strutturato, la routine lo riceve come stringa letterale. Viene passato alla routine insieme al suo prompt salvato. Massimo 65.536 caratteri. | Il body è facoltativo. I campi sconosciuti nel body vengono ignorati. ### Risposta Una richiesta riuscita restituisce `200 OK` con i dettagli della nuova sessione: ```json { "type": "routine_fire", "claude_code_session_id": "session_01HJKLMNOPQRSTUVWXYZ", "claude_code_session_url": "https://claude.ai/code/session_01HJKLMNOPQRSTUVWXYZ" } ``` | Campo | Tipo | Descrizione | | ------------------------- | ------ | ----------------------------------------------------------------------------------------------------------------------------------------- | | `type` | string | Sempre `routine_fire`. | | `claude_code_session_id` | string | L'ID della sessione di Claude Code creata per questa esecuzione. | | `claude_code_session_url` | string | Un link alla sessione su claude.ai. Aprilo in un browser per osservare l'esecuzione, rivedere le modifiche o continuare la conversazione. | ### Errori Gli errori utilizzano la [struttura di errore](https://platform.claude.com/docs/it/api/errors) standard di Anthropic: ```json { "type": "error", "error": { "type": "not_found_error", "message": "" } } ``` | Stato HTTP | Tipo di errore | Causa | | ---------- | ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | 400 | `invalid_request_error` | Header `anthropic-version` mancante o non supportato, `text` supera i 65.536 caratteri, oppure la routine è in pausa (consulta [Modificare e controllare le routine](https://code.claude.com/docs/en/routines#edit-and-control-routines)). | | 401 | `authentication_error` | Nessun bearer token nell'header `Authorization`, oppure il token non corrisponde a questa routine. | | 403 | `permission_error` | L'account o l'organizzazione non ha accesso a questo endpoint. | | 404 | `not_found_error` | La routine non esiste. | | 429 | `rate_limit_error` | È stato raggiunto un limite orario di attivazioni per la routine o per l'account. La risposta include un header `Retry-After` che indica quando la finestra viene reimpostata. | | 500 | `api_error` | Un errore imprevisto del server. Riprova con un "exponential backoff" (attesa esponenziale tra i tentativi); se l'errore persiste, contatta il supporto indicando l'ID della richiesta. | | 503 | `overloaded_error` | Il servizio è temporaneamente sovraccarico. Riprova dopo una breve attesa. La Claude Platform restituisce 529 per questo tipo di errore; questo endpoint restituisce 503. | ## 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](https://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](https://code.claude.com/docs/en/routines#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 job CI e webhook di allerta inviano la richiesta direttamente. ## Vedi anche * [Automatizzare il lavoro con le routine](https://code.claude.com/docs/en/routines) nella documentazione di Claude Code * [Errori](https://platform.claude.com/docs/it/api/errors)