Auf dieser Seite1. Szczegóły maszyny VPS (`/v1/servers/vps/:id/details`)

Maszyny VPS

Zuletzt aktualisiert 21. November 2026

Dieser Artikel ist noch nicht in deiner Sprache verfügbar - die polnische Version wird angezeigt.

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:

PoleJednostkaOpis
cpuLiczba rdzeniPrzydzielona liczba wirtualnych rdzeni (vCPU)
ram_mbMB (Megabajty)Przydzielona pamięć RAM (np. 8192 MB = 8 GB)
disk_gbGB (Gigabajty)Przestrzeń na szybkich dyskach NVMe PCIe 4.0
prefixLiczba (CIDR)Długość maski podsieci (np. 24 dla /24 = 255.255.255.0)
monthly_pricewPLNMiesię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:

PoleJednostkaOpis
stats.cpuUłamek (0.0 - 1.0)Użycie CPU z perspektywy hosta (0.15 = 15% łącznej mocy vCPU)
stats.memBajty (Bytes)Pamięć RAM zaalokowana przez proces maszyny
stats.diskBajty (Bytes)Przestrzeń wirtualnego dysku
stats.uptimeSekundy (s)Czas działania maszyny wirtualnej od startu
stats.netinBajty (Bytes)Łączna liczba odebranych bajtów na interfejsie sieciowym
stats.netoutBajty (Bytes)Łączna liczba wysłanych bajtów
stats.agentDiskUsedBajty (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:

PoleJednostkaOpis
peakPpsPakiety na sekundę (PPS)Szczytowe natężenie pakietów odpartego ataku
peakBpsBity 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:settings)
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)

7.1 Lista kopii zapasowych

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

7.2 Przywracanie kopii PBS (/v1/servers/vps/:id/backups/pbs)

Przywraca maszynę wirtualną ze wskazanej migawki Proxmox Backup Server. Podczas przywracania maszyna zostaje bezpiecznie zatrzymana, a jej dysk odtworzony do stanu z kopii zapasowej.

  • Metoda: POST
  • Ścieżka: /v1/servers/vps/{id}/backups/pbs
  • Wymagany scope: vps:backups lub vps:power
  • Nagłówek: Content-Type: application/json
curl -X POST "https://api.blackhost.pl/v1/servers/vps/vps-8f92a1/backups/pbs" \
  -H "Authorization: Bearer bh_pat_TWOJ_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "action": "restore",
    "backupId": "backup/qemu/105/2026-08-20T02:00:00Z"
  }'
{
  "success": true,
  "message": "Zadanie przywracania kopii PBS zostało pomyślnie zlecone."
}

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:

PoleJednostkaOpis
timeMilisekundy (Unix ms)Znacznik czasu pomiaru
cpu% (Procent)Średnie zużycie procesora
ram% (Procent)Średnie procentowe zużycie pamięci RAM
netinKB/s (Kilobajty/s)Prędkość ruchu przychodzącego
netoutKB/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: vps:settings
  • 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
}

14. Autoinstalatory oprogramowania (1-Click Apps API)

Umożliwia bezobsługową instalację i odinstalowywanie gotowych aplikacji na maszynie VPS za pośrednictwem QEMU Guest Agent.

Dostępne aplikacje (application):

  • pterodactyl-panel - panel zarządzania serwerami gier
  • pterodactyl-wings - demon wykonawczy serwerów gier
  • blueprint - framework rozszerzeń panelu Pterodactyl
  • nginx - serwer WWW i reverse proxy
  • phpmyadmin - webowy interfejs baz danych MySQL/MariaDB

14.1 Lista szablonów i stan instalacji

  • Metoda: GET
  • Ścieżka: /v1/servers/vps/{id}/installations
  • Wymagany scope: vps:read
curl -X GET "https://api.blackhost.pl/v1/servers/vps/vps-8f92a1/installations" \
  -H "Authorization: Bearer bh_pat_TWOJ_TOKEN"

14.2 Rozpoczęcie instalacji oprogramowania

  • Metoda: POST
  • Ścieżka: /v1/servers/vps/{id}/installations
  • Wymagany scope: vps:install lub vps:power
  • Nagłówek: Content-Type: application/json
curl -X POST "https://api.blackhost.pl/v1/servers/vps/vps-8f92a1/installations" \
  -H "Authorization: Bearer bh_pat_TWOJ_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "application": "nginx"
  }'
{
  "success": true,
  "message": "Instalacja została zlecona.",
  "installationId": 42
}

