Справочник REST API: создание VPS через API

00 · Соглашения

Соглашения

Один и тот же набор правил действует для каждого эндпоинта в этом документе. Прочитайте этот раздел один раз, а затем переходите к нужному ресурсу.

Аутентификация

Каждый запрос должен содержать Bearer-токен в заголовке Authorization:

Authorization: Bearer nkv_live_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0u1v2

Доступны три области доступа (scope), каждая строго шире предыдущей:

read — доступ только на чтение ко всем ресурсам, кроме биллинга.
write — чтение, а также создание, изменение и удаление. Нельзя создавать адреса для пополнения.
billing — всё, что может write, плюс эндпоинты биллинга.

Токены создаются в разделе Аккаунт → API-токены. Открытый текст показывается один раз при создании — мы храним только его SHA-256-хеш. Допустимое расхождение часов для любых проверок по времени — 30 секунд.

JSON и типы

Тело запроса должно быть в формате application/json. Мы не принимаем multipart/form-data, кроме POST /images.
Ключи записываются в snake_case. Неизвестные ключи в запросах отклоняются с кодом 400; неизвестные ключи в ответах ваш клиент может спокойно игнорировать.
Метки времени — в формате RFC 3339, в UTC, например 2026-05-12T08:47:12Z.
Денежные суммы передаются как JSON-число в USD с двумя знаками после запятой. Суммы в криптовалюте передаются десятичной строкой, чтобы сохранить точность.
Идентификаторы ресурсов — короткие непрозрачные строки с типизирующим префиксом. Не разбирайте их.

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

Каждый эндпоинт POST принимает необязательный заголовок Idempotency-Key. Стандартный выбор — UUIDv4. Первый ответ для данного ключа кешируется на 24 часа; последующие запросы с тем же ключом получают тот же закешированный ответ. Запрос с тем же ключом, но с другим телом возвращает 409 conflict_state.

curl -X POST .../v1/servers \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Authorization: Bearer $NOKYC_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{...}'

Пагинация

Списочные эндпоинты возвращают до 25 элементов по умолчанию, максимум 100. Пагинация курсорная, без offset. Если элементов больше, в ответе будут has_more: true и next_cursor. Передайте его как ?cursor=..., чтобы получить следующую страницу.

jsonструктура ответа со списком

{
  "object":      "list",
  "data":        [ /* up to page_size items */ ],
  "has_more":    true,
  "next_cursor": "c_8a1f2c34"
}

Параметр page_size переопределяет значение по умолчанию. filter[field]=value — фильтры по равенству (где поддерживаются). sort=-created_at — сортировка по убыванию.

Ошибки

Ошибки всегда возвращаются в JSON в одной и той же обёртке:

jsonобёртка ошибки

{
  "error": {
    "code":       "invalid_request",
    "message":    "ssh_keys must contain at least one valid key id.",
    "errors": [
      { "field": "ssh_keys", "issue": "min_items", "min": 1 }
    ],
    "request_id": "req_2f8b1c4e9d"
  }
}

Всегда логируйте request_id в своём клиенте — это единственное, по чему мы можем найти ваш вызов в наших логах, если вы попросите нас посмотреть конкретный вызов. (Мы смотрим только те строки, для которых вы назвали request_id; клиентские логи мы не просматриваем.)

HTTP-статусы и соответствующие им смысловые коды:

HTTP	Код	Значение
400	invalid_request	Тело запроса или параметры запроса не прошли валидацию. См. `errors[]`.
401	unauthenticated	Bearer-токен отсутствует, имеет неверный формат или истёк.
403	forbidden_scope	У токена нет нужной области доступа (scope).
404	not_found	Ресурс не существует или недоступен для вашего аккаунта.
409	conflict_state	Ресурс находится в состоянии, при котором эта операция недопустима (например, подключение уже подключённого тома).
422	unprocessable	Тело запроса разобрано, но семантическая проверка не пройдена (например, регион недоступен для выбранного тарифа).
429	rate_limited	Корзина токенов (token bucket) исчерпана. Заголовок `Retry-After` — в секундах.
451	jurisdictional_block	Эндпоинт отклонён по юридическим причинам. Это отразится в canary.
500	internal	Ошибка на стороне сервера. Повторяйте только идемпотентные операции.
503	maintenance	Эндпоинт временно недоступен в объявленное окно технического обслуживания.

