API 레퍼런스 › API 사용하기 XenoCI 러너 API의 기본 주소, 인증, 금액 규칙, 멱등, 페이지 넘김, 오류 봉투와 전체 엔드포인트 목록
XenoCI 러너 API는 잡 단위 macOS CI 러너를 HTTP로 다루는 REST API입니다, xenocast CLI, MCP 서버, GitHub Action이 모두 이 API를 씁니다
https://xenoci.com/api/runner/v1이 문서의 경로는 모두 이 주소 아래의 상대 경로입니다, 예를 들어 GET /v1/me는 https://xenoci.com/api/runner/v1/me입니다
방식 헤더 누가 쓰는가 할 수 있는 일 API 키 Authorization: Bearer xci_live_…CLI, MCP, GitHub Action, 직접 호출 키 권한이 run이면 잡 제출과 취소, 조회, read면 조회만, 워크스페이스 하나에 묶입니다 콘솔 세션 쿠키 xci_console 웹 콘솔(Google 또는 이메일 링크 로그인) 조직 역할(owner, admin, developer)에 따라 결제, 멤버, 워크스페이스, 키 관리까지
API 키는 어떤 권한이든 결제, 충전, 키 발급, 멤버와 워크스페이스 관리를 할 수 없습니다, 그런 엔드포인트를 키로 부르면 403 console_only입니다 키 형식은 xci_live_ + 43자 + _ + 6자(CRC32 체크섬)입니다, 옛 xeno_ 접두사 키는 401 invalid_api_key입니다 콘솔 세션으로 상태를 바꾸는 요청(POST, PUT, PATCH, DELETE)은 같은 출처의 Origin 헤더가 있어야 합니다 각 엔드포인트 페이지의 "인증" 표에 허용 방식, 필요한 키 권한, 허용 역할이 있습니다 같은 금액을 두 필드로 항상 함께 줍니다
필드 뜻 예 <이름>_micro_usd정수 µUSD, 1 USD = 1,000,000, 계산과 비교는 이 값으로 118800<이름>_usd같은 값의 USD 문자열, 소수 6자리 고정, 표시용 "0.118800"<이름>_krw원화 정수(원), 충전 주문에만 28775*_krw_per_usd환율 문자열, 소수 2자리 "1438.71"
입력은 USD 정수(usd, monthly_limit_usd)만 받습니다, 소수나 문자열이나 지수 표기는 400 invalid_amount 또는 invalid_request입니다 분당 요율은 부가세 포함입니다, 런칭가 39,600µUSD(US$0.0396), 정가 78,100µUSD(US$0.0781) 시각은 RFC 3339 UTC(2026-10-12T03:11:05Z)이고 일별 집계와 월 한도는 UTC 기준입니다, 환율 day만 KST 영업일입니다 접두사 자원 org_조직 wrk_워크스페이스 usr_사용자 key_API 키 job_잡 lot_크레딧 로트 inv_초대 upl_업로드 art_결과물 bat_배치 rcp_레시피 ntf_알림 req_API 요청 로그
충전 주문 order_id는 [A-Za-z0-9_-]{6,64}이고 PortOne paymentId로 그대로 쓰입니다
쓰기 연산은 Idempotency-Key 헤더(1~255자)를 받습니다, 24시간 안에 같은 키로 다시 보내면 처음 응답을 그대로 돌려주고, 같은 키에 다른 본문이면 409 idempotency_conflict입니다, 네트워크가 끊겨 잡 제출 결과를 못 받았을 때 같은 키로 다시 보내면 잡이 두 번 만들어지지 않습니다
목록 응답은 data 배열과 next_cursor를 돌려줍니다, limit(기본 20, 최대 100)으로 크기를 정하고 next_cursor가 null이 아니면 그 값을 cursor에 넣어 다음 페이지를 받습니다
모든 오류는 같은 모양의 JSON을 돌려줍니다
{
"error": {
"code": "insufficient_credit",
"message": "사용 가능 잔액이 1분 요금보다 적습니다",
"retryable": false,
"retry_after_s": null,
"fault": "payment",
"request_id": "req_7Hq3Zk9Lm2",
"docs_url": "https://xenoci.com/docs/errors#insufficient_credit",
"details": {
"balance_micro_usd": 12000,
"balance_usd": "0.012000",
"required_micro_usd": 39600,
"required_usd": "0.039600",
"topup_url": "https://xenoci.com/console/topup?org=org_7Kq2m9ZtP3"
}
}
}fault는 client(요청 쪽), payment(잔액이나 한도), platform(XenoCI 쪽) 중 하나입니다, 전체 코드 표는 오류 코드 에 있습니다
이 레퍼런스는 계약 파일 docs/runner2/api-contract.openapi.json(0.1.0-draft)과 dev 브랜치 서버 코드를 대조해 썼습니다, 각 페이지의 참고 상자에 서버가 계약과 다른 점을 적었습니다
러너 API 전체는 서버 플래그 XENOCI_RUNNER2=1일 때만 열립니다, 꺼져 있으면 모든 경로가 404 not_found입니다 잔액 조회, 충전 건 목록, 크레딧 원장, 오늘 환율, 충전 주문 5개는 계약에만 있거나 아직 마운트되지 않았습니다, 해당 페이지에 표시했습니다 API 키 요청 속도는 아직 강제하지 않습니다, 10분에 1,000건을 넘으면 소유자와 관리자에게 급증 메일만 갑니다, 429 rate_limited는 지금 로그인 요청(이메일당 15분에 5번, IP당 20번)에만 납니다 모든 응답에 X-Request-Id(req_…)와 Cache-Control: private, no-store가 붙습니다, 문의할 때 request_id를 알려 주세요 내부 경로 /api/runner/downloads/{token}(결과물 바이트), /api/runner/agent/source, /api/runner/agent/artifacts/*(맥 호스트 전용, 잡별 1회용 토큰)는 고객이 직접 부르지 않습니다 메서드 경로 설명 키 역할 GET /v1/me호출자 확인 readowner, admin, developer
메서드 경로 설명 키 역할 POST /v1/uploads소스 업로드 runowner, admin, developer POST /v1/jobs잡 제출 runowner, admin, developer GET /v1/jobs잡 목록 (서버 미구현)readowner, admin, developer GET /v1/jobs/{job_id}잡 조회 readowner, admin, developer POST /v1/jobs/{job_id}/cancel잡 취소 runowner, admin, developer GET /v1/jobs/{job_id}/logs잡 로그 readowner, admin, developer GET /v1/jobs/{job_id}/artifacts결과물 목록 readowner, admin, developer GET /v1/jobs/{job_id}/artifacts/{artifact_id}결과물 내려받기 readowner, admin, developer
메서드 경로 설명 키 역할 GET /v1/balance잔액 조회 (서버 미구현)readowner, admin, developer GET /v1/organizations/{org_id}/credit/lots충전 건 목록 (서버 미구현)콘솔 전용 owner, admin GET /v1/organizations/{org_id}/credit/ledger크레딧 원장 (서버 미구현)콘솔 전용 owner, admin
메서드 경로 설명 키 역할 GET /v1/usage사용량 조회 readowner, admin, developer GET /v1/usage/export.csv사용량 CSV readowner, admin, developer
메서드 경로 설명 키 역할 GET /v1/fx-rates/today오늘 환율 (서버 미구현)콘솔 전용 owner, admin, developer POST /v1/organizations/{org_id}/topups충전 주문 생성 (서버 미구현)콘솔 전용 owner, admin GET /v1/organizations/{org_id}/topups충전 주문 목록 (서버 미구현)콘솔 전용 owner, admin GET /v1/organizations/{org_id}/topups/{order_id}충전 주문 조회 (서버 미구현)콘솔 전용 owner, admin POST /v1/organizations/{org_id}/topups/{order_id}/confirm충전 결제 확인 (서버 미구현)콘솔 전용 owner, admin POST /v1/organizations/{org_id}/topups/{order_id}/withdraw충전 청약철회 (서버 미구현)콘솔 전용 owner, admin
메서드 경로 설명 키 역할 GET /v1/organizations조직 목록 콘솔 전용 owner, admin, developer POST /v1/organizations조직 만들기 콘솔 전용 owner, admin, developer GET /v1/organizations/{org_id}조직 조회 콘솔 전용 owner, admin, developer PATCH /v1/organizations/{org_id}조직 이름 바꾸기 콘솔 전용 owner, admin
메서드 경로 설명 키 역할 GET /v1/organizations/{org_id}/tier조직 티어 조회 콘솔 전용 owner, admin, developer GET /v1/tiers티어 표 readowner, admin, developer
메서드 경로 설명 키 역할 GET /v1/organizations/{org_id}/members멤버 목록 콘솔 전용 owner, admin, developer PATCH /v1/organizations/{org_id}/members/{user_id}멤버 역할 바꾸기 콘솔 전용 owner, admin DELETE /v1/organizations/{org_id}/members/{user_id}멤버 내보내기 콘솔 전용 owner, admin, developer GET /v1/organizations/{org_id}/invites초대 목록 콘솔 전용 owner, admin POST /v1/organizations/{org_id}/invites초대 보내기 콘솔 전용 owner, admin DELETE /v1/organizations/{org_id}/invites/{invite_id}초대 취소 콘솔 전용 owner, admin POST /v1/invites/accept초대 수락 콘솔 전용 owner, admin, developer
메서드 경로 설명 키 역할 GET /v1/organizations/{org_id}/workspaces워크스페이스 목록 콘솔 전용 owner, admin, developer POST /v1/organizations/{org_id}/workspaces워크스페이스 만들기 콘솔 전용 owner, admin GET /v1/organizations/{org_id}/workspaces/{workspace_id}워크스페이스 조회 콘솔 전용 owner, admin, developer PATCH /v1/organizations/{org_id}/workspaces/{workspace_id}워크스페이스 수정 콘솔 전용 owner, admin POST /v1/organizations/{org_id}/workspaces/{workspace_id}/archive워크스페이스 보관 콘솔 전용 owner, admin GET /v1/organizations/{org_id}/workspaces/{workspace_id}/members워크스페이스 멤버 목록 콘솔 전용 owner, admin, developer PUT /v1/organizations/{org_id}/workspaces/{workspace_id}/members/{user_id}워크스페이스 멤버 추가 콘솔 전용 owner, admin DELETE /v1/organizations/{org_id}/workspaces/{workspace_id}/members/{user_id}워크스페이스 멤버 빼기 콘솔 전용 owner, admin
메서드 경로 설명 키 역할 POST /v1/organizations/{org_id}/workspaces/{workspace_id}/api-keysAPI 키 발급 콘솔 전용 owner, admin, developer GET /v1/organizations/{org_id}/api-keysAPI 키 목록 콘솔 전용 owner, admin, developer PATCH /v1/organizations/{org_id}/api-keys/{key_id}API 키 이름 바꾸기 콘솔 전용 owner, admin, developer POST /v1/organizations/{org_id}/api-keys/{key_id}/revokeAPI 키 폐기 콘솔 전용 owner, admin, developer
메서드 경로 설명 키 역할 GET /v1/cost비용 조회 readowner, admin, developer GET /v1/cost/export.csv비용 CSV readowner, admin, developer GET /v1/logs로그 목록 readowner, admin, developer GET /v1/usage/prepare준비 시간 readowner, admin, developer GET /v1/limits한도 조회 readowner, admin, developer
메서드 경로 설명 키 역할 GET /v1/dashboard대시보드 readowner, admin, developer
메서드 경로 설명 키 역할 POST /v1/batches배치 제출 runowner, admin, developer GET /v1/batches배치 목록 readowner, admin, developer GET /v1/batches/{batch_id}배치 조회 readowner, admin, developer POST /v1/batches/{batch_id}/cancel배치 취소 runowner, admin, developer
메서드 경로 설명 키 역할 GET /v1/recipes레시피 목록 readowner, admin, developer POST /v1/recipes레시피 만들기 runowner, admin, developer GET /v1/recipes/{recipe_id}레시피 조회 readowner, admin, developer PATCH /v1/recipes/{recipe_id}레시피 수정 runowner, admin, developer DELETE /v1/recipes/{recipe_id}레시피 삭제 runowner, admin, developer
메서드 경로 설명 키 역할 GET /v1/environments환경 목록 readowner, admin, developer PUT /v1/organizations/{org_id}/workspaces/{workspace_id}/environment워크스페이스 기본 환경 콘솔 전용 owner, admin
메서드 경로 설명 키 역할 GET /v1/files파일 목록 readowner, admin, developer DELETE /v1/files/{file_id}파일 삭제 runowner, admin, developer
메서드 경로 설명 키 역할 POST /v1/organizations/{org_id}/workspaces/{workspace_id}/playground/runs플레이그라운드 실행 콘솔 전용 owner, admin, developer
메서드 경로 설명 키 역할 GET /v1/organizations/{org_id}/notifications알림 목록 콘솔 전용 owner, admin, developer GET /v1/organizations/{org_id}/notification-settings알림 설정 조회 콘솔 전용 owner, admin, developer PUT /v1/organizations/{org_id}/notification-settings알림 설정 변경 콘솔 전용 owner, admin, developer
