API: обзор, доступ, токены, ошибки и лимиты

API Доброго Хостинга — это тот же интерфейс, которым пользуется кабинет: JSON поверх HTTPS. Через него можно следить за серверами из своего мониторинга, перезагружать их по расписанию, управлять firewall и тегами.

Что можно и чего нельзя

Доступно по токену	Недоступно (только из кабинета)
список серверов, карточка, статус у поставщика	заказ, продление, апгрейды, любые списания
включить / выключить / перезагрузить	удаление и переустановка ОС
метрики агента, журнал событий, уведомления	пароли, данные для входа, SSH-ключи в профиле
имя, теги, цвет, заметка	настройки аккаунта, 2FA, e-mail
планировщик и firewall	доступ для друга, заявки, управление токенами

Это сделано намеренно: утечка токена не должна стоить вам сервера или денег.

1. Получите доступ

Настройки → API → Запросить доступ: опишите задачу (1–2 предложения). Заявка создаёт обращение в поддержку.
Ответ придёт уведомлением и в обращении — обычно в течение рабочего дня.
После одобрения в том же разделе появится кнопка Создать токен.

Администратор может отозвать доступ — тогда все токены перестанут работать с ответом 403 token.

2. Создайте токен

Параметры токена:

Поле	Значение
Имя	чтобы отличать: «grafana», «cron-ноутбук»
Права	`read` — просмотр; `power` — питание; `manage` — имя/теги, планировщик, firewall. Можно несколько.
Срок	бессрочно, 30, 90 или 365 дней
Разрешённые IP	список адресов/подсетей через запятую: `203.0.113.5, 10.0.0.0/8`. Пусто — с любых.

Токен имеет вид dh_3f9a1c_… и показывается один раз. До 10 активных токенов на аккаунт. Отозвать — кнопкой в списке; после отзыва запросы получают 401.

3. Делайте запросы

Базовый адрес: https://panel.dobry.host/api
Заголовок: Authorization: Bearer <токен>
Для POST/PATCH — тело JSON и Content-Type: application/json
CSRF-токен и cookie не нужны. Заголовок Origin не проверяется для bearer-запросов.

curl -s https://panel.dobry.host/api/servers \
  -H "Authorization: Bearer dh_3f9a1c_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"

Python:

import requests
API = "https://panel.dobry.host/api"
H = {"Authorization": "Bearer dh_3f9a1c_XXXX"}
print(requests.get(f"{API}/servers", headers=H, timeout=15).json())

JavaScript (Node 18+ / браузер):

const r = await fetch("https://panel.dobry.host/api/servers", { headers: { Authorization: "Bearer dh_3f9a1c_XXXX" } });
const data = await r.json();

4. Формат ответа

Успех — всегда {"ok": true, ...}. Ошибка — HTTP-код 4xx/5xx и тело:

{"ok": false, "error": {"code": "token_scope", "message": "Этот запрос недоступен по API-токену."}}

message — готовый текст на русском, можно показывать пользователю. code — для логики.

5. Коды ошибок

HTTP	code	Когда
401	`token`	токен отозван, истёк, неверный формат или доступ к API закрыт
403	`token_scope`	у токена нет нужного права или маршрут закрыт для API
403	`token_ip`	запрос с адреса не из списка разрешённых
403	`forbidden_shared`	сервер выдан вам другом без этого права
403	`blocked`	аккаунт ограничен
404	`not_found`	сервер/объект не найден или не ваш
400	`validation`, `action`, `password`, `os`	проверьте поля — текст в `message`
409	`operation_in_progress`	по серверу уже идёт операция, подождите
409	`software`	идёт автоустановка ПО, питание/переустановка временно недоступны
409	`idempotency_conflict`	этот `idempotency_key` уже использован для другого действия
429	`rate_limit`	больше 120 запросов в минуту на токен
503	`catalog_unavailable`, `unavailable`	поставщик или сервис измерений не отвечает — повторите позже
500	`internal`	ошибка на нашей стороне — напишите в поддержку с временем запроса

6. Лимиты и рекомендации

120 запросов в минуту на токен. Метрики и карточка сервера кэшируются у нас на 45–60 с — чаще опрашивать нет смысла.
Для мониторинга используйте GET /servers/sparklines — один запрос на все серверы.
Все времена — Unix timestamp в секундах (UTC). Деньги — рубли, число с плавающей точкой.
Действия принимают idempotency_key (16–64 символа): повтор с тем же ключом вернёт ту же операцию, а не выполнит её дважды. Генерируйте ключ на своей стороне (uuid4, дата-серверId).
Храните токен в переменных окружения или секрет-хранилище, не в коде. Для серверных скриптов ограничьте токен по IP.
Совместимость: поля только добавляются, существующие не переименовываются. Если что-то не находите — проверьте раздел «Справочник».

Справочник

Серверы и действия — список, карточка, питание, имя и теги, операции
Метрики, журнал, уведомления
Планировщик и firewall
Публичные методы без токена — каталог, ПО, база знаний, Looking Glass
Готовые примеры — bash, Python, Node.js, Grafana