Документация API

Основы

API построено по принципам REST, принимает и возвращает JSON. Базовый URL:

https://mycloudbird.com/api/v1

• Тела запросов передавайте с заголовком Content-Type: application/json.
• Каждый ключ привязан к вашему изолированному проекту — вы видите и управляете только своими ресурсами.
• Все денежные значения — в тенге (₸), на это указывает суффикс _kzt в полях ответа.
• Идентификатор сервера {id} в путях — это числовой id сервера (целое положительное число).

Аутентификация

Все методы (кроме публичного каталога GET /api/v1) требуют API-ключ в заголовке:

Authorization: Bearer <ваш-ключ>

Ключ имеет вид cb_live_…. Создать, посмотреть и отозвать ключи можно в кабинете на странице «API-ключи». Полный ключ показывается только один раз при создании — сохраните его сразу; на сервере хранится лишь его хеш, восстановить ключ нельзя. Лимит — 10 ключей на аккаунт.

Пример запроса с ключом:

curl https://mycloudbird.com/api/v1/account \
  -H "Authorization: Bearer cb_live_xxxxxxxxxxxxxxxxxxxxxxxx"

Лимиты запросов

• 600 запросов в минуту с одного IP-адреса.
• 120 запросов в минуту на один API-ключ.

При превышении возвращается HTTP 429 с кодом rate_limited — сделайте паузу и повторите запрос.

Формат ошибок

Любая ошибка возвращается с соответствующим HTTP-статусом и телом:

{
  "error": {
    "message": "Человекочитаемое описание",
    "code": "machine_code"
  }
}

Основные коды:

Объект «Сервер»

Методы списка, получения и создания сервера возвращают объект сервера со следующими полями:

Аккаунт и баланс

GET /account

Сводка аккаунта: баланс, расход и текущая ставка проекта (₸).

curl https://mycloudbird.com/api/v1/account \
  -H "Authorization: Bearer cb_live_xxx"

{
  "email": "customer@example.com",
  "balance_kzt": 14250.5,
  "spent_kzt": 8320.75,
  "hourly_rate_kzt": 9.86,
  "suspended": false,
  "exempt": false,
  "servers": 2
}

hourly_rate_kzt — текущая суммарная стоимость проекта в час по всем ресурсам. servers — число активных серверов. Обращение к этому методу обновляет начисления за прошедшее время.

Управление серверами

GET /servers

Список всех серверов проекта.

curl https://mycloudbird.com/api/v1/servers \
  -H "Authorization: Bearer cb_live_xxx"

{
  "servers": [
    {
      "id": 52481234,
      "name": "web-01",
      "status": "running",
      "created": "2026-06-20T09:14:52+00:00",
      "ipv4": "91.99.12.34",
      "ipv6": "2a01:4f8:c012:abcd::1",
      "type": "cx22",
      "cores": 2,
      "memory_gb": 4,
      "disk_gb": 40,
      "location": "fsn1",
      "image": "ubuntu-24.04",
      "backups_enabled": false,
      "rescue_enabled": false,
      "delete_protected": false,
      "rdns_ipv4": "static.91.99.12.34.clients.example.com"
    }
  ]
}

POST /servers

Создать новый сервер. Параметры тела:

curl -X POST https://mycloudbird.com/api/v1/servers \
  -H "Authorization: Bearer cb_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{"name":"web-02","server_type":"cx22","image":"ubuntu-24.04"}'

{
  "server": {
    "id": 52481299,
    "name": "web-02",
    "status": "initializing",
    "created": "2026-06-24T10:15:00+00:00",
    "ipv4": "91.99.55.66",
    "ipv6": "2a01:4f8:c012:abcd::1",
    "type": "cx22",
    "cores": 2,
    "memory_gb": 4,
    "disk_gb": 40,
    "location": "fsn1",
    "image": "ubuntu-24.04",
    "backups_enabled": false,
    "rescue_enabled": false,
    "delete_protected": false,
    "rdns_ipv4": null
  },
  "root_password": "aB3xY7qLmN2pQ9"
}

Ответ — HTTP 201. Поле root_password возвращается только один раз и только если SSH-ключи не передавались (иначе null — вход по ключу). Для создания нужен запас баланса минимум на 24 часа работы проекта; максимум 10 серверов на аккаунт.

GET /servers/{id}

Получить один сервер по id.

curl https://mycloudbird.com/api/v1/servers/52481234 \
  -H "Authorization: Bearer cb_live_xxx"

PATCH /servers/{id}

Переименовать сервер. Тело: name (латиница/цифры, дефис или точка внутри). Возвращает обновлённый объект сервера.

