Reference koncových bodů

KernelHost API

Všechny koncové body vracejí application/json. Chyby se řídí RFC 7807 (Problem+JSON). Každá odpověď nese hlavičku X-Request-Id pro korelaci se serverovým auditním logem.

MethodPathOprávněníÚčel
GET/v1/healthpublicHealth-check bez autentizace.
GET/v1/meanyInformace o vlastním účtu a metadata klíče.
GET/v1/productsread:productsSeznam všech veřejně nabízených produktů s cenami.
GET/v1/products/{id}read:productsDetail produktu včetně konfiguračních možností.
POST/v1/orderswrite:ordersZadat objednávku. Idempotency-Key povinný.
GET/v1/orders/{id}read:ordersStav vlastní objednávky.
GET/v1/servicesread:servicesSeznam vlastních služeb (stránkovaný).
GET/v1/services/{id}read:servicesDetail vlastní služby.
GET/v1/services/{id}/credentialsread:credentialsPřístupové údaje služby (samostatné oprávnění, auditováno).
POST/v1/services/{id}/actionswrite:servicesServisní akce: start, stop, reboot, cancel (ke konci fakturačního období), cancel_revoke.
GET/v1/services/{id}/metricsread:servicesMetriky serveru vlastní služby (CPU, paměť, síť).
GET/v1/services/{id}/ddos/profilesread:ddosDostupné profily Advanced DDoS Protection.
GET/v1/services/{id}/ddos/rulesread:ddosAktuální pravidla přiřazené chráněné IP adresy.
POST/v1/services/{id}/ddos/ruleswrite:ddosPřidat jedno ochranné pravidlo. Idempotency-Key je povinný.
DELETE/v1/services/{id}/ddos/rules/{rule_id}write:ddosSmazat jedno vlastní pravidlo. Idempotency-Key je povinný.
GET/v1/services/{id}/ddos/attacksread:ddosZjištěné útoky na chráněnou IP adresu (Remote DDoS Protection).
GET/v1/services/{id}/ddos/attacks/{attack_id}read:ddosPodrobnosti jednoho útoku: provoz a členění.
GET/v1/billing/balanceread:billingZůstatek kreditu.
GET/v1/billing/invoicesread:billingSeznam Vašich faktur (stránkovaný).
GET/v1/billing/invoices/{id}/pdfread:billingPDF faktury.
GET/v1/webhooksread:webhooksAktuální webhook URL.
PUT/v1/webhookswrite:webhooksNastavit nebo zrušit webhook URL.

Pravidla Advanced DDoS Protection

Tyto endpointy vyžadují službu Advanced DDoS Protection patřící vašemu účtu. Čtení je dostupné ve stavu active nebo suspended; změny vyžadují stav active. Na klíči API výslovně povolte read:ddos pro čtení a write:ddos pro změny. Stávající klíče nezískávají nová oprávnění automaticky. Správa tunelů a seznamů povolených adres není dostupná.

Vyberte app_code z katalogu profilů. port musí být celé číslo od 1 do 65535; u icmp jej vynechte nebo odešlete 0. Volitelný objekt extra_ports přiřazuje přesným názvům z profilu celočíselné porty; vynechané položky použijí výchozí hodnoty profilu. Protokoly určuje server, proto neposílejte protocol. Neznámá pole nebo názvy vracejí 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 vrací HTTP 201 s vytvořeným pravidlem v data. GET vrací pravidla a meta s poli service_id, protection_ip a max_rules. DELETE používá prázdné tělo a vrací HTTP 200 podle příkladu níže. POST i DELETE vyžadují 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 a API sdílejí pevná časová okna UTC: 10 pokusů o zápis za minutu na účet, 5 za minutu na chráněnou IP adresu a 200 za den UTC na účet. Povolené, ale neplatné nebo neúspěšné pokusy se počítají; úspěšná idempotentní opakování ne. Čtení přes DDoS API sdílí 30 požadavků za minutu na účet. Nejvýše 1000 pravidel na chráněnou IP adresu.

HTTP 404: neznámá nebo cizí služba či cizí, chybějící nebo systémové pravidlo. HTTP 409: nejde o službu Advanced DDoS Protection (not_supported_for_product), neaktivní služba, kolize portů nebo souběžná změna. HTTP 429: dosažený limit, respektujte Retry-After. HTTP 502: ochranná služba nemohla požadavek dokončit. Systémové pravidlo block je skryté a nelze jej smazat. HTTP 503: kontrola limitů požadavků je dočasně nedostupná, respektujte Retry-After.

Přehledy DDoS útoků

Tyto endpointy vyžadují službu Remote DDoS Protection patřící vašemu účtu ve stavu active nebo suspended a oprávnění read:ddos, které je třeba výslovně povolit. Seznam ukazuje DDoS útoky zjištěné na chráněné IP adrese služby, od nejnovějších.

Parametry dotazu: from a to jako datum (YYYY-MM-DD) nebo jako datum a čas podle ISO 8601 s časovým pásmem (výchozí: posledních 30 dní), limit od 1 do 100 (výchozí 25) a offset od 0 do 9999 (výchozí 0). Období nikdy nesahá dál než 90 dní zpět ani před okamžik, kdy byla chráněná IP adresa přiřazena této službě; meta.from a meta.to ukazují skutečně použité období.

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ždý útok obsahuje id (UUID), type (ddos_attack, nebo blackhole, pokud byla cílová IP adresa dočasně zablokována směrováním do null route), started_at, ended_at (může být null), detected_bps, detected_pps, source_ip_count, target_ip a details_available. detected_bps a detected_pps udávají intenzitu v okamžiku zjištění; filtrování už v té chvíli běželo, proto mohou být nižší než špička v podrobnostech. paging obsahuje limit, offset, total a truncated (true, pokud období zahrnuje více než 500 útoků), meta obsahuje service_id, protected_ip, from, to a retention_days (90). Seznamy se ukládají do mezipaměti na 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}
}

