Перейти к содержимому
API v1

REST API QoCloud

Через API доступны те же операции, что и в личном кабинете: создание сервера, перезагрузка, переустановка ОС, продление. JSON поверх HTTPS, ключи с правами «чтение» или «управление», события — через вебхуки.

Базовый адресhttps://qocloud.tech/api/v1
Авторизация

Ключ из раздела «Настройки → API-ключи» в заголовке Authorization: Bearer …. Храните ключ так же, как пароль.

Быстрый старт

Первый запрос

Сохраните токен в переменную окружения и запросите список серверов.

bash
$ export QOCLOUD_TOKEN="qc_live_…"$ curl https://qocloud.tech/api/v1/servers -H "Authorization: Bearer $QOCLOUD_TOKEN"
GET/catalog

Конфигурации и цены

Страны, конфигурации с ценами в рублях за месяц, доступные ОС, сроки оплаты и скидки за срок (в процентах). Ключ не нужен.

curl
$ curl -X GET https://qocloud.tech/api/v1/catalog \  -H "Authorization: Bearer $QOCLOUD_TOKEN"
Ответ · 200
{  "locations": [    {      "code": "nl",      "name": "Нидерланды",      "available": true    }  ],  "plans": [    {      "id": "2c-4g-60",      "line": "start",      "cpu": 2,      "ram_gb": 4,      "disk_gb": 60,      "monthly": {        "nl": 945      }    }  ],  "os": [    "ubuntu2404",    "debian12"  ],  "periods": [    "1m",    "3m",    "6m",    "1y"  ],  "discounts": {    "1m": 0,    "3m": 15,    "6m": 20,    "1y": 25  }}
GET/balance

Баланс

Баланс, расходы в месяц по работающим серверам и состояние автопродления. Права: чтение.

curl
$ curl -X GET https://qocloud.tech/api/v1/balance \  -H "Authorization: Bearer $QOCLOUD_TOKEN"
Ответ · 200
{  "balance": 4820,  "currency": "RUB",  "monthly_spend": 6241,  "auto_renew": true}
GET/servers

Список серверов

Все серверы аккаунта. status: provisioning, active, suspended, expired, failed; power: running или stopped. Права: чтение.

curl
$ curl -X GET https://qocloud.tech/api/v1/servers \  -H "Authorization: Bearer $QOCLOUD_TOKEN"
Ответ · 200
{  "servers": [    {      "id": "6f1c2a9e-8b1d-4c1e-9f7a-2d3b4c5e6f70",      "name": "web-01",      "status": "active",      "power": "running",      "plan": "2c-4g-60",      "cpu": 2,      "ram_gb": 4,      "disk_gb": 60,      "location": "nl",      "os": "ubuntu2404",      "ip": "203.0.113.10",      "price_month": 945,      "paid_until": "2026-12-02T09:00:00.000Z",      "created_at": "2026-06-02T09:00:00.000Z",      "last_error": null    }  ]}
POST/servers

Создать сервер

Списывает стоимость срока с баланса (со скидкой за 3, 6 или 12 месяцев) и создаёт сервер (1–3 минуты). Передайте заголовок Idempotency-Key — повтор запроса с тем же ключом в течение суток не создаст второй сервер. Если средств на балансе недостаточно, API вернёт 402 с полем need. Права: управление.

Параметры
ПараметрОписание
planstring · обязательныйid конфигурации из /catalog
locationstring · обязательныйкод страны: nl, de, pl, ee, cz, ch, se
osstring · обязательныйобраз из /catalog
periodstring · обязательный1m, 3m, 6m или 1y
namestring · обязательныйлатиница, цифры и дефис, 2–60 символов
curl
$ curl -X POST https://qocloud.tech/api/v1/servers \  -H "Authorization: Bearer $QOCLOUD_TOKEN" \  -H "Content-Type: application/json" \  -d '{"plan":"2c-4g-60","location":"nl","os":"ubuntu2404","period":"1m","name":"web-02"}'
Ответ · 200
{  "server": {    "id": "6f1c2a9e-8b1d-4c1e-9f7a-2d3b4c5e6f70",    "name": "web-02",    "status": "provisioning",    "power": null,    "plan": "2c-4g-60",    "cpu": 2,    "ram_gb": 4,    "disk_gb": 60,    "location": "nl",    "os": "ubuntu2404",    "ip": null,    "price_month": 945,    "paid_until": "2026-12-02T09:00:00.000Z",    "created_at": "2026-06-02T09:00:00.000Z",    "last_error": null  }}
GET/servers/{id}

Сервер

Актуальные данные о сервере (статус сверяется с дата-центром). Права: чтение.

