Referencja endpointów

KernelHost API

Wszystkie endpointy zwracają application/json. Błędy są zgodne z RFC 7807 (Problem+JSON). Każda odpowiedź zawiera nagłówek X-Request-Id do korelacji z serwerowym dziennikiem audytu.

MethodPathZakres uprawnieńPrzeznaczenie
GET/v1/healthpublicSprawdzenie stanu bez uwierzytelnienia.
GET/v1/meanyInformacje o własnym koncie oraz metadane klucza.
GET/v1/productsread:productsLista wszystkich publicznie oferowanych produktów z cenami.
GET/v1/products/{id}read:productsSzczegóły produktu wraz z opcjami konfiguracyjnymi.
POST/v1/orderswrite:ordersZłożenie zamówienia. Wymagany Idempotency-Key.
GET/v1/orders/{id}read:ordersStatus własnego zamówienia.
GET/v1/servicesread:servicesLista własnych usług (z paginacją).
GET/v1/services/{id}read:servicesSzczegóły własnej usługi.
GET/v1/services/{id}/credentialsread:credentialsDane dostępowe usługi (oddzielny zakres uprawnień, wpis w audycie).
POST/v1/services/{id}/actionswrite:servicesAkcja serwisowa: start, stop, reboot, cancel (na koniec okresu rozliczeniowego), cancel_revoke.
GET/v1/services/{id}/metricsread:servicesMetryki serwera własnej usługi (CPU, pamięć, sieć).
GET/v1/services/{id}/ddos/profilesread:ddosDostępne profile Advanced DDoS Protection.
GET/v1/services/{id}/ddos/rulesread:ddosBieżące reguły przypisanego chronionego adresu IP.
POST/v1/services/{id}/ddos/ruleswrite:ddosDodaj jedną regułę ochrony. Idempotency-Key jest wymagany.
DELETE/v1/services/{id}/ddos/rules/{rule_id}write:ddosUsuń jedną własną regułę. Idempotency-Key jest wymagany.
GET/v1/services/{id}/ddos/attacksread:ddosWykryte ataki na chroniony adres IP (Remote DDoS Protection).
GET/v1/services/{id}/ddos/attacks/{attack_id}read:ddosSzczegóły jednego ataku: ruch i zestawienia.
GET/v1/billing/balanceread:billingSaldo kredytowe.
GET/v1/billing/invoicesread:billingLista Państwa faktur (z paginacją).
GET/v1/billing/invoices/{id}/pdfread:billingFaktura w formacie PDF.
GET/v1/webhooksread:webhooksAktualny URL webhooka.
PUT/v1/webhookswrite:webhooksUstawienie lub usunięcie URL webhooka.

Reguły Advanced DDoS Protection

Te endpointy wymagają usługi Advanced DDoS Protection należącej do Twojego konta. Odczyt jest dostępny w stanie active lub suspended; zmiany wymagają stanu active. Jawnie włącz read:ddos do odczytu i write:ddos do zmian na kluczu API. Istniejące klucze nie otrzymują automatycznie nowych uprawnień. Zarządzanie tunelami i listą dozwolonych adresów nie jest dostępne.

Wybierz app_code z katalogu profili. port musi być liczbą całkowitą od 1 do 65535; dla icmp pomiń go albo wyślij 0. Opcjonalny obiekt extra_ports przypisuje dokładnym etykietom profilu całkowite numery portów; pominięte etykiety zachowują wartości domyślne. Protokoły określa serwer, więc nie wysyłaj protocol. Nieznane pola lub etykiety zwracają HTTP 400.

GET /v1/services/{id}/ddos/profiles

{
  "data": [{
    "app_code": "rust",
    "name": "Rust",
    "default_port": 28015,
    "protocol": "UDP",
    "extra_ports": [
      {"name": "Query", "port": 28016, "protocol": "UDP"},
      {"name": "RCON", "port": 28016, "protocol": "TCP"},
      {"name": "RustPlus", "port": 28082, "protocol": "TCP"}
    ]
  }],
  "meta": {"service_id": 1234, "protection_ip": "192.0.2.10", "max_rules": 1000}
}

POST /v1/services/{id}/ddos/rules

{
  "app_code": "rust",
  "port": 28015,
  "extra_ports": {"Query": 28016, "RCON": 28016, "RustPlus": 28082}
}

