Все примеры — с заголовком Authorization: Bearer <токен>. Время — Unix timestamp (секунды).
Кто я — GET /auth/me
Право read. Проверка токена и баланса.
{"ok": true, "user": {"id": 100, "telegram_id": 100, "username": "client", "email": null, "balance": 2450.0, "is_admin": false, "blocked": false, "created_at": 1789733705, "has_password": true, "two_factor_enabled": false, "unread": 2}, "api_token": true}unread — непрочитанные уведомления. api_token: true подтверждает, что запрос авторизован токеном.
Список серверов — GET /servers
Право read. Свои серверы и серверы, к которым выдан доступ (у них есть поле shared).
{"ok": true, "servers": [{"id": 1, "name": "web-prod", "ip": "93.184.216.34", "country": "Германия", "flag": "de", "cpu_name": "EPYC", "cores": 2, "ram": 4, "disk": 25, "os_name": "Ubuntu 24.04", "price": 1080.0, "period": 720, "paid_until": 1791461705, "created_at": 1789733705, "status": "active", "tier": "Start", "note": "Основной сайт", "tags": ["prod", "nginx"], "color": "blue", "auto_renew": false}]}| Поле | Описание |
|---|---|
id | номер сервера в кабинете — используется во всех маршрутах |
ip | IPv4; пусто, пока сервер выдаётся |
flag | код страны (de, nl, fi…) |
cores, ram, disk | vCPU, ГБ памяти, ГБ диска |
price, period | цена за период и период в часах: 720 = 1 мес, 2160 = 3, 4320 = 6, 8640 = 12 |
paid_until | до какого момента оплачен |
status | active, installing, expired, deleted — локальный статус; живой статус — в карточке |
tier | название тарифной ступени |
note, tags, color, auto_renew | ваши метаданные и тумблер автопродления |
shared | только для чужих серверов: {"owner": "имя", "perms": {"power": true, ...}} |
Карточка сервера — GET /servers/{id}
Право read. Кабинет запрашивает поставщика (кэш 45 с) и отдаёт живой статус, доступные образы, цены продления и разрешённые действия.
{"ok": true, "server": {"id": 1, "name": "web-prod", "ip": "93.184.216.34", "status": "active", "os_name": "Ubuntu 24.04", "paid_until": 1791461705, "auto_renew": false, "tags": ["prod", "nginx"]}, "live": {"status": "active", "ip": "93.184.216.34", "os_name": "Ubuntu 24.04", "paid_until": 1791461705, "eth": "1 Гбит/с"}, "live_available": true, "os": [{"id": 5, "name": "Ubuntu 24.04"}, {"id": 7, "name": "Debian 12"}], "renew_prices": {"720": 1090, "2160": 3090, "4320": 6090, "8640": 11900}, "capabilities": ["power_on", "shutdown", "reboot", "delete", "renew", "reinstall"], "ip_change": {"available": false, "free_remaining": 1, "free_total": 1}, "addons": []}| Поле | Описание |
|---|---|
live.status | active — работает, stopped — выключен, installing — выдаётся/переустанавливается |
live_available | false, если поставщик не ответил за 6 с — тогда live = null, используйте server |
os | образы, доступные для переустановки (переустановка через API недоступна) |
renew_prices | цены продления по периодам |
capabilities | какие действия сейчас разрешены владельцу; по токену из них доступны только power_on, shutdown, reboot |
addons | подключённые допуслуги |
Мини-метрики всех серверов — GET /servers/sparklines
Право read. Один запрос — состояние всех серверов для дашборда. Кэш 60 с (ttl).
{"ok": true, "servers": {"1": {"monitored": true, "status": "up", "cpu": [12.1, 9.8, 14.3, 11.0], "ram": 47, "disk": 38, "updated": 1789736020, "speed": {"down": 812, "up": 640, "at": 1789700000}}, "2": {"monitored": false, "status": "none", "cpu": [], "updated": null}}, "ttl": 60}status: up, down (агент молчит > 4 мин), none (мониторинг не подключён). cpu — последние значения в процентах, ram/disk — занято в процентах, speed — последний спидтест в Мбит/с.
Теги — GET /servers/tags
Право read. Все теги аккаунта: {"ok": true, "tags": ["prod", "vpn", "test"]}.
Действия: включить, выключить, перезагрузить — POST /servers/{id}/actions
Право power. Тело:
| Поле | Описание |
|---|---|
action | power_on, shutdown, reboot |
idempotency_key | строка 16–64 символа, уникальная для действия |
curl -s -X POST https://panel.dobry.host/api/servers/1/actions \
-H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
-d '{"action": "reboot", "idempotency_key": "cron-20260918-1"}'Ответ — операция:
{"ok": true, "operation": {"id": 41, "kind": "reboot", "amount": 0.0, "status": "complete", "created_at": 1789733705, "updated_at": 1789733705, "result": {"message": "Действие выполнено."}}}status | Значение |
|---|---|
complete | поставщик принял команду; статус сервера обновится через 10–30 с |
failed | поставщик отказал — причина в result.message |
needs_review | результат не подтверждён (сеть, таймаут) — проверьте live.status через минуту; администратор увидит операцию в очереди |
pending | ещё выполняется (редко — при повторе с тем же ключом во время выполнения) |
Повтор запроса с тем же idempotency_key возвращает ту же операцию без повторного выполнения. Во время автоустановки ПО действия возвращают 409 software. Если по серверу уже идёт операция — 409 operation_in_progress.
Имя — POST /servers/{id}/rename
Право manage. {"name": "web-prod-2"} → {"ok": true, "name": "web-prod-2"}. Имя: 3–40 символов, латиница, цифры, дефис, подчёркивание; первый и последний символ — буква или цифра.
Теги, цвет, заметка — POST /servers/{id}/meta
Право manage. Любое подмножество полей:
{"color": "green", "tags": ["prod", "nginx"], "note": "Основной сайт"}Ответ: {"ok": true, "meta": {"note": "Основной сайт", "tags": ["prod", "nginx"], "color": "green", "auto_renew": false}}. Цвета: blue, green, orange, red, purple, gray или пусто. Тегов до 10, каждый до 24 символов. auto_renew через API изменить нельзя (это деньги).
Операции аккаунта — GET /operations
Право read. Последние операции (покупки, продления, действия) — новые сверху.
{"ok": true, "operations": [{"id": 41, "kind": "reboot", "amount": 0.0, "status": "complete", "created_at": 1789733705, "updated_at": 1789733705, "result": {"message": "Действие выполнено."}}, {"id": 40, "kind": "renew", "amount": 1090.0, "status": "complete", "created_at": 1789700000, "updated_at": 1789700002, "result": {"message": "Сервер продлён."}}]}kind: purchase, renew, power_on, shutdown, reboot, reinstall, delete, upgrade, addon, spec. amount — списанная сумма.