Sur cette page
- 1. Szczegóły maszyny VPS (`/v1/servers/vps/:id/details`)
- Jednostki zwracanych pól:
- Przykład zapytania cURL
- Przykład odpowiedzi (200 OK)
- 2. Zarządzanie zasilaniem (`/v1/servers/vps/:id/power`)
- Dostępne akcje (`action` / `signal`):
- Przykład zapytania cURL
- Przykład odpowiedzi (200 OK)
- 3. Statystyki zużycia na żywo i Hardware
- 3.1 Statystyki na żywo (`/v1/servers/vps/:id/stats`)
- Jednostki w obiekcie `stats`:
- 3.2 Specyfikacja sprzętowa procesora (`/v1/servers/vps/:id/hardware`)
- 4. Dostęp do Konsoli noVNC (`/v1/servers/vps/:id/console`)
- Przykład zapytania cURL
- Przykład odpowiedzi (200 OK)
- 5. Zapora ogniowa (Firewall API)
- 5.1 Lista reguł zapory
- 5.2 Dodawanie nowej reguły zapory
- 5.3 Modyfikacja lub usunięcie reguły na danej pozycji
- 5.4 Opcje globalne zapory sieciowej
- 5.5 Biała lista adresów IP (Whitelist)
- 5.6 Raport odpartych ataków DDoS (XDP / eBPF)
- Jednostki w raporcie ataków:
- 6. Reverse DNS (rDNS / PTR)
- 7. Kopie zapasowe (Backups)
- 7.1 Lista kopii zapasowych
- 7.2 Przywracanie kopii PBS (`/v1/servers/vps/:id/backups/pbs`)
- 8. Wykresy i historia zużycia RRD (`/v1/servers/vps/:id/history`)
- Jednostki w punktach danych:
- 9. Dziennik logów i zdarzeń (`/v1/servers/vps/:id/logs`)
- 10. Historia ataków DDoS / XDP (`/v1/servers/vps/:id/firewall/xdp/attacks`)
- 11. Harmonogram zadań VPS (`/v1/servers/vps/:id/schedules`)
- 11.1 Lista zaplanowanych zadań
- 11.2 Tworzenie nowego zadania
- 11.3 Modyfikacja zadania
- 11.4 Usunięcie zadania
- 12. Zmiana nazwy maszyny VPS (`/v1/servers/vps/:id/rename`)
- 13. Sesja Webowego Terminala SSH (`/v1/servers/vps/:id/ssh-terminal`)
- Ciało zapytania:
- Odpowiedź (200 OK):
- 14. Autoinstalatory oprogramowania (1-Click Apps API)
- Dostępne aplikacje (`application`):
- 14.1 Lista szablonów i stan instalacji
- 14.2 Rozpoczęcie instalacji oprogramowania
- 14.3 Podgląd stanu i logów instalacji
- 14.4 Anulowanie instalacji
- 15. Zarządzanie kluczami SSH (SSH Keys API)
- 15.1 Lista kluczy SSH
- 15.2 Dodanie klucza publicznego
- 15.3 Automatyczne wygenerowanie pary kluczy
- 15.4 Usunięcie klucza SSH
- 16. Bezpieczeństwo i reinstalacja systemu
- 16.1 Reinstalacja systemu operacyjnego
- 16.2 Zresetowanie hasła konta root
- 17. Delegowanie dostępu i subużytkownicy (Subusers API)
- 17.1 Lista subużytkowników
- 17.2 Zaproszenie subużytkownika
- 17.3 Modyfikacja lub usunięcie subużytkownika
- 17.4 Katalog dostępnych uprawnień dla subużytkowników
- 18. Strumieniowanie telemetryczne w czasie rzeczywistym
- 18.1 Strumień Server-Sent Events (SSE)
- 18.2 WebSocket telemetrii na żywo (Live WebSocket)
- 19. Cykl życia, zakupy i odnowienia VPS (VPS Lifecycle & Billing)
- 19.1 Odnowienie maszyny VPS
- 19.2 Konfiguracja automatycznego odnawiania
- 19.3 Zmiana / Podniesienie pakietu (Upgrade)
- 19.4 Zakup nowej maszyny VPS
- Parametry w ciele zapytania:
Maszyny VPS
Dernière mise à jour 21 novembre 2026
Cet article n'est pas encore disponible dans votre langue - version polonaise affichée.
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}: Identyfikatorunique_idserwera (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 maszynyreboot- bezpieczny restart ACPI systemu operacyjnegoshutdown- bezpieczne wyłączenie ACPI systemu operacyjnegostop- 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: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.8589934592B = 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:backupslubvps: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:
| 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:
POSTlubPUT - Ś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 gierpterodactyl-wings- demon wykonawczy serwerów gierblueprint- framework rozszerzeń panelu Pterodactylnginx- serwer WWW i reverse proxyphpmyadmin- 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:installlubvps: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:installlubvps: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:settingslubvps: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łówkuAuthorization: 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:billinglubvps:power - Ciało zapytania:
{"days": 30, "code": "PROMO10"}
| Pole | Typ | Wymagane | Opis |
|---|---|---|---|
days | Liczba | Nie | Okres przedłużenia w dniach: 30, 90, 180 lub 360 (domyślnie 30) |
code | String | Nie | Opcjonalny 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:billinglubvps: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 polamicurrentTier,availableUpgrades(lista wariantów z ceną i wyliczoną dopłatą) orazuserWpln - Wykonanie ulepszenia:
POST /v1/servers/vps/{id}/upgrade - Wymagany scope:
account:billinglubvps:power - Ciało zapytania:
{"targetPacketId": "vps-nvme", "targetTierName": "Standard"}
| Pole | Typ | Wymagane | Opis |
|---|---|---|---|
targetPacketId | String | Tak | Identyfikator oferty (uniqueId z katalogu /v1/shop/packets) |
targetTierName | String | Tak | Nazwa 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:
| Pole | Typ | Wymagane | Opis |
|---|---|---|---|
offerId | String | Tak | Identyfikator oferty VPS (uniqueId z katalogu, np. vps-nvme) |
packageName | String | Tak | Nazwa wariantu pakietu (servers[].name, np. Standard) |
node | String | Tak | Lokalizacja: PL_BASE lub PL_PREMIUM (musi występować w locations[] wariantu) |
system | String | Tak | Szablon systemowy z installations[] oferty (np. debian-12, ubuntu-24.04) |
days | Liczba | Nie | Okres: 30, 90, 180 lub 360 dni (domyślnie 30; rabaty jak przy odnowieniu) |
code | String | Nie | Opcjonalny kod promocyjny |
ℹ️ Nazwa maszyny jest nadawana automatycznie (format
vps-{vmid}) - polenamenie 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
}'