Параметры
ПараметрОписание
idstring · обязательныйid сервера
curl
$ curl -X GET https://qocloud.tech/api/v1/servers/6f1c2a9e-8b1d-4c1e-9f7a-2d3b4c5e6f70 \  -H "Authorization: Bearer $QOCLOUD_TOKEN"
Ответ · 200
{  "server": {    "id": "6f1c2a9e-8b1d-4c1e-9f7a-2d3b4c5e6f70",    "name": "web-01",    "status": "active",    "power": "running",    "plan": "2c-4g-60",    "cpu": 2,    "ram_gb": 4,    "disk_gb": 60,    "location": "nl",    "os": "ubuntu2404",    "ip": "203.0.113.10",    "price_month": 945,    "paid_until": "2026-12-02T09:00:00.000Z",    "created_at": "2026-06-02T09:00:00.000Z",    "last_error": null  }}
GET/servers/{id}/password

Root-пароль

Текущий root-пароль. Каждый запрос записывается в журнал безопасности. Права: управление.

curl
$ curl -X GET https://qocloud.tech/api/v1/servers/6f1c2a9e-8b1d-4c1e-9f7a-2d3b4c5e6f70/password \  -H "Authorization: Bearer $QOCLOUD_TOKEN"
Ответ · 200
{  "id": "6f1c2a9e-…",  "root_password": "k3P…"}
GET/servers/{id}/events

Журнал сервера

Кто и когда управлял сервером: панель (user), API-ключ (api, имя ключа — в api_key), поддержка (admin) или автоматика (system). Сумма: минус — списание, плюс — возврат. Новые записи сверху. Права: чтение.

Параметры
ПараметрОписание
idstring · обязательныйid сервера
limitnumberсколько записей вернуть, 1–200 (по умолчанию 100)
curl
$ curl -X GET https://qocloud.tech/api/v1/servers/6f1c2a9e-8b1d-4c1e-9f7a-2d3b4c5e6f70/events \  -H "Authorization: Bearer $QOCLOUD_TOKEN"
Ответ · 200
{  "events": [    {      "id": "0b7e…",      "at": "2026-06-02T09:05:00.000Z",      "action": "change_ip",      "label": "Смена IP",      "actor": "api",      "api_key": "deploy",      "ok": true,      "detail": "Прежний 203.0.113.10",      "amount": -150    }  ]}
POST/servers/{id}/actions/{action}

Действие с сервером

start, stop, reboot, reinstall (нужен os), reset-password, change-ip (платно), renew (продление на месяц с баланса), upgrade (нужен plan, доплата за остаток срока). Операции асинхронные — ответ 202, статус меняется за секунды–минуты. Права: управление.

Параметры
ПараметрОписание
actionstring · обязательныйstart, stop, reboot, reinstall, reset-password, change-ip, renew, upgrade
osstringтолько для reinstall
planstringтолько для upgrade
curl
$ curl -X POST https://qocloud.tech/api/v1/servers/6f1c2a9e-8b1d-4c1e-9f7a-2d3b4c5e6f70/actions/reinstall \  -H "Authorization: Bearer $QOCLOUD_TOKEN" \  -H "Content-Type: application/json" \  -d '{"os":"debian12"}'
Ответ · 200
{  "ok": true,  "action": "reinstall",  "message": "Переустановка началась",  "server": {    "id": "6f1c2a9e-…",    "status": "active",    "power": "running"  }}
PATCH/servers/{id}

Изменить сервер

Имя, заметка, теги и автопродление. Передайте только поля, которые меняете; auto_renew: null — как в настройке аккаунта. Права: управление.

Параметры
ПараметрОписание
namestringлатиница, цифры и дефис, 2–60 символов
notestring | nullзаметка до 1000 символов; null — удалить
tagsstring[]теги целиком (заменяют прежние)
auto_renewboolean | nullавтопродление этого сервера
curl
$ curl -X PATCH https://qocloud.tech/api/v1/servers/6f1c2a9e-8b1d-4c1e-9f7a-2d3b4c5e6f70 \  -H "Authorization: Bearer $QOCLOUD_TOKEN" \  -H "Content-Type: application/json" \  -d '{"name":"web-02","tags":["prod","eu"],"auto_renew":true}'
Ответ · 200
{  "server": {    "id": "6f1c2a9e-8b1d-4c1e-9f7a-2d3b4c5e6f70",    "name": "web-02",    "status": "active",    "power": "running",    "plan": "2c-4g-60",    "cpu": 2,    "ram_gb": 4,    "disk_gb": 60,    "location": "nl",    "os": "ubuntu2404",    "ip": "203.0.113.10",    "price_month": 945,    "paid_until": "2026-12-02T09:00:00.000Z",    "created_at": "2026-06-02T09:00:00.000Z",    "last_error": null,    "note": null,    "tags": [      "eu",      "prod"    ],    "auto_renew": true  }}
GET/ssh-keys

SSH-ключи

Публичные ключи аккаунта с отпечатками SHA256 — те же, что в «Настройках». Права: чтение.

