--- title: API를 통해 루틴 트리거하기 url: https://platform.claude.com/docs/ko/api/claude-code/routines-fire description: 인증된 POST 요청을 보내 Claude Code 루틴 세션을 온디맨드로 시작합니다. --- 이것은 실험적인 API입니다. 요청 및 응답 형식, "rate limit"(속도 제한), 토큰 의미 체계는 변경될 수 있습니다. [Claude Code](https://code.claude.com/docs)는 Anthropic의 에이전트형 코딩 도구입니다. [웹용 Claude Code](https://code.claude.com/docs/ko/claude-code-on-the-web)는 claude.ai/code에서 Anthropic이 관리하는 클라우드 인프라 위에서 Claude Code 세션을 실행하며, "routine"(루틴)은 그곳에 저장된 구성입니다. 즉, 프롬프트, 하나 이상의 리포지토리, 커넥터를 패키징하여 일정에 따라, GitHub 이벤트에 대한 응답으로, 또는 HTTP를 통해 호출될 때 무인으로 실행될 수 있도록 한 것입니다. 자세한 내용은 [루틴](https://code.claude.com/docs/ko/routines)을 참조하세요. 이 엔드포인트는 HTTP 진입점입니다. 여기에 POST 요청을 보내면 기존 루틴의 새 실행이 시작되고 결과 세션 ID와 URL이 반환됩니다. 일반적인 호출자는 Claude Code 세션을 프로그래밍 방식으로 시작해야 하는 알림 시스템, CI 파이프라인, 내부 도구입니다. 이 엔드포인트를 호출하려면 Pro, Max, Team 또는 Enterprise 플랜의 claude.ai 계정에서 [웹용 Claude Code](https://code.claude.com/docs/ko/claude-code-on-the-web)가 활성화되어 있어야 합니다. 인증에는 Claude API 키가 아니라 Claude Code 웹 UI에서 생성한 루틴별 "bearer token"(베어러 토큰)을 사용합니다. ## Claude Platform과의 차이점 루틴 실행 엔드포인트는 Claude Code 제품 영역에 속하며, 이는 Claude Platform API 및 SDK와 몇 가지 면에서 다릅니다: | 항목 | 이 엔드포인트 | Claude Platform API | | --------- | ------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------- | | 인증 | [claude.ai/code/routines](https://claude.ai/code/routines)에서 생성한 루틴별 토큰(`sk-ant-oat01-...`)을 사용하는 `Authorization: Bearer` | Claude Console에서 발급한 Claude API 키를 사용하는 `x-api-key` | | 토큰 범위 | 하나의 루틴만 해당, 읽기 권한 없음 | 워크스페이스 수준 | | SDK 지원 | 없음 | 모든 [클라이언트 SDK](https://platform.claude.com/docs/ko/cli-sdks-libraries/overview)에서 사용 가능 | | 청구 | claude.ai의 Claude Code 구독 사용량 | Claude Platform 사용량 | | 경로 네임스페이스 | `/v1/claude_code/...` | `/v1/...` | | 안정성 | 실험적 | 안정 버전 또는 표준 베타 | ## 시작하기 전에 이 엔드포인트를 호출하려면 다음이 필요합니다: 1. [claude.ai/code/routines](https://claude.ai/code/routines)에서 생성한 루틴. 2. 해당 루틴에 대해 생성된 bearer 토큰: 루틴을 편집 모드로 열고, **Select a trigger** 아래의 **Add another trigger**를 클릭한 다음 **API**를 선택하고, 모달 창에서 **Generate token**을 클릭하세요. 토큰은 한 번만 표시되며 나중에 다시 조회할 수 없습니다. 전체 설정 과정은 Claude Code 문서의 [API 트리거 추가](https://code.claude.com/docs/ko/routines#add-an-api-trigger)를 참조하세요. ## 루틴 트리거하기 ```http POST https://api.anthropic.com/v1/claude_code/routines/{routine_id}/fire ``` Claude Code 웹 UI는 API 트리거를 추가할 때 토큰과 함께 전체 URL을 제공하므로, 대부분의 통합에서는 둘 다 시크릿으로 저장하고 엔드포인트를 직접 호출합니다. 다음 예시는 셸 호출과 CI 실패 시 루틴을 트리거하는 GitHub Actions 단계를 보여줍니다. ```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\"}" ``` 요청은 세션이 생성되면 반환됩니다. 세션 출력을 스트리밍하거나 세션이 완료될 때까지 기다리지 않습니다. ### 헤더 | 이름 | 필수 | 설명 | | ------------------- | --------- | --------------------------------------------------------------------------------------- | | `Authorization` | 예 | `Bearer `. Claude Code 웹 UI에서 생성한 루틴별 토큰으로, `sk-ant-oat01-` 접두사가 붙습니다. | | `anthropic-version` | 예 | [API 버전](https://platform.claude.com/docs/ko/api/versioning). 허용되는 값은 `2023-06-01`뿐입니다. | | `Content-Type` | 본문이 있는 경우 | `application/json`. | `anthropic-beta: experimental-cc-routine-2026-04-01` 헤더를 보내는 기존 통합은 영향을 받지 않습니다. 엔드포인트는 이 헤더가 있는 요청과 없는 요청을 모두 허용합니다. ### 경로 매개변수 | 이름 | 타입 | 설명 | | ------------ | ------ | ------------------------------------------------------------------------------------------------------- | | `routine_id` | string | 루틴의 식별자입니다. 매개변수 이름과 달리 값에는 `routine_`이 아닌 `trig_` 접두사가 붙습니다. API 트리거를 추가할 때 모달 창에 표시되는 URL에 포함되어 있습니다. | ### 요청 본문 | 필드 | 타입 | 필수 | 설명 | | ------ | ------ | --- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `text` | string | 아니요 | 알림 본문, 실패한 로그 라인, git diff 등 이번 실행을 위한 초기 컨텍스트입니다. 값은 자유 형식 텍스트이며 파싱되지 않습니다. JSON이나 다른 구조화된 페이로드를 보내면 루틴은 이를 리터럴 문자열로 받습니다. 저장된 프롬프트와 함께 루틴에 전달됩니다. 최대 65,536자입니다. | 본문은 선택 사항입니다. 본문의 알 수 없는 필드는 무시됩니다. ### 응답 성공한 요청은 새 세션 세부 정보와 함께 `200 OK`를 반환합니다: ```json { "type": "routine_fire", "claude_code_session_id": "session_01HJKLMNOPQRSTUVWXYZ", "claude_code_session_url": "https://claude.ai/code/session_01HJKLMNOPQRSTUVWXYZ" } ``` | 필드 | 타입 | 설명 | | ------------------------- | ------ | ----------------------------------------------------------------------- | | `type` | string | 항상 `routine_fire`입니다. | | `claude_code_session_id` | string | 이번 실행을 위해 생성된 Claude Code 세션의 ID입니다. | | `claude_code_session_url` | string | claude.ai의 세션 링크입니다. 브라우저에서 열어 실행을 지켜보거나, 변경 사항을 검토하거나, 대화를 이어갈 수 있습니다. | ### 오류 오류는 표준 Anthropic [오류 엔벨로프](https://platform.claude.com/docs/ko/api/errors)를 사용합니다: ```json { "type": "error", "error": { "type": "not_found_error", "message": "" } } ``` | HTTP 상태 | 오류 타입 | 원인 | | ------- | ----------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | 400 | `invalid_request_error` | `anthropic-version` 헤더가 없거나 지원되지 않는 경우, `text`가 65,536자를 초과하는 경우, 또는 루틴이 일시 중지된 경우입니다([루틴 편집 및 제어](https://code.claude.com/docs/ko/routines#edit-and-control-routines) 참조). | | 401 | `authentication_error` | `Authorization` 헤더에 bearer 토큰이 없거나, 토큰이 이 루틴과 일치하지 않습니다. | | 403 | `permission_error` | 계정 또는 조직에 이 엔드포인트에 대한 접근 권한이 없습니다. | | 404 | `not_found_error` | 루틴이 존재하지 않습니다. | | 429 | `rate_limit_error` | 루틴 또는 계정의 시간당 실행 한도에 도달했습니다. 응답에는 한도 기간이 재설정되는 시점을 나타내는 `Retry-After` 헤더가 포함됩니다. | | 500 | `api_error` | 예기치 않은 서버 오류입니다. 지수 백오프로 재시도하세요. 오류가 계속되면 요청 ID와 함께 지원팀에 문의하세요. | | 503 | `overloaded_error` | 서비스가 일시적으로 과부하 상태입니다. 잠시 후 재시도하세요. Claude Platform은 이 오류 타입에 대해 529를 반환하지만, 이 엔드포인트는 503을 반환합니다. | ## 인증 bearer 토큰은 단일 루틴으로 범위가 한정됩니다. 유출된 토큰은 해당 루틴만 트리거할 수 있으며, 읽기 권한, 다른 루틴에 대한 접근 권한, 계정 데이터에 대한 접근 권한을 부여하지 않습니다. [claude.ai/code/routines](https://claude.ai/code/routines)의 루틴 API 트리거 설정에서 토큰을 생성하고 폐기하세요. 토큰 관리를 위한 공개 API는 없습니다. 새 토큰을 생성하면 이전 토큰이 폐기됩니다. ## 멱등성 성공한 각 요청은 새 세션을 생성합니다. 멱등성 키는 없습니다. 웹훅 호출자가 재시도하면 엔드포인트는 여러 세션을 생성합니다. ## 속도 제한 API 실행은 시간 단위로 제한됩니다. 각 루틴은 시간당 최대 30회의 실행을 허용하며(API 실행, 웹 UI의 **Run now** 버튼, 일회성 재예약 간에 공유됨), 각 계정은 모든 루틴을 통틀어 시간당 최대 100회의 API 실행을 할 수 있습니다. 이렇게 생성된 세션은 대화형 세션과 동일한 Claude Code 구독 사용량을 소모합니다. 한도에 도달하면 엔드포인트는 `Retry-After` 헤더와 함께 `429 rate_limit_error`를 반환합니다. 루틴 사용량이 구독 한도 및 추가 사용량 청구와 어떻게 상호작용하는지 알아보려면 Claude Code 문서의 [사용량 및 한도](https://code.claude.com/docs/ko/routines#usage-and-limits)를 참조하세요. ## SDK 지원 이 엔드포인트는 Anthropic SDK에 포함되어 있지 않습니다. 토큰 모델이 API 키 인증과 다르며, CI 작업이나 알림 웹훅 같은 일반적인 호출자는 요청을 직접 보냅니다. ## 참고 항목 * Claude Code 문서의 [루틴으로 작업 자동화하기](https://code.claude.com/docs/ko/routines) * [오류](https://platform.claude.com/docs/ko/api/errors)