Riferimento endpoint

KernelHost API

Tutti gli endpoint restituiscono application/json. Gli errori seguono RFC 7807 (Problem+JSON). Ogni risposta contiene un header X-Request-Id per la correlazione con l'audit log lato server.

MethodPathPermessoScopo
GET/v1/healthpublicHealth check non autenticato.
GET/v1/meanyInformazioni del proprio account e metadati chiave.
GET/v1/productsread:productsElenco di tutti i prodotti pubblicamente disponibili con prezzi.
GET/v1/products/{id}read:productsDettagli prodotto incluse opzioni di configurazione.
POST/v1/orderswrite:ordersEffettuare un ordine. Idempotency-Key obbligatoria.
GET/v1/orders/{id}read:ordersStato di un proprio ordine.
GET/v1/servicesread:servicesElenco dei propri servizi (paginato).
GET/v1/services/{id}read:servicesDettagli di un proprio servizio.
GET/v1/services/{id}/credentialsread:credentialsCredenziali del servizio (permesso separato, registrato in audit).
POST/v1/services/{id}/actionswrite:servicesAzione sul servizio: start, stop, reboot, cancel (alla fine del periodo di fatturazione), cancel_revoke.
GET/v1/services/{id}/metricsread:servicesMetriche del server di un proprio servizio (CPU, memoria, rete).
GET/v1/services/{id}/ddos/profilesread:ddosProfili Advanced DDoS Protection disponibili.
GET/v1/services/{id}/ddos/rulesread:ddosRegole attuali dell'IP protetto assegnato.
POST/v1/services/{id}/ddos/ruleswrite:ddosAggiungere una regola di protezione. Idempotency-Key obbligatorio.
DELETE/v1/services/{id}/ddos/rules/{rule_id}write:ddosEliminare una propria regola. Idempotency-Key obbligatorio.
GET/v1/services/{id}/ddos/attacksread:ddosAttacchi rilevati sull'IP protetto (Remote DDoS Protection).
GET/v1/services/{id}/ddos/attacks/{attack_id}read:ddosDettagli di un attacco: traffico e ripartizioni.
GET/v1/billing/balanceread:billingSaldo credito.
GET/v1/billing/invoicesread:billingElenco delle sue fatture (paginato).
GET/v1/billing/invoices/{id}/pdfread:billingPDF della fattura.
GET/v1/webhooksread:webhooksURL del webhook corrente.
PUT/v1/webhookswrite:webhooksImpostare o rimuovere l'URL del webhook.

Regole Advanced DDoS Protection

Questi endpoint richiedono un servizio Advanced DDoS Protection appartenente al proprio account. La lettura è disponibile con stato active o suspended; le modifiche richiedono lo stato active. Attivare esplicitamente read:ddos per la lettura e write:ddos per le modifiche sulla chiave API. Le chiavi esistenti non ricevono automaticamente nuovi permessi. Non è disponibile la gestione di tunnel e whitelist.

Scegliere app_code dal catalogo dei profili. port deve essere un intero da 1 a 65535; per icmp, ometterlo o inviare 0. L'oggetto facoltativo extra_ports associa le etichette esatte del profilo a porte intere; le etichette omesse mantengono i valori predefiniti. I protocolli vengono determinati dal server, quindi non inviare protocol. Campi o etichette sconosciuti restituiscono 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 restituisce HTTP 201 con la regola creata in data. GET restituisce le regole e meta con service_id, protection_ip e max_rules. DELETE richiede un corpo vuoto e restituisce HTTP 200 come nell'esempio seguente. POST e DELETE richiedono entrambi 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}}

Il pannello e l'API condividono finestre UTC fisse: 10 tentativi di scrittura al minuto per account, 5 al minuto per IP protetto e 200 per giorno UTC per account. Si contano i tentativi ammessi non validi o falliti; le ripetizioni idempotenti riuscite non si contano. Le letture DDoS dell'API condividono 30 richieste al minuto per account. Massimo: 1000 regole per IP protetto.

HTTP 404: servizio sconosciuto o altrui, oppure regola altrui, assente o di sistema. HTTP 409: il servizio non è Advanced DDoS Protection (not_supported_for_product), servizio inattivo, conflitto di porte o modifica simultanea. HTTP 429: limite raggiunto, rispettare Retry-After. HTTP 502: il servizio di protezione non ha completato la richiesta. La regola di sistema block è nascosta e non può essere eliminata. HTTP 503: i controlli dei limiti non sono temporaneamente disponibili, rispettare Retry-After.

Report degli attacchi DDoS

Questi endpoint richiedono un servizio Remote DDoS Protection appartenente al proprio account, con stato active o suspended, e il permesso read:ddos, da attivare esplicitamente. L'elenco mostra gli attacchi DDoS rilevati sull'indirizzo IP protetto del servizio, dal più recente al meno recente.

Parametri di query: from e to come data (YYYY-MM-DD) o come data e ora ISO 8601 con fuso orario (predefinito: gli ultimi 30 giorni), limit da 1 a 100 (predefinito 25) e offset da 0 a 9999 (predefinito 0). Il periodo non risale mai a più di 90 giorni fa né a prima dell'assegnazione dell'indirizzo IP protetto a questo servizio; meta.from e meta.to indicano il periodo effettivamente usato.

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

