KO
NexCMP 무료로 시작하기
NexCMP 1.6.1에 적용됩니다·업데이트됨 ·마크다운으로 보기

REST API ​

포털 위치: https://<your-domain>/apidoc의 API 참조 (공개) 및 /api-keys의 API 키. 관리자 위치: Customers › API keys (/customers/apikeys)에는 고객이 생성한 키가 나열됩니다.

작동 내용 ​

고객이 포털에서 수행할 수 있는 모든 작업(VM 목록 조회 및 제어, 인프라 관리, 청구서 읽기, SSH 키 관리, Kubernetes, 스토리지, 지원 티켓)은 https://<your-domain>/v1/ 아래의 버전이 지정된 REST API를 통해 사용할 수 있습니다. 고객은 범위가 지정된 API key를 사용하여 스크립트와 CI에서 이를 호출합니다. 동일한 API가 cmp command-line tool 및 MCP server에 전송되며, 레퍼런스는 실행 중인 설치에서 생성되므로 활성화한 기능이 정확히 나열됩니다.

요구 사항 ​

항목요구 사항
공용 HTTPS 주소API는 기본 도메인(및 각 리셀러의 고유 도메인)에서 서비스됩니다.
API 키포털에서 고객이 생성합니다. API keys을(를) 참조하세요.
의존성없음. 활성화하지 않은 모듈(예: Kubernetes 또는 Object Storage)의 엔드포인트는 레퍼런스에서 숨겨지고 거부됩니다.

인프라 준비 ​

설치할 내용이 없습니다. NexCMP 앞에 리버스 프록시가 있는 경우 /v1/, /mcp, /cli/ 및 /apidoc을(를) 패널로 전달하세요(설치 프로그램의 nginx 구성이 이미 처리합니다).

NexCMP에서 연결 ​

대화형 레퍼런스 ​

https://cloud.example.com/apidoc을(를) 엽니다(호스트를 도메인으로 교체하세요. 리셀러의 고객은 리셀러의 이름과 함께 리셀러의 도메인에서 레퍼런스를 보게 됩니다). 여기에는 curl, cmp CLI, JavaScript, Python, Go의 요청 및 응답 예제가 포함된 엔드포인트 문서, 검색 상자(Ctrl 또는 Cmd + K), Try it 패널이 있습니다. Try it은 방문자가 붙여넣은 키(브라우저 세션에 유지됨)를 사용하여 동일한 사이트에만 요청을 보냅니다. 기본적으로 읽기 전용이며, 쓰기 또는 유료 호출에는 추가 스위치와 확인이 필요합니다.

다운로드 및 기계 판독 가능 문서 ​

모두 공개되어 있으며 키가 필요 없고 사이트별로 생성됩니다:

URL내용
/apidoc대화형 레퍼런스.
/v1/public/openapi.jsonOpenAPI 3.1 문서.
/v1/public/openapi.yaml동일, YAML.
/v1/public/postman.jsonPostman 컬렉션.
/v1/public/insomnia.jsonInsomnia 내보내기.
/v1/public/api.md단일 Markdown 파일 형태의 레퍼런스.
/v1/public/api-catalog가벼운 JSON: 브랜드, 기본 URL, 키 접두사, 모든 범위, 그리고 메서드, 경로, 범위 및 Idempotency-Key이 필요한지 여부가 포함된 모든 엔드포인트.
bash
curl -s https://cloud.example.com/v1/public/api-catalog | python3 -m json.tool | head -40
curl -sO https://cloud.example.com/v1/public/openapi.yaml

Postman에서 Import › Link를 선택하고 https://cloud.example.com/v1/public/postman.json을(를) 붙여넣습니다. 참조 페이지에서는 JavaScript 및 Python용 단일 파일 API 클라이언트도 제공합니다.

인증 ​

Authorization 헤더에 키를 전송합니다.

bash
curl -s https://cloud.example.com/v1/billing/wallet \
  -H "Authorization: Bearer vk_XXXX"
  • 고객 키는 vk_(으)로 시작합니다. 키는 사이트 귀속형입니다. cloud.example.com에서 생성된 키는 리셀러 도메인에서 작동하지 않습니다.
  • 브라우저 세션 토큰(pt_...)은 포털 전용이므로, 자동화 작업에는 키를 사용하세요.
  • 키의 **권한(scope)**에 따라 호출 가능한 작업이 결정되며, 누락된 권한은 HTTP 403 scope_required을(를) 반환합니다. API keys을(를) 참조하세요.
  • GET /v1/apikeys/self을(를) 사용하여 키를 확인하세요. 호출하는 키의 이름, 권한, 만료일 및 남은 요청 제한 허용량(모든 키로 호출 가능)을 반환합니다.

예제 ​

bash
# List virtual machines
curl -s "https://cloud.example.com/v1/vm?page=1" -H "Authorization: Bearer vk_XXXX"

# Start one (needs vm:write)
curl -s -X POST https://cloud.example.com/v1/vm/3f2a1c9e-0000-4000-8000-000000000000/start \
  -H "Authorization: Bearer vk_XXXX"

# Create a VM (paid: needs vm:create and an Idempotency-Key)
curl -s -X POST https://cloud.example.com/v1/vm \
  -H "Authorization: Bearer vk_XXXX" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d @vm.json

