API QoCloud — это REST поверх HTTPS с JSON в запросах и ответах. Через него доступно всё основное из панели: каталог, баланс, создание серверов и действия с ними. Полный список методов с примерами на curl, Python и JavaScript — в разделе «API» на сайте (/api-docs).
Адрес и авторизация
Все запросы идут на https://qocloud.tech/api/v1. Ключ передаётся в заголовке Authorization:
$ curl https://qocloud.tech/api/v1/balance \ -H "Authorization: Bearer $QOCLOUD_TOKEN"Каталог — без ключа
Метод /catalog публичный: страны, конфигурации с ценами в рублях за месяц, доступные ОС, сроки оплаты и скидки. Удобно для проверки подключения и выбора параметров будущего сервера.
$ curl -s https://qocloud.tech/api/v1/catalog | jq '.plans[] | {id, cpu, ram_gb, disk_gb, monthly}'id конфигурации вида 2c-4g-60 означает 2 vCPU, 4 ГБ памяти и 60 ГБ диска. Коды стран: nl, de, pl, ee.
Баланс и серверы
$ curl -s https://qocloud.tech/api/v1/balance -H "Authorization: Bearer $QOCLOUD_TOKEN"$ curl -s https://qocloud.tech/api/v1/servers -H "Authorization: Bearer $QOCLOUD_TOKEN" \ | jq -r '.servers[] | [.name, .status, .ip, .paid_until] | @tsv'Статус сервера: provisioning — создаётся, active — работает, suspended — приостановлен, expired — срок истёк, failed — создать не удалось. Поле power показывает питание: running или stopped.
Ошибки
Ошибка приходит с HTTP-кодом и телом вида {"error": {"code": "…", "message": "…"}}. Код стабильный, по нему удобно ветвиться в скрипте; message — для человека.
| HTTP | code | Что значит |
|---|---|---|
| 401 | unauthorized | Нет ключа, ключ отозван или истёк. |
| 403 | forbidden | Ключ только для чтения или аккаунт заблокирован. |
| 400 | bad_request | Неверные поля, подробности в fields. |
| 402 | insufficient_balance | Не хватает денег, сумма в рублях — в need. |
| 404 | not_found | Сервер не найден или принадлежит другому аккаунту. |
| 409 | conflict | Действие сейчас невозможно: сервер создаётся, остановлен и т. п. |
| 429 | rate_limited | Превышен лимит запросов. |
Лимиты
На один ключ — 120 запросов в минуту, тяжёлые операции — 10 за 10 минут. При превышении API вернёт 429 с заголовком Retry-After: подождите указанное число секунд и повторите.
Дальше
Как создать сервер скриптом, дождаться IP и корректно обработать ошибки — в статье «Автоматизация через API».