Docs
Powered by

Maszyny VPS (VPS API)

In 

Kompletny przewodnik po endpointach do automatyzacji i zarządzania wirtualnymi serwerami prywatnymi (KVM VPS) w chmurze BlackHost.

1. Szczegóły maszyny VPS (/v1/servers/vps/:id/details)

Zwraca pełną specyfikację techniczną, przydzielony główny adres IP, bramę domyślną, status oraz system operacyjny serwera.

  • Metoda: GET
  • Ścieżka: /v1/servers/vps/{id}/details
  • Wymagany scope: vps:read
  • Parametr {id}: Identyfikator unique_id serwera (np. vps-8f92a1).

Jednostki zwracanych pól:

Pole Jednostka Opis
cpu Liczba rdzeni Przydzielona liczba wirtualnych rdzeni (vCPU)
ram_mb MB (Megabajty) Przydzielona pamięć RAM (np. 8192 MB = 8 GB)
disk_gb GB (Gigabajty) Przestrzeń na szybkich dyskach NVMe PCIe 4.0
prefix Liczba (CIDR) Długość maski podsieci (np. 24 dla /24 = 255.255.255.0)
monthly_price wPLN Miesięczna cena odnowienia usługi

Przykład zapytania cURL

curl -X GET "https://api.blackhost.pl/v1/servers/vps/vps-8f92a1/details" \
  -H "Authorization: Bearer bh_pat_TWOJ_TOKEN" \
  -H "Accept: application/json"

Przykład odpowiedzi (200 OK)

{
  "success": true,
  "server": {
    "id": 45,
    "unique_id": "vps-8f92a1",
    "name": "Moja Maszyna Produkcyjna",
    "node": "waw-1",
    "status": "running",
    "cpu": 4,
    "ram_mb": 8192,
    "disk_gb": 80,
    "ip": "185.25.10.15",
    "prefix": 24,
    "gateway": "185.25.10.1",
    "system": "debian-12",
    "monthly_price": 49.00,
    "expires_at": "2026-09-01T12:00:00.000Z"
  }
}

2. Zarządzanie zasilaniem (/v1/servers/vps/:id/power)

Wysyła polecenie zasilania (ACPI / Force) do hypervisora maszyny wirtualnej.

  • Metoda: POST
  • Ścieżka: /v1/servers/vps/{id}/power
  • Wymagany scope: vps:power
  • Nagłówek: Content-Type: application/json

Dostępne akcje (action / signal):

  • start - uruchomienie maszyny
  • reboot - bezpieczny restart ACPI systemu operacyjnego
  • shutdown - bezpieczne wyłączenie ACPI systemu operacyjnego
  • stop - natychmiastowe odcięcie zasilania maszyny (force stop)

Przykład zapytania cURL

curl -X POST "https://api.blackhost.pl/v1/servers/vps/vps-8f92a1/power" \
  -H "Authorization: Bearer bh_pat_TWOJ_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"action": "reboot"}'

Przykład odpowiedzi (200 OK)

{
  "success": true,
  "message": "Polecenie reboot zostało pomyślnie wysłane."
}

3. Statystyki zużycia na żywo i Hardware

3.1 Statystyki na żywo (/v1/servers/vps/:id/stats)

Pobiera aktualny stan i zużycie zasobów maszyny KVM prosto z hypervisora oraz agenta gościa (QEMU Guest Agent).

  • Metoda: GET
  • Ścieżka: /v1/servers/vps/{id}/stats
  • Wymagany scope: vps:read

Jednostki w obiekcie stats:

Pole Jednostka Opis
stats.cpu Ułamek (0.0 - 1.0) Użycie CPU z perspektywy hosta (0.15 = 15% łącznej mocy vCPU)
stats.mem Bajty (Bytes) Pamięć RAM zaalokowana przez proces maszyny
stats.disk Bajty (Bytes) Przestrzeń wirtualnego dysku
stats.uptime Sekundy (s) Czas działania maszyny wirtualnej od startu
stats.netin Bajty (Bytes) Łączna liczba odebranych bajtów na interfejsie sieciowym
stats.netout Bajty (Bytes) Łączna liczba wysłanych bajtów
stats.agentDiskUsed Bajty (Bytes) Rzeczywiste zajęcie dysku partycji / odczytane przez QEMU Guest Agent 
curl -X GET "https://api.blackhost.pl/v1/servers/vps/vps-8f92a1/stats" \
  -H "Authorization: Bearer bh_pat_TWOJ_TOKEN" \
  -H "Accept: application/json"
{
  "success": true,
  "status": "running",
  "system": "Debian GNU/Linux 12 (bookworm)",
  "stats": {
    "status": "running",
    "cpu": 0.15,
    "mem": 3435973836,
    "disk": 21474836480,
    "uptime": 864000,
    "netin": 104857600,
    "netout": 524288000,
    "agentDiskUsed": 12884901888
  }
}