/apidoc에서 각 작업의 정확한 요청 필드를 확인하세요.

오류 ​

모든 오류는 고정된 code 및 사람이 읽을 수 있는 message(이)가 포함된 JSON입니다.

json
{"error": {"code": "scope_required", "message": "Key lacks scope vm:write"}}
HTTP일반적인 code의미
401unauthenticated, key_invalid, key_revoked, key_expired, key_ip_denied, site_mismatch, api_keys_disabled키 누락 또는 알 수 없음, 철회됨, 만료됨, 키의 허용 목록에 없는 발신자 IP, 다른 사이트의 키 또는 API 키 비활성화.
403scope_required, endpoint_not_public, account_blocked, quota_exceeded, impersonate_forbidden키에 권한이 없음; 엔드포인트를 키에서 사용할 수 없음; 계정이 잠김; quota에 도달함; 대행(impersonated) 세션에서는 허용되지 않는 작업.
404not_found찾을 수 없음 — 다른 사용자의 리소스인 경우에도 반환됩니다.
422invalid_argument유효성 검사 오류 (응답에 필드 이름이 명시됨).
429rate_limited요청이 너무 많습니다. Retry-After 동안 기다려 주세요.
503maintenance유지보수 모드가 켜져 있습니다. 읽기는 가능하지만 쓰기는 거부됩니다.

요청 제한 ​

제한Default
키당분당 120회 요청
계정당 (모든 키 합산)분당 300회 요청

모든 응답에는 X-RateLimit-Limit, X-RateLimit-Remaining 및 X-RateLimit-Reset이(가) 포함되며, 429 응답에는 Retry-After이(가) 추가됩니다.

멱등성 ​

비용이 발생하거나 반복할 수 없는 명령(생성, 요금제 변경, 구매, 삭제 등)에는 Idempotency-Key 헤더가 필수입니다(200자 이내의 임의 문자열; UUID가 적합합니다). 타임아웃 후에 동일한 키로 다시 전송하면 서버는 작업을 반복하는 대신 (Idempotency-Replayed: 1과(와) 함께) 원본 결과를 반환합니다. 다른 명령에 키를 재사용하면 422를 반환하고, 아직 진행 중인 요청은 409/Retry-After를 반환합니다. 헤더가 없으면 유료 호출이 거부됩니다.

확인 ​

  1. 포털에서 vm:read 범위의 키를 생성합니다 (API keys › Create key).

  2. 실행:

    bash
    curl -i https://cloud.example.com/v1/apikeys/self -H "Authorization: Bearer vk_XXXX"

    HTTP 200과 요청 제한 헤더를 받게 됩니다.

  3. curl -s https://cloud.example.com/v1/vm -H "Authorization: Bearer vk_XXXX"은(는) 계정의 VM 목록을 조회합니다. 포털의 키 Last used 열과 Key usage log에서 호출 내역을 확인할 수 있습니다.

한도 및 참고 사항 ​

  • 키로 절대 사용할 수 없는 작업: 잔액 충전, 출금, 카드 변경 또는 자동 충전, 비밀번호·이메일·2FA 변경, 계정 삭제, 다른 키 생성·편집·철회. 이러한 작업에는 로그인된 브라우저 세션이 필요합니다.
  • 숨겨진 모듈: 참조 문서와 OpenAPI 문서에는 해당 사이트에서 활성화된 기능만 나열됩니다.
  • 응답 크기 및 페이징: 목록 조회 엔드포인트는 페이징 처리가 적용됩니다(page, per_page). 각 엔드포인트에 대한 OpenAPI 문서를 참조하세요.
  • 시간 및 금액: 필드 이름에 별도의 언급이 없는 한 금액은 USD 센트 단위입니다.
  • 관리자 API: 관리자 콘솔에는 자체적인 System › Admin › API 페이지와 관리를 위한 관리자 키(ofw_...)가 있으며, 여기서 설명하는 고객 API와는 별개입니다.
  • 버전 관리: 경로 접두사 /v1은(는) 안정적이며, 응답에 새 필드가 추가될 수 있습니다.

Troubleshooting ​

증상원인해결 방법
새 키 사용 시 401 오류다른 도메인의 키이거나, 만료되었거나, 공백이 포함되어 입력됨호출하는 도메인에서 키를 생성하고 Authorization: Bearer vk_... 헤더를 확인하세요.
403 scope_required스코프 누락포털에서 키를 편집하고 스코프를 추가하세요.
401 key_ip_denied 또는 site_mismatch다른 IP로 제한된 키("허용된 IP")이거나 다른 도메인에서 생성됨키의 허용된 IP에 서버 IP를 추가하거나, 키가 생성된 도메인을 호출하세요.
존재하는 VM에 대한 404다른 계정 소유의 VM임소유자의 키를 사용하세요.
Idempotency-Key을(를) 요구하는 400/422헤더가 없는 유료 작업Idempotency-Key: <uuid>을(를) 추가하세요.
429한도 초과요청을 줄이거나 Retry-After을(를) 사용하세요.
/apidoc의 표시 값이 예상보다 적음모듈이 꺼져 있음License & updates에서 모듈을 활성화하세요.