Sur cette page1. Lista serwerów (`/v1/servers`)

Serwery Gier

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 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:

PoleJednostkaOpis
cpu% (Procent)Limit procesora (100 = 1 rdzeń vCPU, 200 = 2 rdzenie)
ram_mbMB (Megabajty)Przypisany limit pamięci operacyjnej RAM
disk_gbGB (Gigabajty)Przypisana przestrzeń dyskowa
unique_idStringPubliczny unikalny identyfikator serwera (używany we wszystkich endpointach)
monthly_pricewPLNMiesię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 obiekt pagination z polami total, 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:

PoleJednostkaOpis
limits.memoryMB (Megabajty)Limit pamięci RAM (np. 4096 MB)
limits.swapMB (Megabajty)Limit pamięci SWAP (0 = wyłączony)
limits.diskMB (Megabajty)Przestrzeń dyskowa w megabajtach (np. 20480 MB = 20 GB)
limits.cpu% (Procent)Limit CPU (200 = 200% alokacji)
limits.ioWaga (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:

PoleJednostkaOpis
stats.cpu% (Procent)Aktualne zużycie CPU (np. 42.5 oznacza 42.5% rdzenia)
stats.memBajty (Bytes)Aktualnie zajęta pamięć RAM (np. 2147483648 B = 2 GB)
stats.diskBajty (Bytes)Aktualnie zajęta przestrzeń dyskowa (np. 8589934592 B = 8 GB)
stats.uptimeSekundy (s)Czas nieprzerwanego działania serwera od startu
stats.netinBajty (Bytes)Łączna liczba odebranych bajtów przez interfejs sieciowy
stats.netoutBajty (Bytes)Łączna liczba wysłanych bajtów
stats.players.onlineLiczbaAktualna liczba graczy na serwerze
stats.players.maxLiczbaMaksymalna 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 serwera
  • stop - bezpieczne zatrzymanie (graceful shutdown)
  • restart - ponowne uruchomienie
  • kill - 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) oraz content (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/compress

    curl -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/decompress

    curl -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 (reason opcjonalny)
  • ban - zablokowanie gracza na serwerze
  • pardon - odbanowanie gracza
  • op - nadanie uprawnień operatora serwera
  • deop - odebranie uprawnień operatora
  • gamemode - zmiana trybu gry (gamemode: survival, creative, adventure, spectator)
  • whitelist_add - dodanie gracza do białej listy
  • whitelist_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 operacji GET) / game:command (dla POST, PUT, DELETE)

Dostępne zasoby (resource):

Wartość resourceMetodyZastosowanie
databasesGET, POST, DELETEPobieranie listy, tworzenie i usuwanie baz danych MySQL
backupsGET, POST, DELETELista kopii zapasowych, tworzenie nowego backupu i pobieranie
schedulesGET, POST, DELETEZarządzanie zaplanowanymi zadaniami i automatycznymi akcjami
networkGET, POST, DELETEPrzegląd alokacji portów oraz ustawianie alokacji głównej
startupGET, PUTOdczyt i modyfikacja zmiennych środowiskowych i parametrów startowych
settingsGETSzczegółowe parametry techniczne i limity funkcji serwera
activityGETDziennik 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, paczki
    • q - 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:command lub game: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:billing lub game:power
  • Ciało zapytania: {"days": 30}
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%.

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:billing lub game: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:billing lub game:power) - zwraca obiekt z polami currentTier, availableUpgrades (lista wariantów z ceną i wyliczoną dopłatą) oraz userWpln
  • Wykonanie ulepszenia: POST /v1/servers/game/{id}/upgrade
  • Wymagany scope: account:billing lub game:power
  • Ciało zapytania: {"targetPacketId": "minecraft-java", "targetTierName": "Premium"}
PoleTypWymaganeOpis
targetPacketIdStringTakIdentyfikator oferty (uniqueId z katalogu /v1/shop/packets)
targetTierNameStringTakNazwa 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:

PoleTypWymaganeOpis
offerIdStringTakIdentyfikator oferty (uniqueId z katalogu /v1/shop/packets, np. minecraft-java)
packageNameStringTakNazwa wariantu pakietu (servers[].name z katalogu, np. Start)
nodeStringTakLokalizacja: PL_BASE lub PL_PREMIUM (musi występować w locations[] wybranego wariantu)
systemStringNieSystem / silnik z installations[] oferty (np. Paper). Wymagany, gdy oferta definiuje listę instalacji
nameStringNieNazwa serwera (maks. 80 znaków; domyślnie Serwer Minecraft)
daysLiczbaNieOkres: 30, 90, 180 lub 360 dni (domyślnie 30; rabaty jak przy odnowieniu)
codeStringNieOpcjonalny 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, nestId ani 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ór uniqueId, 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.