Acionar uma rotina através da API

O Claude Code é a ferramenta de codificação agêntica da Anthropic. O Claude Code na web executa sessões do Claude Code na infraestrutura de nuvem gerenciada pela Anthropic em claude.ai/code. Uma "routine" (rotina) é uma configuração salva nesse ambiente. Ela reúne um prompt, um ou mais repositórios e conectores, empacotados para serem executados sem supervisão: em um agendamento, em resposta a eventos do GitHub ou quando chamados via HTTP.

Este endpoint é o ponto de entrada HTTP. Um POST para ele inicia uma nova execução de uma rotina existente e retorna o ID e a URL da sessão resultante. Os 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 o Claude Code na web habilitado. Autentique-se com um "bearer token" (token de portador) por 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 disparo de rotinas pertence à superfície de produto do Claude Code. Ele 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 na janela modal. O token é exibido uma única vez e não pode ser recuperado posteriormente.

Consulte Adicionar um gatilho de API 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

Ao adicionar um gatilho de API, a interface web do Claude Code fornece a URL completa junto com o token. Por isso, a maioria das integrações armazena ambos como segredos e chama o endpoint diretamente. Os exemplos a seguir mostram uma chamada via shell e uma etapa do GitHub Actions que aciona a rotina quando o CI falha.

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\"}"

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

Cabeçalhos

Integrações mais antigas que enviam o cabeçalho anthropic-beta: experimental-cc-routine-2026-04-01 não são afetadas: o endpoint aceita requisições com ou sem ele.

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 restrito a uma única rotina. Um token comprometido só pode acionar essa rotina; ele não concede acesso de leitura, nem acesso a outras rotinas, nem acesso a dados da conta.

Gere e revogue tokens nas configurações do 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 criará múltiplas sessões.

Limites de taxa

Os disparos via API são limitados por hora: cada rotina aceita até 30 disparos por hora (limite compartilhado entre os disparos via API, o botão Run now na interface web e os rearmes de execução única), e cada conta pode fazer até 100 disparos via API por hora, somando todas as rotinas. As sessões resultantes consomem o mesmo uso da assinatura do Claude Code que as sessões interativas. Quando um limite é atingido, o endpoint retorna 429 rate_limit_error com um cabeçalho Retry-After.

Para saber como o uso de rotinas interage com os limites da assinatura e com a cobrança de uso extra, consulte Uso e limites 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

• Automatize o trabalho com rotinas na documentação do Claude Code
• Erros