Лимиты запросов

60 запросов в минуту на токен со всплеском до 10 запросов. Корзина пополняется со скоростью 1 запрос/с. Эндпоинты развёртывания (POST /servers, POST /images) используют отдельную корзину на 200 запросов в минуту, потому что нагрузка на них по природе пиковая.

X-RateLimit-Limit:     60
X-RateLimit-Remaining: 57
X-RateLimit-Reset:     1747049892
Retry-After:           23           # only on 429

Версионирование

Версия API указывается в пути: /v1/.... Мы обязуемся:

Никаких обратно несовместимых изменений в пределах мажорной версии.
Допускаются дополняющие изменения (новые поля, новые эндпоинты) в текущей версии — о них сообщается в истории изменений.
Перед удалением любого эндпоинта или поля в следующей мажорной версии действует период депрекации — 12 месяцев.
Бета-эндпоинты доступны только при заголовке X-Nokyc-Beta: true и могут ломаться без предупреждения.

Ресурсы

Каждый ресурс ниже описан тремя частями: схема объекта, эндпоинты, которые с ним работают, и один или несколько примеров запросов с реальными телами ответов.

01 · ядро

Серверы

server — это одна виртуальная машина в нашем пуле гипервизоров или один физический узел в линейке выделенных серверов. Любой другой ресурс на этой странице либо описывает сервер, либо привязывается к нему, либо порождает связанные с ним события.

Объект

Поле	Тип	Описание
id ro	string	Уникальный идентификатор. Префикс `srv_`.
object ro	string	Всегда `"server"`.
name	string · 1–63	Имя, заданное клиентом. `[a-z0-9-]`, должно начинаться с буквы.
status ro	enum	`provisioning`, `installing`, `running`, `stopped`, `suspended`, `destroying`.
plan	string	Идентификатор тарифа (см. Тарифы). Не меняется после развёртывания.
region	string	Код региона (см. Регионы). Не меняется.
image	string	Идентификатор образа на момент установки. Обновляется при пересборке сервера.
ipv4 ro	object · nullable	`{address, gateway, rdns}`. Равно null, пока сервер не перейдёт в состояние `running`.
ipv6 ro	object · nullable	`{address, prefix, rdns}`. Всегда маршрутизируемая подсеть /64.
ssh_keys	array<string>	Идентификаторы SSH-ключей, внедряемых при установке.
user_data_b64	string · write-only	user-data для cloud-init в кодировке Base64. До 64 KiB.
tags	array<string>	Произвольные теги. Удобны для фильтрации.
labels	object<string,string>	До 32 пар «ключ/значение». Ключи должны соответствовать `[a-z0-9_-]{1,63}`.
created_at ro	string · RFC 3339	Метка времени в UTC.
updated_at ro	string · RFC 3339	Метка времени в UTC. Обновляется при любом изменении.

Эндпоинты

GET /servers Список ваших серверов.
POST /servers Создать новый сервер.
GET /servers/{id} Получить один сервер.
PATCH /servers/{id} Изменить name, tags или labels.
DELETE /servers/{id} Уничтожить сервер. Необратимо.
POST /servers/{id}/reboot Перезагрузить. Добавьте ?hard=true, чтобы пропустить ACPI.
POST /servers/{id}/rebuild Переустановить ОС из образа. Данные на диске уничтожаются.
POST /servers/{id}/rescue Загрузиться с rescue-ISO.
POST /servers/{id}/stop Плавная остановка (выключение через ACPI).
POST /servers/{id}/start Запустить остановленный сервер.
GET /servers/{id}/console Одноразовый подписанный URL для noVNC (действует 5 минут).
GET /servers/{id}/metrics Сводка за 30 дней по CPU / RAM / диску / трафику.
POST /servers/{id}/rdns Задать обратную DNS-запись (rDNS) для IPv4 и/или IPv6.

02 · ресурсы

Образы

image — это шаблон диска, с которого загружается сервер. Официальные образы поддерживаем мы; пользовательские образы — это ISO, которые вы загрузили.

Объект

