API를 통해 루틴 트리거하기

Claude Code는 Anthropic의 에이전틱 코딩 도구입니다. Claude Code on the web은 claude.ai/code에서 Anthropic이 관리하는 클라우드 인프라에서 Claude Code 세션을 실행하며, 루틴은 그곳에 저장된 구성입니다. 즉, 프롬프트, 하나 이상의 리포지토리, 커넥터를 패키징하여 일정에 따라, GitHub 이벤트에 대한 응답으로, 또는 HTTP를 통해 호출될 때 무인으로 실행할 수 있도록 한 것입니다.

이 엔드포인트는 HTTP 진입점입니다. 여기에 POST 요청을 보내면 기존 루틴의 새 실행이 시작되고 결과 세션 ID와 URL이 반환됩니다. 일반적인 호출자는 알림 시스템, CI 파이프라인, 그리고 Claude Code 세션을 프로그래밍 방식으로 시작해야 하는 내부 도구입니다.

이 엔드포인트를 호출하려면 Claude Code on the web이 활성화된 Pro, Max, Team 또는 Enterprise 플랜의 claude.ai 계정이 필요합니다. Claude API 키가 아닌 Claude Code 웹 UI에서 생성한 루틴별 베어러 토큰으로 인증하세요.



Claude Platform과의 차이점

루틴 실행 엔드포인트는 Claude Code 제품 영역에 속하며, 이는 Claude Platform API 및 SDK와 몇 가지 면에서 다릅니다.



시작하기 전에

이 엔드포인트를 호출하려면 다음이 필요합니다.

1. claude.ai/code/routines에서 생성한 루틴
2. 해당 루틴에 대해 생성된 베어러 토큰: 루틴을 편집 모드로 열고, Select a trigger 아래에서 Add another trigger를 클릭한 다음, API를 선택하고, 모달에서 Generate token을 클릭하세요. 토큰은 한 번만 표시되며 나중에 다시 확인할 수 없습니다.

전체 설정 과정은 Claude Code 문서의 API 트리거 추가하기를 참조하세요.



루틴 트리거하기

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

모든 요청에는 anthropic-beta: experimental-cc-routine-2026-04-01 헤더가 포함되어야 합니다. 이 헤더가 없는 요청은 400 invalid_request_error를 반환합니다.

API 트리거를 추가할 때 Claude Code 웹 UI는 토큰과 함께 전체 URL을 제공하므로, 대부분의 통합에서는 둘 다 시크릿으로 저장하고 엔드포인트를 직접 호출합니다. 아래 예제는 셸 호출과 CI 실패 시 루틴을 트리거하는 GitHub Actions 단계를 보여줍니다.

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

요청은 세션이 생성되면 반환됩니다. 세션 출력을 스트리밍하거나 세션이 완료될 때까지 기다리지 않습니다.



헤더



경로 매개변수



요청 본문

본문은 선택 사항입니다. 본문의 알 수 없는 필드는 무시됩니다.



응답

성공적인 요청은 새 세션 세부 정보와 함께 200 OK를 반환합니다.

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



오류

오류는 표준 Anthropic 오류 엔벨로프를 사용합니다.

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



인증

베어러 토큰은 단일 루틴으로 범위가 제한됩니다. 토큰이 유출되더라도 해당 루틴만 트리거할 수 있으며, 읽기 액세스, 다른 루틴에 대한 액세스, 계정 데이터에 대한 액세스는 부여되지 않습니다.

claude.ai/code/routines의 루틴 API 트리거 설정에서 토큰을 생성하고 폐기하세요. 토큰 관리를 위한 공개 API는 없습니다. 새 토큰을 생성하면 이전 토큰이 폐기됩니다.



멱등성

성공적인 각 요청은 새 세션을 생성합니다. 멱등성 키는 없습니다. 웹훅 호출자가 재시도하면 엔드포인트는 여러 세션을 생성합니다.



속도 제한

루틴 실행은 플랜에 따라 달라지는 계정별 일일 허용량에 포함되며, 결과 세션은 대화형 세션과 동일한 Claude Code 구독 사용량을 차감합니다. 두 한도 중 하나에 도달하면 엔드포인트는 Retry-After 헤더와 함께 429 rate_limit_error를 반환합니다. 추가 사용량이 활성화된 조직은 포함된 허용량을 초과하여 종량제 초과 사용으로 계속 진행합니다.

남은 일일 실행 횟수는 claude.ai/code/routines에 표시됩니다. 루틴 사용량이 구독 한도 및 추가 사용량 과금과 어떻게 상호작용하는지에 대해서는 Claude Code 문서의 사용량 및 한도를 참조하세요.



SDK 지원

이 엔드포인트는 Anthropic SDK에 포함되어 있지 않습니다. 토큰 모델이 API 키 인증과 다르며, CI 작업 및 알림 웹훅과 같은 일반적인 호출자는 요청을 직접 전송합니다.



참고 항목

• Claude Code 문서의 루틴으로 작업 자동화하기
• 베타 헤더
• 오류