API для VPS

Через API можно заказывать VPS, управлять ими и продлевать их из своего кода: панели реселлера, бота, скрипта. Ещё API показывает баланс и историю операций. Домены, DNS и правила защиты через API не управляются — только в панели. Для доступа нужен токен.

#Основы

• Адрес: https://turtleguard.cloud/api/v1.
• Заголовок в каждом запросе: Authorization: Bearer crp_....
• Тела запросов и ответов — JSON. Создание сервера и остальные действия отвечают 200.
• Деньги — целое число в минимальных единицах валюты из соседнего поля currency: для долларов это центы.
• Время — строки RFC 3339, идентификаторы — UUID.
• В каждом ответе есть заголовок X-Request-Id. Приложите его, когда пишете в поддержку о конкретном запросе.

curl -s -H "Authorization: Bearer $TOKEN" https://turtleguard.cloud/api/v1/cloud/vms

Проверить токен можно запросом GET /auth/me: в ответе будут аккаунт, "auth": "token" и права токена в scopes.

#Описание OpenAPI

Полное описание всех методов, полей и ответов — в файле https://turtleguard.cloud/api/v1/openapi.json (OpenAPI 3.1, доступен без токена). Его можно импортировать в Postman или Insomnia или сгенерировать по нему клиент для своего языка. Если эта страница и файл расходятся, верен файл.

#Что доступно токену

• Все методы /cloud/… из этой страницы.
• GET /billing/balance и GET /billing/transactions.
• GET /auth/me и GET /openapi.json.

На любой другой адрес токен получит 403 с кодом auth.token_area. Пополнить баланс, сменить пароль аккаунта, выпустить или отозвать токен через API нельзя: это делается в кабинете.

Каждому методу нужно одно из трёх прав: cloud:read — смотреть серверы, cloud:write — заказывать и менять их, billing:read — видеть баланс и операции. Тарифы и образы (GET /cloud/plans, GET /cloud/cloud-images) отдаются и без токена.

#Лимиты

Сверх лимита API отвечает 429 с кодом rate_limited и заголовком Retry-After — через столько секунд можно повторить. Лимиты считаются на каждый токен отдельно.

#Ошибки

{"error": {"code": "billing.insufficient_funds", "message": "..."}}

code не меняется между версиями, по нему и стоит разбирать ответ. message — подсказка на английском. При ошибке в данных добавляется field с именем поля. Если тело запроса не является корректным JSON для метода, ответ будет простым текстом с кодом 400, 415 или 422.

«Сервер занят» (cloud.vm_busy) значит, что он создаётся, переустанавливается, переезжает или удаляется. Дождитесь, пока статус сменится, и повторите.

#Тарифы и образы

• Заказывать можно в локациях с "available": true. Код локации — поле code, например de.
• У тарифа цена за период — price_monthly. Если для локации задана своя цена, она лежит в country_prices по коду локации. traffic_gb: null — трафик не ограничен.
• Цены в unit_prices даны в миллионных долях валюты за месяц, там же пределы: min_cpu…max_disk_gb.

#Заказ сервера

curl -s -X POST -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"plan_id": "6f1c2b9e-4d1a-4c47-9b52-1f0e7a3d8c21", "region": "de", "os_key": "ubuntu-24.04",
       "hostname": "client-42", "root_password": "q7-Lm2vX9rTp", "idempotency_key": "order-1042"}' \
  https://turtleguard.cloud/api/v1/cloud/vms

В ответе: vm_id, hostname, выданный адрес ip, списанная сумма price с currency и duplicate. Сервер появляется сразу со статусом creating и переходит в running, когда готов. Если создать его не получилось, деньги возвращаются на баланс.

Для заказа нужна подтверждённая почта аккаунта. Не хватает денег — 402, нет места в локации или свободного адреса — 409 с cloud.no_capacity или cloud.ip_pool_empty.

#Повтор без двойного списания

Если ответ на заказ потерялся — оборвалась связь, истёк таймаут, — повторите тот же запрос с тем же idempotency_key. Второго сервера не будет: API вернёт первый заказ с "duplicate": true. Ключ любой непустой, он действует в пределах вашего аккаунта; удобно брать номер заказа из своей системы. Без ключа каждый запрос — новый заказ и новое списание.

#Список и данные сервера

Главное в vm: status, адреса public_ipv4 и ipv6, expires_at — до какого числа оплачен, auto_renew, price_monthly, трафик за период traffic_in и traffic_out в байтах. Пароль root лежит в root_password — последний заданный; пустая строка, если он неизвестен.

#Питание и удаление

Запрос ждёт, пока действие выполнится, и возвращает новый статус: {"ok": true, "action": "reboot", "status": "running"}. Включить приостановленный за неоплату сервер нельзя (402) — сначала продлите его. Остановленный за нарушение правил — тоже (403).

#Переустановка

Тело: os_key и root_password обязательны, ssh_key — по желанию. Переустановка идёт в фоне, на это время статус — reinstalling. У приложений и игровых серверов os_key не учитывается: контейнер пересоздаётся из того же образа, и приложение ставится заново с текущими настройками.