Поле	Тип	Описание
id ro	string	Префикс `img_` (официальный) или `custom_` (пользовательская загрузка).
object ro	string	Всегда `"image"`.
type ro	enum	`official` или `custom`.
family ro	string	`debian`, `ubuntu`, `alpine` и т. д. Для загруженных образов — `custom`.
version ro	string	Версия дистрибутива (например, `13`, `24.04`, `rolling`).
variant ro	string · nullable	Вариант образа: `minimal`, `cloud` и т. д.
arch ro	array<string>	Поддерживаемые архитектуры: `amd64`, `arm64`.
size_gb ro	number	Размер на диске, GiB. Помогает оценить время развёртывания.
cloud_init ro	boolean	Входит ли в образ cloud-init.
released_at ro	string · ISO 8601	Дата публикации этой версии.
deprecated_at ro	string · ISO 8601 · nullable	Если задано, образ доступен только для чтения и будет удалён через 90 дней после этой даты.

Эндпоинты

GET /images Список образов (фильтры: family, arch, type).
GET /images/{id} Получить один образ.
POST /images Загрузить собственный ISO. multipart/form-data, максимум 4 GiB.
DELETE /images/{id} Удалить пользовательский образ (для официальных образов ничего не делает).

02 · ресурсы

Тарифы

plan описывает одну доступную для заказа аппаратную конфигурацию. Цены указаны справочно, в USD; каждый сервер оплачивается заранее с вашего баланса при развёртывании — на цикл в 1, 3, 6 или 12 месяцев (скидка 0 %, 25 %, 35 % и 50 % соответственно). Сумма пополнения в криптовалюте рассчитывается по спотовому курсу на момент выставления счёта.

Объект

Поле	Тип	Описание
id ro	string	Код тарифа. Не меняется при изменении цен.
object ro	string	Всегда `"plan"`.
category ro	enum	`vps` или `dedicated`.
cpu ro	integer	Число vCPU (для VPS) или физических ядер (для выделенных серверов).
cpu_model ro	string	Модель процессора без маркетинговых названий, например `"AMD EPYC 7763 (Milan)"`.
ram_mb ro	integer	Объём RAM в MiB.
disk_gb ro	integer	Объём NVMe-диска в GiB.
transfer_tb ro	number	Исходящий трафик в месяц, TiB. Входящий — безлимитный.
price_usd_month ro	number	Справочная месячная цена в USD.
price_usd_hour ro	number	Справочная цена в пересчёте на час — только для сравнения. Серверы оплачиваются заранее за цикл, а не почасово.
available_in ro	array<string>	Коды регионов, в которых этот тариф сейчас можно развернуть.

Эндпоинты

GET /plans Список тарифов.
GET /plans/{id} Получить тариф.

02 · ресурсы

Регионы

region — это одна из наших четырёх точек присутствия (PoP). Каждая управляется отдельным юридическим лицом и маршрутизируется независимо.

Объект

Поле	Тип	Описание
id ro	string	Трёхбуквенный код: `par`, `rkv`, `zrh`, `buh`.
object ro	string	Всегда `"region"`.
name ro	string	Читаемое название (Paris, Reykjavík, Zürich, Bucharest).
country ro	string	Код страны по стандарту ISO 3166-1 alpha-2.
pop_id ro	string	Внутреннее обозначение PoP (например, `nky-par-01`).
available ro	boolean	`true`, если сейчас можно развернуть хотя бы один тариф.
ipv4_pool_remaining ro	integer	Сколько IPv4-адресов осталось в региональном пуле. Если меньше 50, развёртывание может застопориться.
tor_onion ro	string · nullable	Onion-эндпоинт региона, если есть.

Эндпоинты

GET /regions Список регионов.
GET /regions/{id} Получить регион.

02 · ресурсы

SSH-ключи

Публичные ключи, которые при установке добавляются в authorized_keys сервера. Приватная часть никогда не покидает ваш компьютер и никогда не попадает к нам.

Объект

Поле	Тип	Описание
id ro	string	Префикс `k_`.
object ro	string	Всегда `"ssh_key"`.
name	string · 1–63	Отображаемое имя — для вашего удобства.
type ro	enum	`ssh-ed25519` · `ssh-rsa` · `ecdsa-sha2-nistp{256,384,521}`.
fingerprint ro	string	SHA-256 в кодировке base64. Формат: `SHA256:<digest>`.
public_key	string	Публичный ключ в формате OpenSSH (в ответах со списком опускается ради экономии размера).
created_at ro	string · RFC 3339

