Endpoint-Referenz

KernelHost API

Alle Endpoints liefern application/json. Fehler folgen RFC 7807 (Problem+JSON). Antwort enthält stets den Header X-Request-Id zur Korrelation mit dem serverseitigen Audit-Log.

MethodPathScopeZweck
GET/v1/healthpublicHealth-Check ohne Auth.
GET/v1/meanyEigene Account-Info + Key-Metadaten.
GET/v1/productsread:productsListe aller öffentlich gelisteten Produkte mit Preisen.
GET/v1/products/{id}read:productsProdukt-Details inkl. Konfigurations-Optionen.
POST/v1/orderswrite:ordersNeue Bestellung. Idempotency-Key Pflicht.
GET/v1/orders/{id}read:ordersStatus einer eigenen Bestellung.
GET/v1/servicesread:servicesListe der eigenen Services (paginiert).
GET/v1/services/{id}read:servicesDetails eines eigenen Service.
GET/v1/services/{id}/credentialsread:credentialsZugangsdaten (separater Scope, audit-geloggt).
POST/v1/services/{id}/actionswrite:servicesService-Aktion: start, stop, reboot, cancel (zum Laufzeitende), cancel_revoke.
GET/v1/services/{id}/metricsread:servicesServermesswerte eines eigenen Service (CPU, Arbeitsspeicher, Netzwerk).
GET/v1/services/{id}/ddos/profilesread:ddosVerfügbare Profile der Advanced DDoS Protection.
GET/v1/services/{id}/ddos/rulesread:ddosAktuelle Regeln der zugewiesenen Schutz-IP.
POST/v1/services/{id}/ddos/ruleswrite:ddosEine Schutzregel hinzufügen. Idempotency-Key erforderlich.
DELETE/v1/services/{id}/ddos/rules/{rule_id}write:ddosEine eigene Regel löschen. Idempotency-Key erforderlich.
GET/v1/services/{id}/ddos/attacksread:ddosErkannte Angriffe auf die geschützte IP (Remote DDoS Protection).
GET/v1/services/{id}/ddos/attacks/{attack_id}read:ddosDetails eines Angriffs: Verkehr und Aufschlüsselungen.
GET/v1/billing/balanceread:billingGuthaben.
GET/v1/billing/invoicesread:billingListe Ihrer Rechnungen (paginiert).
GET/v1/billing/invoices/{id}/pdfread:billingRechnungs-PDF.
GET/v1/webhooksread:webhooksAktuelle Webhook-URL.
PUT/v1/webhookswrite:webhooksWebhook-URL setzen oder entfernen.

Regeln der Advanced DDoS Protection

Diese Endpunkte setzen einen Advanced-DDoS-Protection-Dienst des eigenen Kontos voraus. Lesezugriffe sind im Status active oder suspended möglich, Änderungen ausschließlich im Status active. read:ddos für Lesezugriffe und write:ddos für Änderungen müssen am API-Schlüssel ausdrücklich aktiviert werden. Bestehende Schlüssel erhalten keine neuen Rechte automatisch. Tunnel- und Whitelist-Verwaltung stehen nicht zur Verfügung.

app_code aus dem Profilkatalog wählen. port muss eine Ganzzahl von 1 bis 65535 sein; bei icmp weglassen oder 0 senden. Das optionale extra_ports ordnet exakt geschriebenen Profilbezeichnungen ganzzahlige Ports zu; ausgelassene Einträge verwenden die Profilstandardwerte. Protokolle bestimmt der Server, deshalb kein protocol senden. Unbekannte Felder oder Bezeichnungen ergeben 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 liefert HTTP 201 mit der angelegten Regel in data. GET liefert Regeln und meta mit service_id, protection_ip und max_rules. DELETE erhält einen leeren Body und liefert HTTP 200 wie unten gezeigt. POST und DELETE erfordern jeweils 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 und API teilen feste UTC-Zeitfenster: 10 Schreibversuche pro Minute je Konto, 5 pro Minute je Schutz-IP und 200 pro UTC-Tag je Konto. Zugelassene ungültige oder fehlgeschlagene Versuche zählen mit, erfolgreiche Idempotenz-Wiederholungen nicht. DDoS-Lesezugriffe über die API teilen 30 Anfragen pro Minute je Konto. Höchstens 1000 Regeln je Schutz-IP.

