엔드포인트 레퍼런스

KernelHost API

모든 엔드포인트는 application/json을 반환해요. 에러는 RFC 7807 (Problem+JSON)을 따라요. 모든 응답에는 서버 감사 로그와 상관관계를 맺기 위한 X-Request-Id 헤더가 포함돼요.

MethodPath권한 범위용도
GET/v1/healthpublic인증 없는 헬스 체크.
GET/v1/meany본인 계정 정보 및 키 메타데이터.
GET/v1/productsread:products공개 판매 중인 모든 제품과 가격 목록.
GET/v1/products/{id}read:products제품 상세, 구성 옵션 포함.
POST/v1/orderswrite:orders주문 처리. Idempotency-Key 필수.
GET/v1/orders/{id}read:orders본인 주문 상태 조회.
GET/v1/servicesread:services본인 서비스 목록 (페이지네이션 지원).
GET/v1/services/{id}read:services본인 서비스 상세.
GET/v1/services/{id}/credentialsread:credentials서비스 자격증명 (별도 권한 범위, 감사 로그 기록).
POST/v1/services/{id}/actionswrite:services서비스 액션: start, stop, reboot, cancel (결제 기간 종료 시), cancel_revoke.
GET/v1/services/{id}/metricsread:services본인 서비스의 서버 지표(CPU, 메모리, 네트워크).
GET/v1/services/{id}/ddos/profilesread:ddos사용 가능한 Advanced DDoS Protection 프로필.
GET/v1/services/{id}/ddos/rulesread:ddos할당된 보호 IP의 현재 규칙.
POST/v1/services/{id}/ddos/ruleswrite:ddos보호 규칙 하나 추가. Idempotency-Key가 필요합니다.
DELETE/v1/services/{id}/ddos/rules/{rule_id}write:ddos소유한 규칙 하나 삭제. Idempotency-Key가 필요합니다.
GET/v1/services/{id}/ddos/attacksread:ddos보호 IP에서 탐지된 공격(Remote DDoS Protection).
GET/v1/services/{id}/ddos/attacks/{attack_id}read:ddos공격 한 건의 상세 정보: 트래픽 및 세부 분석.
GET/v1/billing/balanceread:billing크레딧 잔액.
GET/v1/billing/invoicesread:billing본인 청구서 목록 (페이지네이션 지원).
GET/v1/billing/invoices/{id}/pdfread:billing청구서 PDF.
GET/v1/webhooksread:webhooks현재 웹훅 URL.
PUT/v1/webhookswrite:webhooks웹훅 URL 설정 또는 해제.

Advanced DDoS Protection 규칙

이 엔드포인트를 사용하려면 본인 계정에 속한 Advanced DDoS Protection 서비스가 필요합니다. 조회는 active 또는 suspended 상태에서 가능하며, 변경하려면 active 상태여야 합니다. API 키에서 조회용 read:ddos와 변경용 write:ddos를 명시적으로 활성화하세요. 기존 키에는 새 권한이 자동으로 부여되지 않습니다. 터널 및 허용 목록 관리는 지원하지 않습니다.

프로필 목록에서 app_code를 선택하세요. port는 1부터 65535까지의 정수여야 하며, icmp에서는 생략하거나 0을 보내세요. 선택 항목인 extra_ports 객체는 프로필과 정확히 일치하는 이름에 정수 포트를 지정합니다. 생략한 항목에는 프로필 기본값을 사용합니다. 프로토콜은 서버에서 결정하므로 protocol을 보내지 마세요. 알 수 없는 필드나 이름은 HTTP 400을 반환합니다.

GET /v1/services/{id}/ddos/profiles

{
  "data": [{
    "app_code": "rust",
    "name": "Rust",
    "default_port": 28015,
    "protocol": "UDP",
    "extra_ports": [
      {"name": "Query", "port": 28016, "protocol": "UDP"},
      {"name": "RCON", "port": 28016, "protocol": "TCP"},
      {"name": "RustPlus", "port": 28082, "protocol": "TCP"}
    ]
  }],
  "meta": {"service_id": 1234, "protection_ip": "192.0.2.10", "max_rules": 1000}
}

POST /v1/services/{id}/ddos/rules

{
  "app_code": "rust",
  "port": 28015,
  "extra_ports": {"Query": 28016, "RCON": 28016, "RustPlus": 28082}
}

