Docs
Powered by

Serwery Gier (Game API)

In 

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)

{
  "success": true,
  "gameServers": [
    {
      "id": 1191,
      "unique_id": "d0969f0b",
      "name": "Minecraft Survival 1.21",
      "system": "MC",
      "node": "PL-P",
      "status": "running",
      "is_suspended": false,
      "cpu": 200,
      "ram_mb": 4096,
      "disk_gb": 20,
      "monthly_price": 0,
      "ip": "s1.blackhost.pl:25565",
      "created_at": null,
      "expires_at": null
    }
  ],
  "pveServers": []
}

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 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,
  "data": {
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "socket": "wss://node1.blackhost.pl:8080/api/client/servers/d0969f0b/ws"
  }
}

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?file={filepath}
  • Wymagany scope: game:files:write
  • Nagłówek: Content-Type: text/plain
curl -X POST "https://api.blackhost.pl/v1/servers/game/d0969f0b/files/contents?file=/server.properties" \
  -H "Authorization: Bearer bh_pat_TWOJ_TOKEN" \
  -H "Content-Type: text/plain" \
  --data-raw "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"}'

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