Справочник endpoint

KernelHost API

Все endpoint возвращают application/json. Ошибки следуют RFC 7807 (Problem+JSON). Каждый ответ содержит заголовок X-Request-Id для сопоставления с серверным журналом аудита.

MethodPathРазрешениеНазначение
GET/v1/healthpublicПроверка работоспособности без аутентификации.
GET/v1/meanyИнформация о собственном аккаунте и метаданные ключа.
GET/v1/productsread:productsСписок всех публично продаваемых продуктов с ценами.
GET/v1/products/{id}read:productsДетали продукта, включая опции конфигурации.
POST/v1/orderswrite:ordersРазмещение заказа. Idempotency-Key обязателен.
GET/v1/orders/{id}read:ordersСтатус собственного заказа.
GET/v1/servicesread:servicesСписок собственных услуг (с пагинацией).
GET/v1/services/{id}read:servicesДетали собственной услуги.
GET/v1/services/{id}/credentialsread:credentialsУчётные данные услуги (отдельное разрешение, фиксируется в журнале аудита).
POST/v1/services/{id}/actionswrite:servicesДействие с услугой: start, stop, reboot, cancel (по окончании расчётного периода), cancel_revoke.
GET/v1/services/{id}/metricsread:servicesМетрики сервера собственной услуги (CPU, память, сеть).
GET/v1/services/{id}/ddos/profilesread:ddosДоступные профили Advanced DDoS Protection.
GET/v1/services/{id}/ddos/rulesread:ddosТекущие правила назначенного защищённого IP-адреса.
POST/v1/services/{id}/ddos/ruleswrite:ddosДобавить одно правило защиты. Требуется Idempotency-Key.
DELETE/v1/services/{id}/ddos/rules/{rule_id}write:ddosУдалить одно своё правило. Требуется Idempotency-Key.
GET/v1/services/{id}/ddos/attacksread:ddosОбнаруженные атаки на защищённый IP-адрес (Remote DDoS Protection).
GET/v1/services/{id}/ddos/attacks/{attack_id}read:ddosПодробности одной атаки: трафик и разбивки.
GET/v1/billing/balanceread:billingБаланс.
GET/v1/billing/invoicesread:billingСписок ваших счетов (с пагинацией).
GET/v1/billing/invoices/{id}/pdfread:billingPDF счёта.
GET/v1/webhooksread:webhooksТекущий URL вебхука.
PUT/v1/webhookswrite:webhooksУстановить или удалить URL вебхука.

Правила Advanced DDoS Protection

Эти эндпоинты требуют услугу Advanced DDoS Protection, принадлежащую вашему аккаунту. Чтение доступно при статусе active или suspended; изменения требуют статуса active. Явно включите read:ddos для чтения и write:ddos для изменений в API-ключе. Существующие ключи не получают новые права автоматически. Управление туннелями и списками разрешённых адресов недоступно.

Выберите app_code из каталога профилей. port должен быть целым числом от 1 до 65535; для icmp пропустите его или передайте 0. Необязательный объект extra_ports сопоставляет точные названия из профиля с целыми номерами портов; для пропущенных названий действуют значения профиля по умолчанию. Протоколы определяет сервер, поэтому не передавайте protocol. Неизвестные поля или названия возвращают 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 возвращает HTTP 201 с созданным правилом в data. GET возвращает правила и meta с полями service_id, protection_ip и max_rules. DELETE требует пустое тело и возвращает HTTP 200, как показано ниже. И POST, и DELETE требуют 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}}

Панель и API используют общие фиксированные окна UTC: 10 попыток записи в минуту на аккаунт, 5 в минуту на защищённый IP-адрес и 200 в сутки UTC на аккаунт. Допущенные некорректные или неудачные попытки учитываются; успешные идемпотентные повторы не учитываются. Чтение через DDoS API имеет общий лимит 30 запросов в минуту на аккаунт. Максимум 1000 правил на защищённый IP-адрес.

HTTP 404: неизвестная или чужая услуга либо чужое, отсутствующее или системное правило. HTTP 409: это не услуга Advanced DDoS Protection (not_supported_for_product), неактивная услуга, конфликт портов или одновременное изменение. HTTP 429: достигнут лимит, соблюдайте Retry-After. HTTP 502: сервис защиты не смог завершить запрос. Системное правило block скрыто, удалить его нельзя. HTTP 503: проверка лимитов запросов временно недоступна, соблюдайте Retry-After.

Отчёты о DDoS-атаках

Для этих эндпоинтов нужна услуга Remote DDoS Protection вашего аккаунта в статусе active или suspended и право read:ddos, которое необходимо включить явно. Список показывает DDoS-атаки, обнаруженные на защищённом IP-адресе услуги, начиная с самых новых.

Параметры запроса: from и to в виде даты (YYYY-MM-DD) или даты и времени в формате ISO 8601 с часовым поясом (по умолчанию: последние 30 дней), limit от 1 до 100 (по умолчанию 25) и offset от 0 до 9999 (по умолчанию 0). Период никогда не уходит в прошлое дальше чем на 90 дней и не начинается раньше момента, когда защищённый IP-адрес был назначен этой услуге; meta.from и meta.to показывают фактически использованный период.

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