POST는 생성된 규칙을 data에 담아 HTTP 201을 반환합니다. GET은 규칙과 service_id, protection_ip, max_rules가 포함된 meta를 반환합니다. DELETE는 빈 본문을 사용하며 아래와 같은 HTTP 200 응답을 반환합니다. POST와 DELETE 모두 Idempotency-Key가 필요합니다.

GET /v1/services/{id}/ddos/rules

{
  "data": [{
    "id": "example-rule-id",
    "app_code": "rust",
    "port": 28015,
    "protocol": "UDP",
    "extra_ports": [
      {"name": "Query", "port": 28016, "protocol": "UDP"},
      {"name": "RCON", "port": 28016, "protocol": "TCP"},
      {"name": "RustPlus", "port": 28082, "protocol": "TCP"}
    ]
  }],
  "meta": {"service_id": 1234, "protection_ip": "192.0.2.10", "max_rules": 1000}
}

DELETE /v1/services/{id}/ddos/rules/{rule_id}

{"data": {"id": "example-rule-id", "deleted": true}}

패널과 API는 고정 UTC 구간을 공유합니다. 쓰기 시도는 계정당 분당 10회, 보호 IP당 분당 5회, 계정당 UTC 날짜 기준 하루 200회입니다. 제한 검사를 통과한 잘못되거나 실패한 시도도 집계되지만, 성공한 멱등 재응답은 제외됩니다. DDoS API 조회는 계정당 분당 30회를 공유합니다. 보호 IP당 최대 1000개 규칙입니다.

HTTP 404: 알 수 없거나 다른 소유자의 서비스, 다른 소유자의 규칙, 없는 규칙 또는 시스템 규칙. HTTP 409: Advanced DDoS Protection 서비스가 아님(not_supported_for_product), 비활성 서비스, 포트 충돌 또는 동시 변경. HTTP 429: 한도 도달, Retry-After를 따르세요. HTTP 502: 보호 서비스가 요청을 완료하지 못했습니다. 시스템 규칙 block은 숨겨지며 삭제할 수 없습니다. HTTP 503: 요청 한도 확인 기능을 일시적으로 사용할 수 없습니다. Retry-After를 따르세요.

DDoS 공격 보고서

이 엔드포인트를 사용하려면 본인 계정에 속하고 active 또는 suspended 상태인 Remote DDoS Protection 서비스와, 명시적으로 활성화한 read:ddos 권한이 필요합니다. 목록은 서비스의 보호 IP 주소에서 탐지된 DDoS 공격을 최신순으로 보여줍니다.

쿼리 매개변수: from과 to는 날짜(YYYY-MM-DD) 또는 시간대가 포함된 ISO 8601 날짜와 시간으로 지정합니다(기본값: 최근 30일). limit은 1부터 100까지(기본값 25), offset은 0부터 9999까지(기본값 0)입니다. 조회 기간은 90일보다 이전으로 거슬러 올라가지 않으며, 보호 IP 주소가 이 서비스에 할당되기 이전으로도 거슬러 올라가지 않습니다. 실제로 사용된 기간은 meta.from과 meta.to에서 확인할 수 있습니다.

GET /v1/services/{id}/ddos/attacks?from=2026-10-10

{
  "data": [{
    "id": "3f6c1a2e-9b47-4d8a-b5e2-7c0d9e4a1f63",
    "type": "ddos_attack",
    "started_at": "2026-11-07T18:34:06Z",
    "ended_at": null,
    "detected_bps": 20938227712,
    "detected_pps": 1998848,
    "source_ip_count": 341,
    "target_ip": "203.0.113.111",
    "details_available": true
  }],
  "paging": {"limit": 25, "offset": 0, "total": 1, "truncated": false},
  "meta": {"service_id": 5678, "protected_ip": "203.0.113.111", "from": "2026-10-10T00:00:00Z", "to": "2026-11-09T11:10:16Z", "retention_days": 90}
}

각 공격에는 id(UUID), type(ddos_attack, 또는 대상 IP가 일시적으로 널 라우팅으로 차단된 경우 blackhole), started_at, ended_at(null일 수 있음), detected_bps, detected_pps, source_ip_count, target_ip, details_available이 포함됩니다. detected_bps와 detected_pps는 탐지 시점의 속도입니다. 이때 이미 필터링이 시작된 상태이므로 상세 정보의 최대값보다 낮을 수 있습니다. paging에는 limit, offset, total, truncated(기간 내 공격이 500건을 넘으면 true)가, meta에는 service_id, protected_ip, from, to, retention_days(90)가 포함됩니다. 목록은 60초 동안 캐시됩니다.

