Referência de endpoints

KernelHost API

Todos os endpoints retornam application/json. Erros seguem a RFC 7807 (Problem+JSON). Cada resposta traz um cabeçalho X-Request-Id para correlação com o log de auditoria do servidor.

MethodPathEscopoFinalidade
GET/v1/healthpublicHealth check sem autenticação.
GET/v1/meanyInformações da própria conta e metadados da chave API.
GET/v1/productsread:productsLista de todos os produtos listados publicamente, com preços.
GET/v1/products/{id}read:productsDetalhes do produto, incluindo opções de configuração.
POST/v1/orderswrite:ordersRealizar um pedido. Idempotency-Key obrigatório.
GET/v1/orders/{id}read:ordersStatus de um pedido próprio.
GET/v1/servicesread:servicesLista dos próprios serviços (paginada).
GET/v1/services/{id}read:servicesDetalhes de um serviço próprio.
GET/v1/services/{id}/credentialsread:credentialsCredenciais do serviço (escopo separado, registrado em auditoria).
POST/v1/services/{id}/actionswrite:servicesAção de serviço: start, stop, reboot, cancel (no fim do período de faturação), cancel_revoke.
GET/v1/services/{id}/metricsread:servicesMétricas do servidor de um serviço próprio (CPU, memória, rede).
GET/v1/services/{id}/ddos/profilesread:ddosPerfis de Advanced DDoS Protection disponíveis.
GET/v1/services/{id}/ddos/rulesread:ddosRegras atuais do IP protegido atribuído.
POST/v1/services/{id}/ddos/ruleswrite:ddosAdicionar uma regra de proteção. Idempotency-Key obrigatório.
DELETE/v1/services/{id}/ddos/rules/{rule_id}write:ddosEliminar uma regra própria. Idempotency-Key obrigatório.
GET/v1/services/{id}/ddos/attacksread:ddosAtaques detetados no IP protegido (Remote DDoS Protection).
GET/v1/services/{id}/ddos/attacks/{attack_id}read:ddosDetalhes de um ataque: tráfego e repartições.
GET/v1/billing/balanceread:billingSaldo de crédito.
GET/v1/billing/invoicesread:billingLista das suas faturas (paginada).
GET/v1/billing/invoices/{id}/pdfread:billingPDF da fatura.
GET/v1/webhooksread:webhooksURL atual do webhook.
PUT/v1/webhookswrite:webhooksDefinir ou remover a URL do webhook.

Regras de Advanced DDoS Protection

Estes endpoints exigem um serviço Advanced DDoS Protection pertencente à sua conta. As consultas funcionam com o estado active ou suspended; as alterações exigem o estado active. Ative explicitamente read:ddos para consultas e write:ddos para alterações na chave API. As chaves existentes não recebem novas permissões automaticamente. A gestão de túneis e listas de permissões não está disponível.

Escolha app_code no catálogo de perfis. port tem de ser um inteiro de 1 a 65535; para icmp, omita-o ou envie 0. O objeto opcional extra_ports associa as etiquetas exatas do perfil a portas inteiras; as etiquetas omitidas mantêm os valores predefinidos. Os protocolos são determinados pelo servidor, por isso não envie protocol. Campos ou etiquetas desconhecidos devolvem 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 devolve HTTP 201 com a regra criada em data. GET devolve as regras e meta com service_id, protection_ip e max_rules. DELETE utiliza um corpo vazio e devolve HTTP 200 como no exemplo abaixo. POST e DELETE exigem 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}}

O painel e a API partilham intervalos UTC fixos: 10 tentativas de escrita por minuto e por conta, 5 por minuto e por IP protegido, e 200 por dia UTC e por conta. Contam as tentativas admitidas que sejam inválidas ou falhem; as repetições idempotentes bem-sucedidas não contam. As consultas DDoS da API partilham 30 pedidos por minuto e por conta. Máximo: 1000 regras por IP protegido.

HTTP 404: serviço desconhecido ou de outra conta, ou regra de outra conta, inexistente ou de sistema. HTTP 409: o serviço não é Advanced DDoS Protection (not_supported_for_product), serviço inativo, conflito de portas ou alteração simultânea. HTTP 429: limite atingido, respeite Retry-After. HTTP 502: o serviço de proteção não conseguiu concluir o pedido. A regra de sistema block está oculta e não pode ser eliminada. HTTP 503: os controlos dos limites estão temporariamente indisponíveis, respeite Retry-After.

Relatórios de ataques DDoS

Estes endpoints exigem um serviço Remote DDoS Protection pertencente à sua conta, com o estado active ou suspended, e a permissão read:ddos, que tem de ser ativada explicitamente. A lista mostra os ataques DDoS detetados no endereço IP protegido do serviço, do mais recente para o mais antigo.

Parâmetros de consulta: from e to como data (YYYY-MM-DD) ou como data e hora ISO 8601 com fuso horário (predefinição: os últimos 30 dias), limit de 1 a 100 (predefinição 25) e offset de 0 a 9999 (predefinição 0). O período nunca recua mais de 90 dias nem para antes de o endereço IP protegido ter sido atribuído a este serviço; meta.from e meta.to mostram o período efetivamente utilizado.

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