POST zwraca HTTP 201 z utworzoną regułą w data. GET zwraca reguły i meta z service_id, protection_ip oraz max_rules. DELETE wymaga pustej treści żądania i zwraca HTTP 200 jak poniżej. Zarówno POST, jak i DELETE wymagają Idempotency-Key.

GET /v1/services/{id}/ddos/rules

{
  "data": [{
    "id": "example-rule-id",
    "app_code": "rust",
    "port": 28015,
    "protocol": "UDP",
    "extra_ports": [
      {"name": "Query", "port": 28016, "protocol": "UDP"},
      {"name": "RCON", "port": 28016, "protocol": "TCP"},
      {"name": "RustPlus", "port": 28082, "protocol": "TCP"}
    ]
  }],
  "meta": {"service_id": 1234, "protection_ip": "192.0.2.10", "max_rules": 1000}
}

DELETE /v1/services/{id}/ddos/rules/{rule_id}

{"data": {"id": "example-rule-id", "deleted": true}}

Panel i API współdzielą stałe okna UTC: 10 prób zapisu na minutę na konto, 5 na minutę na chroniony adres IP i 200 na dzień UTC na konto. Dopuszczone nieprawidłowe lub nieudane próby są liczone; udane powtórzenia idempotentne nie są. Odczyty DDoS przez API współdzielą limit 30 żądań na minutę na konto. Maksymalnie 1000 reguł na chroniony adres IP.

HTTP 404: nieznana lub cudza usługa albo cudza, brakująca lub systemowa reguła. HTTP 409: to nie jest usługa Advanced DDoS Protection (not_supported_for_product), nieaktywna usługa, konflikt portów lub równoczesna zmiana. HTTP 429: osiągnięty limit, przestrzegaj Retry-After. HTTP 502: usługa ochrony nie mogła ukończyć żądania. Reguła systemowa block jest ukryta i nie można jej usunąć. HTTP 503: kontrola limitów żądań jest chwilowo niedostępna, przestrzegaj Retry-After.

Raporty ataków DDoS

Te endpointy wymagają usługi Remote DDoS Protection należącej do Twojego konta, w stanie active lub suspended, oraz uprawnienia read:ddos, które trzeba jawnie włączyć. Lista pokazuje ataki DDoS wykryte na chronionym adresie IP usługi, od najnowszych.

Parametry zapytania: from i to jako data (YYYY-MM-DD) lub data z godziną w formacie ISO 8601 ze strefą czasową (domyślnie: ostatnie 30 dni), limit od 1 do 100 (domyślnie 25) oraz offset od 0 do 9999 (domyślnie 0). Okres nigdy nie sięga dalej niż 90 dni wstecz ani przed moment przypisania chronionego adresu IP do tej usługi; meta.from i meta.to pokazują faktycznie użyty okres.

GET /v1/services/{id}/ddos/attacks?from=2026-10-10

{
  "data": [{
    "id": "3f6c1a2e-9b47-4d8a-b5e2-7c0d9e4a1f63",
    "type": "ddos_attack",
    "started_at": "2026-11-07T18:34:06Z",
    "ended_at": null,
    "detected_bps": 20938227712,
    "detected_pps": 1998848,
    "source_ip_count": 341,
    "target_ip": "203.0.113.111",
    "details_available": true
  }],
  "paging": {"limit": 25, "offset": 0, "total": 1, "truncated": false},
  "meta": {"service_id": 5678, "protected_ip": "203.0.113.111", "from": "2026-10-10T00:00:00Z", "to": "2026-11-09T11:10:16Z", "retention_days": 90}
}

Każdy atak zawiera id (UUID), type (ddos_attack albo blackhole, jeśli docelowy adres IP został tymczasowo zablokowany trasą zerową), started_at, ended_at (może mieć wartość null), detected_bps, detected_pps, source_ip_count, target_ip i details_available. detected_bps i detected_pps podają natężenie w chwili wykrycia; filtrowanie już wtedy działało, dlatego wartości te mogą być niższe od szczytu podanego w szczegółach. paging zawiera limit, offset, total i truncated (true, jeśli okres obejmuje ponad 500 ataków), meta zawiera service_id, protected_ip, from, to i retention_days (90). Listy są przechowywane w pamięci podręcznej przez 60 sekund.

GET /v1/services/{id}/ddos/attacks/{attack_id}