curl -X PATCH https://mycloudbird.com/api/v1/servers/52481234 \
  -H "Authorization: Bearer cb_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{"name":"web-prod"}'

DELETE /servers/{id}

Удалить сервер. Перед удалением списывается плата за фактическое время работы. Сервер с включённой защитой от удаления удалить нельзя (код delete_protected).

curl -X DELETE https://mycloudbird.com/api/v1/servers/52481234 \
  -H "Authorization: Bearer cb_live_xxx"

{ "deleted": true, "id": 52481234 }

Действия над сервером

Все действия — метод POST на путь /servers/{id}/actions/<действие>.

POST /servers/{id}/actions/power

Управление питанием. Тело: action — одно из poweron, poweroff, reboot, shutdown, reset. Включение (poweron) недоступно при нулевом балансе.

curl -X POST https://mycloudbird.com/api/v1/servers/52481234/actions/power \
  -H "Authorization: Bearer cb_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{"action":"reboot"}'

{ "ok": true, "id": 52481234, "action": "reboot" }

POST /servers/{id}/actions/reset-password

Сбросить root-пароль. Тело не требуется. Возвращает новый пароль.

{ "ok": true, "root_password": "vT3xQ9kLpZ2mWbN7" }

POST /servers/{id}/actions/rebuild

Переустановить ОС (диск будет очищен). Тело: image — имя системного образа или id снимка. Возвращает новый root-пароль (или null, если использовался SSH-ключ).

curl -X POST https://mycloudbird.com/api/v1/servers/52481234/actions/rebuild \
  -H "Authorization: Bearer cb_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{"image":"ubuntu-24.04"}'

{ "ok": true, "root_password": "aB9cD2eF5gH8jK1m" }

POST /servers/{id}/actions/resize

Изменить конфигурацию (тип) сервера. Тело: server_type — имя новой конфигурации; upgrade_disk (необязательно, булево) — увеличить ли диск. Сервер должен быть выключен (иначе код server_not_off). Новый диск не может быть меньше текущего. upgrade_disk: true необратимо (после этого тип нельзя понизить). Увеличение конфигурации требует запаса баланса на 24 часа.

curl -X POST https://mycloudbird.com/api/v1/servers/52481234/actions/resize \
  -H "Authorization: Bearer cb_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{"server_type":"cpx31","upgrade_disk":false}'

{ "ok": true, "id": 52481234, "server_type": "cpx31", "upgrade_disk": false }

POST /servers/{id}/actions/rescue

Режим восстановления. Тело: enabled — булево; ssh_keys (необязательно) — массив id SSH-ключей. При включении возвращает одноразовый root_password (или null, если переданы ключи) и вступает в силу после перезагрузки — выполните reboot, чтобы войти в среду восстановления.

curl -X POST https://mycloudbird.com/api/v1/servers/52481234/actions/rescue \
  -H "Authorization: Bearer cb_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{"enabled":true}'

{
  "ok": true,
  "id": 52481234,
  "rescue_enabled": true,
  "root_password": "rT9xQ2kLpZ7m",
  "note": "Перезагрузите сервер (reboot), чтобы войти в режим восстановления."
}

POST /servers/{id}/actions/rdns

Обратная DNS-запись (PTR). Тело: ip — адрес сервера (IPv4 или один полный IPv6); dns_ptr — имя хоста, либо null (или пустая строка) для сброса к значению по умолчанию.

curl -X POST https://mycloudbird.com/api/v1/servers/52481234/actions/rdns \
  -H "Authorization: Bearer cb_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{"ip":"91.99.12.34","dns_ptr":"mail.example.com"}'

{ "ok": true, "id": 52481234, "ip": "91.99.12.34", "dns_ptr": "mail.example.com" }

POST /servers/{id}/actions/protection

Защита от удаления/переустановки. Тело: delete и/или rebuild (булевы). Для сервера обе защиты задаются одним значением (требование провайдера): передайте любой из флагов — будет установлено единое состояние. При включённой защите удаление и переустановка (rebuild) сервера запрещены.

curl -X POST https://mycloudbird.com/api/v1/servers/52481234/actions/protection \
  -H "Authorization: Bearer cb_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{"delete":true}'

{ "ok": true, "id": 52481234, "delete": true, "rebuild": true }

POST /servers/{id}/actions/snapshot

Создать снимок сервера. Тело: description (необязательно). Снимок увеличивает стоимость проекта (хранилище), поэтому требует положительного баланса. Ответ — HTTP 201.