Cada ataque contém id (UUID), type (ddos_attack, ou blackhole se o IP de destino foi temporariamente encaminhado para uma rota nula), started_at, ended_at (pode ser null), detected_bps, detected_pps, source_ip_count, target_ip e details_available. detected_bps e detected_pps indicam a taxa no momento da deteção; a filtragem já tinha começado, por isso podem ser inferiores ao pico indicado nos detalhes. paging contém limit, offset, total e truncated (true se o período incluir mais de 500 ataques), meta contém service_id, protected_ip, from, to e retention_days (90). As listas ficam em cache durante 60 segundos.

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

Os detalhes contêm todos os campos da lista e ainda peak_bps, peak_pps, total_bytes, total_packets e interval_seconds. traffic lista o tráfego de ataque recebido por intervalo ({time, bps, pps}) tal como a rede de filtragem o registou, desde cerca de 10 minutos antes até cerca de 10 minutos depois da deteção. As repartições protocols, destination_ports, source_ports, source_countries, source_ips e packet_sizes contêm normalmente as 5 entradas principais: avg_bps e avg_pps são médias sobre a janela de medição, bps_percent e pps_percent são percentagens. protocols contém também bytes e packets, packet_sizes contém range, avg_bps e percent. Os detalhes ficam em cache até 15 minutos.

HTTP 400 validation_failed: valor inválido ou parâmetro de consulta desconhecido. HTTP 404: serviço desconhecido ou de outra conta, ID de ataque desconhecido ou ataque a outro endereço IP. HTTP 409 not_supported_for_product: não é um serviço Remote DDoS Protection (por exemplo, Advanced DDoS Protection ou um servidor). HTTP 409 service_not_active: o serviço não está no estado active nem suspended. HTTP 409 protection_not_ready: a proteção ainda está a ser configurada.

Métricas do servidor

Este endpoint exige um serviço ativo da sua conta e a permissão read:services. Os Edge Unlimited Traffic VPS fornecem dados de CPU, memória e rede de entrada e de saída (bit/s e pacotes/s), bem como o tráfego de saída por dia e desde o início do mês. Os VPS Unlimited Traffic da gama habitual, nas localizações Europa, Alemanha, França, Canadá Oriental, Reino Unido e Polónia, fornecem apenas dados da rede de entrada e de saída em bit/s.

Parâmetro de consulta range: 1h, 6h, 24h, 7d ou 14d (predefinição 1h). O intervalo entre pontos depende do período: nos Edge Unlimited Traffic VPS, cerca de 15 segundos (1h), 20 segundos (6h), 2 minutos (24h), 10 minutos (7d) e 20 minutos (14d); nos VPS Unlimited Traffic da gama habitual, 5 minutos até 24h, 30 minutos com 7d e 2 horas com 14d. step_seconds indica o intervalo da resposta.

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

Os valores são medidos na interface de rede do servidor e mostram, por isso, o tráfego que realmente chegou ao servidor. A memória requer o agente convidado (guest agent) no servidor. Os valores que não puderam ser medidos são null; available lista as métricas com valores medidos e summary indica avg, max e last de cada uma. traffic contém o tráfego de saída em bytes por dia e desde o início do mês (final é true quando o dia está concluído) e é null nos produtos sem contador de tráfego. As respostas ficam em cache de 30 segundos (1h) a 10 minutos (14d); meta.cached indica se a resposta veio da cache.

HTTP 400 validation_failed: outro valor de range ou parâmetro de consulta desconhecido. HTTP 404: serviço desconhecido ou de outra conta. HTTP 409 not_supported_for_product: não há métricas disponíveis para este serviço (outros produtos e localizações). HTTP 409 service_not_active: o serviço não está ativo.

Para as métricas do servidor e os relatórios de ataques aplicam-se os limites de taxa gerais. Além disso, os pedidos de dados que não podem ser respondidos a partir da cache estão limitados a 20 por minuto e por conta no conjunto destes três endpoints; acima disso, recebe HTTP 429 com Retry-After. HTTP 502 monitoring_unavailable ou reports_unavailable: a fonte de dados está temporariamente indisponível, tente mais tarde. HTTP 503 temporarily_unavailable com Retry-After: um pedido paralelo está a preparar os mesmos dados.

Não disponível através da API: relatórios de ataques para Advanced DDoS Protection e para servidores como os Edge Unlimited Traffic VPS; estatísticas de tráfego limpo ou descartado por IP protegido; CPU e memória dos VPS Unlimited Traffic da gama habitual; entrega de webhooks e exportação CSV.

Idempotência

POST /v1/orders e POST /v1/services/{id}/actions exigem um cabeçalho Idempotency-Key (1 a 80 caracteres do conjunto [A-Za-z0-9_.-]). Esta chave fica associada ao método, ao caminho e ao corpo. Se repetir o mesmo pedido com a mesma chave no prazo de uma hora, recebe a resposta guardada; depois desse prazo, obtém 410 com reason replay_stale e deve enviar uma chave nova. A mesma chave com um corpo diferente ou noutro endpoint é rejeitada com 409 idempotency_conflict.

Limites de taxa

Por predefinição: 60 pedidos por minuto (mais um burst de 20) e 5000 por dia por chave, 120 por minuto por conta (somando todas as chaves) e 600 por minuto por IP de origem. Se um limite for excedido, recebe HTTP 429 com o cabeçalho Retry-After. Os cabeçalhos de resposta X-RateLimit-Remaining e X-RateLimit-Reset indicam o estado atual do limite da chave.