3.2 Specyfikacja sprzętowa procesora (/v1/servers/vps/:id/hardware)

  • Metoda: GET
  • Ścieżka: /v1/servers/vps/{id}/hardware
  • Wymagany scope: vps:read
curl -X GET "https://api.blackhost.pl/v1/servers/vps/vps-8f92a1/hardware" \
  -H "Authorization: Bearer bh_pat_TWOJ_TOKEN"
{
  "success": true,
  "hardware": {
    "cpuModel": "AMD EPYC 9654 96-Core Processor",
    "cores": 4,
    "ram": "8 GB",
    "disk": "80 GB NVMe PCIe 4.0",
    "networkSpeed": "1 Gbps"
  }
}

4. Dostęp do Konsoli noVNC (/v1/servers/vps/:id/console)

Generuje jednorazowy bilet (ticket) oraz parametry sesji noVNC umożliwiającej zdalny pulpit / dostęp awaryjny do terminala maszyny.

  • Metoda: POST
  • Ścieżka: /v1/servers/vps/{id}/console
  • Wymagany scope: vps:console

Przykład zapytania cURL

curl -X POST "https://api.blackhost.pl/v1/servers/vps/vps-8f92a1/console" \
  -H "Authorization: Bearer bh_pat_TWOJ_TOKEN"

Przykład odpowiedzi (200 OK)

{
  "success": true,
  "ticket": "PVE:vnc:...token...",
  "port": "5900",
  "upid": "UPID:waw-1:..."
}

5. Zapora ogniowa (Firewall API)

5.1 Lista reguł zapory

  • Metoda: GET
  • Ścieżka: /v1/servers/vps/{id}/firewall/rules
  • Wymagany scope: vps:read
curl -X GET "https://api.blackhost.pl/v1/servers/vps/vps-8f92a1/firewall/rules" \
  -H "Authorization: Bearer bh_pat_TWOJ_TOKEN"
{
  "success": true,
  "rules": [
    {
      "pos": 0,
      "type": "in",
      "action": "ACCEPT",
      "proto": "tcp",
      "dport": "22",
      "comment": "SSH Access",
      "enable": 1
    }
  ]
}

5.2 Dodawanie nowej reguły zapory

  • Metoda: POST
  • Ścieżka: /v1/servers/vps/{id}/firewall/rules
  • Wymagany scope: vps:firewall
  • Nagłówek: Content-Type: application/json
curl -X POST "https://api.blackhost.pl/v1/servers/vps/vps-8f92a1/firewall/rules" \
  -H "Authorization: Bearer bh_pat_TWOJ_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "in",
    "action": "ACCEPT",
    "proto": "tcp",
    "dport": "8080",
    "comment": "Moja Aplikacja Web",
    "enable": 1
  }'
{
  "success": true,
  "message": "Reguła firewall została pomyślnie dodana."
}

5.3 Modyfikacja lub usunięcie reguły na danej pozycji

  • Edycja reguły: PUT /v1/servers/vps/{id}/firewall/rules/{pos} 
    curl -X PUT "https://api.blackhost.pl/v1/servers/vps/vps-8f92a1/firewall/rules/0" \
  -H "Authorization: Bearer bh_pat_TWOJ_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"action": "DROP", "proto": "tcp", "dport": "22", "enable": 1}'
  • Usunięcie reguły: DELETE /v1/servers/vps/{id}/firewall/rules/{pos} 
    curl -X DELETE "https://api.blackhost.pl/v1/servers/vps/vps-8f92a1/firewall/rules/0" \
  -H "Authorization: Bearer bh_pat_TWOJ_TOKEN"
  • Wymagany scope: vps:firewall

5.4 Opcje globalne zapory sieciowej

  • Pobranie stanu: GET /v1/servers/vps/{id}/firewall/options (Scope: vps:read)
  • Zmiana opcji: POST /v1/servers/vps/{id}/firewall/options (Scope: vps:firewall)
curl -X POST "https://api.blackhost.pl/v1/servers/vps/vps-8f92a1/firewall/options" \
  -H "Authorization: Bearer bh_pat_TWOJ_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "enable": 1,
    "policy_in": "DROP",
    "policy_out": "ACCEPT"
  }'

5.5 Biała lista adresów IP (Whitelist)

Adresy z białej listy omijają filtry zapory.

  • Pobranie listy: GET /v1/servers/vps/{id}/firewall/whitelist (Scope: vps:read)
  • Dodanie adresu IP: POST /v1/servers/vps/{id}/firewall/whitelist (Scope: vps:firewall)