{
  "data": {
    "id": "3f6c1a2e-9b47-4d8a-b5e2-7c0d9e4a1f63",
    "type": "ddos_attack",
    "started_at": "2026-11-07T18:34:06Z",
    "ended_at": null,
    "detected_bps": 20938227712,
    "detected_pps": 1998848,
    "source_ip_count": 341,
    "target_ip": "203.0.113.111",
    "details_available": true,
    "peak_bps": 20938227712,
    "peak_pps": 1998848,
    "total_bytes": 104809201664,
    "total_packets": 81887232,
    "interval_seconds": 1,
    "traffic": [{"time": "2026-11-07T18:34:06Z", "bps": 20938227712, "pps": 1998848}],
    "protocols": [{"protocol": "UDP", "avg_bps": 695618765, "avg_pps": 65645, "bytes": 104342814720, "packets": 78774272, "bps_percent": 99.56, "pps_percent": 96.2}],
    "destination_ports": [{"port": 58675, "protocol": "UDP", "avg_bps": 695556506, "avg_pps": 65481, "bps_percent": 99.55, "pps_percent": 95.96}],
    "source_ports": [{"port": 53, "protocol": "UDP", "avg_bps": 41896312, "avg_pps": 3511, "bps_percent": 5.996, "pps_percent": 5.15}],
    "source_countries": [{"country": "MX", "avg_bps": 96051528, "avg_pps": 8656}],
    "source_ips": [{"ip": "198.51.100.7", "avg_bps": 46162248, "avg_pps": 4151, "bps_percent": 6.61, "pps_percent": 6.08}],
    "packet_sizes": [{"range": "1400-1499", "avg_bps": 374806938, "percent": 54.076}]
  },
  "meta": {"service_id": 5678, "cached": false}
}

Szczegóły zawierają wszystkie pola listy oraz peak_bps, peak_pps, total_bytes, total_packets i interval_seconds. traffic podaje przychodzący ruch ataku w kolejnych interwałach ({time, bps, pps}) tak, jak widziała go sieć filtrująca, od około 10 minut przed wykryciem do około 10 minut po nim. Zestawienia protocols, destination_ports, source_ports, source_countries, source_ips i packet_sizes zawierają zwykle 5 największych pozycji: avg_bps i avg_pps to średnie z okna pomiarowego, bps_percent i pps_percent to udziały. protocols zawiera dodatkowo bytes i packets, packet_sizes zawiera range, avg_bps i percent. Szczegóły są przechowywane w pamięci podręcznej do 15 minut.

HTTP 400 validation_failed: nieprawidłowa wartość lub nieznany parametr zapytania. HTTP 404: nieznana lub cudza usługa, nieznany identyfikator ataku albo atak na inny adres IP. HTTP 409 not_supported_for_product: to nie jest usługa Remote DDoS Protection (np. Advanced DDoS Protection albo serwer). HTTP 409 service_not_active: usługa nie jest w stanie active ani suspended. HTTP 409 protection_not_ready: ochrona jest jeszcze konfigurowana.

Metryki serwera

Ten endpoint wymaga aktywnej usługi Twojego konta i uprawnienia read:services. Edge Unlimited Traffic VPS dostarczają dane o CPU, pamięci oraz ruchu sieciowym przychodzącym i wychodzącym (bit/s i pakiety/s), a także o ruchu wychodzącym dziennie i od początku miesiąca. Standardowe VPS Unlimited Traffic w lokalizacjach Europa, Niemcy, Francja, Kanada Wschodnia, Wielka Brytania i Polska dostarczają tylko dane o ruchu sieciowym przychodzącym i wychodzącym w bit/s.

Parametr zapytania range: 1h, 6h, 24h, 7d lub 14d (domyślnie 1h). Odstęp między punktami zależy od okresu: w Edge Unlimited Traffic VPS około 15 sekund (1h), 20 sekund (6h), 2 minuty (24h), 10 minut (7d) i 20 minut (14d); w standardowych VPS Unlimited Traffic 5 minut do 24h, 30 minut dla 7d i 2 godziny dla 14d. step_seconds pokazuje odstęp w odpowiedzi.

GET /v1/services/{id}/metrics?range=24h