Каждая атака содержит id (UUID), type (ddos_attack или blackhole, если целевой IP-адрес временно блокировался нулевым маршрутом), started_at, ended_at (может быть null), detected_bps, detected_pps, source_ip_count, target_ip и details_available. detected_bps и detected_pps показывают интенсивность в момент обнаружения; фильтрация к тому времени уже работала, поэтому эти значения могут быть ниже пика в подробностях. paging содержит limit, offset, total и truncated (true, если в периоде больше 500 атак), meta содержит service_id, protected_ip, from, to и retention_days (90). Списки кешируются на 60 секунд.

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

Подробности содержат все поля списка, а также peak_bps, peak_pps, total_bytes, total_packets и interval_seconds. traffic перечисляет входящий трафик атаки по интервалам ({time, bps, pps}) так, как его видела сеть фильтрации, примерно с 10 минут до обнаружения и до 10 минут после него. Разбивки protocols, destination_ports, source_ports, source_countries, source_ips и packet_sizes обычно содержат 5 крупнейших записей: avg_bps и avg_pps являются средними значениями за окно измерения, bps_percent и pps_percent показывают доли. protocols дополнительно содержит bytes и packets, packet_sizes содержит range, avg_bps и percent. Подробности кешируются на срок до 15 минут.

HTTP 400 validation_failed: недопустимое значение или неизвестный параметр запроса. HTTP 404: неизвестная или чужая услуга, неизвестный ID атаки или атака на другой IP-адрес. HTTP 409 not_supported_for_product: это не услуга Remote DDoS Protection (например, Advanced DDoS Protection или сервер). HTTP 409 service_not_active: услуга не находится в статусе active или suspended. HTTP 409 protection_not_ready: защита ещё настраивается.

Метрики сервера

Для этого эндпоинта нужна активная услуга вашего аккаунта и право read:services. Edge Unlimited Traffic VPS предоставляют данные о CPU, памяти и входящем и исходящем сетевом трафике (бит/с и пакеты/с), а также об исходящем трафике по дням и с начала месяца. Обычные Unlimited Traffic VPS в Европе, Германии, Франции, восточной Канаде, Великобритании и Польше предоставляют только данные о входящем и исходящем сетевом трафике в бит/с.

Параметр запроса range: 1h, 6h, 24h, 7d или 14d (по умолчанию 1h). Шаг между точками зависит от периода: для Edge Unlimited Traffic VPS около 15 секунд (1h), 20 секунд (6h), 2 минуты (24h), 10 минут (7d) и 20 минут (14d); для обычных Unlimited Traffic VPS 5 минут до 24h, 30 минут для 7d и 2 часа для 14d. step_seconds показывает шаг в ответе.

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

Значения измеряются на сетевом интерфейсе сервера, поэтому показывают трафик, который действительно дошёл до сервера. Для памяти нужен гостевой агент внутри сервера. Значения, которые не удалось измерить, равны null; available перечисляет метрики с измеренными значениями, а summary показывает для каждой из них avg, max и last. Поле traffic содержит исходящий трафик в байтах по дням и с начала месяца (final принимает значение true, когда день завершён) и равно null у продуктов без счётчика трафика. Ответы кешируются от 30 секунд (1h) до 10 минут (14d); meta.cached показывает, получен ли ответ из кеша.

HTTP 400 validation_failed: другое значение range или неизвестный параметр запроса. HTTP 404: неизвестная или чужая услуга. HTTP 409 not_supported_for_product: для этой услуги метрики недоступны (другие продукты и локации). HTTP 409 service_not_active: услуга не активна.

Для метрик сервера и отчётов об атаках действуют общие ограничения частоты запросов. Кроме того, запросы данных, на которые нельзя ответить из кеша, ограничены 20 в минуту на аккаунт суммарно для этих трёх эндпоинтов; при превышении вы получите HTTP 429 с Retry-After. HTTP 502 monitoring_unavailable или reports_unavailable: источник данных временно недоступен, повторите попытку позже. HTTP 503 temporarily_unavailable с Retry-After: параллельный запрос уже готовит те же данные.

Через API недоступны: отчёты об атаках для Advanced DDoS Protection и для серверов, например Edge Unlimited Traffic VPS; статистика чистого или отброшенного трафика по защищённому IP-адресу; CPU и память у обычных Unlimited Traffic VPS; доставка вебхуков и экспорт в CSV.

Идемпотентность

POST /v1/orders и POST /v1/services/{id}/actions требуют заголовок Idempotency-Key (от 1 до 80 символов из набора [A-Za-z0-9_.-]). Ключ привязан к методу, пути и телу запроса. Если повторить тот же запрос с тем же ключом в течение часа, вернётся сохранённый ответ; позже вы получите 410 с reason replay_stale, и тогда нужно отправить новый ключ. Тот же ключ с другим телом запроса или на другом endpoint отклоняется с 409 idempotency_conflict.

Ограничения частоты

По умолчанию действуют лимиты: 60 запросов в минуту (плюс burst в 20 запросов) и 5 000 в сутки на ключ, 120 в минуту на аккаунт по всем ключам и 600 в минуту на исходный IP-адрес. При превышении лимита вы получите HTTP 429 с заголовком Retry-After. Заголовки ответа X-RateLimit-Remaining и X-RateLimit-Reset показывают текущее состояние лимита ключа.