모든 엔드포인트는 application/json을 반환해요. 에러는 RFC 7807 (Problem+JSON)을 따라요. 모든 응답에는 서버 감사 로그와 상관관계를 맺기 위한 X-Request-Id 헤더가 포함돼요.
| Method | Path | 권한 범위 | 용도 |
|---|---|---|---|
| GET | /v1/health | public | 인증 없는 헬스 체크. |
| GET | /v1/me | any | 본인 계정 정보 및 키 메타데이터. |
| GET | /v1/products | read:products | 공개 판매 중인 모든 제품과 가격 목록. |
| GET | /v1/products/{id} | read:products | 제품 상세, 구성 옵션 포함. |
| POST | /v1/orders | write:orders | 주문 처리. Idempotency-Key 필수. |
| GET | /v1/orders/{id} | read:orders | 본인 주문 상태 조회. |
| GET | /v1/services | read:services | 본인 서비스 목록 (페이지네이션 지원). |
| GET | /v1/services/{id} | read:services | 본인 서비스 상세. |
| GET | /v1/services/{id}/credentials | read:credentials | 서비스 자격증명 (별도 권한 범위, 감사 로그 기록). |
| POST | /v1/services/{id}/actions | write:services | 서비스 액션: start, stop, reboot, reinstall, suspend, unsuspend, terminate. |
| GET | /v1/billing/balance | read:billing | 크레딧 잔액. |
| GET | /v1/billing/invoices | read:billing | 본인 청구서 목록 (페이지네이션 지원). |
| GET | /v1/billing/invoices/{id}/pdf | read:billing | 청구서 PDF. |
| GET | /v1/webhooks | read:webhooks | 현재 웹훅 URL. |
| PUT | /v1/webhooks | write:webhooks | 웹훅 URL 설정 또는 해제. |
멱등성
POST /v1/orders와 POST /v1/services/{id}/actions에는 Idempotency-Key 헤더가 필요해요 ([A-Za-z0-9_.-] 문자 1-80자). 서버는 응답과 본문 해시를 24시간 캐시해요. 동일한 키와 동일한 본문으로 들어온 두 번째 요청은 동일한 응답을 반환하고, 동일한 키지만 다른 본문이면 409 idempotency_conflict로 거부돼요.
속도 제한
기본값은 키당 분당 60회(버스트 20회 허용) 및 일 5000회, 추가로 키와 무관하게 IP당 분당 600회예요. 초과 시 HTTP 429와 Retry-After 헤더가 반환돼요. 응답 헤더 X-RateLimit-Remaining과 X-RateLimit-Reset에서 현재 상태를 확인하실 수 있어요.