Ogni attacco contiene id (UUID), type (ddos_attack, oppure blackhole se l'IP di destinazione è stato temporaneamente bloccato tramite null route), started_at, ended_at (può essere null), detected_bps, detected_pps, source_ip_count, target_ip e details_available. detected_bps e detected_pps indicano il volume al momento del rilevamento; il filtraggio era già iniziato, quindi possono essere inferiori al picco riportato nei dettagli. paging contiene limit, offset, total e truncated (true se il periodo comprende più di 500 attacchi), meta contiene service_id, protected_ip, from, to e retention_days (90). Gli elenchi restano in cache per 60 secondi.

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

I dettagli contengono tutti i campi dell'elenco e inoltre peak_bps, peak_pps, total_bytes, total_packets e interval_seconds. traffic elenca il traffico di attacco in ingresso per intervallo ({time, bps, pps}) così come lo ha rilevato la rete di filtraggio, da circa 10 minuti prima a circa 10 minuti dopo il rilevamento. Le ripartizioni protocols, destination_ports, source_ports, source_countries, source_ips e packet_sizes contengono di solito le 5 voci principali: avg_bps e avg_pps sono medie sulla finestra di misurazione, bps_percent e pps_percent sono quote percentuali. protocols contiene anche bytes e packets, packet_sizes contiene range, avg_bps e percent. I dettagli restano in cache fino a 15 minuti.

HTTP 400 validation_failed: valore non valido o parametro di query sconosciuto. HTTP 404: servizio sconosciuto o altrui, ID di attacco sconosciuto o attacco a un altro indirizzo IP. HTTP 409 not_supported_for_product: non è un servizio Remote DDoS Protection (ad esempio Advanced DDoS Protection o un server). HTTP 409 service_not_active: il servizio non è né active né suspended. HTTP 409 protection_not_ready: la protezione è ancora in fase di configurazione.

Metriche del server

Questo endpoint richiede un servizio attivo del proprio account e il permesso read:services. Gli Edge Unlimited Traffic VPS forniscono i dati di CPU, memoria e rete in ingresso e in uscita (bit/s e pacchetti/s), oltre al traffico in uscita per giorno e dall'inizio del mese. I VPS Unlimited Traffic tradizionali in Europa, Germania, Francia, Canada orientale, Regno Unito e Polonia forniscono solo i dati della rete in ingresso e in uscita in bit/s.

Parametro di query range: 1h, 6h, 24h, 7d o 14d (predefinito 1h). La distanza tra i punti dipende dal periodo: per gli Edge Unlimited Traffic VPS circa 15 secondi (1h), 20 secondi (6h), 2 minuti (24h), 10 minuti (7d) e 20 minuti (14d); per i VPS Unlimited Traffic tradizionali 5 minuti fino a 24h, 30 minuti con 7d e 2 ore con 14d. step_seconds indica la distanza della risposta.

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

I valori sono misurati sull'interfaccia di rete del server e mostrano quindi il traffico che ha effettivamente raggiunto il server. La memoria richiede il guest agent all'interno del server. I valori non misurabili sono null; available elenca le metriche con valori misurati e summary indica per ciascuna avg, max e last. traffic contiene il traffico in uscita in byte per giorno e dall'inizio del mese (final è true quando la giornata è conclusa) ed è null per i prodotti senza contatore del traffico. Le risposte restano in cache da 30 secondi (1h) a 10 minuti (14d); meta.cached indica se la risposta proviene dalla cache.

HTTP 400 validation_failed: altro valore di range o parametro di query sconosciuto. HTTP 404: servizio sconosciuto o altrui. HTTP 409 not_supported_for_product: nessuna metrica disponibile per questo servizio (altri prodotti e sedi). HTTP 409 service_not_active: il servizio non è attivo.

Per le metriche del server e i report degli attacchi valgono i limiti di velocità generali. Inoltre, i recuperi che non possono essere serviti dalla cache sono limitati a 20 al minuto per account sull'insieme di questi tre endpoint; oltre questa soglia si riceve HTTP 429 con Retry-After. HTTP 502 monitoring_unavailable o reports_unavailable: la fonte dei dati è temporaneamente non disponibile, riprovare più tardi. HTTP 503 temporarily_unavailable con Retry-After: una richiesta parallela sta preparando gli stessi dati.

Non disponibile tramite API: report degli attacchi per Advanced DDoS Protection e per server come gli Edge Unlimited Traffic VPS; statistiche sul traffico pulito o scartato per IP protetto; CPU e memoria dei VPS Unlimited Traffic tradizionali; invio dei webhook ed esportazione CSV.

Idempotenza

POST /v1/orders e POST /v1/services/{id}/actions richiedono un header Idempotency-Key (da 1 a 80 caratteri dell'insieme [A-Za-z0-9_.-]). La chiave è legata a metodo, percorso e body. Se ripete la stessa richiesta con la stessa chiave entro un'ora, riceve la risposta memorizzata; trascorsa l'ora, riceve 410 con reason replay_stale e deve inviare una nuova chiave. La stessa chiave con un body diverso o su un altro endpoint viene rifiutata con 409 idempotency_conflict.

Limiti di velocità

Per impostazione predefinita valgono 60 richieste al minuto (più un burst di 20) e 5.000 al giorno per chiave, 120 al minuto per account su tutte le chiavi e 600 al minuto per IP di origine. Se un limite viene superato, riceve HTTP 429 con l'header Retry-After. Gli header di risposta X-RateLimit-Remaining e X-RateLimit-Reset mostrano lo stato attuale del limite della chiave.