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