Acionar uma rotina via API

Claude Code é a ferramenta de codificação agêntica da Anthropic. Claude Code on the web executa sessões do Claude Code em infraestrutura de nuvem gerenciada pela Anthropic em claude.ai/code, e uma rotina é uma configuração salva lá: um prompt, um ou mais repositórios e conectores, empacotados para que possam ser executados sem supervisão em um cronograma, em resposta a eventos do GitHub ou quando chamados via HTTP.

Este endpoint é o ponto de entrada HTTP. Fazer um POST para ele inicia uma nova execução de uma rotina existente e retorna o ID e a URL da sessão resultante. Chamadores típicos são sistemas de alerta, pipelines de CI e ferramentas internas que precisam iniciar uma sessão do Claude Code programaticamente.

Chamar este endpoint requer uma conta claude.ai em um plano Pro, Max, Team ou Enterprise com Claude Code on the web habilitado. Autentique-se com um bearer token específico da rotina criado na interface web do Claude Code, em vez de uma chave de API do Claude.



Diferenças em relação à Claude Platform

O endpoint de acionamento de rotina pertence à superfície do produto Claude Code, que difere das APIs e SDKs da Claude Platform em alguns aspectos:



Antes de começar

Para chamar este endpoint, você precisa de:

1. Uma rotina criada em claude.ai/code/routines
2. Um bearer token gerado para essa rotina: abra a rotina para edição, clique em Add another trigger em Select a trigger, escolha API e, em seguida, clique em Generate token no modal. O token é exibido uma única vez e não pode ser recuperado posteriormente.

Consulte Add an API trigger na documentação do Claude Code para o passo a passo completo de configuração.



Acionar uma rotina

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

Toda requisição deve incluir o cabeçalho anthropic-beta: experimental-cc-routine-2026-04-01. Requisições sem ele retornam 400 invalid_request_error.

A interface web do Claude Code fornece a URL completa junto com o token quando você adiciona um gatilho de API, então a maioria das integrações armazena ambos como segredos e chama o endpoint diretamente. Os exemplos abaixo mostram uma chamada de shell e uma etapa do GitHub Actions que aciona a rotina em caso de falha de 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\"}"

A requisição retorna assim que a sessão é criada. Ela não faz streaming da saída da sessão nem espera a sessão ser concluída.



Cabeçalhos



Parâmetros de caminho



Corpo da requisição

O corpo é opcional. Campos desconhecidos no corpo são ignorados.



Resposta

Uma requisição bem-sucedida retorna 200 OK com os detalhes da nova sessão:

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



Erros

Os erros usam o envelope de erro padrão da Anthropic:

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



Autenticação

O bearer token tem escopo limitado a uma única rotina. Um token comprometido só pode acionar essa rotina; ele não concede acesso de leitura, acesso a outras rotinas nem acesso a dados da conta.

Gere e revogue tokens nas configurações de gatilho de API da rotina em claude.ai/code/routines. Não há API pública para gerenciamento de tokens. Gerar um novo token revoga o anterior.



Idempotência

Cada requisição bem-sucedida cria uma nova sessão. Não há chave de idempotência. Se um chamador de webhook fizer novas tentativas, o endpoint cria múltiplas sessões.



Limites de taxa

As execuções de rotina contam para uma cota diária por conta que varia conforme o plano, e as sessões resultantes consomem o mesmo uso de assinatura do Claude Code que as sessões interativas. Quando qualquer um dos limites é atingido, o endpoint retorna 429 rate_limit_error com um cabeçalho Retry-After. Organizações com uso extra habilitado continuam além da cota incluída com cobrança por excedente medido.

Suas execuções diárias restantes são exibidas em claude.ai/code/routines. Para saber como o uso de rotinas interage com os limites de assinatura e a cobrança de uso extra, consulte Usage and limits na documentação do Claude Code.



Suporte a SDK

Este endpoint não está nos SDKs da Anthropic. Seu modelo de token difere da autenticação por chave de API, e chamadores típicos, como jobs de CI e webhooks de alerta, enviam a requisição diretamente.



Veja também

• Automate work with routines na documentação do Claude Code
• Cabeçalhos beta
• Erros