VPS API 문서, 서버 만들기와 관리 REST API

API로 할 수 있는 일

API는 서버를 많이 다루거나 배포를 자동으로 돌리고 싶을 때 쓰는 방법이에요. 사양, 지역, 이미지 목록을 불러오고, 서버를 만들면 결제가 진행되고, 결제 확인 후 서버가 만들어져요. 화면과 같은 규칙이 그대로 적용돼서 API로 만든 서버도 계정의 서버 목록에 함께 보여요.

처음 쓴다면 API 빠른 시작 가이드에서 키 만들기부터 첫 서버 만들기까지 순서대로 따라 해 보세요. 이 페이지는 모든 엔드포인트와 필드를 한곳에 모은 참고 문서예요.

기본 주소

모든 요청은 아래 주소 뒤에 경로를 붙여 보내요. 요청과 응답 본문은 모두 JSON(UTF-8)이에요.

https://helpervps.com/api/v1

인증

Authorization: Bearer YOUR_API_KEY 헤더를 보내 주세요. 키는 첫 결제 후 계정의 API 키 메뉴에서 만들 수 있고, hvp_로 시작해요. 키는 만든 직후 한 번만 전체가 표시되고, 새 키를 만들면 기존 키는 바로 사용할 수 없게 돼요.

curl https://helpervps.com/api/v1/servers \
  -H "Authorization: Bearer YOUR_API_KEY"

요청 한도

서버 코드

서버는 숫자 번호가 아니라 S-7K2M-9QX4-HB3T 같은 서버 코드로 구분해요. 서버 목록이나 만들기 응답의 id 값을 그대로 경로에 넣으면 돼요. 대소문자는 구분하지 않아요.

GET /catalog

판매 중인 사양(plans), 지역(locations), 이미지(images), 추가 옵션(addons)을 한 번에 돌려줘요. 서버를 만들 때 넣는 코드는 모두 여기서 나와요. monthly는 미국 달러 월 요금이고, 판매하지 않는 옵션은 null로 와요. 추가 디스크의 monthly_per_gb는 소수점 셋째 자리까지 표시돼요.

요청 예시

curl https://helpervps.com/api/v1/catalog \
  -H "Authorization: Bearer YOUR_API_KEY"

응답 예시

{
  "plans": [
    { "code": "s2", "type": "basic", "vcpu": 1, "ram_mb": 2048, "disk_gb": 50, "transfer_tb": 2, "monthly": "2.48" }
  ],
  "locations": ["frankfurt", "singapore", "seoul"],
  "images": ["ubuntu-24-04", "debian-13", "almalinux-10", "app-docker"],
  "addons": {
    "backups": { "percent_of_plan": 5.6 },
    "extra_disk": { "sizes_gb": [50, 100, 250, 500, 1000], "monthly_per_gb": "0.028" },
    "ddos_protection": { "monthly": "1.68" }
  }
}

GET /servers

내 서버 목록을 최근에 만든 순서로 돌려줘요. 삭제됐거나 만들지 못한 서버는 빠져요.

요청 예시

curl https://helpervps.com/api/v1/servers \
  -H "Authorization: Bearer YOUR_API_KEY"

응답 예시

[
  {
    "id": "S-7K2M-9QX4-HB3T",
    "label": "web-1",
    "state": "running",
    "ipv4": "192.0.2.15",
    "ipv6": "2001:db8::15",
    "monthly": "2.48",
    "backups": false,
    "extra_disk_gb": 0,
    "ddos_protection": false,
    "paid_until": "2026-11-18T09:00:00.000Z"
  }
]

POST /servers

서버를 만들고 결제를 진행해요. plan, location, image는 카탈로그의 코드를 그대로 넣어요. label은 영문, 숫자, 점, 대시로 40자까지이고 다른 글자는 대시로 바뀌어요. backups, extra_disk_gb, ddos_protection은 선택 옵션이에요. 성공하면 201과 함께 서버 정보가 오고, root_password는 이 응답에 한 번 들어 있어요(계정의 서버 페이지에서도 7일 동안 볼 수 있어요).