#Пароль и SSH-ключи

Пароль и ключи записываются через cloud-init. У включённого сервера пароль меняется ещё и через гостевого агента, в фоне.

#Смена IP

• Смена платная, цена указана в панели на странице сервера. Деньги списываются с баланса, сумма приходит в ответе в charged. Не хватает денег — 402.
• Включённый сервер перезапускается, чтобы получить новый адрес.
• Между сменами на одном сервере — не меньше 60 секунд, иначе 409 cloud.ip_change_cooldown.
• Число смен за последние 24 часа ограничено — отдельно на сервер (cloud.ip_change_vm_daily) и на весь аккаунт (cloud.ip_change_user_daily).
• В ответе старый адрес old_ip и новый ip. Если apply_error не пустой, адрес выдан, но применить его на узле сразу не вышло — мы повторим сами.

#Смена тарифа и конфигурации

При переходе на тариф доплата считается за всё оплаченное время, а не только за текущий месяц: разница в цене × оставшиеся дни ÷ дни периода. Начатый день считается целым. Если сервер продлён на несколько периодов вперёд, доплата будет за все. Сумма к оплате видна заранее в charge_now у каждого варианта из /upgrades, там же days_left и period_days. Перейти на меньший тариф нельзя.

Своя конфигурация считается по ценам за ядро, память и диск в локации сервера. Если она дороже прежней, разница в цене за период списывается сразу; если дешевле, ничего не списываем и не возвращаем, новая цена действует с продления. Диск можно только увеличить.

В обоих случаях включённый сервер перезапускается ("restarting": true в ответе). Не хватает денег — 402. Серверы приложений из маркета так не меняются.

#Продление

• Продление привязано к текущей дате окончания: повтор того же запроса не спишет деньги второй раз, а вернёт "duplicate": true и "charged": 0. Новая дата — в expires_at.
• Приостановленный за неоплату сервер после продления включается сам.
• С автопродлением деньги списываются с баланса в день окончания срока.
• Если в этот день денег не хватает, сервер выключается и получает статус suspended. Пополните баланс в течение льготного срока — сервер продлится и включится сам, иначе будет удалён.

#Снимки

Создание и удаление идут в фоне, список обновляется не сразу. Когда снимков уже max, новый не создаётся: 409 cloud.snapshot_limit. POST /cloud/vms/{id}/snapshot — то же, что POST …/snapshots.

#Режим восстановления

Нужен, когда система не загружается. Сервер перезапускается и грузится с образа восстановления, ваш диск остаётся подключённым: его можно смонтировать и починить. Повторный вызов возвращает обычную загрузку, сервер снова перезапускается.

#Консоль

С пропуском откройте websocket wss://turtleguard.cloud/api/v1/vnc/{token} (подпротокол binary), например через noVNC, и введите password. Пропуск срабатывает один раз. Заголовок Authorization к этому подключению не добавляйте: пропуск уже в адресе, а с токеном адрес ответит 403.

#Графики нагрузки

Каждая точка — время time в секундах Unix и значения cpu, mem, maxmem, disk, maxdisk, netin, netout (сеть — байты в секунду).

#Название и комментарий

Поля: name — до 64 символов, comment — до 200, avatar — цвет #rrggbb или картинка data:image/... до 400 000 байт. Пустая строка очищает поле, не переданные поля остаются как были. В данных сервера они видны как display_name, comment и avatar.

#Баланс и операции

У операции: сумма amount (списание — со знаком минус), остаток после неё balance_after, тип kind (например, cloud_vm — заказ, продление или смена тарифа сервера, cloud_ip — смена IP, topup — пополнение), описание и ref_id — к какому серверу она относится. Пополнять баланс через API нельзя, только в кабинете.

#Для реселлеров

Обычный порядок, если вы продаёте наши VPS своим клиентам:

1. Проверьте баланс: GET /billing/balance. Заказ и продление списываются с него.
2. Возьмите тарифы, локации и образы: GET /cloud/plans и GET /cloud/cloud-images.
3. Закажите сервер: POST /cloud/vms с idempotency_key = номер заказа в вашей системе. При сетевой ошибке повторяйте с тем же ключом.
4. Опрашивайте GET /cloud/vms/{vm_id}, пока status не станет running.
5. Отдайте клиенту адрес из public_ipv4 и пароль root — тот, что вы задали при заказе, он же в root_password.
6. Подпишите сервер: PATCH /cloud/vms/{id}/profile с именем клиента в name и номером договора или контактом в comment. Название показывается в панели вместо имени сервера, комментарий виден в данных сервера через API.
7. Следите за сроком по expires_at: продлевайте через POST /cloud/vms/{id}/renew, когда клиент заплатил, или включите автопродление и держите на балансе запас.

Для этого нужен токен «Управление VPS». Для витрины, которая только показывает клиентам состояние серверов, хватит токена «Только чтение».