Эндпоинты

GET /ssh-keys Список SSH-ключей.
POST /ssh-keys Добавить новый SSH-ключ.
GET /ssh-keys/{id} Получить ключ.
DELETE /ssh-keys/{id} Удалить ключ. Уже развёрнутые серверы это не затрагивает.

02 · ресурсы

API-токены

Долгоживущие секреты для аутентификации в этом API. Токен в открытом виде возвращается один раз при создании; на стороне сервера хранится только его SHA-256-хеш.

Объект

Поле	Тип	Описание
id ro	string	Префикс `tok_`.
object ro	string	Всегда `"api_token"`.
name	string	Для вашего собственного учёта.
scope	enum	`read`, `write` или `billing`.
token	string · write-only	Токен в открытом виде. Возвращается один раз, в ответе на POST. Формат: `nkv_live_<52 chars>`.
last_used_at ro	string · RFC 3339 · nullable	Обновляется не чаще раза в минуту, чтобы ограничить усиление записи.
expires_at	string · RFC 3339 · nullable	Необязательно. Если задано, токен перестаёт работать в этот момент.
created_at ro	string · RFC 3339

Эндпоинты

GET /account/tokens Список токенов.
POST /account/tokens Создать токен (в открытом виде возвращается один раз).
DELETE /account/tokens/{id} Немедленно отозвать токен.

03 · финансы

Биллинг

Преимущественно эндпоинты для чтения: они описывают ваш текущий баланс, историю транзакций и процесс пополнения.

Объект `balance`

Поле	Тип	Описание
object ro	string	Всегда `"balance"`.
usd ro	number	Справочный баланс в USD, два знака после запятой.
as_of ro	string · RFC 3339	Время фиксации данных.
runway_until ro	string · date · nullable	Календарная дата, до которой оплачены все ваши работающие серверы (ближайшее окончание цикла). `null`, если работающих серверов нет.
active_servers ro	integer	Серверы, которые сейчас работают на оплаченном цикле.
daily_cost_usd ro	number	Справочная стоимость всех работающих серверов в пересчёте на день — только для сравнения. Ежедневных списаний нет.
low_balance_at ro	string · RFC 3339 · nullable	Когда мы отправим письмо с предупреждением о низком балансе (сейчас — за 7 дней до runway).

Эндпоинты

GET /billing/balance Текущий баланс и runway.
GET /billing/ledger История транзакций с пагинацией (списания, пополнения, зачисления).
POST /billing/topup Сгенерировать одноразовый адрес для пополнения в выбранной монете.
GET /billing/topup/{id} Проверить статус заявки на пополнение (pending / confirming / credited / expired).

04 · хранилище

Тома

Постоянное блочное хранилище, которое можно подключить к серверу в том же регионе. Тома переживают уничтожение сервера.

Объект

Поле	Тип	Описание
id ro	string	Префикс `vol_`.
object ro	string	Всегда `"volume"`.
name	string	Отображаемое имя.
size_gb	integer · 10–4096	Размер в GiB. Можно увеличить без остановки (уменьшить нельзя).
region	string	Код региона. Должен совпадать с регионом подключённого сервера.
attached_to ro	string · nullable	Идентификатор сервера или `null`, если том отключён.
device ro	string · nullable	Путь к блочному устройству Linux при подключении (`/dev/vdb`, …).
encrypted	boolean	LUKS на уровне тома; ключ хранится у клиента и передаётся через cloud-init.
filesystem	string · nullable	Для вашего учёта. Мы не форматируем тома.
created_at ro	string · RFC 3339

Эндпоинты

GET /volumes Список томов.
POST /volumes Создать том.
GET /volumes/{id} Получить.
PATCH /volumes/{id} Изменить размер (только увеличение size_gb) или переименовать.
DELETE /volumes/{id} Уничтожить. Сначала том нужно отключить.
POST /volumes/{id}/attach Подключить к серверу (тело запроса: {"server":"srv_…"}).
POST /volumes/{id}/detach Отключить.

