Trigger a routine via API

Claude Code is Anthropic's agentic coding tool. Claude Code on the web runs Claude Code sessions on Anthropic-managed cloud infrastructure at claude.ai/code, and a routine is a saved configuration there: a prompt, one or more repositories, and connectors, packaged so it can run unattended on a schedule, in response to GitHub events, or when called over HTTP.

This endpoint is the HTTP entry point. POSTing to it starts a new run of an existing routine and returns the resulting session ID and URL. Typical callers are alerting systems, CI pipelines, and internal tools that need to start a Claude Code session programmatically.

Calling this endpoint requires a claude.ai account on a Pro, Max, Team, or Enterprise plan with Claude Code on the web enabled. Authenticate with a per-routine bearer token created in the Claude Code web UI rather than an Anthropic API key.

Differences from the Claude Platform

The routine fire endpoint belongs to the Claude Code product surface, which differs from the Claude Platform APIs and SDKs in a few ways:

Before you begin

To call this endpoint, you need:

1. A routine created at claude.ai/code/routines
2. A bearer token generated for that routine: open the routine for editing, click Add another trigger under Select a trigger, choose API, then click Generate token in the modal. The token is shown once and cannot be retrieved later.

See Add an API trigger in the Claude Code documentation for the full setup walkthrough.

Trigger a routine

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

Every request must include the anthropic-beta: experimental-cc-routine-2026-04-01 header. Requests without it return 400 invalid_request_error.

The Claude Code web UI provides the full URL alongside the token when you add an API trigger, so most integrations store both as secrets and call the endpoint directly. The examples below show a shell call and a GitHub Actions step that triggers the routine on CI failure.

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

The request returns once the session is created. It does not stream session output or wait for the session to complete.

Headers

Path parameters

Request body

The body is optional. Unknown fields in the body are ignored.

Response

A successful request returns 200 OK with the new session details:

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

Errors

Errors use the standard Anthropic error envelope:

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

Authentication

The bearer token is scoped to a single routine. A compromised token can only trigger that routine; it grants no read access, no access to other routines, and no access to account data.

Generate and revoke tokens from the routine's API trigger settings at claude.ai/code/routines. There is no public API for token management. Generating a new token revokes the previous one.

Idempotency

Each successful request creates a new session. There is no idempotency key. If a webhook caller retries, the endpoint creates multiple sessions.

Rate limits

Routine runs count against a per-account daily allowance that varies by plan, and the resulting sessions draw down the same Claude Code subscription usage as interactive sessions. When either limit is reached, the endpoint returns 429 rate_limit_error with a Retry-After header. Organizations with extra usage enabled continue past the included allowance on metered overage.

Your remaining daily runs are shown at claude.ai/code/routines. For how routine usage interacts with subscription limits and extra usage billing, see Usage and limits in the Claude Code documentation.

SDK support

This endpoint is not in the Anthropic SDKs. Its token model differs from API key authentication, and typical callers such as CI jobs and alerting webhooks send the request directly.

See also

• Automate work with routines in the Claude Code documentation
• Beta headers
• Errors