Керування 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 або з Settings → API tokens у кабінеті. Не тримайте його в історії 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, а одноразовий показ не витрачається. Зачекайте пів хвилини й запитайте знову.

Живлення: start, stop, reboot

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 вимагає вписати поточний hostname сервера в 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": "<hostname>" і не скасовується. Якщо ви справді цього не хочете, використовуйте end_of_period.

Підтримувати токен живим

Нові токени за замовчуванням живуть рік. Кожна автентифікована відповідь має заголовок X-Token-Expires-At, тож скрипт може помітити це заздалегідь. Замініть токен на свіжий:

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

Старий токен перестає працювати одразу, тож збережіть новий, перш ніж робити щось інше.

Помилки, які варто обробляти

Робите це з ІІ-клієнта, а не зі скрипта? Ті самі дії є як інструменти MCP — див. Як агент сам веде свій VPS через MCP і довідник API. Ще немає сервера? Оберіть тариф.