04 · хранилище

Снапшоты

Снимок состояния корневого диска сервера на определённый момент времени. Снапшоты дедуплицируются и хранятся в зашифрованном виде. Экспортировать их нельзя — они нужны, чтобы вы могли пересобрать сервер из заведомо рабочего состояния.

Объект

Поле	Тип	Описание
id ro	string	Префикс `snap_`.
object ro	string	Всегда `"snapshot"`.
server ro	string	Идентификатор сервера, с которого сделан снапшот. Фиксируется при создании.
name	string	Отображаемое имя.
size_gb ro	number	Размер после дедупликации — именно столько хранилища вы оплачиваете.
status ro	enum	`creating` · `ready` · `error`.
expires_at	string · RFC 3339 · nullable	Необязательная дата автоудаления.
created_at ro	string · RFC 3339

Эндпоинты

GET /snapshots Список снапшотов.
POST /servers/{id}/snapshots Сделать снапшот сервера.
GET /snapshots/{id} Получить.
POST /servers/{id}/restore Восстановить сервер из снапшота (пересборка из snap_…).
DELETE /snapshots/{id} Удалить снапшот.

05 · сеть

Группы файрвола

Пакетный фильтр с отслеживанием состояния соединений, по умолчанию отбрасывающий трафик и работающий на уровне гипервизора — вне гостевой системы. Группа — это именованный набор правил; каждое правило разрешает входящий или исходящий трафик, соответствующий 5-tuple (пятёрке параметров соединения).

Объект

Поле	Тип	Описание
id ro	string	Префикс `fwg_`.
object ro	string	Всегда `"firewall_group"`.
name	string	Отображаемое имя.
applied_to	array<string>	Идентификаторы серверов, к которым применяется эта группа.
rules	array<rule>	См. объект правила ниже. Порядок важен: срабатывает первое совпавшее правило.
default_action	enum	`drop` (рекомендуется) или `accept`.
created_at ro	string · RFC 3339

Объект правила

Поле	Тип	Описание
id ro	string	Префикс `fwr_`. Назначается на стороне сервера.
direction	enum	`in` или `out`.
proto	enum	`tcp` · `udp` · `icmp` · `any`.
port	string · nullable	Один порт (`"22"`), список через запятую (`"80,443"`) или диапазон (`"5000-5100"`). Для протоколов без портов — null.
source	string	CIDR. Допускаются `0.0.0.0/0` и `::/0`.
action	enum	`accept`, `drop` или `reject` (отправляет RST/ICMP-unreach).
note	string · nullable	Необязательный комментарий.

Эндпоинты

GET /firewall/groups Список групп файрвола.
POST /firewall/groups Создать группу.
GET /firewall/groups/{id} Получить.
PATCH /firewall/groups/{id} Изменить name, default_action, applied_to.
DELETE /firewall/groups/{id} Удалить группу (она не должна быть применена).
POST /firewall/groups/{id}/rules Добавить правило в конец списка.
PUT /firewall/groups/{id}/rules Заменить список правил (атомарно).
DELETE /firewall/groups/{id}/rules/{rule_id} Удалить одно правило.

06 · автоматизация

Подписки на вебхуки

Подпишите URL на события вашего аккаунта. Каждый раз, когда происходит что-то важное, мы отправляем на ваш эндпоинт POST с JSON-событием; запрос подписан HMAC-SHA256, и подпись можно проверить.

Объект

Поле	Тип	Описание
id ro	string	Префикс `whk_`.
object ro	string	Всегда `"webhook"`.
url	string · HTTPS only	Эндпоинт, на который мы отправляем POST. Требуется HTTPS с действительным сертификатом.
events	array<string>	События, на которые оформлена подписка. `["*"]` — подписка на все.
active	boolean	Если `false`, доставка приостановлена.
secret_hint ro	string	Последние 4 символа секрета подписи (`whsec_…`) — для справки. Полный секрет возвращается один раз при создании.
created_at ro	string · RFC 3339

Эндпоинты