14.3 Podgląd stanu i logów instalacji

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

14.4 Anulowanie instalacji

  • Metoda: POST
  • Ścieżka: /v1/servers/vps/{id}/installations/{installationId}/cancel
  • Wymagany scope: vps:install lub vps:power

15. Zarządzanie kluczami SSH (SSH Keys API)

Pozwala na bezpieczne zarządzanie kluczami publicznymi OpenSSH wstrzykiwanymi do maszyny wirtualnej przez Cloud-Init.

15.1 Lista kluczy SSH

  • Metoda: GET
  • Ścieżka: /v1/servers/vps/{id}/ssh-keys
  • Wymagany scope: vps:read
curl -X GET "https://api.blackhost.pl/v1/servers/vps/vps-8f92a1/ssh-keys" \
  -H "Authorization: Bearer bh_pat_TWOJ_TOKEN"

15.2 Dodanie klucza publicznego

  • Metoda: POST
  • Ścieżka: /v1/servers/vps/{id}/ssh-keys
  • Wymagany scope: vps:settings
  • Nagłówek: Content-Type: application/json
curl -X POST "https://api.blackhost.pl/v1/servers/vps/vps-8f92a1/ssh-keys" \
  -H "Authorization: Bearer bh_pat_TWOJ_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Mój Klucz Laptop",
    "publicKey": "ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAI..."
  }'

15.3 Automatyczne wygenerowanie pary kluczy

Generuje nową parę kluczy ED25519, instaluje klucz publiczny na VPS i jednorazowo zwraca klucz prywatny.

  • Metoda: POST
  • Ścieżka: /v1/servers/vps/{id}/ssh-keys/generate
  • Wymagany scope: vps:settings
  • Nagłówek: Content-Type: application/json
curl -X POST "https://api.blackhost.pl/v1/servers/vps/vps-8f92a1/ssh-keys/generate" \
  -H "Authorization: Bearer bh_pat_TWOJ_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "Automatyczny Klucz Skryptu"}'

15.4 Usunięcie klucza SSH

  • Metoda: DELETE
  • Ścieżka: /v1/servers/vps/{id}/ssh-keys/{keyId}
  • Wymagany scope: vps:settings

16. Bezpieczeństwo i reinstalacja systemu

16.1 Reinstalacja systemu operacyjnego

Wdraża czysty obraz wybranego systemu operacyjnego na maszynie VPS z opcjonalnym podpięciem klucza SSH.

  • Metoda: POST
  • Ścieżka: /v1/servers/vps/{id}/reinstall
  • Wymagany scope: vps:settings lub vps:power
  • Nagłówek: Content-Type: application/json
curl -X POST "https://api.blackhost.pl/v1/servers/vps/vps-8f92a1/reinstall" \
  -H "Authorization: Bearer bh_pat_TWOJ_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "system": "debian-12",
    "sshKeyId": 5
  }'

16.2 Zresetowanie hasła konta root

Ustala nowe hasło użytkownika root za pośrednictwem Proxmox Cloud-Init.

  • Metoda: POST
  • Ścieżka: /v1/servers/vps/{id}/ssh-password
  • Wymagany scope: vps:settings
  • Nagłówek: Content-Type: application/json
curl -X POST "https://api.blackhost.pl/v1/servers/vps/vps-8f92a1/ssh-password" \
  -H "Authorization: Bearer bh_pat_TWOJ_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "password": "NoweBezpieczneHaslo!2026"
  }'

17. Delegowanie dostępu i subużytkownicy (Subusers API)

Umożliwia przydzielanie dostępu do maszyny VPS innym użytkownikom panelu z granularnym wyborem uprawnień.

17.1 Lista subużytkowników

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

17.2 Zaproszenie subużytkownika

  • Metoda: POST
  • Ścieżka: /v1/servers/vps/{id}/subusers
  • Wymagany scope: vps:subusers
  • Nagłówek: Content-Type: application/json
curl -X POST "https://api.blackhost.pl/v1/servers/vps/vps-8f92a1/subusers" \
  -H "Authorization: Bearer bh_pat_TWOJ_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]",
    "permissions": ["power", "console", "firewall"]
  }'

17.3 Modyfikacja lub usunięcie subużytkownika

  • Edycja uprawnień: PUT /v1/servers/vps/{id}/subusers/{subuserId} (Scope: vps:subusers)
  • Usunięcie dostępu: DELETE /v1/servers/vps/{id}/subusers/{subuserId} (Scope: vps:subusers)

