Управление VPS через REST API и curl: статус, питание, переустановка, продление

Заказ сервера через API — один запрос, это разобрано в статье Заказ VPS за 4 вызова API. Здесь — всё, что после него: рутинные действия, которые иначе пришлось бы прокликивать в кабинете, в виде команд curl, которые можно вставить в скрипт.

Каждую команду ниже мы выполнили против нашего API перед публикацией, а ответы — сокращённые копии того, что пришло.

Подготовка

Две переменные сокращают команды:

export API=https://api.eqvps.com/api/v1/eqvps
export EQVPS_TOKEN='paste-your-token-here'

Токен берётся из POST /auth/register или в кабинете: Настройки → API-токены. Если машиной пользуются другие люди, не оставляйте его в истории shell: достаточно читать из файла через export EQVPS_TOKEN=$(cat ~/.eqvps_token).

Найти свои серверы

curl -s $API/services -H "Authorization: Bearer $EQVPS_TOKEN"

У каждой записи есть id вроде 47HZ7YF — код услуги, который принимают все остальные вызовы. Полная картина по одному серверу:

curl -s $API/services/47HZ7YF -H "Authorization: Bearer $EQVPS_TOKEN"

{ "data": {
    "id": "47HZ7YF", "status": "active", "queued": false,
    "product": { "slug": "nano", "name": "Nano" },
    "specs": { "vcpu": 2, "memory_mb": 1024, "disk_gb": 15 },
    "hostname": "agent-box",
    "vm": { "state": "running", "uptime": 5340 },
    "access": { "method": "ssh", "host": "203.0.113.10", "port": 21521, "user": "root", "nat": true, ... } } }

В access — как войти. На тарифе со своим IPv4 порт 22, на NAT-тарифе — ваш личный проброшенный порт. Вызов только читает, так что опрашивать его в цикле безопасно.

Если заказ был без ключа SSH, пароль root показывается один раз:

curl -s "$API/services/47HZ7YF?reveal=1" -H "Authorization: Bearer $EQVPS_TOKEN"

Пока сервер загружается, ответ говорит password_pending, и одноразовый показ не тратится. Подождите полминуты и спросите снова.

Питание: включить, выключить, перезагрузить

curl -s -X POST $API/services/47HZ7YF/power \
  -H "Authorization: Bearer $EQVPS_TOKEN" -H "Content-Type: application/json" \
  -d '{"action": "reboot"}'

action — это start, stop или reboot. Сервер, который ещё не активен (создаётся или приостановлен за неоплату), отвечает 409 Service is not active. Это не ошибка вашего скрипта — сначала проверьте status.

Метрики

curl -s "$API/services/47HZ7YF/metrics?timeframe=day" -H "Authorization: Bearer $EQVPS_TOKEN"

CPU, память, сеть и диск рядами. timeframe — hour (по умолчанию), day, week или month. Удобно для cron-задачи, которая напишет вам, если диск растёт и растёт. Счётчики трафика за текущий период — в статье Скорость и трафик.

Переименовать сервер

curl -s -X POST $API/services/47HZ7YF/hostname \
  -H "Authorization: Bearer $EQVPS_TOKEN" -H "Content-Type: application/json" \
  -d '{"hostname": "web-01"}'

Новое имя применяется внутри работающей системы через гостевой агент, на Linux без перезагрузки. Если сервер выключен или вы удалили qemu-guest-agent, вызов вернёт 409 agent_unavailable и ничего не изменит.

Переустановить ОС

Эта команда стирает диск. API требует вписать в confirm текущее имя сервера, поэтому скрипт с ошибочным id не сотрёт чужую машину:

curl -s -X POST $API/services/47HZ7YF/reinstall \
  -H "Authorization: Bearer $EQVPS_TOKEN" -H "Content-Type: application/json" \
  -d '{"os_id": 4, "confirm": "web-01"}'

os_id берётся из списка available_os вашего тарифа в GET /products или из данных самого сервера. Переустановка идёт в фоне — опрашивайте GET /services/{id}, пока status снова не станет active.

Продление и баланс

Серверы продлеваются раз в месяц с предоплаченного баланса. Сколько стоят более длинные сроки для этого сервера:

curl -s $API/services/47HZ7YF/renew-options -H "Authorization: Bearer $EQVPS_TOKEN"

Оплатить вперёд, скажем, три месяца одним вызовом:

curl -s -X POST $API/services/47HZ7YF/renew \
  -H "Authorization: Bearer $EQVPS_TOKEN" -H "Content-Type: application/json" \
  -d '{"months": 3}'

months — 1, 3, 6 или 12, причём 12 считается по годовой цене со скидкой. В ответе будут paid_from_balance: true и новая дата окончания. Если баланса не хватает, ничего не спишется: придут paid_from_balance: false и checkout_url для этого счёта. После пополнения POST $API/invoices/{invoice_id}/pay оплатит этот счёт с баланса; если баланса всё ещё мало, вернёт такой же checkout_url и ничего не спишет. Проверить и пополнить баланс:

curl -s $API/balance -H "Authorization: Bearer $EQVPS_TOKEN"

curl -s -X POST $API/balance/topup \
  -H "Authorization: Bearer $EQVPS_TOKEN" -H "Content-Type: application/json" \
  -d '{"amount": 25}'

В ответе на пополнение — checkout_url, крипто-оплата: USDT, USDC или ETH в сетях Base, Ethereum или Polygon. Баланс зачисляется, когда платёж подтвердится в сети. Оплата — единственный шаг, который скрипт за вас не сделает, если у него нет кошелька.

Monero тоже подходит, но только для пополнения баланса с ручной проверкой: вы отправляете XMR, передаёте ID транзакции, и мы зачисляем после сверки. Подробнее — Оплата в Monero.

Отменить и передумать

Безопасная отмена оставляет сервер работать до конца оплаченного срока и просто не продлевает его:

curl -s -X POST $API/services/47HZ7YF/cancel \
  -H "Authorization: Bearer $EQVPS_TOKEN" -H "Content-Type: application/json" \
  -d '{"type": "end_of_period", "reason": "moving the project elsewhere"}'

reason обязателен, хватит пары слов. Передумали до даты?

curl -s -X POST $API/services/47HZ7YF/cancel/undo -H "Authorization: Bearer $EQVPS_TOKEN"

Есть и "type": "immediate". Он сразу удаляет сервер вместе с данными, требует "confirm": "<имя сервера>" и отмене не подлежит. Если вы не уверены на сто процентов — используйте end_of_period.

Чтобы токен не протух

Новые токены по умолчанию живут год. Каждый ответ с авторизацией несёт заголовок X-Token-Expires-At, так что скрипт может заметить это заранее. Поменять токен на свежий:

curl -s -X POST $API/auth/token/refresh -H "Authorization: Bearer $EQVPS_TOKEN"

Старый токен перестаёт работать сразу, поэтому сначала сохраните новый.

Ошибки, которые стоит обрабатывать

Хотите то же самое не из скрипта, а из ИИ-клиента? Эти действия есть в виде MCP-инструментов — см. Как агент сам обслуживает свой VPS через MCP и справочник API. Если сервера ещё нет, выберите тариф.