curl -X POST https://mycloudbird.com/api/v1/servers/52481234/actions/snapshot \
  -H "Authorization: Bearer cb_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{"description":"pre-upgrade"}'

{
  "ok": true,
  "image": { "id": 98765432, "description": "pre-upgrade", "status": "creating" }
}

POST /servers/{id}/actions/console

Получить доступ к VNC-консоли. Тело не требуется. Возвращает WebSocket-URL и одноразовый пароль консоли.

{
  "wss_url": "wss://…/?server_id=52481234&token=…",
  "password": "Qx7mZ2pL9kVn"
}

POST /servers/{id}/actions/backup

Включить или выключить автоматические бэкапы. Тело: enabled — булево (true/false). Включение добавляет надбавку к стоимости и требует положительного баланса; выключение доступно всегда.

curl -X POST https://mycloudbird.com/api/v1/servers/52481234/actions/backup \
  -H "Authorization: Bearer cb_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{"enabled":true}'

{ "ok": true, "backups_enabled": true }

Метрики сервера

GET /servers/{id}/metrics

Временные ряды нагрузки. Параметры запроса: type — повторяемый параметр, одно или несколько из cpu, disk, network (например ?type=cpu&type=network; по умолчанию все три); start и end — метки времени ISO-8601; step — разрешение в секундах (необязательно). Без start/end берутся последние 30 минут.

curl "https://mycloudbird.com/api/v1/servers/52481234/metrics?type=cpu&type=network" \
  -H "Authorization: Bearer cb_live_xxx"

{
  "metrics": {
    "start": "2026-06-24T09:30:00Z",
    "end": "2026-06-24T10:00:00Z",
    "step": 60,
    "time_series": {
      "cpu": { "values": [[1750758600, "1.5"], [1750758660, "2.1"]] },
      "network.0.bandwidth.in":  { "values": [[1750758600, "1024.0"]] },
      "network.0.bandwidth.out": { "values": [[1750758600, "512.0"]] }
    }
  }
}

В каждой паре [метка_времени, значение] метка времени — число (Unix-секунды), а значение — строка. Набор рядов в time_series зависит от запрошенных типов — перебирайте ключи, не полагайтесь на фиксированный список.

Справочники

GET /server-types

Доступные конфигурации и цена в ₸ (за час и за месяц) для локации fsn1.

{
  "location": "fsn1",
  "server_types": [
    {
      "name": "cx22",
      "description": "CX22",
      "cores": 2,
      "memory_gb": 4,
      "disk_gb": 40,
      "cpu_type": "shared",
      "architecture": "x86",
      "price_hourly_kzt": 6.59,
      "price_monthly_kzt": 4290,
      "available": true
    }
  ]
}

Сервер создаётся по полю name (например cx22).

GET /images

Образы. Параметр запроса type: system (системные ОС, по умолчанию), snapshot (ваши снимки) или backup (автоматические бэкапы).

curl "https://mycloudbird.com/api/v1/images?type=system" \
  -H "Authorization: Bearer cb_live_xxx"

{
  "type": "system",
  "images": [
    {
      "id": 114690387,
      "name": "ubuntu-24.04",
      "description": "Ubuntu 24.04",
      "os_flavor": "ubuntu",
      "os_version": "24.04",
      "architecture": "x86",
      "type": "system",
      "status": "available",
      "image_size_gb": null
    }
  ]
}

GET /ssh-keys

SSH-ключи, зарегистрированные в вашем проекте.

{
  "ssh_keys": [
    { "id": 18452301, "name": "laptop", "fingerprint": "3c:9a:1f:7e:…" }
  ]
}

POST /ssh-keys

Добавить публичный SSH-ключ в проект. Тело: name и public_key (строка ключа в формате OpenSSH). Затем его можно передавать при создании сервера в поле ssh_keys.

curl -X POST https://mycloudbird.com/api/v1/ssh-keys \
  -H "Authorization: Bearer cb_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{"name":"laptop","public_key":"ssh-ed25519 AAAA... user@host"}'

{ "ssh_key": { "id": 18452301, "name": "laptop", "fingerprint": "3c:9a:1f:7e:…" } }

DELETE /ssh-keys/{id}

Удалить SSH-ключ. На уже созданные серверы это не влияет (ключ был внедрён при создании).

curl -X DELETE https://mycloudbird.com/api/v1/ssh-keys/18452301 \
  -H "Authorization: Bearer cb_live_xxx"

{ "deleted": true, "id": 18452301 }

GET /api/v1

Публичный каталог — машиночитаемый список всех методов. Без авторизации.

curl https://mycloudbird.com/api/v1