# Maszyny VPS (VPS API)

Kompletny przewodnik po endpointach do automatyzacji i zarządzania wirtualnymi serwerami prywatnymi (KVM VPS) w chmurze BlackHost.

---

## 1. Szczegóły maszyny VPS (`/v1/servers/vps/:id/details`)

Zwraca pełną specyfikację techniczną, przydzielony główny adres IP, bramę domyślną, status oraz system operacyjny serwera.

* **Metoda:** `GET`
* **Ścieżka:** `/v1/servers/vps/{id}/details`
* **Wymagany scope:** `vps:read`
* **Parametr `{id}`:** Identyfikator `unique_id` serwera (np. `vps-8f92a1`).

### Jednostki zwracanych pól:
| Pole | Jednostka | Opis |
| :--- | :--- | :--- |
| `cpu` | **Liczba rdzeni** | Przydzielona liczba wirtualnych rdzeni (vCPU) |
| `ram_mb` | **MB (Megabajty)** | Przydzielona pamięć RAM (np. `8192` MB = 8 GB) |
| `disk_gb` | **GB (Gigabajty)** | Przestrzeń na szybkich dyskach NVMe PCIe 4.0 |
| `prefix` | **Liczba (CIDR)** | Długość maski podsieci (np. `24` dla `/24` = 255.255.255.0) |
| `monthly_price`| **wPLN** | Miesięczna cena odnowienia usługi |

### Przykład zapytania cURL

```bash
curl -X GET "https://api.blackhost.pl/v1/servers/vps/vps-8f92a1/details" \
  -H "Authorization: Bearer bh_pat_TWOJ_TOKEN" \
  -H "Accept: application/json"
```

### Przykład odpowiedzi (200 OK)

```json
{
  "success": true,
  "server": {
    "id": 45,
    "unique_id": "vps-8f92a1",
    "name": "Moja Maszyna Produkcyjna",
    "node": "waw-1",
    "status": "running",
    "cpu": 4,
    "ram_mb": 8192,
    "disk_gb": 80,
    "ip": "185.25.10.15",
    "prefix": 24,
    "gateway": "185.25.10.1",
    "system": "debian-12",
    "monthly_price": 49.00,
    "expires_at": "2026-09-01T12:00:00.000Z"
  }
}
```

---

## 2. Zarządzanie zasilaniem (`/v1/servers/vps/:id/power`)

Wysyła polecenie zasilania (ACPI / Force) do hypervisora maszyny wirtualnej.

* **Metoda:** `POST`
* **Ścieżka:** `/v1/servers/vps/{id}/power`
* **Wymagany scope:** `vps:power`
* **Nagłówek:** `Content-Type: application/json`

### Dostępne akcje (`action` / `signal`):
* `start` - uruchomienie maszyny
* `reboot` - bezpieczny restart ACPI systemu operacyjnego
* `shutdown` - bezpieczne wyłączenie ACPI systemu operacyjnego
* `stop` - natychmiastowe odcięcie zasilania maszyny (force stop)

### Przykład zapytania cURL

```bash
curl -X POST "https://api.blackhost.pl/v1/servers/vps/vps-8f92a1/power" \
  -H "Authorization: Bearer bh_pat_TWOJ_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"action": "reboot"}'
```

### Przykład odpowiedzi (200 OK)

```json
{
  "success": true,
  "message": "Polecenie reboot zostało pomyślnie wysłane."
}
```

---

## 3. Statystyki zużycia na żywo i Hardware

### 3.1 Statystyki na żywo (`/v1/servers/vps/:id/stats`)

Pobiera aktualny stan i zużycie zasobów maszyny KVM prosto z hypervisora oraz agenta gościa (QEMU Guest Agent).

* **Metoda:** `GET`
* **Ścieżka:** `/v1/servers/vps/{id}/stats`
* **Wymagany scope:** `vps:read`

### Jednostki w obiekcie `stats`:
| Pole | Jednostka | Opis |
| :--- | :--- | :--- |
| `stats.cpu` | **Ułamek (0.0 - 1.0)** | Użycie CPU z perspektywy hosta (`0.15` = 15% łącznej mocy vCPU) |
| `stats.mem` | **Bajty (Bytes)** | Pamięć RAM zaalokowana przez proces maszyny |
| `stats.disk` | **Bajty (Bytes)** | Przestrzeń wirtualnego dysku |
| `stats.uptime` | **Sekundy (s)** | Czas działania maszyny wirtualnej od startu |
| `stats.netin` | **Bajty (Bytes)** | Łączna liczba odebranych bajtów na interfejsie sieciowym |
| `stats.netout` | **Bajty (Bytes)** | Łączna liczba wysłanych bajtów |
| `stats.agentDiskUsed` | **Bajty (Bytes)** | Rzeczywiste zajęcie dysku partycji `/` odczytane przez QEMU Guest Agent |

