Dokumentacja VPS API: REST API do tworzenia serwerów i zarządzania nimi

Co można robić przez API

API jest przydatne, gdy zarządzasz wieloma serwerami lub chcesz zautomatyzować wdrożenia. Pobierz listy planów, regionów i obrazów; przy tworzeniu serwera płatność jest przetwarzana, a serwer jest tworzony po potwierdzeniu. Obowiązują te same zasady co na stronach internetowych, więc serwery utworzone za pomocą API również pojawiają się na liście serwerów w Twoim koncie.

Jeśli zaczynasz, przejdź krok po kroku szybki start API: od utworzenia klucza do pierwszego serwera. Ta strona to dokumentacja referencyjna ze wszystkimi endpointami i polami.

Adres bazowy

Wszystkie żądania wysyłasz na ścieżkę po poniższym adresie. Treść żądań i odpowiedzi to zawsze JSON (UTF-8).

https://helpervps.com/api/v1

Uwierzytelnianie

Wyślij nagłówek Authorization: Bearer YOUR_API_KEY. Klucz możesz utworzyć z menu kluczy API w swoim koncie po pierwszej płatności; klucze zaczynają się od hvp_. Pełny klucz jest wyświetlany tylko raz, zaraz po utworzeniu, a utworzenie nowego klucza natychmiast dezaktywuje poprzedni.

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

Limity żądań

Kod serwera

Serwery rozróżnia się nie po numerze, lecz po kodzie w postaci S-7K2M-9QX4-HB3T. Wstaw do ścieżki wartość id z listy serwerów lub odpowiedzi na utworzenie. Wielkość liter nie ma znaczenia.

GET /catalog

Zwraca naraz dostępne plany (plans), regiony (locations), obrazy (images) i opcje dodatkowe (addons). Wszystkie kody do tworzenia serwera pochodzą stąd. monthly to cena miesięczna w dolarach USA, a niedostępne opcje mają wartość null. monthly_per_gb dodatkowego dysku jest podawane z dokładnością do trzech miejsc po przecinku.

Przykład żądania

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

Przykład odpowiedzi

{
  "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

Zwraca listę Twoich serwerów, od najnowszych. Usunięte i nieutworzone serwery są pomijane.

Przykład żądania

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

Przykład odpowiedzi

[
  {
    "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

Tworzy serwer i przetwarza płatność. Użyj kodów katalogowych dla planu, lokalizacji i obrazu takimi, jakie są. label może zawierać do 40 liter łacińskich, cyfr, kropek i myślników; inne znaki są zamieniane na myślniki. backups, extra_disk_gb i ddos_protection są opcjonalne. Po powodzeniu otrzymujesz 201 ze szczegółami serwera, a root_password jest zawarte tylko raz w tej odpowiedzi (możesz je również zobaczyć na stronie serwera w swoim koncie przez 7 dni).

Przykład żądania

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}'

Przykład odpowiedzi

{
  "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}

Zwraca stan i adresy jednego serwera, cenę miesięczną i datę końca opłaconego okresu. Nowy serwer zaczyna od stanu creating, po przygotowaniu przechodzi w running i uzupełniane są ipv4 oraz ipv6. Wystarczy sprawdzać co kilka sekund.

Przykład żądania

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

Przykład odpowiedzi

{
  "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 włącza zatrzymany (stopped) serwer, a stop i reboot wyłączają lub restartują działający (running) serwer. W odpowiedzi przychodzą zaktualizowane dane serwera.

Przykład żądania

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

Przykład odpowiedzi

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

POST /servers/{id}/renew

Zapłać teraz, aby przedłużyć okres ważności. Serwer zawieszony po wygaśnięciu również zostanie ponownie włączony tym żądaniem.

Przykład żądania

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

Przykład odpowiedzi

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

DELETE /servers/{id}

Usuwa serwer i dyski. Od następnej daty płatności opłaty nie są pobierane, a pozostała część opłaconego miesiąca nie jest zwracana.

Przykład żądania

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

Przykład odpowiedzi

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

Pola odpowiedzi serwera

Wartości stanu

Błędy

Przy błędzie wraz z kodem stanu zwracany jest JSON w postaci {"error": "kod"}. Obsługuj błędy według wartości kodu.

Przydatne poradniki

Płatności są dokonywane przez bezpieczną kasę PayGate. Możesz ponownie zainstalować i utworzyć nowe hasło root na stronie serwera w swoim koncie; kroki są opisane w przewodniku ponownej instalacji.

Możliwości API i przykłady automatyzacji znajdziesz na stronie VPS API, a ceny miesięczne planów na stronie cennika.