На цій сторінці
- 1. Lista serwerów (`/v1/servers`)
- Jednostki zwracanych pól:
- Przykład zapytania cURL
- Przykład odpowiedzi (200 OK)
- 2. Szczegóły i stan serwera (`/v1/servers/game/:id/details`)
- Jednostki w obiekcie `limits`:
- Przykład zapytania cURL
- Przykład odpowiedzi (200 OK)
- 3. Statystyki zużycia na żywo (`/v1/servers/game/:id/stats`)
- Jednostki w obiekcie `stats`:
- Przykład zapytania cURL
- Przykład odpowiedzi (200 OK)
- 4. Zarządzanie zasilaniem (`/v1/servers/game/:id/power`)
- Dostępne sygnały (`signal`):
- Przykład zapytania cURL
- Przykład odpowiedzi (200 OK)
- 5. Wysyłanie poleceń do konsoli (`/v1/servers/game/:id/command`)
- Przykład zapytania cURL
- Przykład odpowiedzi (200 OK)
- 6. Połączenie z konsolą na żywo (`/v1/servers/game/:id/websocket`)
- Przykład zapytania cURL
- Przykład odpowiedzi (200 OK)
- 7. Menedżer plików (File Manager API)
- 7.1 Lista plików w katalogu
- 7.2 Odczyt zawartości pliku
- 7.3 Zapis zawartości do pliku
- 7.4 Pobieranie pliku (Download URL)
- 7.5 Wyszukiwanie plików po nazwie
- 7.6 Tworzenie folderu
- 7.7 Usuwanie plików i folderów
- 7.8 Zmiana nazwy lub przenoszenie
- 7.9 Pakowanie (ZIP) i Rozpakowywanie
- 7.10 Pobranie adresu do wgrywania plików (Upload URL)
- 8. Zarządzanie Graczami (Players API)
- 8.1 Lista graczy
- 8.2 Akcje na graczach (Kick, Ban, Op, Whitelist)
- 8.3 Podgląd ekwipunku gracza Minecraft (Inventory API)
- 9. Integracja z Webhookiem Discord (`/v1/servers/game/:id/webhook`)
- Przykład zapytania (PUT):
- 10. Zasoby i dane serwera (`/v1/servers/game/:id/data`)
- Dostępne zasoby (`resource`):
- 11. Autoinstalatory oprogramowania i silników (Game Installer API)
- 11.1 Przeglądanie katalogu instalatora
- 11.2 Dostępne wersje dodatku / modpacka
- 11.3 Rozpoczęcie instalacji
- 12. Cykl życia, finanse i serwery darmowe (Game Lifecycle & Billing)
- 12.1 Odnowienie serwera gry
- 12.2 Konfiguracja automatycznego odnawiania
- 12.3 Zmiana / Podniesienie pakietu (Upgrade)
- 12.4 Zakup nowego serwera gry z portfela
- Parametry w ciele zapytania:
- Przykład odpowiedzi (201 Created)
- 12.5 Serwery darmowe (Free Tier)
Serwery Gier
Останнє оновлення 21 листопада 2026 р.
Ця стаття ще недоступна вашою мовою - показуємо польську версію.
Kompletny przewodnik po endpointach do zarządzania instancjami serwerów gier (Minecraft, GTA V / FiveM, Rust, Palworld, CS2, ARK itp.).
1. Lista serwerów (/v1/servers)
Zwraca listę wszystkich aktywnych serwerów gier oraz maszyn VPS przypisanych do Twojego konta.
- Metoda:
GET - Ścieżka:
/v1/servers - Wymagany scope:
account:read
Jednostki zwracanych pól:
| Pole | Jednostka | Opis |
|---|---|---|
cpu | % (Procent) | Limit procesora (100 = 1 rdzeń vCPU, 200 = 2 rdzenie) |
ram_mb | MB (Megabajty) | Przypisany limit pamięci operacyjnej RAM |
disk_gb | GB (Gigabajty) | Przypisana przestrzeń dyskowa |
unique_id | String | Publiczny unikalny identyfikator serwera (używany we wszystkich endpointach) |
monthly_price | wPLN | Miesięczny koszt odnowienia usługi |
Przykład zapytania cURL
curl -X GET "https://api.blackhost.pl/v1/servers" \
-H "Authorization: Bearer bh_pat_TWOJ_TOKEN" \
-H "Accept: application/json"
Przykład odpowiedzi (200 OK)
Serwery gier są zwracane w tablicy pterodactyl_servers, a maszyny VPS w tablicy pve_servers:
{
"success": true,
"pve_servers": [],
"pterodactyl_servers": [
{
"id": 1191,
"unique_id": "d0969f0b",
"name": "Minecraft Survival 1.21",
"system": "MC",
"node": "PL-P",
"status": "running",
"is_suspended": false,
"is_subuser": false,
"server_owner": true,
"cpu": 200,
"ram_mb": 4096,
"disk_gb": 20,
"monthly_price": 15,
"ip": "s1.blackhost.pl:25565",
"created_at": null,
"expires_at": null
}
]
}
ℹ️ Paginacja: Domyślnie zwracane są wszystkie serwery. Po dodaniu
?pagination=true(lub?page=N) odpowiedź zawiera tablicęservers(25 pozycji na stronę) oraz obiektpaginationz polamitotal,per_page,current_page,total_pages.
2. Szczegóły i stan serwera (/v1/servers/game/:id/details)
Pobiera szczegółowe parametry wybranego serwera gry, w tym alokacje portów, limity i konfigurację techniczną.
- Metoda:
GET - Ścieżka:
/v1/servers/game/{id}/details - Wymagany scope:
game:read - Parametr
{id}: Krótki identyfikator serwera (unique_id, np.d0969f0b).
Jednostki w obiekcie limits:
| Pole | Jednostka | Opis |
|---|---|---|
limits.memory | MB (Megabajty) | Limit pamięci RAM (np. 4096 MB) |
limits.swap | MB (Megabajty) | Limit pamięci SWAP (0 = wyłączony) |
limits.disk | MB (Megabajty) | Przestrzeń dyskowa w megabajtach (np. 20480 MB = 20 GB) |
limits.cpu | % (Procent) | Limit CPU (200 = 200% alokacji) |
limits.io | Waga (10-1000) | Priorytet operacji wejścia/wyjścia I/O dysku |
Przykład zapytania cURL
curl -X GET "https://api.blackhost.pl/v1/servers/game/d0969f0b/details" \
-H "Authorization: Bearer bh_pat_TWOJ_TOKEN" \
-H "Accept: application/json"
Przykład odpowiedzi (200 OK)
{
"success": true,
"server": {
"id": 1191,
"unique_id": "d0969f0b",
"name": "Minecraft Survival 1.21",
"node": "PL-P",
"status": "running",
"limits": {
"memory": 4096,
"swap": 0,
"disk": 20480,
"io": 500,
"cpu": 200
},
"allocations": [
{
"ip": "89.144.32.28",
"ip_alias": "s1.blackhost.pl",
"port": 25565,
"is_default": true
}
]
}
}
3. Statystyki zużycia na żywo (/v1/servers/game/:id/stats)
Pobiera aktualne zużycie zasobów w czasie rzeczywistym (CPU, RAM, dysk, transfer sieciowy, uptime) oraz stan procesu.
- Metoda:
GET - Ścieżka:
/v1/servers/game/{id}/stats - Wymagany scope:
game:read
Jednostki w obiekcie stats:
| Pole | Jednostka | Opis |
|---|---|---|
stats.cpu | % (Procent) | Aktualne zużycie CPU (np. 42.5 oznacza 42.5% rdzenia) |
stats.mem | Bajty (Bytes) | Aktualnie zajęta pamięć RAM (np. 2147483648 B = 2 GB) |
stats.disk | Bajty (Bytes) | Aktualnie zajęta przestrzeń dyskowa (np. 8589934592 B = 8 GB) |
stats.uptime | Sekundy (s) | Czas nieprzerwanego działania serwera od startu |
stats.netin | Bajty (Bytes) | Łączna liczba odebranych bajtów przez interfejs sieciowy |
stats.netout | Bajty (Bytes) | Łączna liczba wysłanych bajtów |
stats.players.online | Liczba | Aktualna liczba graczy na serwerze |
stats.players.max | Liczba | Maksymalna liczba slotów graczy |
Przykład zapytania cURL
curl -X GET "https://api.blackhost.pl/v1/servers/game/d0969f0b/stats" \
-H "Authorization: Bearer bh_pat_TWOJ_TOKEN" \
-H "Accept: application/json"
Przykład odpowiedzi (200 OK)
{
"success": true,
"status": "running",
"stats": {
"status": "running",
"cpu": 42.5,
"mem": 2147483648,
"disk": 8589934592,
"uptime": 364000,
"netin": 10240000,
"netout": 40960000,
"players": {
"online": 14,
"max": 50
}
}
}
4. Zarządzanie zasilaniem (/v1/servers/game/:id/power)
Wysyła sygnał zasilania do serwera gry.
- Metoda:
POST - Ścieżka:
/v1/servers/game/{id}/power - Wymagany scope:
game:power - Nagłówek:
Content-Type: application/json
Dostępne sygnały (signal):
start- uruchomienie serwerastop- bezpieczne zatrzymanie (graceful shutdown)restart- ponowne uruchomieniekill- natychmiastowe ubicie procesu (force kill)
Przykład zapytania cURL
curl -X POST "https://api.blackhost.pl/v1/servers/game/d0969f0b/power" \
-H "Authorization: Bearer bh_pat_TWOJ_TOKEN" \
-H "Content-Type: application/json" \
-d '{"signal": "restart"}'
Przykład odpowiedzi (200 OK)
{
"success": true,
"message": "Signal restart sent successfully."
}
5. Wysyłanie poleceń do konsoli (/v1/servers/game/:id/command)
Wykonuje polecenie tekstowe bezpośrednio w konsoli działającego serwera gry.
- Metoda:
POST - Ścieżka:
/v1/servers/game/{id}/command - Wymagany scope:
game:command
Przykład zapytania cURL
curl -X POST "https://api.blackhost.pl/v1/servers/game/d0969f0b/command" \
-H "Authorization: Bearer bh_pat_TWOJ_TOKEN" \
-H "Content-Type: application/json" \
-d '{"command": "say Serwer zostanie zrestartowany za 5 minut!"}'
Przykład odpowiedzi (200 OK)
{
"success": true
}
6. Połączenie z konsolą na żywo (/v1/servers/game/:id/websocket)
Zwraca jednorazowy token uwierzytelniający JWT oraz adres URL WebSocket umożliwiający dwukierunkowy odbiór logów i wysyłanie poleceń konsoli w czasie rzeczywistym.
- Metoda:
GET - Ścieżka:
/v1/servers/game/{id}/websocket - Wymagany scope:
game:read
Przykład zapytania cURL
curl -X GET "https://api.blackhost.pl/v1/servers/game/d0969f0b/websocket" \
-H "Authorization: Bearer bh_pat_TWOJ_TOKEN" \
-H "Accept: application/json"
Przykład odpowiedzi (200 OK)
{
"success": true,
"token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
"socket": "wss://node1.blackhost.pl:8080/api/client/servers/d0969f0b/ws",
"uuid": "d0969f0b-1a2b-4c3d-9e8f-7a6b5c4d3e2f"
}
7. Menedżer plików (File Manager API)
7.1 Lista plików w katalogu
- Metoda:
GET - Ścieżka:
/v1/servers/game/{id}/files/list?directory={dir} - Wymagany scope:
game:files:read - Jednostka
size: Bajty (Bytes)
curl -X GET "https://api.blackhost.pl/v1/servers/game/d0969f0b/files/list?directory=/config" \
-H "Authorization: Bearer bh_pat_TWOJ_TOKEN" \
-H "Accept: application/json"
{
"success": true,
"files": [
{
"name": "paper-global.yml",
"mode": "-rw-r--r--",
"size": 4096,
"isFile": true,
"isSymlink": false,
"mimetype": "text/yaml",
"createdAt": "2026-08-10T12:00:00.000Z",
"modifiedAt": "2026-08-20T14:30:00.000Z"
}
]
}
7.2 Odczyt zawartości pliku
- Metoda:
GET - Ścieżka:
/v1/servers/game/{id}/files/contents?file={filepath} - Wymagany scope:
game:files:read
curl -X GET "https://api.blackhost.pl/v1/servers/game/d0969f0b/files/contents?file=/server.properties" \
-H "Authorization: Bearer bh_pat_TWOJ_TOKEN"
7.3 Zapis zawartości do pliku
- Metoda:
POST - Ścieżka:
/v1/servers/game/{id}/files/contents - Wymagany scope:
game:files:write - Nagłówek:
Content-Type: application/json - Ciało zapytania: obie JSON z polami
file(ścieżka pliku) orazcontent(nowa zawartość)
curl -X POST "https://api.blackhost.pl/v1/servers/game/d0969f0b/files/contents" \
-H "Authorization: Bearer bh_pat_TWOJ_TOKEN" \
-H "Content-Type: application/json" \
-d '{"file": "/server.properties", "content": "server-port=25565\nmotd=Nowy opis serwera!\ndifficulty=hard"}'
7.4 Pobieranie pliku (Download URL)
- Metoda:
GET - Ścieżka:
/v1/servers/game/{id}/files/download?file={filepath} - Wymagany scope:
game:files:read
curl -X GET "https://api.blackhost.pl/v1/servers/game/d0969f0b/files/download?file=/logs/latest.log" \
-H "Authorization: Bearer bh_pat_TWOJ_TOKEN"
{
"success": true,
"url": "https://node1.blackhost.pl:8080/download/backup/file?token=..."
}
7.5 Wyszukiwanie plików po nazwie
- Metoda:
GET - Ścieżka:
/v1/servers/game/{id}/files/search?query={search_term} - Wymagany scope:
game:files:read
curl -X GET "https://api.blackhost.pl/v1/servers/game/d0969f0b/files/search?query=paper" \
-H "Authorization: Bearer bh_pat_TWOJ_TOKEN"
{
"success": true,
"results": [
{
"name": "paper.jar",
"path": "/paper.jar",
"isFile": true,
"size": 48234496
}
]
}
7.6 Tworzenie folderu
- Metoda:
POST - Ścieżka:
/v1/servers/game/{id}/files/create-folder - Wymagany scope:
game:files:write
curl -X POST "https://api.blackhost.pl/v1/servers/game/d0969f0b/files/create-folder" \
-H "Authorization: Bearer bh_pat_TWOJ_TOKEN" \
-H "Content-Type: application/json" \
-d '{"root": "/", "name": "plugins"}'
7.7 Usuwanie plików i folderów
- Metoda:
POST - Ścieżka:
/v1/servers/game/{id}/files/delete - Wymagany scope:
game:files:write
curl -X POST "https://api.blackhost.pl/v1/servers/game/d0969f0b/files/delete" \
-H "Authorization: Bearer bh_pat_TWOJ_TOKEN" \
-H "Content-Type: application/json" \
-d '{"root": "/", "files": ["logs/old.log", "cache"]}'
7.8 Zmiana nazwy lub przenoszenie
- Metoda:
POST - Ścieżka:
/v1/servers/game/{id}/files/rename - Wymagany scope:
game:files:write
curl -X POST "https://api.blackhost.pl/v1/servers/game/d0969f0b/files/rename" \
-H "Authorization: Bearer bh_pat_TWOJ_TOKEN" \
-H "Content-Type: application/json" \
-d '{"root": "/", "files": [{"from": "config.yml", "to": "config.yml.bak"}]}'
7.9 Pakowanie (ZIP) i Rozpakowywanie
-
Kompresja:
POST /v1/servers/game/{id}/files/compresscurl -X POST "https://api.blackhost.pl/v1/servers/game/d0969f0b/files/compress" \ -H "Authorization: Bearer bh_pat_TWOJ_TOKEN" \ -H "Content-Type: application/json" \ -d '{"root": "/", "files": ["world", "world_nether"]}' -
Rozpakowywanie:
POST /v1/servers/game/{id}/files/decompresscurl -X POST "https://api.blackhost.pl/v1/servers/game/d0969f0b/files/decompress" \ -H "Authorization: Bearer bh_pat_TWOJ_TOKEN" \ -H "Content-Type: application/json" \ -d '{"root": "/", "file": "backup.zip"}'
7.10 Pobranie adresu do wgrywania plików (Upload URL)
Zwraca podpisany, jednorazowy adres URL demona Wings umożliwiający bezpośrednie przesłanie pliku (np. paczki ZIP, konfiguracji, jar) na serwer metodą multipart/form-data.
- Metoda:
GET - Ścieżka:
/v1/servers/game/{id}/files/upload - Wymagany scope:
game:files:write
curl -X GET "https://api.blackhost.pl/v1/servers/game/d0969f0b/files/upload" \
-H "Authorization: Bearer bh_pat_TWOJ_TOKEN"
{
"success": true,
"url": "https://node1.blackhost.pl:8080/upload/file?token=eyJhbGciOi..."
}
8. Zarządzanie Graczami (Players API)
8.1 Lista graczy
- Metoda:
GET - Ścieżka:
/v1/servers/game/{id}/players - Wymagany scope:
game:read
curl -X GET "https://api.blackhost.pl/v1/servers/game/d0969f0b/players" \
-H "Authorization: Bearer bh_pat_TWOJ_TOKEN"
{
"success": true,
"players": [
{
"name": "Steve",
"uuid": "853c80ef-3c37-49fd-aa49-938b674adae6",
"isOp": true,
"isOnline": true
}
],
"banned": []
}
8.2 Akcje na graczach (Kick, Ban, Op, Whitelist)
- Metoda:
POST - Ścieżka:
/v1/servers/game/{id}/players/action - Wymagany scope:
game:command
curl -X POST "https://api.blackhost.pl/v1/servers/game/d0969f0b/players/action" \
-H "Authorization: Bearer bh_pat_TWOJ_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"action": "kick",
"player": "Steve",
"reason": "Złamanie regulaminu"
}'
{
"success": true
}
Dostępne wartości action:
kick- wyrzucenie gracza z serwera (reasonopcjonalny)ban- zablokowanie gracza na serwerzepardon- odbanowanie graczaop- nadanie uprawnień operatora serweradeop- odebranie uprawnień operatoragamemode- zmiana trybu gry (gamemode:survival,creative,adventure,spectator)whitelist_add- dodanie gracza do białej listywhitelist_remove- usunięcie gracza z białej listy
8.3 Podgląd ekwipunku gracza Minecraft (Inventory API)
Zwraca aktualny stan ekwipunku gracza Minecraft (Hotbar, ekwipunek główny, założona zbroja, druga ręka, skrzynia kresu / Ender Chest) oraz parametry życiowe i punkty doświadczenia.
- Metoda:
GET - Ścieżka:
/v1/servers/game/{id}/players/inventory?uuid={uuid}(lub?name={nick}) - Wymagany scope:
game:read
curl -X GET "https://api.blackhost.pl/v1/servers/game/d0969f0b/players/inventory?uuid=853c80ef-3c37-49fd-aa49-938b674adae6" \
-H "Authorization: Bearer bh_pat_TWOJ_TOKEN"
{
"success": true,
"gamemode": "survival",
"inventory": {
"player": {
"name": "Steve",
"uuid": "853c80ef-3c37-49fd-aa49-938b674adae6",
"health": 20,
"maxHealth": 20,
"food": 18,
"xpLevel": 34
},
"armor": {
"helmet": { "id": "minecraft:netherite_helmet", "count": 1 },
"chestplate": { "id": "minecraft:netherite_chestplate", "count": 1 },
"leggings": { "id": "minecraft:netherite_leggings", "count": 1 },
"boots": { "id": "minecraft:netherite_boots", "count": 1 }
},
"offhand": { "id": "minecraft:totem_of_undying", "count": 1 },
"hotbar": [
{ "id": "minecraft:netherite_sword", "count": 1, "name": "Excalibur" },
{ "id": "minecraft:golden_apple", "count": 16 }
],
"inventory": [],
"enderchest": []
}
}
9. Integracja z Webhookiem Discord (/v1/servers/game/:id/webhook)
Umożliwia konfigurację i odczyt powiadomień oraz kafelka statusu serwera gry (embeda) na Twoim kanale Discord.
- Odczyt konfiguracji:
GET /v1/servers/game/{id}/webhook(Scope:game:read) - Ustawienie webhooka:
PUT /v1/servers/game/{id}/webhook(Scope:game:read) - Usunięcie webhooka:
DELETE /v1/servers/game/{id}/webhook(Scope:game:read)
Przykład zapytania (PUT):
curl -X PUT "https://api.blackhost.pl/v1/servers/game/d0969f0b/webhook" \
-H "Authorization: Bearer bh_pat_TWOJ_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"webhookUrl": "https://discord.com/api/webhooks/123456789/abcdefgh",
"lang": "pl"
}'
{
"success": true,
"messageId": "123456789012345678"
}
Dostępne kody języka (lang): pl, en, uk, de, fr.
10. Zasoby i dane serwera (/v1/servers/game/:id/data)
Uniwersalny endpoint do bezpośredniej obsługi podzasobów instancji serwera gier.
- Ścieżka:
/v1/servers/game/{id}/data?resource={typ} - Wymagany scope:
game:read(dla operacjiGET) /game:command(dlaPOST,PUT,DELETE)
Dostępne zasoby (resource):
Wartość resource | Metody | Zastosowanie |
|---|---|---|
databases | GET, POST, DELETE | Pobieranie listy, tworzenie i usuwanie baz danych MySQL |
backups | GET, POST, DELETE | Lista kopii zapasowych, tworzenie nowego backupu i pobieranie |
schedules | GET, POST, DELETE | Zarządzanie zaplanowanymi zadaniami i automatycznymi akcjami |
network | GET, POST, DELETE | Przegląd alokacji portów oraz ustawianie alokacji głównej |
startup | GET, PUT | Odczyt i modyfikacja zmiennych środowiskowych i parametrów startowych |
settings | GET | Szczegółowe parametry techniczne i limity funkcji serwera |
activity | GET | Dziennik aktywności i audyt zdarzeń serwera |
11. Autoinstalatory oprogramowania i silników (Game Installer API)
Umożliwia przeglądanie, wyszukiwanie i automatyczną 1-click instalację pluginów (Spigot / Paper), modyfikacji (Modrinth dla Fabric / NeoForge / Forge) oraz kompletnych paczek serwerowych (CurseForge Server Packs).
11.1 Przeglądanie katalogu instalatora
- Metoda:
GET - Ścieżka:
/v1/servers/game/{id}/installer?type={typ}&q={szukaj}&sort={sort} - Wymagany scope:
game:read - Parametry query:
type-pluginy(domyślnie),mody,paczkiq- fraza wyszukiwania (opcjonalnie)sort-a-z,downloads,rating,updated
curl -X GET "https://api.blackhost.pl/v1/servers/game/d0969f0b/installer?type=pluginy&q=essentials" \
-H "Authorization: Bearer bh_pat_TWOJ_TOKEN"
11.2 Dostępne wersje dodatku / modpacka
- Metoda:
GET - Ścieżka:
/v1/servers/game/{id}/installer/versions?itemType={typ}&itemId={id} - Wymagany scope:
game:read
curl -X GET "https://api.blackhost.pl/v1/servers/game/d0969f0b/installer/versions?itemType=pluginy&itemId=9089" \
-H "Authorization: Bearer bh_pat_TWOJ_TOKEN"
11.3 Rozpoczęcie instalacji
Pobiera i wdraża pliki wybranego komponentu na serwerze gry.
- Metoda:
POST - Ścieżka:
/v1/servers/game/{id}/installer/install - Wymagany scope:
game:commandlubgame:files:write - Nagłówek:
Content-Type: application/json
curl -X POST "https://api.blackhost.pl/v1/servers/game/d0969f0b/installer/install" \
-H "Authorization: Bearer bh_pat_TWOJ_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"type": "plugin",
"plugin_id": "9089",
"plugin_name": "EssentialsX"
}'
{
"success": true,
"message": "Plugin EssentialsX został pomyślnie zainstalowany."
}
12. Cykl życia, finanse i serwery darmowe (Game Lifecycle & Billing)
Endpointy do zarządzania ważnością, odnawianiem, modyfikacją planów sprzętowych oraz serwerami darmowymi.
12.1 Odnowienie serwera gry
Przedłuża ważność serwera gry o wskazany okres, pobierając środki z portfela wPLN.
- Metoda:
POST - Ścieżka:
/v1/servers/game/{id}/renew - Wymagany scope:
account:billinglubgame:power - Ciało zapytania:
{"days": 30}
| 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%.
curl -X POST "https://api.blackhost.pl/v1/servers/game/d0969f0b/renew" \
-H "Authorization: Bearer bh_pat_TWOJ_TOKEN" \
-H "Content-Type: application/json" \
-d '{"days": 30}'
12.2 Konfiguracja automatycznego odnawiania
Włącza lub wyłącza samoczynne opłacanie serwera z portfela wPLN w dniu wygaśnięcia (dostępne wyłącznie dla właściciela serwera).
- Metoda:
POST - Ścieżka:
/v1/servers/game/{id}/auto-renew - Wymagany scope:
account:billinglubgame:power - Ciało zapytania:
{"enabled": true}
12.3 Zmiana / Podniesienie pakietu (Upgrade)
Zmienia pakiet serwera gry na wyższy (przeliczając proporcjonalnie różnicę w cenie za pozostały okres ważności).
- Podgląd dostępnych ulepszeń:
GET /v1/servers/game/{id}/upgrade(Scope:account:billinglubgame:power) - zwraca obiekt z polamicurrentTier,availableUpgrades(lista wariantów z ceną i wyliczoną dopłatą) orazuserWpln - Wykonanie ulepszenia:
POST /v1/servers/game/{id}/upgrade - Wymagany scope:
account:billinglubgame:power - Ciało zapytania:
{"targetPacketId": "minecraft-java", "targetTierName": "Premium"}
| 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) |
curl -X POST "https://api.blackhost.pl/v1/servers/game/d0969f0b/upgrade" \
-H "Authorization: Bearer bh_pat_TWOJ_TOKEN" \
-H "Content-Type: application/json" \
-d '{"targetPacketId": "minecraft-java", "targetTierName": "Premium"}'
12.4 Zakup nowego serwera gry z portfela
Tworzy i uruchamia nową instancję serwera gry opłaconą ze środków wPLN.
- Metoda:
POST - Ścieżka:
/v1/servers/game/purchase - Wymagany scope:
account:billing
Parametry w ciele zapytania:
| Pole | Typ | Wymagane | Opis |
|---|---|---|---|
offerId | String | Tak | Identyfikator oferty (uniqueId z katalogu /v1/shop/packets, np. minecraft-java) |
packageName | String | Tak | Nazwa wariantu pakietu (servers[].name z katalogu, np. Start) |
node | String | Tak | Lokalizacja: PL_BASE lub PL_PREMIUM (musi występować w locations[] wybranego wariantu) |
system | String | Nie | System / silnik z installations[] oferty (np. Paper). Wymagany, gdy oferta definiuje listę instalacji |
name | String | Nie | Nazwa serwera (maks. 80 znaków; domyślnie Serwer Minecraft) |
days | Liczba | Nie | Okres: 30, 90, 180 lub 360 dni (domyślnie 30; rabaty jak przy odnowieniu) |
code | String | Nie | Opcjonalny kod promocyjny |
curl -X POST "https://api.blackhost.pl/v1/servers/game/purchase" \
-H "Authorization: Bearer bh_pat_TWOJ_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"offerId": "minecraft-java",
"packageName": "Start",
"node": "PL_BASE",
"system": "Paper",
"name": "Nowy Serwer Survival",
"days": 30
}'
Przykład odpowiedzi (201 Created)
{
"success": true,
"message": "Serwer Nowy Serwer Survival został zakupiony i pomyślnie utworzony!",
"uniqueId": "a1b2c3d4",
"remainingBalance": 34.00
}
ℹ️ Uwaga: Endpoint nie przyjmuje identyfikatorów
eggId,nestIdani fizycznego węzła - egg, nest i konkretna maszyna w wybranej lokalizacji (node) dobierane są automatycznie po stronie panelu. Pełny przepływ zakupu:GET /v1/shop/packets→ wybóruniqueId,servers[].name,locations[],installations[]→POST /v1/servers/game/purchase.
12.5 Serwery darmowe (Free Tier)
Podgląd stanu bezpłatnego serwera testowego:
- Status serwera darmowego:
GET /v1/servers/game/free/status(Scope:game:read)
ℹ️ Uwaga: Ze względów bezpieczeństwa oraz ochrony przed masowym botowaniem i multi-kontami, odbiór nowego darmowego serwera (
POST /free/claim) oraz jego odnawianie (POST /free/renew) wymagają interaktywnej weryfikacji antybotowej (Turnstile) i są dostępne wyłącznie w panelu klienta (Dashboard). Wywołania przez tokeny API (PAT) są zablokowane.