HTTP 404: unbekannter oder fremder Dienst beziehungsweise fremde, fehlende oder Systemregel. HTTP 409: kein Advanced-DDoS-Protection-Dienst (not_supported_for_product), inaktiver Dienst, Portkollision oder gleichzeitige Änderung. HTTP 429: Grenze erreicht, Retry-After beachten. HTTP 502: Der Schutzdienst konnte die Anfrage nicht abschließen. Die Systemregel block bleibt ausgeblendet und kann nicht gelöscht werden. HTTP 503: Die Anfragegrenzen sind vorübergehend nicht verfügbar, Retry-After beachten.

DDoS-Angriffsberichte

Diese Endpunkte setzen einen Remote-DDoS-Protection-Dienst des eigenen Kontos im Status active oder suspended voraus sowie den Scope read:ddos, der ausdrücklich aktiviert sein muss. Die Liste zeigt die DDoS-Angriffe, die auf der geschützten IP-Adresse des Dienstes erkannt wurden, die neuesten zuerst.

Query-Parameter: from und to als Datum (YYYY-MM-DD) oder als Datum mit Uhrzeit nach ISO 8601 mit Zeitzone (Standard: die letzten 30 Tage), limit von 1 bis 100 (Standard 25) und offset von 0 bis 9999 (Standard 0). Der Zeitraum reicht nie mehr als 90 Tage zurück und nie vor den Zeitpunkt, zu dem die geschützte IP-Adresse diesem Dienst zugewiesen wurde; meta.from und meta.to zeigen den tatsächlich verwendeten Zeitraum.

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

Jeder Angriff enthält id (UUID), type (ddos_attack, oder blackhole, wenn die Ziel-IP vorübergehend per Nullrouting gesperrt wurde), started_at, ended_at (kann null sein), detected_bps, detected_pps, source_ip_count, target_ip und details_available. detected_bps und detected_pps geben die Rate im Moment der Erkennung an; die Filterung lief da bereits, deshalb können sie unter dem Spitzenwert in den Details liegen. paging enthält limit, offset, total und truncated (true, wenn der Zeitraum mehr als 500 Angriffe umfasst), meta enthält service_id, protected_ip, from, to und retention_days (90). Listen werden 60 Sekunden zwischengespeichert.

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

Die Details enthalten alle Felder der Liste sowie peak_bps, peak_pps, total_bytes, total_packets und interval_seconds. traffic listet den eingehenden Angriffsverkehr je Intervall ({time, bps, pps}), wie ihn das Filternetz gesehen hat, von etwa 10 Minuten vor bis etwa 10 Minuten nach der Erkennung. Die Aufschlüsselungen protocols, destination_ports, source_ports, source_countries, source_ips und packet_sizes enthalten meist die 5 größten Einträge: avg_bps und avg_pps sind Durchschnittswerte über das Messfenster, bps_percent und pps_percent Anteile. protocols enthält zusätzlich bytes und packets, packet_sizes enthält range, avg_bps und percent. Details werden bis zu 15 Minuten zwischengespeichert.

HTTP 400 validation_failed: ungültiger Wert oder unbekannter Query-Parameter. HTTP 404: unbekannter oder fremder Dienst, unbekannte Angriffs-ID oder Angriff auf eine andere IP-Adresse. HTTP 409 not_supported_for_product: kein Remote-DDoS-Protection-Dienst (zum Beispiel Advanced DDoS Protection oder ein Server). HTTP 409 service_not_active: Der Dienst ist weder active noch suspended. HTTP 409 protection_not_ready: Der Schutz wird noch eingerichtet.

Servermesswerte