요청 예시

curl -X POST https://helpervps.com/api/v1/servers \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"plan":"s2","location":"frankfurt","image":"ubuntu-24-04","label":"web-1","backups":true,"extra_disk_gb":0,"ddos_protection":false}'

응답 예시

{
  "id": "S-7K2M-9QX4-HB3T",
  "label": "web-1",
  "state": "creating",
  "ipv4": null,
  "ipv6": null,
  "monthly": "2.61",
  "backups": true,
  "extra_disk_gb": 0,
  "ddos_protection": false,
  "paid_until": "2026-11-18T09:00:00.000Z",
  "root_password": "..."
}

GET /servers/{id}

서버 하나의 상태와 주소, 월 요금, 결제 만료일을 돌려줘요. 새 서버는 creating으로 시작해 준비가 끝나면 running이 되고 ipv4, ipv6가 채워져요. 몇 초 간격으로 확인하면 넉넉해요.

요청 예시

curl https://helpervps.com/api/v1/servers/S-7K2M-9QX4-HB3T \
  -H "Authorization: Bearer YOUR_API_KEY"

응답 예시

{
  "id": "S-7K2M-9QX4-HB3T",
  "label": "web-1",
  "state": "running",
  "ipv4": "192.0.2.15",
  "ipv6": "2001:db8::15",
  "monthly": "2.61",
  "backups": true,
  "extra_disk_gb": 0,
  "ddos_protection": false,
  "paid_until": "2026-11-18T09:00:00.000Z"
}

POST /servers/{id}/start (stop, reboot)

start는 중지된(stopped) 서버를 켜고, stop과 reboot는 실행 중인(running) 서버를 끄거나 다시 시작해요. 응답은 바뀐 서버 정보예요.

요청 예시

curl -X POST https://helpervps.com/api/v1/servers/S-7K2M-9QX4-HB3T/reboot \
  -H "Authorization: Bearer YOUR_API_KEY"

응답 예시

{
  "id": "S-7K2M-9QX4-HB3T",
  "label": "web-1",
  "state": "rebooting",
  ...
}

POST /servers/{id}/renew

지금 결제해서 유효 기간을 늘려요. 유효 기간이 지나 정지된 서버도 이 요청으로 다시 켜져요.

요청 예시

curl -X POST https://helpervps.com/api/v1/servers/S-7K2M-9QX4-HB3T/renew \
  -H "Authorization: Bearer YOUR_API_KEY"

응답 예시

{
  "id": "S-7K2M-9QX4-HB3T",
  "state": "running",
  "paid_until": "2026-12-18T09:00:00.000Z",
  ...
}

DELETE /servers/{id}

서버와 디스크를 삭제해요. 다음 결제일부터 요금이 나가지 않고, 이미 결제한 달의 남은 기간은 환불되지 않아요.

요청 예시

curl -X DELETE https://helpervps.com/api/v1/servers/S-7K2M-9QX4-HB3T \
  -H "Authorization: Bearer YOUR_API_KEY"

응답 예시

{
  "id": "S-7K2M-9QX4-HB3T",
  "state": "deleted"
}

서버 응답 필드

상태 값

오류

오류가 나면 상태 코드와 함께 {"error": "코드"} 모양의 JSON이 돌아와요. 코드 값으로 처리를 나누면 돼요.

함께 보면 좋은 안내

결제는 PayGate 보안 결제창에서 이루어져요. 재설치와 root 비밀번호 새로 만들기는 계정의 서버 페이지에서 할 수 있고, 순서는 재설치 가이드에 있어요.

API로 할 수 있는 일과 자동화 예시는 VPS API 페이지에서, 사양별 월 요금은 요금 페이지에서 볼 수 있어요.