REST API & Integrations
API endpoint reference for managing services and payments.
Last updated November 21, 2026
Articles in this category
This article is not available in your language yet - showing the Polish version.
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łówkiemAuthorization: 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 (https://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 |
account:billing | Doładowania portfela, historia transakcji, płatności i zakupy |
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 |
vps:settings | Zmiana nazwy, konfiguracja rekordu PTR/rDNS, zarządzanie kluczami SSH i hasłem |
vps:backups | Tworzenie, przywracanie i zarządzanie kopiami zapasowymi VPS |
vps:install | 1-Click instalatory oprogramowania na VPS oraz instalacje systemowe |
vps:subusers | Zarządzanie subużytkownikami i delegowanie uprawnień do maszyn VPS |
⏱️ 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())
📚 Moduły dokumentacji API
Przejdź do szczegółowych przewodników i specyfikacji technicznych poszczególnych modułów:
- Serwery Gier (Game API) - zarządzanie stanem serwerów gier, konsola, menedżer plików, autoinstalatory silników/modów/pluginów, ekwipunki graczy, powiadomienia Discord oraz cykl życia usług.
- Maszyny VPS (VPS API) - kontrola maszyn KVM, zapora ogniowa (Firewall), rekordy rDNS/PTR, kopie zapasowe PBS, autoinstalatory aplikacji (1-Click Apps), klucze SSH, telemetria SSE/WebSocket oraz subużytkownicy.
- Portfel, Płatności i Sklep (Billing & Shop API) - saldo portfela wPLN, historia transakcji, automatyczne doładowania (Stripe, Litecoin LTC), przelewy wewnętrzne P2P, metody płatności oraz katalog pakietów.