Dieser Endpunkt setzt einen aktiven Dienst des eigenen Kontos und den Scope read:services voraus. Edge Unlimited Traffic VPS liefern Werte für CPU, Arbeitsspeicher und Netzwerk ein- und ausgehend (Bit/s und Pakete/s) sowie den ausgehenden Traffic je Tag und im laufenden Monat. Reguläre Unlimited Traffic VPS an den Standorten Europa, Deutschland, Frankreich, Kanada Ost, Vereinigtes Königreich und Polen liefern nur Netzwerkwerte ein- und ausgehend in Bit/s.

Query-Parameter range: 1h, 6h, 24h, 7d oder 14d (Standard 1h). Der Abstand zwischen den Messpunkten hängt vom Zeitraum ab: bei Edge Unlimited Traffic VPS etwa 15 Sekunden (1h), 20 Sekunden (6h), 2 Minuten (24h), 10 Minuten (7d) und 20 Minuten (14d); bei regulären Unlimited Traffic VPS 5 Minuten bis 24h, 30 Minuten bei 7d und 2 Stunden bei 14d. step_seconds zeigt den Abstand der jeweiligen Antwort.

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

Die Werte werden an der Netzwerkschnittstelle des Servers gemessen und zeigen damit den Verkehr, der den Server tatsächlich erreicht hat. Der Arbeitsspeicher setzt den Gast-Agenten im Server voraus. Nicht messbare Werte sind null; available nennt die Kennzahlen mit gemessenen Werten, summary zeigt dazu jeweils avg, max und last. traffic enthält den ausgehenden Traffic in Bytes je Tag und im laufenden Monat (final ist true, sobald ein Tag abgeschlossen ist) und ist null bei Produkten ohne Traffic-Zähler. Antworten werden 30 Sekunden (1h) bis 10 Minuten (14d) zwischengespeichert; meta.cached zeigt, ob die Antwort aus dem Zwischenspeicher kam.

HTTP 400 validation_failed: anderer Wert für range oder unbekannter Query-Parameter. HTTP 404: unbekannter oder fremder Dienst. HTTP 409 not_supported_for_product: Für diesen Dienst gibt es keine Messwerte (andere Produkte und Standorte). HTTP 409 service_not_active: Der Dienst ist nicht aktiv.

Für Servermesswerte und Angriffsberichte gelten die allgemeinen Rate-Limits. Zusätzlich sind Abrufe, die nicht aus dem Zwischenspeicher beantwortet werden können, über diese drei Endpunkte zusammen auf 20 pro Minute je Konto begrenzt; darüber folgt HTTP 429 mit Retry-After. HTTP 502 monitoring_unavailable oder reports_unavailable: Die Datenquelle ist vorübergehend nicht erreichbar, später erneut versuchen. HTTP 503 temporarily_unavailable mit Retry-After: Eine parallele Anfrage bereitet dieselben Daten gerade auf.

Über die API nicht verfügbar: Angriffsberichte für Advanced DDoS Protection und für Server wie Edge Unlimited Traffic VPS; Statistiken zu sauberem oder verworfenem Verkehr je geschützter IP; CPU und Arbeitsspeicher bei regulären Unlimited Traffic VPS; Webhook-Zustellung und CSV-Export.

Idempotenz

POST /v1/orders und POST /v1/services/{id}/actions verlangen einen Idempotency-Key-Header (1 bis 80 Zeichen aus [A-Za-z0-9_.-]). Der Key ist an Methode, Pfad und Body gebunden. Wiederholen Sie dieselbe Anfrage mit demselben Key innerhalb einer Stunde, erhalten Sie die gespeicherte Antwort; danach kommt 410 mit reason replay_stale, dann bitte einen neuen Key senden. Derselbe Key mit anderem Body oder auf einem anderen Endpoint wird mit 409 idempotency_conflict abgelehnt.

Rate-Limits

Standardmäßig 60 Anfragen pro Minute (plus 20 Burst) und 5.000 pro Tag pro Key, 120 pro Minute pro Konto über alle Keys und 600 pro Minute pro Quell-IP. Bei Überschreitung folgt HTTP 429 mit dem Header Retry-After. Die Antwort-Header X-RateLimit-Remaining und X-RateLimit-Reset zeigen den Stand des Key-Limits.