--- title: Acionar uma rotina através da API url: https://platform.claude.com/docs/pt-BR/api/claude-code/routines-fire description: Inicie uma sessão de rotina do Claude Code sob demanda enviando uma requisição POST autenticada. --- Esta é uma API experimental. Os formatos de requisição e resposta, os limites de taxa e a semântica dos tokens podem mudar. O [Claude Code](https://code.claude.com/docs) é a ferramenta de codificação agêntica da Anthropic. O [Claude Code na web](https://code.claude.com/docs/en/claude-code-on-the-web) executa sessões do Claude Code na infraestrutura de nuvem gerenciada pela Anthropic em claude.ai/code. Uma "[routine](https://code.claude.com/docs/en/routines)" (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](https://code.claude.com/docs/en/claude-code-on-the-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: | Aspecto | Este endpoint | APIs da Claude Platform | | -------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------ | | Autenticação | `Authorization: Bearer` com um token por rotina (`sk-ant-oat01-...`) criado em [claude.ai/code/routines](https://claude.ai/code/routines) | `x-api-key` com uma chave de API do Claude obtida no Claude Console | | Escopo do token | Apenas uma rotina; sem acesso de leitura | Nível de workspace | | Suporte a SDK | Nenhum | Disponível em todos os [SDKs de cliente](https://platform.claude.com/docs/pt-BR/cli-sdks-libraries/overview) | | Cobrança | Uso da assinatura do Claude Code no claude.ai | Uso da Claude Platform | | Namespace do caminho | `/v1/claude_code/...` | `/v1/...` | | Estabilidade | Experimental | Estável ou beta padrão | ## Antes de começar Para chamar este endpoint, você precisa de: 1. Uma rotina criada em [claude.ai/code/routines](https://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](https://code.claude.com/docs/en/routines#add-an-api-trigger) na documentação do Claude Code para o passo a passo completo de configuração. ## Acionar uma rotina ```http 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. ```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\"}" ``` 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 | Nome | Obrigatório | Descrição | | ------------------- | --------------- | -------------------------------------------------------------------------------------------------------------- | | `Authorization` | Sim | `Bearer `. O token por rotina criado na interface web do Claude Code, com o prefixo `sk-ant-oat01-`. | | `anthropic-version` | Sim | A [versão da API](https://platform.claude.com/docs/pt-BR/api/versioning). `2023-06-01` é o único valor aceito. | | `Content-Type` | Quando há corpo | `application/json`. | 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 | Nome | Tipo | Descrição | | ------------ | ------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `routine_id` | string | O identificador da rotina. Apesar do nome do parâmetro, o valor tem o prefixo `trig_` em vez de `routine_`. Incluído na URL que a janela modal exibe quando você adiciona um gatilho de API. | ### Corpo da requisição | Campo | Tipo | Obrigatório | Descrição | | ------ | ------ | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `text` | string | Não | Contexto inicial para esta execução, como o corpo de um alerta, uma linha de log com falha ou um git diff. O valor é texto livre e não é analisado; se você enviar JSON ou outro payload estruturado, a rotina o recebe como uma string literal. Passado para a rotina junto com seu prompt salvo. Máximo de 65.536 caracteres. | 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: ```json { "type": "routine_fire", "claude_code_session_id": "session_01HJKLMNOPQRSTUVWXYZ", "claude_code_session_url": "https://claude.ai/code/session_01HJKLMNOPQRSTUVWXYZ" } ``` | Campo | Tipo | Descrição | | ------------------------- | ------ | ---------------------------------------------------------------------------------------------------------------------------------- | | `type` | string | Sempre `routine_fire`. | | `claude_code_session_id` | string | O ID da sessão do Claude Code criada para esta execução. | | `claude_code_session_url` | string | Um link para a sessão em claude.ai. Abra-o em um navegador para acompanhar a execução, revisar alterações ou continuar a conversa. | ### Erros Os erros usam o [envelope de erro](https://platform.claude.com/docs/pt-BR/api/errors) padrão da Anthropic: ```json { "type": "error", "error": { "type": "not_found_error", "message": "" } } ``` | Status HTTP | Tipo de erro | Causa | | ----------- | ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | 400 | `invalid_request_error` | Uma destas situações: o cabeçalho `anthropic-version` está ausente ou não é suportado; `text` excede 65.536 caracteres; ou a rotina está pausada (consulte [Editar e controlar rotinas](https://code.claude.com/docs/en/routines#edit-and-control-routines)). | | 401 | `authentication_error` | Não há bearer token no cabeçalho `Authorization`, ou o token não corresponde a esta rotina. | | 403 | `permission_error` | A conta ou organização não tem acesso a este endpoint. | | 404 | `not_found_error` | A rotina não existe. | | 429 | `rate_limit_error` | Um limite horário de disparos da rotina ou da conta foi atingido. A resposta inclui um cabeçalho `Retry-After` que indica quando a janela é reiniciada. | | 500 | `api_error` | Um erro inesperado do servidor. Tente novamente com backoff exponencial. Se o erro persistir, entre em contato com o suporte informando o ID da requisição. | | 503 | `overloaded_error` | O serviço está temporariamente sobrecarregado. Tente novamente após um breve intervalo. A Claude Platform retorna 529 para este tipo de erro; este endpoint retorna 503. | ## 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](https://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](https://code.claude.com/docs/en/routines#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 * [Automatize o trabalho com rotinas](https://code.claude.com/docs/en/routines) na documentação do Claude Code * [Erros](https://platform.claude.com/docs/pt-BR/api/errors)