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 em infraestrutura de nuvem gerenciada pela Anthropic em claude.ai/code, e uma rotina é uma configuração salva ali: um prompt, um ou mais repositórios e conectores, empacotados para que possam ser 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. 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. 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 rotina pertence à superfície de produto do Claude Code, que difere das APIs e SDKs da Claude Platform de algumas maneiras:

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

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, portanto a maioria das integrações armazena ambos como segredos e chama o endpoint diretamente. Os exemplos a seguir 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 aguarda a conclusão da sessão.

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 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

As execuções de rotina são contabilizadas em uma cota diária por conta que varia de acordo com o plano, e as sessões resultantes consomem o mesmo uso da 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 excedente medido.

Veja suas execuções diárias restantes em claude.ai/code/routines. Para saber como o uso de rotinas interage com os limites da assinatura e 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
• Cabeçalhos beta
• Erros