curl
$ curl -X GET https://qocloud.tech/api/v1/ssh-keys \  -H "Authorization: Bearer $QOCLOUD_TOKEN"
Ответ · 200
{  "ssh_keys": [    {      "id": "3a1b…",      "name": "laptop",      "type": "ssh-ed25519",      "fingerprint": "SHA256:4f2A…",      "public_key": "ssh-ed25519 AAAAC3Nza… laptop",      "created_at": "2026-06-02T09:00:00.000Z"    }  ]}
POST/ssh-keys

Добавить SSH-ключ

Принимает ed25519, ECDSA и RSA от 2048 бит. Тот же ключ второй раз — 409. Не больше 20 ключей. Ответ — 201. Права: управление.

Параметры
ПараметрОписание
public_keystring · обязательныйстрока из ~/.ssh/id_ed25519.pub
namestringподпись; по умолчанию — комментарий ключа
curl
$ curl -X POST https://qocloud.tech/api/v1/ssh-keys \  -H "Authorization: Bearer $QOCLOUD_TOKEN" \  -H "Content-Type: application/json" \  -d '{"name":"laptop","public_key":"ssh-ed25519 AAAAC3Nza… laptop"}'
Ответ · 200
{  "ssh_key": {    "id": "3a1b…",    "name": "laptop",    "type": "ssh-ed25519",    "fingerprint": "SHA256:4f2A…",    "public_key": "ssh-ed25519 AAAAC3Nza… laptop",    "created_at": "2026-06-02T09:00:00.000Z"  }}
DELETE/ssh-keys/{id}

Удалить SSH-ключ

Удаляет ключ из аккаунта. На уже созданных серверах он остаётся в authorized_keys — уберите его там сами. Права: управление.

curl
$ curl -X DELETE https://qocloud.tech/api/v1/ssh-keys/6f1c2a9e-8b1d-4c1e-9f7a-2d3b4c5e6f70 \  -H "Authorization: Bearer $QOCLOUD_TOKEN"
Ответ · 200
{  "id": "3a1b…",  "deleted": true}
DELETE/servers/{id}

Удалить сервер

Удаляет сервер и все данные — необратимо. Нужен заголовок X-Confirm-Name с именем сервера. Оплаченный срок не возвращается (см. политику возврата). Права: управление.

curl
$ curl -X DELETE https://qocloud.tech/api/v1/servers/6f1c2a9e-8b1d-4c1e-9f7a-2d3b4c5e6f70 \  -H "Authorization: Bearer $QOCLOUD_TOKEN" \  -H "X-Confirm-Name: web-01"
Ответ · 200
{  "id": "6f1c2a9e-…",  "status": "deleted"}
Вебхуки

События на ваш сервер

Адрес и события задаются в «Настройки → API → Вебхуки». Мы отправляем POST с JSON и ждём ответ 2xx за 10 секунд; при ошибке повторяем через 1, 5, 30 минут, 2, 6 и 12 часов. По редиректам не переходим.

  • server.readyсервер создан и готов, в data.server — id, имя, IP
  • server.expiringсрок заканчивается: за 7 и 3 дня, за 3 часа и после окончания (stage)
  • server.renewedсервер продлён, в data.amount — списанная сумма
  • balance.lowбаланса не хватит на ближайшие продления или он ниже порога
  • alert.firingсработало оповещение мониторинга или проверки доступности
  • alert.resolvedоповещение снято
  • payment.succeededплатёж зачислен на баланс

Проверка подписи

Заголовок X-QoCloud-Signature: t=<время>,v1=<HMAC-SHA256 от «t.тело» на секрете адреса>. Сверяйте подпись и отклоняйте запросы старше 5 минут.

js
import crypto from 'node:crypto';function verify(body, header, secret) {  const { t, v1 } = Object.fromEntries(header.split(',').map((p) => p.split('=')));  if (Math.abs(Date.now() / 1000 - Number(t)) > 300) return false;  const expected = crypto.createHmac('sha256', secret).update(`${t}.${body}`).digest('hex');  return crypto.timingSafeEqual(Buffer.from(v1, 'hex'), Buffer.from(expected, 'hex'));}
Ошибки и лимиты

Коды ошибок

Ответ с ошибкой: { "error": { "code", "message" } }. Коды не меняются, по ним можно строить логику скриптов.

  • 401unauthorizedНет ключа, ключ отозван или истёк.
  • 403forbiddenКлюч только для чтения или аккаунт заблокирован.
  • 400bad_requestНеверные поля; подробности — в fields.
  • 402insufficient_balanceНедостаточно средств на балансе; недостающая сумма — в need.
  • 404not_foundСервер не найден (или он чужой).
  • 409conflictДействие сейчас недоступно: например, сервер ещё создаётся или остановлен.
  • 429rate_limited120 запросов в минуту на ключ; тяжёлые операции — 10 за 10 минут.

Только нужные cookie.Подробнее