Podrobnosti obsahují všechna pole seznamu a navíc peak_bps, peak_pps, total_bytes, total_packets a interval_seconds. traffic uvádí příchozí útočný provoz po intervalech ({time, bps, pps}) tak, jak jej zaznamenala filtrační síť, přibližně od 10 minut před zjištěním do 10 minut po něm. Členění protocols, destination_ports, source_ports, source_countries, source_ips a packet_sizes obvykle obsahují 5 největších položek: avg_bps a avg_pps jsou průměry za měřicí okno, bps_percent a pps_percent jsou podíly. protocols navíc obsahuje bytes a packets, packet_sizes obsahuje range, avg_bps a percent. Podrobnosti se ukládají do mezipaměti až na 15 minut.

HTTP 400 validation_failed: neplatná hodnota nebo neznámý parametr dotazu. HTTP 404: neznámá nebo cizí služba, neznámé ID útoku nebo útok na jinou IP adresu. HTTP 409 not_supported_for_product: nejde o službu Remote DDoS Protection (například Advanced DDoS Protection nebo server). HTTP 409 service_not_active: služba není ve stavu active ani suspended. HTTP 409 protection_not_ready: ochrana se teprve nastavuje.

Metriky serveru

Tento endpoint vyžaduje aktivní službu vašeho účtu a oprávnění read:services. Edge Unlimited Traffic VPS poskytují údaje o CPU, paměti a příchozím i odchozím síťovém provozu (bit/s a pakety/s) a také o odchozím přenosu za den a od začátku měsíce. Běžné Unlimited Traffic VPS v lokalitách Evropa, Německo, Francie, východní Kanada, Spojené království a Polsko poskytují pouze údaje o příchozím a odchozím síťovém provozu v bit/s.

Parametr dotazu range: 1h, 6h, 24h, 7d nebo 14d (výchozí 1h). Rozestup mezi body závisí na období: u Edge Unlimited Traffic VPS přibližně 15 sekund (1h), 20 sekund (6h), 2 minuty (24h), 10 minut (7d) a 20 minut (14d); u běžných Unlimited Traffic VPS 5 minut do 24h, 30 minut pro 7d a 2 hodiny pro 14d. step_seconds ukazuje rozestup v odpovědi.

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"}
}

Hodnoty se měří na síťovém rozhraní serveru, a ukazují tak provoz, který na server skutečně dorazil. Pro paměť je nutný guest agent uvnitř serveru. Hodnoty, které nebylo možné změřit, jsou null; available uvádí metriky s naměřenými hodnotami a summary ke každé z nich udává avg, max a last. traffic obsahuje odchozí přenos v bajtech za den a od začátku měsíce (final je true, jakmile je den uzavřen) a u produktů bez počítadla přenosu je null. Odpovědi se ukládají do mezipaměti na 30 sekund (1h) až 10 minut (14d); meta.cached ukazuje, zda odpověď pochází z mezipaměti.

HTTP 400 validation_failed: jiná hodnota range nebo neznámý parametr dotazu. HTTP 404: neznámá nebo cizí služba. HTTP 409 not_supported_for_product: pro tuto službu nejsou metriky k dispozici (jiné produkty a lokality). HTTP 409 service_not_active: služba není aktivní.

Pro metriky serveru a přehledy útoků platí obecná omezení rychlosti. Navíc jsou načtení, která nelze obsloužit z mezipaměti, omezena na 20 za minutu na účet pro tyto tři endpointy dohromady; nad tento limit dostanete HTTP 429 s hlavičkou Retry-After. HTTP 502 monitoring_unavailable nebo reports_unavailable: zdroj dat je dočasně nedostupný, zkuste to později. HTTP 503 temporarily_unavailable s hlavičkou Retry-After: souběžný požadavek právě připravuje stejná data.

Přes API není k dispozici: přehledy útoků pro Advanced DDoS Protection a pro servery, například Edge Unlimited Traffic VPS; statistiky čistého nebo zahozeného provozu na chráněnou IP adresu; CPU a paměť u běžných Unlimited Traffic VPS; doručování webhooků a export do CSV.

Idempotence

POST /v1/orders a POST /v1/services/{id}/actions vyžadují hlavičku Idempotency-Key (1 až 80 znaků z [A-Za-z0-9_.-]). Klíč je vázán na metodu, cestu a tělo. Pokud stejný požadavek se stejným klíčem zopakujete během jedné hodiny, obdržíte uloženou odpověď; po uplynutí této doby dostanete 410 (reason replay_stale) a je třeba poslat nový klíč. Stejný klíč s jiným tělem nebo na jiném koncovém bodu je odmítnut s 409 idempotency_conflict.

Omezení rychlosti

Standardně 60 požadavků za minutu (s burstem 20) a 5 000 za den pro každý klíč, 120 za minutu pro každý účet napříč všemi klíči a 600 za minutu pro každou zdrojovou IP. Při překročení limitu dostanete HTTP 429 s hlavičkou Retry-After. Hlavičky odpovědi X-RateLimit-Remaining a X-RateLimit-Reset ukazují aktuální stav limitu klíče.