curl -X POST "https://api.blackhost.pl/v1/servers/vps/vps-8f92a1/firewall/whitelist" \
  -H "Authorization: Bearer bh_pat_TWOJ_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "ip": "203.0.113.50/32",
    "comment": "Adres IP Biura"
  }'

5.6 Raport odpartych ataków DDoS (XDP / eBPF)

Zwraca statystyki ruchu odfiltrowanego przez sprzętowe i programowe filtry anty-DDoS (XDP).

  • Metoda: GET
  • Ścieżka: /v1/servers/vps/{id}/firewall/xdp/attacks
  • Wymagany scope: vps:read

Jednostki w raporcie ataków:

Pole Jednostka Opis
peakPps Pakiety na sekundę (PPS) Szczytowe natężenie pakietów odpartego ataku
peakBps Bity na sekundę (bps) Szczytowa przepustowość odpartego ataku (np. 10500000000 bps = 10.5 Gbps) 
curl -X GET "https://api.blackhost.pl/v1/servers/vps/vps-8f92a1/firewall/xdp/attacks" \
  -H "Authorization: Bearer bh_pat_TWOJ_TOKEN"
{
  "success": true,
  "attacks": [
    {
      "id": "atk-1",
      "source": "UDP Flood",
      "dstIp": "185.25.10.15",
      "peakPps": 1250000,
      "peakBps": 10500000000,
      "status": "mitigated",
      "startedAt": "2026-08-24T18:15:00.000Z",
      "endedAt": "2026-08-24T18:22:00.000Z"
    }
  ]
}

6. Reverse DNS (rDNS / PTR)

Konfiguracja rekordu PTR dla głównego adresu IPv4 Twojej maszyny.

  • Odczyt rekordu: GET /v1/servers/vps/{id}/ptr (Scope: vps:read)
  • Zmiana rekordu: POST /v1/servers/vps/{id}/ptr (Scope: vps:read)
curl -X POST "https://api.blackhost.pl/v1/servers/vps/vps-8f92a1/ptr" \
  -H "Authorization: Bearer bh_pat_TWOJ_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"hostname": "vps.twojadomena.pl"}'
{
  "success": true,
  "message": "Rekord PTR został zaktualizowany."
}

7. Kopie zapasowe (Backups)

Pobiera listę utworzonych kopii zapasowych (Proxmox Backup Server / Snapshots) maszyny VPS.

  • Metoda: GET
  • Ścieżka: /v1/servers/vps/{id}/backups
  • Wymagany scope: vps:read
  • Jednostka size: Bajty (Bytes) (np. 8589934592 B = 8 GB)
curl -X GET "https://api.blackhost.pl/v1/servers/vps/vps-8f92a1/backups" \
  -H "Authorization: Bearer bh_pat_TWOJ_TOKEN"
{
  "success": true,
  "snapshots": [],
  "pbsBackups": [
    {
      "id": "backup/qemu/105/2026-08-20T02:00:00Z",
      "size": 8589934592,
      "created_at": "2026-08-20T02:00:00.000Z",
      "format": "pbs"
    }
  ]
}

8. Wykresy i historia zużycia RRD (/v1/servers/vps/:id/history)

Pobiera dane historyczne zużycia zasobów procesora, pamięci operacyjnej oraz przepustowości sieciowej.

  • Metoda: GET
  • Ścieżka: /v1/servers/vps/{id}/history?timeframe={zakres}
  • Wymagany scope: vps:read
  • Dozwolone wartości timeframe: hour (domyślnie), day, week, month

Jednostki w punktach danych:

Pole Jednostka Opis
time Milisekundy (Unix ms) Znacznik czasu pomiaru
cpu % (Procent) Średnie zużycie procesora
ram % (Procent) Średnie procentowe zużycie pamięci RAM
netin KB/s (Kilobajty/s) Prędkość ruchu przychodzącego
netout KB/s (Kilobajty/s) Prędkość ruchu wychodzącego 
curl -X GET "https://api.blackhost.pl/v1/servers/vps/vps-8f92a1/history?timeframe=day" \
  -H "Authorization: Bearer bh_pat_TWOJ_TOKEN"
{
  "success": true,
  "data": [
    {
      "time": 1729000000000,
      "cpu": 14.2,
      "ram": 52.8,
      "netin": 128.4,
      "netout": 450.1
    }
  ]
}

9. Dziennik logów i zdarzeń (/v1/servers/vps/:id/logs)

Zwraca listę ostatnich 100 operacji i zdarzeń administracyjnych wykonanych na serwerze VPS.

  • Metoda: GET
  • Ścieżka: /v1/servers/vps/{id}/logs
  • Wymagany scope: vps:read
