BlackHost REST API

api

Oficjalny interfejs BlackHost Public REST API umożliwia bezpieczną automatyzację, integrację z zewnętrznymi botami (np. Discord), skryptami CI/CD oraz własnymi panelami zarządzania.

🌐 Podstawowe informacje

Base URL: https://api.blackhost.pl/v1
Format danych: JSON (application/json)
Kodowanie: UTF-8
Protokół: HTTPS (wymagany TLS 1.3 / 1.2)
CORS: Dostępny dla wszystkich domen (Access-Control-Allow-Origin: *) przy zapytaniach z nagłówkiem Authorization: Bearer

🔑 Uwierzytelnianie (Klucze API)

Wszystkie zapytania do API wymagają przekazania aktywnego tokenu dostępowego (Personal Access Token) w nagłówku HTTP:

Authorization: Bearer bh_pat_twoj_unikalny_token

Jak wygenerować klucz API?

Zaloguj się do panelu klienta na dash.blackhost.pl.
Przejdź do zakładki Konto (/account).
W sekcji Klucze API kliknij przycisk Nowy klucz.
Wpisz nazwę identyfikacyjną (np. Bot Discord, Skrypt backupu).
Zaznacz wymagane uprawnienia (Scopes).
Opcjonalnie wybierz datę i godzinę wygaśnięcia tokenu.
Skopiuj wygenerowany token bh_pat_... i zapisz go w bezpiecznym miejscu (sekret nie będzie widoczny ponownie).

⚠️ Bezpieczeństwo: Nigdy nie udostępniaj tokenu publicznie (np. w publicznych repozytoriach GitHub). Klucz API daje dostęp do Twoich serwerów w ramach wybranych uprawnień.

🛡️ Dostępne uprawnienia (Scopes)

Podczas generowania klucza możesz precyzyjnie określić, do jakich operacji ma on dostęp:

Uprawnienie (Scope)	Opis
`account:read`	Odczyt listy aktywnych serwerów i usług przypisanych do konta
`game:read`	Odczyt statusu, parametrów, zużycia zasobów i graczy serwerów gier
`game:power`	Start, stop, restart oraz natychmiastowe zatrzymanie (kill) serwera gry
`game:command`	Wysyłanie poleceń do konsoli serwera gry oraz akcje na graczach (kick/ban/op)
`game:files:read`	Przeglądanie katalogów, wyszukiwanie oraz odczyt i pobieranie plików
`game:files:write`	Edycja plików, tworzenie katalogów, usuwanie, zmiana nazw, pakowanie ZIP
`vps:read`	Odczyt parametrów, statystyk zużycia, logów, kopii i zapory maszyn VPS
`vps:power`	Zarządzanie zasilaniem VPS (Start, Stop, Reboot, Shutdown)
`vps:console`	Generowanie sesji i dostęp do konsoli noVNC maszyny VPS
`vps:firewall`	Konfiguracja reguł zapory ogniowej, białej listy IP oraz opcji bezpieczeństwa

⏱️ Limity zapytań (Rate Limiting)

Dla zachowania stabilności infrastruktury obowiązuje standardowy limit 60 zapytań na minutę na każdy klucz API.

Po przekroczeniu limitu serwer zwróci odpowiedź HTTP 429 Too Many Requests wraz z nagłówkiem informującym o czasie odblokowania:

HTTP/1.1 429 Too Many Requests
Retry-After: 60
Content-Type: application/json

{
  "success": false,
  "error": "Zbyt wiele zapytań. Spróbuj ponownie za chwilę."
}

🚀 Przykłady wywołań

cURL

# Pobranie listy swoich serwerów
curl -X GET "https://api.blackhost.pl/v1/servers" \
  -H "Authorization: Bearer bh_pat_TWOJ_TOKEN" \
  -H "Accept: application/json"

Node.js / TypeScript (Fetch)

const API_TOKEN = "bh_pat_TWOJ_TOKEN";

async function getServers() {
  const response = await fetch("https://api.blackhost.pl/v1/servers", {
    method: "GET",
    headers: {
      "Authorization": `Bearer ${API_TOKEN}`,
      "Accept": "application/json"
    }
  });

  const data = await response.json();
  console.log("Moje serwery:", data);
}

getServers();

Python (Requests)

import requests

API_TOKEN = "bh_pat_TWOJ_TOKEN"
headers = {
    "Authorization": f"Bearer {API_TOKEN}",
    "Accept": "application/json"
}

response = requests.get("https://api.blackhost.pl/v1/servers", headers=headers)
print("Odpowiedź API:", response.json())