GET /v1/services/{id}/ddos/attacks/{attack_id}

{
  "data": {
    "id": "3f6c1a2e-9b47-4d8a-b5e2-7c0d9e4a1f63",
    "type": "ddos_attack",
    "started_at": "2026-11-07T18:34:06Z",
    "ended_at": null,
    "detected_bps": 20938227712,
    "detected_pps": 1998848,
    "source_ip_count": 341,
    "target_ip": "203.0.113.111",
    "details_available": true,
    "peak_bps": 20938227712,
    "peak_pps": 1998848,
    "total_bytes": 104809201664,
    "total_packets": 81887232,
    "interval_seconds": 1,
    "traffic": [{"time": "2026-11-07T18:34:06Z", "bps": 20938227712, "pps": 1998848}],
    "protocols": [{"protocol": "UDP", "avg_bps": 695618765, "avg_pps": 65645, "bytes": 104342814720, "packets": 78774272, "bps_percent": 99.56, "pps_percent": 96.2}],
    "destination_ports": [{"port": 58675, "protocol": "UDP", "avg_bps": 695556506, "avg_pps": 65481, "bps_percent": 99.55, "pps_percent": 95.96}],
    "source_ports": [{"port": 53, "protocol": "UDP", "avg_bps": 41896312, "avg_pps": 3511, "bps_percent": 5.996, "pps_percent": 5.15}],
    "source_countries": [{"country": "MX", "avg_bps": 96051528, "avg_pps": 8656}],
    "source_ips": [{"ip": "198.51.100.7", "avg_bps": 46162248, "avg_pps": 4151, "bps_percent": 6.61, "pps_percent": 6.08}],
    "packet_sizes": [{"range": "1400-1499", "avg_bps": 374806938, "percent": 54.076}]
  },
  "meta": {"service_id": 5678, "cached": false}
}

상세 정보에는 목록의 모든 필드와 함께 peak_bps, peak_pps, total_bytes, total_packets, interval_seconds가 포함됩니다. traffic은 필터링 네트워크가 관측한 수신 공격 트래픽을 구간별({time, bps, pps})로 보여주며, 탐지 약 10분 전부터 약 10분 후까지를 다룹니다. 세부 분석 항목 protocols, destination_ports, source_ports, source_countries, source_ips, packet_sizes에는 보통 상위 5개 항목이 포함됩니다. avg_bps와 avg_pps는 측정 구간 전체의 평균이고, bps_percent와 pps_percent는 비율입니다. protocols에는 bytes와 packets도 포함되며, packet_sizes에는 range, avg_bps, percent가 포함됩니다. 상세 정보는 최대 15분 동안 캐시됩니다.

HTTP 400 validation_failed: 잘못된 값 또는 알 수 없는 쿼리 매개변수. HTTP 404: 알 수 없거나 다른 소유자의 서비스, 알 수 없는 공격 ID 또는 다른 IP 주소에 대한 공격. HTTP 409 not_supported_for_product: Remote DDoS Protection 서비스가 아닙니다(예: Advanced DDoS Protection 또는 서버). HTTP 409 service_not_active: 서비스가 active 또는 suspended 상태가 아닙니다. HTTP 409 protection_not_ready: 보호 설정이 아직 진행 중입니다.

서버 지표

이 엔드포인트를 사용하려면 본인 계정의 활성 서비스와 read:services 권한이 필요합니다. Edge Unlimited Traffic VPS는 CPU, 메모리, 수신 및 송신 네트워크(bit/s 및 패킷/s) 지표와 함께 일별 및 이번 달 누적 송신 트래픽을 제공합니다. 유럽, 독일, 프랑스, 캐나다 동부, 영국, 폴란드 위치의 일반 Unlimited Traffic VPS는 수신 및 송신 네트워크 지표를 bit/s로만 제공합니다.

쿼리 매개변수 range: 1h, 6h, 24h, 7d 또는 14d(기본값 1h). 데이터 포인트 간격은 기간에 따라 다릅니다. Edge Unlimited Traffic VPS는 약 15초(1h), 20초(6h), 2분(24h), 10분(7d), 20분(14d)이며, 일반 Unlimited Traffic VPS는 24h까지 5분, 7d는 30분, 14d는 2시간입니다. step_seconds는 응답의 간격을 보여줍니다.

GET /v1/services/{id}/metrics?range=24h

