Справочник API
Используйте операции API и интерпретируйте их результаты
Прочитайте доступные конечные точки, правила идемпотентности, ответы на отложенные действия и текущие ограничения на отслеживание операций.
На этой странице
Перед началом
- Действительная сессия и, для защищённых изменений, её CSRF-токен.
- Идентификаторы, взятые из текущего каталога или аутентифицированных ответов API.
- Уникальный ключ идемпотентности для каждого заказа, вывода средств или действия с оборудованием.
Прочитайте аккаунт перед его изменением
Используйте конечные точки чтения, чтобы подтвердить аккаунт, баланс и целевой ресурс. GET /api/v1/me возвращает username, balanceUsd и csrfToken сессии. Идентификаторы ресурсов привязаны к аккаунту; используйте идентификатор сервера или сети, возвращённый для текущего аккаунта, а не копируйте значение из другой среды.
Текущий API — это компактный интерфейс учетной записи, а не полноценная платформа асинхронных заданий. Сохраняйте ссылки на успешные записи в своих записях. Нет конечной точки для перечисления всех заказов, проверки конкретного действия в очереди или получения последнего статуса проверки вывода средств.
| Конечная точка чтения | Возвращённые данные |
|---|---|
| GET /api/v1/ledger | Последние записи реестра 100, сначала новые; без контракта на пагинацию. |
| GET /api/v1/servers | Непрекращённые серверы, состояние, регион, paidThrough, graceUntil и autoRenew. |
| GET /api/v1/network | Назначенные адреса, длины префиксов, значения PTR и связанные идентификаторы серверов. |
| GET /api/health | Базовый сервис и количество позиций в каталоге; без гарантии состояния аккаунта или физического сервера. |
Используйте соответствующий endpoint для изменения
Поддерживаемые действия с сервером: reboot, power_off, reinstall, mount_iso, kvm и rotate_root_password. Пользовательский URL ISO должен использовать публичный HTTPS без встроенных учётных данных. Срок заказа — еженедельный или ежемесячный, что означает семь или тридцать дней. Цена, скидки, средства и ёмкость проверяются сервисом; не отправляйте цену, вычисленную клиентом, как авторитетную.
| Конечная точка | Поля запроса и результат |
|---|---|
| POST /api/v1/orders | configId, regionId, osId, срок, количество; необязательно sshPublicKey. Возвращает идентификатор заказа и ACCEPTED. |
| POST /api/v1/deposit-addresses | актив. Возвращает адрес, актив, сеть, требуемое количество подтверждений и режим, либо ошибку о недоступности расчёта. |
| POST /api/v1/withdrawals | актив, назначение, usd. Возвращает id и PENDING_REVIEW; баланс удерживается. |
| POST /api/v1/servers/{id}/actions | действие; isoUrl для mount_iso. Возвращает идентификатор действия и QUEUED. |
| PUT /api/v1/servers/{id}/ddos | режим: BASELINE или ADVANCED. Возвращает QUEUED или UNCHANGED и quoteRequired. |
| PUT /api/v1/network/{id}/rdns | ptr или пустое значение для очистки. Возвращает сохранённое значение PTR. |
Делайте повторные попытки осознанно
Заказы, вывод средств, действия с сервером и запросы DDoS требуют Idempotency-Key. Используйте 8–100 буквы, цифры, дефисы или подчеркивания и выделяйте новый ключ для каждой отдельной предполагаемой операции. Сохраните исходный ключ, ресурс и полезную нагрузку перед отправкой, чтобы можно было исследовать неопределенный ответ.
Заказы могут воспроизвести существующий результат для того же ключа и нормализованного запроса; измененные детали заказа приводят к конфликту. Повторные действия сервера возвращают существующее действие, если оно совместимо. Держите ключи действий уникальными для всех серверов в учетной записи. Вывод средств сообщает о конфликте, если уже записан, а не возвращает исходный запрос как успешный.
POST /api/v1/servers/{serverId}/actions HTTP/1.1
Content-Type: application/json
x-csrf-token: <current-session-token>
Idempotency-Key: <unique-operation-key>
Cookie: <current-session-cookies>
{"action":"reboot"}Отличайте приёмку от завершения
Ответ QUEUED от 202 подтверждает, что запрос на оборудование был записан. Он не содержит рабочего URL KVM, нового root-пароля или доказательства перезагрузки машины. Аналогично, ACCEPTED фиксирует заказ, поступивший в подготовку; PENDING_REVIEW фиксирует вывод средств, ожидающий проверки оператором. Сохраните возвращённый идентификатор при запросе о выполнении.
В этой версии нет маршрута опроса статуса действия. Перечитайте данные сервера или сети, где это уместно, и получите подтверждение оператора о физических эффектах. Сохранённый PTR или предпочтение DDoS само по себе не является измерением публичного DNS или действующей защиты сети.
Реагируйте на сбои без дублирования работы
- Ошибка валидации 400: исправьте задокументированные поля перед повторной отправкой.
- 401 или 403: исправьте аутентификацию сеанса или проверку CSRF перед повторной попыткой.
- 404: убедитесь, что идентификатор ресурса принадлежит аккаунту, в который выполнен вход.
- 409: проверьте код ошибки; недостаточный баланс, исчерпанная ёмкость и конфликты идемпотентности требуют разных ответов.
- 502 или 503 по депозитам: не возвращен пригодный новый адрес; не инициируйте перевод.
- Тайм-аут или нечитаемый ответ: проверьте доступные записи аккаунта и сохраните исходные детали запроса. Не создавайте вслепую новый операционный ключ.