고객 API · V1 베타
VPS 및 전용 서버를 위한
REST API
코드로 서버를 관리하세요. 시간제 VPS 주문과 삭제, 전원 작업과 재설치, 자체 이미지 캡처와 배포, 잔액으로 청구서 결제까지 할 수 있습니다.
X-ZoneServers 고객 API(v1, 공개 베타)는 HTTPS로 92개의 작업을 제공하며, OpenAPI 3.0 명세, 권한 범위를 지정한 API 키, 키당 시간당 1,000회 요청의 기본 한도를 갖추고 있습니다. 모든 계정에 추가 비용 없이 포함됩니다.
92 API 작업1,000 요청/시간 (키당)
첫 API 호출
고객 센터의 Profile → API Keys 메뉴에서 키를 만든 다음, API에 내가 누구인지 물어보세요.
curl https://my.x-zoneservers.com/api/v1/ \
-H "Authorization: Bearer $XZ_API_KEY"
{ "success": true,
"data": {
"version": "1",
"key": { "scopes": ["read", "services"] },
"rate_limit": { "limit": 1000, "remaining": 999 }
} }01기능
자동화할 수 있는 작업
API는 주문부터 청구서까지 서버의 전체 수명 주기를 다루며, 고객 센터와 동일한 권한으로 동작합니다.
배포 & 삭제
시간제 또는 월 단위 과금으로 VPS를 주문하고, 첫 부팅용 cloud-init user-data와 SSH 키를 전달한 뒤, 작업이 끝나면 삭제하세요. 서버가 사라지는 순간 시간제 과금도 멈춥니다.
전원, 재설치 & 통계
VPS를 시작, 중지, 재부팅, 재설치하고, 루트 비밀번호를 재설정하며, 모니터링 스크립트에서 사용량과 트래픽 통계를 읽어 오세요.
커스텀 이미지
VPS를 이미지로 캡처하거나(계정당 최대 3개), 자체 qcow2 또는 raw 이미지를 등록해(SHA-256으로 검증) 그 이미지로 새 서버를 배포하세요.
청구 & 사용량
계정 잔액과 이번 달 시간제 요금을 조회하고, 청구서와 프로포마 청구서를 나열하며, 잔액으로 결제하세요. 비용 대시보드와 예산 알림에 유용합니다.
애드온 & 업그레이드
추가 IP 주소 같은 애드온을 기존 서비스에 구매하거나, 고객 센터를 열지 않고 더 큰 플랜으로 옮기세요.
프로젝트 & 권한 범위 키
서버를 프로젝트로 묶고 단일 프로젝트에만 연결된 키를 발급하세요. 스테이징 키가 프로덕션을 조회하거나 건드리는 일은 결코 없습니다.
02작동 방식
예시: CI 작업 하나를 위한 시간제 VPS
깨끗한 빌드 머신을 만들고, 파이프라인을 실행하고, 삭제하세요 — 비용은 서버가 존재한 시간만큼만 지불합니다.
시간제 서비스는 청구서가 발행되지 않고 계정 잔액에서 차감되므로, 계정에 잔액을 유지하세요. 주문할 때마다 Idempotency-Key 헤더를 보내면 시간 초과된 요청을 재시도해도 두 번째 서버가 생성되지 않습니다.
1. 플랜 선택: 시간당 요금과 월 요금이 포함된 상품 목록을 조회합니다.
curl https://my.x-zoneservers.com/api/v1/products \
-H "Authorization: Bearer $XZ_API_KEY"2. 첫 부팅 스크립트와 SSH 키를 지정해 시간제 과금으로 주문합니다.
curl -X POST https://my.x-zoneservers.com/api/v1/orders \
-H "Authorization: Bearer $XZ_API_KEY" \
-H "Idempotency-Key: ci-run-4812" \
-H "Content-Type: application/json" \
-d '{"productId": "<plan-id>", "billingCycle": "hourly",
"hostname": "ci-4812.example.com", "location": "<location>",
"configOptions": {"os_image_id": "<image-id>",
"ssh_keys": ["ssh-ed25519 AAAA... ci@runner"],
"user_data": "#!/bin/sh\n/opt/ci/run-pipeline.sh"}}'3. 작업이 끝나면 서버를 삭제합니다. 과금은 즉시 멈춥니다.
curl -X DELETE https://my.x-zoneservers.com/api/v1/vps/<vps-id> \
-H "Authorization: Bearer $XZ_API_KEY" \
-H "Content-Type: application/json" \
-d '{"immediate": true}'03API
스크립트와 AI 에이전트를 위한 설계
버튼을 누르는 주체가 사람이 아닌 프로그램이라면, 엔드포인트 수보다 예측 가능한 동작이 더 중요합니다.
권한 범위 지정 키
각 키에는 부여한 권한 범위(read, services, orders, billing, destructive)만 담기며, 선택적으로 IP 허용 목록과 만료일을 지정할 수 있습니다.
공개된 속도 제한
기본값은 키당 시간당 1,000회 요청이며 X-RateLimit 헤더로 알려 드립니다. 전원 및 재설치 작업에는 서버별로 짧은 쿨다운이 적용됩니다.
안전한 재시도
주문은 Idempotency-Key를 지원하고 모든 거부 응답은 기계가 읽을 수 있는 오류 코드를 반환하므로, 자동화가 재시도 가능한 실패와 진짜 실패를 구분할 수 있습니다.
기계가 읽을 수 있는 문서
클라이언트 생성기를 위한 OpenAPI 3.0 명세와, 코딩 어시스턴트와 AI 에이전트가 바로 읽을 수 있는 일반 Markdown 가이드를 제공합니다.
04관련 항목
자체 고객에게 서버를 판매하시나요?
이 고객 API는 본인 계정을 자동화합니다. 자체 브랜드로 재판매하려면 리셀러 프로그램에 가입하고 대신 리셀러 API를 사용하세요. 물량별 등급이 적용되는 도매가, HMAC 서명 요청, 웹훅, 고객별 키, 그리고 고객이 당사 계정 없이 열 수 있는 콘솔 링크를 제공합니다.
05자주 묻는 질문
API 자주 묻는 질문
X-ZoneServers 자동화에 관해 자주 묻는 질문입니다.
X-ZoneServers에 API가 있나요?
네. 고객 API(v1)는 https://my.x-zoneservers.com/api/v1 에서 HTTPS로 제공되는 REST API로, VPS, 전용 서버, 주문, 애드온, 업그레이드, 청구서, SSH 키, 커스텀 이미지를 다루는 92개의 작업을 제공합니다. 현재 공개 베타 단계로, 실제 개발에 쓸 만큼 안정적이지만 엔드포인트와 응답 형식은 아직 바뀔 수 있습니다.
API 액세스는 무료인가요?
네. API 액세스는 모든 계정에 추가 비용 없이 포함됩니다. 주문한 서버와 애드온에 대해서만 웹사이트 및 고객 센터와 동일한 가격으로 지불하면 됩니다.
API로 시간제 VPS를 생성하고 삭제할 수 있나요?
네. 결제 주기를 시간 단위로 설정해 주문하고(선택적으로 cloud-init user-data와 SSH 키 포함), 더 이상 필요 없으면 VPS를 삭제하면 됩니다. 시간제 서비스는 계정 잔액에서 차감되며, 삭제하는 즉시 과금이 멈춥니다.
API가 전용 서버도 지원하나요?
일부만 지원합니다. 전용 서버의 경우 API는 주문, 애드온, 청구서, 서비스 세부 정보를 다룹니다. 전원 제어, OS 재설치, 비밀번호 재설정은 API와 고객 센터 모두에서 전용 서버에 제공되지 않습니다.
인증은 어떻게 하나요?
고객 센터의 Profile → API Keys 메뉴에서 API 키를 만들고 Bearer 토큰으로 전송하세요. 키를 만들 때 권한 범위를 선택하고, 필요하면 특정 IP 주소로 제한하거나 만료일을 지정할 수 있습니다. 키는 한 번만 표시되며 고객 센터에서 언제든 폐기할 수 있습니다.
OpenAPI 또는 Swagger 명세가 있나요?
네. 전체 OpenAPI 3.0 명세는 https://my.x-zoneservers.com/api/v1/openapi.json 에 게시되어 있으며, 렌더링된 문서와 Markdown 사용 가이드도 함께 제공됩니다.