Pierwsze kroki z API

Pierwsze wywołania REST API Hostava z curl — sprawdzenie konta, katalog, utworzenie serwera i obsługa błędów.

Wszystko, co zrobisz w panelu, zrobisz też przez REST API: serwery, projekty, klucze SSH, bazy danych, load balancery, Kubernetes, Storage S3, VPN i rozliczenia. Pełny opis wszystkich operacji znajdziesz w dokumentacji API (menu Dla programistów → Dokumentacja API).

Zanim zaczniesz

1. Wygeneruj token w Dla programistów → Tokeny API — zobacz Tokeny API.
2. Sprawdź adres bazowy API — jest podany na początku dokumentacji API oraz w przykładzie na stronie Tokeny API.
3. Zapisz oba w zmiennych środowiskowych:

export HOSTAVA_TOKEN="hv_…"
export HOSTAVA_API="https://api-prod.hostava.pl"

Podstawowe zasady:

• dane wysyłasz i odbierasz w formacie JSON,
• kwoty są w złotych netto, daty w formacie ISO 8601 (UTC),
• token przekazujesz w nagłówku Authorization: Bearer <token>.

Krok 1. Sprawdź, czy token działa

curl -H "Authorization: Bearer $HOSTAVA_TOKEN" $HOSTAVA_API/auth/me

W odpowiedzi dostaniesz dane konta, w tym saldo (balance).

Krok 2. Pobierz katalog

curl -H "Authorization: Bearer $HOSTAVA_TOKEN" $HOSTAVA_API/catalog

Katalog zawiera dostępne lokalizacje (locations), plany (plans) i obrazy systemów (images). Z niego bierzesz nazwę lokalizacji oraz planId i imageId.

Wskazówka: Plany i obrazy mogą się zmieniać — nie zapisuj ich identyfikatorów na sztywno bez sprawdzenia katalogu.

Krok 3. Lista serwerów i kluczy SSH

curl -H "Authorization: Bearer $HOSTAVA_TOKEN" $HOSTAVA_API/servers
curl -H "Authorization: Bearer $HOSTAVA_TOKEN" $HOSTAVA_API/ssh-keys

Listę serwerów możesz filtrować parametrami project (ID projektu), tag i q (szukanie po nazwie i adresach IP).

Krok 4. Utwórz serwer

curl -X POST -H "Authorization: Bearer $HOSTAVA_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"hostname":"web-01","location":"Warszawa","planId":1,"imageId":1,"sshKeyIds":[1],"tags":["web"]}' \
  $HOSTAVA_API/servers

Wymagane są hostname, location, planId, imageId oraz sshKeyIds albo password. Opcjonalnie podasz projectId — bez niego serwer trafi do projektu domyślnego.

Odpowiedź przychodzi od razu ze statusem provisioning. Serwer jest gotowy, gdy status zmieni się na running — zwykle w niecałą minutę. Sprawdzisz to tak:

curl -H "Authorization: Bearer $HOSTAVA_TOKEN" $HOSTAVA_API/servers/42

Uwaga: Utworzenie serwera od razu pobiera z salda opłatę za pierwszą godzinę. Jeśli saldo jej nie pokrywa, API zwróci błąd 400. Jeśli tworzenie się nie powiedzie (status: error), opłatę zwracamy.

Krok 5. Zarządzaj zasilaniem

curl -X POST -H "Authorization: Bearer $HOSTAVA_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"action":"reboot"}' $HOSTAVA_API/servers/42/power

Dostępne akcje: start, shutdown, reboot, reset, stop. Operacje na serwerze są asynchroniczne — trwającą operację widać w polu currentTask. Na serwerze może trwać tylko jedna operacja naraz.

Kody błędów

Błąd zawsze ma postać { "error": "…" } z komunikatem po polsku.

Specyfikacja OpenAPI

Na stronie dokumentacji API kliknij OpenAPI, aby pobrać specyfikację w formacie OpenAPI 3.1. Zaimportujesz ją do Postmana lub Insomnii albo wygenerujesz z niej klienta SDK w swoim języku.

Powiązane artykuły:

• Tokeny API
• Jak liczymy koszty
• Czym są projekty