GET /webhooks Список подписок.
POST /webhooks Создать. В ответ включён secret (в открытом виде, один раз).
GET /webhooks/{id} Получить.
PATCH /webhooks/{id} Изменить url, events, active.
DELETE /webhooks/{id} Отписаться.
POST /webhooks/{id}/test Отправить синтетическое событие ping.
GET /webhooks/{id}/deliveries Попытки доставки за последние 7 дней.

07 · наблюдаемость

Журнал аудита

Каждый аутентифицированный запрос к вашему аккаунту, изменяющий состояние, с указанием того, кто его выполнил. Хранится 90 дней.

Объект

Поле	Тип	Описание
id ro	string	Префикс `audit_`.
object ro	string	Всегда `"audit_event"`.
action ro	string	Имя операции через точку (например, `server.create`).
resource ro	string · nullable	Идентификатор затронутого ресурса.
actor_token ro	string · nullable	Идентификатор использованного токена (если вызов через API).
actor_session ro	string · nullable	Идентификатор сессии (если действие выполнено из панели управления).
request_id ro	string	Идентификатор корреляции (совпадает с заголовком `X-Request-Id` в исходном ответе).
ip_country ro	string	Код страны ISO-3166 на момент проверки. IP-адрес не сохраняется.
result ro	enum	`ok` · `error` · `denied`.
created_at ro	string · RFC 3339

Эндпоинты

GET /audit/events Список событий аудита. Фильтры: action, resource, from, to.
GET /audit/events/{id} Получить одно событие.

Пример · создание сервера

Развёртывание от начала до конца в одной сессии оболочки

Минимальный рабочий путь от «у меня есть аккаунт» до «у меня есть работающий сервер»:

Запрос

curlPOST /v1/servers

curl https://api.cryptovpshost.com/v1/servers \
  -H "Authorization: Bearer $NOKYC_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "name":     "edge-paris",
    "plan":     "vps-s2",
    "region":   "par",
    "image":    "debian-13-minimal",
    "ssh_keys": ["k_5f3a8c91"],
    "tags":     ["production","edge"],
    "labels":   { "owner":"ops" },
    "user_data_b64": null
  }'

Ответ — `201 Created`

jsonобъект сервера

{
  "id":         "srv_8a1f2c34",
  "object":     "server",
  "name":       "edge-paris",
  "status":     "provisioning",
  "plan":       "vps-s2",
  "region":     "par",
  "image":      "debian-13-minimal",
  "ipv4":       null,
  "ipv6":       null,
  "ssh_keys":   ["k_5f3a8c91"],
  "tags":       ["production","edge"],
  "labels":     { "owner":"ops" },
  "created_at": "2026-05-12T08:47:12Z",
  "updated_at": "2026-05-12T08:47:12Z"
}

Через два события вебхука (обычно за 60–120 с):

jsonвебхук server.running

{
  "id":         "evt_3c8a1f4b",
  "object":     "event",
  "type":       "server.running",
  "created_at": "2026-05-12T08:48:34Z",
  "data": {
    "server": {
      "id":     "srv_8a1f2c34",
      "status": "running",
      "ipv4":   { "address":"198.51.100.42", "gateway":"198.51.100.1", "rdns":null },
      "ipv6":   { "address":"2001:db8::1",   "prefix":"2001:db8::/64", "rdns":null }
    }
  }
}

Теперь можно подключиться: ssh [email protected].

08 · События вебхуков

Каталог событий

Каждое событие относится к одному из типов ниже. Блок data содержит полный объект в том виде, в каком он существовал в момент события — повторно запрашивать его не нужно, если только вам не требуется гарантированно свежее состояние.

Событие	Когда срабатывает
server.created	Новый сервер начал развёртываться.
server.running	Сервер завершил установку и доступен.
server.stopped	Сервер штатно выключен.
server.rebooted	Сервер завершил перезагрузку.
server.rebuilt	Сервер завершил пересборку из образа.
server.suspended	Оплаченный цикл закончился, а баланса не хватило на следующий; сервер остановлен.
server.destroyed	Диск сервера стёрт, IP-адреса освобождены.
snapshot.ready	Снапшот перешёл из состояния `creating` в `ready`.
volume.attached	Том успешно подключён.
volume.detached	Том отключён.
topup.pending	Депозит обнаружен в сети; ожидаем подтверждений.
topup.confirmed	Депозит подтверждён; баланс пополнен.
topup.expired	Фиксация курса истекла до подтверждения.
billing.charged	Оплата цикла списана с вашего баланса. Включает сумму и итоговый баланс.
billing.low_balance	Оплаченный цикл закончится в течение 7 дней, а баланса не хватает на следующий.
token.created	Создан новый API-токен.
token.revoked	API-токен отозван.
firewall.applied	Группа файрвола привязана к серверу.