curl -X GET "https://api.blackhost.pl/v1/servers/vps/vps-8f92a1/logs" \
  -H "Authorization: Bearer bh_pat_TWOJ_TOKEN"
{
  "success": true,
  "logs": [
    {
      "action": "POWER_START",
      "method": "POST",
      "message": "server.started",
      "ip": "193.70.xx.xx",
      "date": "2026-10-10T12:00:00.000Z",
      "createdAt": "2026-10-10 12:00:00"
    }
  ]
}

10. Historia ataków DDoS / XDP (/v1/servers/vps/:id/firewall/xdp/attacks)

Pobiera historię zablokowanych ataków DDoS zarejestrowanych przez warstwę ochrony XDP na adresach IP przypisanych do Twojego VPS.

  • Metoda: GET
  • Ścieżka: /v1/servers/vps/{id}/firewall/xdp/attacks
  • Wymagany scope: vps:read
curl -X GET "https://api.blackhost.pl/v1/servers/vps/vps-8f92a1/firewall/xdp/attacks" \
  -H "Authorization: Bearer bh_pat_TWOJ_TOKEN"
{
  "success": true,
  "attacks": [
    {
      "id": "att_105291",
      "ip": "193.70.12.34",
      "started_at": "2026-10-09T22:15:00.000Z",
      "ended_at": "2026-10-09T22:20:00.000Z",
      "duration_seconds": 300,
      "peak_bandwidth_mbps": 2400,
      "peak_packets_pps": 1200000,
      "attack_type": "SYN Flood",
      "status": "mitigated"
    }
  ],
  "total": 1
}

11. Harmonogram zadań VPS (/v1/servers/vps/:id/schedules)

Zarządzanie zaplanowanymi automatycznymi akcjami zasilania maszyny VPS (np. nocny restart w formacie CRON).

11.1 Lista zaplanowanych zadań

  • Metoda: GET
  • Ścieżka: /v1/servers/vps/{id}/schedules
  • Wymagany scope: vps:read
{
  "success": true,
  "schedules": [
    {
      "id": 12,
      "server_unique_id": "vps-8f92a1",
      "action": "reboot",
      "cron_expression": "0 4 * * *",
      "label": "Restart nocny",
      "enabled": true,
      "next_run_at": "2026-10-12T04:00:00.000Z"
    }
  ]
}

11.2 Tworzenie nowego zadania

  • Metoda: POST
  • Ścieżka: /v1/servers/vps/{id}/schedules
  • Wymagany scope: vps:power
  • Dozwolone akcje (action): start, stop, reboot, shutdown
curl -X POST "https://api.blackhost.pl/v1/servers/vps/vps-8f92a1/schedules" \
  -H "Authorization: Bearer bh_pat_TWOJ_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "action": "reboot",
    "cron_expression": "0 4 * * *",
    "label": "Restart nocny",
    "enabled": true
  }'

11.3 Modyfikacja zadania

  • Metoda: PATCH
  • Ścieżka: /v1/servers/vps/{id}/schedules/{scheduleId}
  • Wymagany scope: vps:power

11.4 Usunięcie zadania

  • Metoda: DELETE
  • Ścieżka: /v1/servers/vps/{id}/schedules/{scheduleId}
  • Wymagany scope: vps:power

12. Zmiana nazwy maszyny VPS (/v1/servers/vps/:id/rename)

Aktualizuje etykietę i nazwę wyświetlaną serwera VPS w panelu.

  • Metoda: POST lub PUT
  • Ścieżka: /v1/servers/vps/{id}/rename
  • Wymagany scope: Token z pełnymi uprawnieniami (*) lub sesja
  • Długość nazwy: od 1 do 64 znaków
curl -X POST "https://api.blackhost.pl/v1/servers/vps/vps-8f92a1/rename" \
  -H "Authorization: Bearer bh_pat_TWOJ_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "VPS Produkcja Web"}'
{
  "success": true,
  "name": "VPS Produkcja Web"
}

13. Sesja Webowego Terminala SSH (/v1/servers/vps/:id/ssh-terminal)

Generuje bezpieczny jednorazowy token połączenia WebSocket do wbudowanego w panel terminala SSH (xterm.js).

  • Metoda: POST
  • Ścieżka: /v1/servers/vps/{id}/ssh-terminal
  • Wymagany scope: vps:console

Ciało zapytania:

{
  "username": "root",
  "password": "twoje_haslo_root",
  "port": 22
}

Odpowiedź (200 OK):

{
  "success": true,
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "serverId": "vps-8f92a1",
  "username": "root",
  "ip": "193.70.12.34",
  "port": 22
}