{
  "data": {
    "service_id": 1234,
    "range": "24h",
    "step_seconds": 120,
    "available": ["cpu_percent", "memory_percent", "network_in_bps", "network_out_bps", "network_in_pps", "network_out_pps"],
    "summary": {
      "cpu_percent": {"avg": 3.1, "max": 41.7, "last": 2.9},
      "network_in_bps": {"avg": 64012.5, "max": 912345.0, "last": 60026.2}
    },
    "points": [
      {"time": "2026-11-08T11:12:00Z", "cpu_percent": 3.254, "memory_percent": 43.001, "network_in_bps": 68515.425, "network_out_bps": 650.767, "network_in_pps": 119.992, "network_out_pps": 0.775},
      {"time": "2026-11-08T11:14:00Z", "cpu_percent": 3.118, "memory_percent": 43.004, "network_in_bps": 66120.871, "network_out_bps": 702.134, "network_in_pps": 115.317, "network_out_pps": 0.825}
    ],
    "traffic": {
      "month_to_date_out_bytes": 111844510,
      "daily": [{"date": "2026-11-09", "out_bytes": 10485760, "final": false}],
      "as_of": "2026-11-09T11:00:01Z",
      "unit": "bytes",
      "direction": "outbound"
    }
  },
  "meta": {"generated_at": "2026-11-09T11:12:30Z", "cached": false, "measured_at": "server_network_interface"}
}

값은 서버의 네트워크 인터페이스에서 측정되므로 실제로 서버에 도달한 트래픽을 보여줍니다. 메모리 값을 얻으려면 서버 안에 게스트 에이전트가 필요합니다. 측정할 수 없었던 값은 null입니다. available은 측정값이 있는 지표를 나열하고, summary는 각 지표의 avg, max, last를 보여줍니다. traffic에는 일별 및 이번 달 누적 송신 트래픽이 바이트 단위로 포함되며(하루 집계가 확정되면 final이 true가 됩니다), 트래픽 카운터가 없는 상품에서는 null입니다. 응답은 30초(1h)에서 10분(14d)까지 캐시됩니다. meta.cached에서 응답이 캐시에서 왔는지 확인할 수 있습니다.

HTTP 400 validation_failed: 지원하지 않는 range 값 또는 알 수 없는 쿼리 매개변수. HTTP 404: 알 수 없거나 다른 소유자의 서비스. HTTP 409 not_supported_for_product: 이 서비스에는 사용할 수 있는 지표가 없습니다(다른 상품 및 위치). HTTP 409 service_not_active: 서비스가 활성 상태가 아닙니다.

서버 지표와 공격 보고서에는 일반 속도 제한이 적용됩니다. 또한 캐시에서 응답할 수 없는 데이터 조회는 이 세 엔드포인트를 합산해 계정당 분당 20회로 제한되며, 이를 초과하면 Retry-After와 함께 HTTP 429가 반환됩니다. HTTP 502 monitoring_unavailable 또는 reports_unavailable: 데이터 소스를 일시적으로 사용할 수 없습니다. 나중에 다시 시도하세요. HTTP 503 temporarily_unavailable(Retry-After 포함): 병렬 요청이 같은 데이터를 준비하고 있습니다.

API로 제공되지 않는 항목: Advanced DDoS Protection 및 Edge Unlimited Traffic VPS 같은 서버의 공격 보고서, 보호 IP별 정상 트래픽 또는 폐기된 트래픽 통계, 일반 Unlimited Traffic VPS의 CPU 및 메모리, 웹훅 전송, CSV 내보내기.

멱등성

POST /v1/orders와 POST /v1/services/{id}/actions에는 Idempotency-Key 헤더가 필요합니다([A-Za-z0-9_.-] 문자로 이루어진 1자 이상 80자 이하). 이 키는 메서드, 경로, 본문에 연결됩니다. 1시간 이내에 같은 키로 같은 요청을 반복하면 저장된 응답이 반환됩니다. 그 이후에는 reason replay_stale과 함께 410이 반환되므로 새 키를 전송하십시오. 같은 키를 다른 본문이나 다른 엔드포인트에 사용하면 409 idempotency_conflict로 거부됩니다.

속도 제한

기본적으로 키당 분당 60회(버스트 20회 추가 허용)와 하루 5,000회, 모든 키를 합산한 계정당 분당 120회, 출발지 IP당 분당 600회로 제한됩니다. 제한을 초과하면 Retry-After 헤더와 함께 HTTP 429가 반환됩니다. 응답 헤더 X-RateLimit-Remaining과 X-RateLimit-Reset에서 키 제한의 현재 상태를 확인하실 수 있습니다.