# BlackHost REST 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:

```http
Authorization: Bearer bh_pat_twoj_unikalny_token
```

### Jak wygenerować klucz API?

1. Zaloguj się do panelu klienta na [dash.blackhost.pl](https://dash.blackhost.pl).
2. Przejdź do zakładki **Konto** (`/account`).
3. W sekcji **Klucze API** kliknij przycisk **Nowy klucz**.
4. Wpisz nazwę identyfikacyjną (np. `Bot Discord`, `Skrypt backupu`).
5. Zaznacz wymagane uprawnienia (*Scopes*).
6. Opcjonalnie wybierz datę i godzinę wygaśnięcia tokenu.
7. 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
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

```bash
# 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)

```typescript
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)

```python
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())
```