09 · Подпись вебхуков

Проверка подлинности вебхуков

Каждая доставка содержит заголовок X-Nokyc-Signature. Вы сравниваете его с HMAC-SHA256 от тела запроса, вычисленным на секрете, который вы получили при создании подписки.

Формат заголовков

X-Nokyc-Signature:   t=1747049892,v1=4f8c1a...e9d
X-Nokyc-Delivery-Id: del_7c3a1f9b
Content-Type:        application/json

t — Unix-время создания подписи.
v1 — HMAC-SHA256 от "{t}.{raw_body}" в виде hex строчными буквами.
Отклоняйте любую доставку, где t расходится с вашими часами более чем на 5 минут.

Проверка — Python

pythonverify_signature.py

import hmac, hashlib, time

def verify(raw_body: bytes, header: str, secret: str, tolerance: int = 300) -> bool:
    parts = dict(p.split("=", 1) for p in header.split(","))
    t  = int(parts["t"])
    v1 = parts["v1"]
    if abs(time.time() - t) > tolerance:
        return False
    payload = f"{t}.".encode() + raw_body
    expected = hmac.new(secret.encode(), payload, hashlib.sha256).hexdigest()
    return hmac.compare_digest(v1, expected)

Политика повторных попыток

Каждая доставка предпринимается не более 6 раз со следующими интервалами отката:

attempt 1:  immediate
attempt 2:  + 1   minute
attempt 3:  + 5   minutes
attempt 4:  + 30  minutes
attempt 5:  + 5   hours
attempt 6:  + 24  hours
              => give up

Доставка считается успешной, если ваш эндпоинт возвращает HTTP 2xx в течение 10 секунд. Ответ 410 Gone немедленно прекращает все последующие попытки и приостанавливает подписку. Неудачные доставки видны через GET /webhooks/{id}/deliveries.

10 · История изменений

История изменений

Дополняющие изменения в рамках v1. Следующая мажорная версия (v2) пока не запланирована.

v1.4 2026-04-22
- Добавлен эндпоинт /servers/{id}/metrics (сводка за 30 дней).
- В объект баланса добавлены поля runway_until и low_balance_at.
- Вебхуки теперь содержат X-Nokyc-Delivery-Id для безопасной обработки повторных доставок.
v1.3 2026-01-10
- Добавлен ресурс «Тома» (блочное хранилище с подключением и отключением).
- Группы файрвола получили default_action, а правила — note.
- Число labels у сервера ограничено 32 парами (было 16).
v1.2 2025-09-15
- Добавлены ресурс «Снапшоты» и /servers/{id}/restore.
- В регионы добавлено поле ipv4_pool_remaining.
v1.1 2025-06-04
- Списочные эндпоинты переведены на курсорную пагинацию. offset/limit объявлены устаревшими и будут удалены в v2.
- Добавлена поддержка Idempotency-Key для каждого POST.
- Добавлен ресурс «Журнал аудита».
v1.0 2024-09-12
- Первый стабильный релиз.
- Серверы, образы, тарифы, регионы, SSH-ключи, API-токены, финансы, вебхуки.

Один API. Одна страница. Никакой привязки к SDK.

Аутентификация

JSON и типы

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

Пагинация

Ошибки

Лимиты запросов

Версионирование

Объект

Эндпоинты

Объект

Эндпоинты

Объект

Эндпоинты

Объект

Эндпоинты

Объект

Эндпоинты

Объект

Эндпоинты

Объект balance

Эндпоинты

Объект

Эндпоинты

Объект

Эндпоинты

Объект

Объект правила

Эндпоинты

Объект

Эндпоинты

Объект

Эндпоинты

Запрос

Ответ — 201 Created

Формат заголовков

Проверка — Python

Политика повторных попыток

Объект `balance`

Ответ — `201 Created`