```bash
curl -X GET "https://api.blackhost.pl/v1/servers/vps/vps-8f92a1/stats" \
  -H "Authorization: Bearer bh_pat_TWOJ_TOKEN" \
  -H "Accept: application/json"
```

```json
{
  "success": true,
  "status": "running",
  "system": "Debian GNU/Linux 12 (bookworm)",
  "stats": {
    "status": "running",
    "cpu": 0.15,
    "mem": 3435973836,
    "disk": 21474836480,
    "uptime": 864000,
    "netin": 104857600,
    "netout": 524288000,
    "agentDiskUsed": 12884901888
  }
}
```

---

### 3.2 Specyfikacja sprzętowa procesora (`/v1/servers/vps/:id/hardware`)

* **Metoda:** `GET`
* **Ścieżka:** `/v1/servers/vps/{id}/hardware`
* **Wymagany scope:** `vps:read`

```bash
curl -X GET "https://api.blackhost.pl/v1/servers/vps/vps-8f92a1/hardware" \
  -H "Authorization: Bearer bh_pat_TWOJ_TOKEN"
```

```json
{
  "success": true,
  "hardware": {
    "cpuModel": "AMD EPYC 9654 96-Core Processor",
    "cores": 4,
    "ram": "8 GB",
    "disk": "80 GB NVMe PCIe 4.0",
    "networkSpeed": "1 Gbps"
  }
}
```

---

## 4. Dostęp do Konsoli noVNC (`/v1/servers/vps/:id/console`)

Generuje jednorazowy bilet (ticket) oraz parametry sesji noVNC umożliwiającej zdalny pulpit / dostęp awaryjny do terminala maszyny.

* **Metoda:** `POST`
* **Ścieżka:** `/v1/servers/vps/{id}/console`
* **Wymagany scope:** `vps:console`

### Przykład zapytania cURL

```bash
curl -X POST "https://api.blackhost.pl/v1/servers/vps/vps-8f92a1/console" \
  -H "Authorization: Bearer bh_pat_TWOJ_TOKEN"
```

### Przykład odpowiedzi (200 OK)

```json
{
  "success": true,
  "ticket": "PVE:vnc:...token...",
  "port": "5900",
  "upid": "UPID:waw-1:..."
}
```

---

## 5. Zapora ogniowa (Firewall API)

### 5.1 Lista reguł zapory
* **Metoda:** `GET`
* **Ścieżka:** `/v1/servers/vps/{id}/firewall/rules`
* **Wymagany scope:** `vps:read`

```bash
curl -X GET "https://api.blackhost.pl/v1/servers/vps/vps-8f92a1/firewall/rules" \
  -H "Authorization: Bearer bh_pat_TWOJ_TOKEN"
```

```json
{
  "success": true,
  "rules": [
    {
      "pos": 0,
      "type": "in",
      "action": "ACCEPT",
      "proto": "tcp",
      "dport": "22",
      "comment": "SSH Access",
      "enable": 1
    }
  ]
}
```

---

### 5.2 Dodawanie nowej reguły zapory
* **Metoda:** `POST`
* **Ścieżka:** `/v1/servers/vps/{id}/firewall/rules`
* **Wymagany scope:** `vps:firewall`
* **Nagłówek:** `Content-Type: application/json`

```bash
curl -X POST "https://api.blackhost.pl/v1/servers/vps/vps-8f92a1/firewall/rules" \
  -H "Authorization: Bearer bh_pat_TWOJ_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "in",
    "action": "ACCEPT",
    "proto": "tcp",
    "dport": "8080",
    "comment": "Moja Aplikacja Web",
    "enable": 1
  }'
```

```json
{
  "success": true,
  "message": "Reguła firewall została pomyślnie dodana."
}
```

---

### 5.3 Modyfikacja lub usunięcie reguły na danej pozycji
* **Edycja reguły:** `PUT /v1/servers/vps/{id}/firewall/rules/{pos}`
  ```bash
  curl -X PUT "https://api.blackhost.pl/v1/servers/vps/vps-8f92a1/firewall/rules/0" \
    -H "Authorization: Bearer bh_pat_TWOJ_TOKEN" \
    -H "Content-Type: application/json" \
    -d '{"action": "DROP", "proto": "tcp", "dport": "22", "enable": 1}'
  ```