17.4 Katalog dostępnych uprawnień dla subużytkowników

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

18. Strumieniowanie telemetryczne w czasie rzeczywistym

Zapewnia ciągły strumień danych zużycia CPU, RAM, dysku i ruchu sieciowego bez narzutu ciągłego odpytywania (polling).

18.1 Strumień Server-Sent Events (SSE)

  • Metoda: GET
  • Ścieżka: /v1/servers/vps/{id}/stream
  • Format: text/event-stream
  • Wymagany scope: vps:read
curl -N -X GET "https://api.blackhost.pl/v1/servers/vps/vps-8f92a1/stream" \
  -H "Authorization: Bearer bh_pat_TWOJ_TOKEN" \
  -H "Accept: text/event-stream"

18.2 WebSocket telemetrii na żywo (Live WebSocket)

  • Protokół: WSS
  • Ścieżka: wss://api.blackhost.pl/v1/servers/vps/{id}/live?token=bh_pat_TWOJ_TOKEN
  • Wymagany scope: vps:read (Token API można przekazać zarówno w parametrze zapytania ?token=, jak i w nagłówku Authorization: Bearer).

19. Cykl życia, zakupy i odnowienia VPS (VPS Lifecycle & Billing)

Endpointy do przedłużania ważności, auto-odnawiania oraz zakupu maszyn VPS.

19.1 Odnowienie maszyny VPS

  • Metoda: POST
  • Ścieżka: /v1/servers/vps/{id}/renew
  • Wymagany scope: account:billing lub vps:power
  • Ciało zapytania: {"days": 30, "code": "PROMO10"}
PoleTypWymaganeOpis
daysLiczbaNieOkres przedłużenia w dniach: 30, 90, 180 lub 360 (domyślnie 30)
codeStringNieOpcjonalny kod promocyjny

ℹ️ Dłuższe okresy objęte są automatycznym rabatem: 90 dni −5%, 180 dni −10%, 360 dni −15%.


19.2 Konfiguracja automatycznego odnawiania

  • Metoda: POST
  • Ścieżka: /v1/servers/vps/{id}/auto-renew
  • Wymagany scope: account:billing lub vps:power
  • Ciało zapytania: {"enabled": true}

19.3 Zmiana / Podniesienie pakietu (Upgrade)

  • Podgląd dostępnych ulepszeń: GET /v1/servers/vps/{id}/upgrade - zwraca obiekt z polami currentTier, availableUpgrades (lista wariantów z ceną i wyliczoną dopłatą) oraz userWpln
  • Wykonanie ulepszenia: POST /v1/servers/vps/{id}/upgrade
  • Wymagany scope: account:billing lub vps:power
  • Ciało zapytania: {"targetPacketId": "vps-nvme", "targetTierName": "Standard"}
PoleTypWymaganeOpis
targetPacketIdStringTakIdentyfikator oferty (uniqueId z katalogu /v1/shop/packets)
targetTierNameStringTakNazwa wariantu docelowego (servers[].name z katalogu)

19.4 Zakup nowej maszyny VPS

Tworzy i uruchamia nową maszynę VPS opłaconą ze środków wPLN. Kontrakt jest identyczny jak przy zakupie serwera gry.

  • Metoda: POST
  • Ścieżka: /v1/servers/vps/purchase
  • Wymagany scope: account:billing
  • Nagłówek: Content-Type: application/json

Parametry w ciele zapytania:

PoleTypWymaganeOpis
offerIdStringTakIdentyfikator oferty VPS (uniqueId z katalogu, np. vps-nvme)
packageNameStringTakNazwa wariantu pakietu (servers[].name, np. Standard)
nodeStringTakLokalizacja: PL_BASE lub PL_PREMIUM (musi występować w locations[] wariantu)
systemStringTakSzablon systemowy z installations[] oferty (np. debian-12, ubuntu-24.04)
daysLiczbaNieOkres: 30, 90, 180 lub 360 dni (domyślnie 30; rabaty jak przy odnowieniu)
codeStringNieOpcjonalny kod promocyjny

ℹ️ Nazwa maszyny jest nadawana automatycznie (format vps-{vmid}) - pole name nie występuje w ciele zapytania.

curl -X POST "https://api.blackhost.pl/v1/servers/vps/purchase" \
  -H "Authorization: Bearer bh_pat_TWOJ_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "offerId": "vps-nvme",
    "packageName": "Standard",
    "node": "PL_BASE",
    "system": "debian-12",
    "days": 30
  }'