{
  "data": {
    "service_id": 1234,
    "range": "24h",
    "step_seconds": 120,
    "available": ["cpu_percent", "memory_percent", "network_in_bps", "network_out_bps", "network_in_pps", "network_out_pps"],
    "summary": {
      "cpu_percent": {"avg": 3.1, "max": 41.7, "last": 2.9},
      "network_in_bps": {"avg": 64012.5, "max": 912345.0, "last": 60026.2}
    },
    "points": [
      {"time": "2026-11-08T11:12:00Z", "cpu_percent": 3.254, "memory_percent": 43.001, "network_in_bps": 68515.425, "network_out_bps": 650.767, "network_in_pps": 119.992, "network_out_pps": 0.775},
      {"time": "2026-11-08T11:14:00Z", "cpu_percent": 3.118, "memory_percent": 43.004, "network_in_bps": 66120.871, "network_out_bps": 702.134, "network_in_pps": 115.317, "network_out_pps": 0.825}
    ],
    "traffic": {
      "month_to_date_out_bytes": 111844510,
      "daily": [{"date": "2026-11-09", "out_bytes": 10485760, "final": false}],
      "as_of": "2026-11-09T11:00:01Z",
      "unit": "bytes",
      "direction": "outbound"
    }
  },
  "meta": {"generated_at": "2026-11-09T11:12:30Z", "cached": false, "measured_at": "server_network_interface"}
}

Wartości są mierzone na interfejsie sieciowym serwera, więc pokazują ruch, który faktycznie do niego dotarł. Pamięć wymaga agenta gościa działającego w serwerze. Wartości, których nie udało się zmierzyć, mają wartość null; available wymienia metryki ze zmierzonymi wartościami, a summary podaje dla każdej z nich avg, max i last. traffic zawiera ruch wychodzący w bajtach dziennie i od początku miesiąca (final ma wartość true, gdy dzień jest zamknięty), a dla produktów bez licznika ruchu ma wartość null. Odpowiedzi są przechowywane w pamięci podręcznej od 30 sekund (1h) do 10 minut (14d); meta.cached pokazuje, czy odpowiedź pochodzi z pamięci podręcznej.

HTTP 400 validation_failed: inna wartość range lub nieznany parametr zapytania. HTTP 404: nieznana lub cudza usługa. HTTP 409 not_supported_for_product: dla tej usługi metryki nie są dostępne (inne produkty i lokalizacje). HTTP 409 service_not_active: usługa nie jest aktywna.

Dla metryk serwera i raportów ataków obowiązują ogólne limity szybkości. Dodatkowo pobrania, których nie da się obsłużyć z pamięci podręcznej, są ograniczone do 20 na minutę na konto łącznie dla tych trzech endpointów; powyżej tego limitu otrzymasz HTTP 429 z nagłówkiem Retry-After. HTTP 502 monitoring_unavailable lub reports_unavailable: źródło danych jest chwilowo niedostępne, spróbuj ponownie później. HTTP 503 temporarily_unavailable z nagłówkiem Retry-After: równoległe żądanie właśnie przygotowuje te same dane.

Niedostępne przez API: raporty ataków dla Advanced DDoS Protection i dla serwerów, takich jak Edge Unlimited Traffic VPS; statystyki ruchu czystego lub odrzuconego na chroniony adres IP; CPU i pamięć w standardowych VPS Unlimited Traffic; dostarczanie webhooków i eksport CSV.

Idempotencja

POST /v1/orders oraz POST /v1/services/{id}/actions wymagają nagłówka Idempotency-Key (od 1 do 80 znaków z zestawu [A-Za-z0-9_.-]). Klucz jest powiązany z metodą, ścieżką i treścią żądania. Powtórzenie tego samego żądania z tym samym kluczem w ciągu godziny zwraca zapisaną odpowiedź; po upływie tego czasu otrzymają Państwo kod 410 z reason replay_stale i należy wtedy wysłać nowy klucz. Ten sam klucz z inną treścią lub na innym endpoincie zostaje odrzucony z kodem 409 idempotency_conflict.

Limity szybkości

Domyślnie 60 żądań na minutę (plus burst do 20 żądań) i 5000 dziennie na klucz, 120 na minutę na konto łącznie dla wszystkich kluczy oraz 600 na minutę na źródłowy adres IP. Po przekroczeniu limitu otrzymają Państwo HTTP 429 z nagłówkiem Retry-After. Nagłówki odpowiedzi X-RateLimit-Remaining i X-RateLimit-Reset pokazują bieżący stan limitu klucza.