* **Usunięcie reguły:** `DELETE /v1/servers/vps/{id}/firewall/rules/{pos}`
  ```bash
  curl -X DELETE "https://api.blackhost.pl/v1/servers/vps/vps-8f92a1/firewall/rules/0" \
    -H "Authorization: Bearer bh_pat_TWOJ_TOKEN"
  ```
* **Wymagany scope:** `vps:firewall`

---

### 5.4 Opcje globalne zapory sieciowej
* **Pobranie stanu:** `GET /v1/servers/vps/{id}/firewall/options` (Scope: `vps:read`)
* **Zmiana opcji:** `POST /v1/servers/vps/{id}/firewall/options` (Scope: `vps:firewall`)

```bash
curl -X POST "https://api.blackhost.pl/v1/servers/vps/vps-8f92a1/firewall/options" \
  -H "Authorization: Bearer bh_pat_TWOJ_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "enable": 1,
    "policy_in": "DROP",
    "policy_out": "ACCEPT"
  }'
```

---

### 5.5 Biała lista adresów IP (Whitelist)
Adresy z białej listy omijają filtry zapory.

* **Pobranie listy:** `GET /v1/servers/vps/{id}/firewall/whitelist` (Scope: `vps:read`)
* **Dodanie adresu IP:** `POST /v1/servers/vps/{id}/firewall/whitelist` (Scope: `vps:firewall`)

```bash
curl -X POST "https://api.blackhost.pl/v1/servers/vps/vps-8f92a1/firewall/whitelist" \
  -H "Authorization: Bearer bh_pat_TWOJ_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "ip": "203.0.113.50/32",
    "comment": "Adres IP Biura"
  }'
```

---

### 5.6 Raport odpartych ataków DDoS (XDP / eBPF)
Zwraca statystyki ruchu odfiltrowanego przez sprzętowe i programowe filtry anty-DDoS (XDP).

* **Metoda:** `GET`
* **Ścieżka:** `/v1/servers/vps/{id}/firewall/xdp/attacks`
* **Wymagany scope:** `vps:read`

### Jednostki w raporcie ataków:
| Pole | Jednostka | Opis |
| :--- | :--- | :--- |
| `peakPps` | **Pakiety na sekundę (PPS)** | Szczytowe natężenie pakietów odpartego ataku |
| `peakBps` | **Bity na sekundę (bps)** | Szczytowa przepustowość odpartego ataku (np. `10500000000` bps = 10.5 Gbps) |

```bash
curl -X GET "https://api.blackhost.pl/v1/servers/vps/vps-8f92a1/firewall/xdp/attacks" \
  -H "Authorization: Bearer bh_pat_TWOJ_TOKEN"
```

```json
{
  "success": true,
  "attacks": [
    {
      "id": "atk-1",
      "source": "UDP Flood",
      "dstIp": "185.25.10.15",
      "peakPps": 1250000,
      "peakBps": 10500000000,
      "status": "mitigated",
      "startedAt": "2026-08-24T18:15:00.000Z",
      "endedAt": "2026-08-24T18:22:00.000Z"
    }
  ]
}
```

---

## 6. Reverse DNS (rDNS / PTR)

Konfiguracja rekordu PTR dla głównego adresu IPv4 Twojej maszyny.

* **Odczyt rekordu:** `GET /v1/servers/vps/{id}/ptr` (Scope: `vps:read`)
* **Zmiana rekordu:** `POST /v1/servers/vps/{id}/ptr` (Scope: `vps:read`)

```bash
curl -X POST "https://api.blackhost.pl/v1/servers/vps/vps-8f92a1/ptr" \
  -H "Authorization: Bearer bh_pat_TWOJ_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"hostname": "vps.twojadomena.pl"}'
```

```json
{
  "success": true,
  "message": "Rekord PTR został zaktualizowany."
}
```

---

## 7. Kopie zapasowe (Backups)

Pobiera listę utworzonych kopii zapasowych (Proxmox Backup Server / Snapshots) maszyny VPS.

* **Metoda:** `GET`
* **Ścieżka:** `/v1/servers/vps/{id}/backups`
* **Wymagany scope:** `vps:read`
* **Jednostka `size`:** **Bajty (Bytes)** (np. `8589934592` B = 8 GB)

```bash
curl -X GET "https://api.blackhost.pl/v1/servers/vps/vps-8f92a1/backups" \
  -H "Authorization: Bearer bh_pat_TWOJ_TOKEN"
```

```json
{
  "success": true,
  "snapshots": [],
  "pbsBackups": [
    {
      "id": "backup/qemu/105/2026-08-20T02:00:00Z",
      "size": 8589934592,
      "created_at": "2026-08-20T02:00:00.000Z",
      "format": "pbs"
    }
  ]
}
```