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

Программное управление виртуальными машинами MAATRIX: создание, список, действия, удаление. Все ответы — JSON, все запросы с телом — Content-Type: application/json.

Введение

API работает поверх той же инфраструктуры, что и панель. У вас свои идентификаторы серверов вида srv_xxxxxxxxxxxx — они не привязаны к внутренним id гипервизора, поэтому не сломаются при миграции машины или смене оборудования.

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

Каждый запрос к /v1/* требует токен в заголовке. Токен создаётся в панели управления и показывается один раз.

Authorization: Bearer mx_live_xxxxxxxxxxxxxxxxxxxx

Базовый URL

https://api.maatrix.io/v1

Служебная проверка доступности (без токена): GET /health. Каждый ответ несёт X-Request-Id — указывайте его в обращениях в поддержку.

Каталог

Справочники регионов и образов ОС. Цены — per-unit (cpu/ram/disk), фиксированных планов нет. /v1/plans оставлен для совместимости и возвращает ту же rate-card.

Цена зависит от локации: базовый тариф — US; UK +6%, FR +12% (как средняя разница тарифов на maatrix.io). Передавайте region=us2|uk3|fr1 в GET /v1/pricing и при POST /v1/servers. В quote будут region и location_factor.

GET /v1/pricing без параметров — ставки и правила трафика. С параметрами ?cpu=&ram=&disk= — готовый quote для конфигурации. Если на аккаунте есть постоянная скидка, в ответе будут discount_percent, цена без скидки (monthly_list) и цена со скидкой (monthly / hourly).

curl -s https://api.maatrix.io/v1/pricing?cpu=2&ram=4&disk=40 \
  -H "Authorization: Bearer mx_live_..."

{
  "discount_percent": 30,
  "quote": {
    "cpu": 2, "ram": 4, "disk": 40,
    "currency": "GBP",
    "monthly_list": 16.00,
    "monthly": 11.20,
    "hourly": 0.016667,
    "monthly_usd": 14.56,
    "hourly_usd": 0.021667
  }
}

Серверы

Создаёт сервер. Отвечает 202 и объектом со статусом provisioning — машина готовится в фоне, опрашивайте её по id. Передавайте Idempotency-Key, чтобы повтор при потере ответа не создал дубль.

curl -X POST https://api.maatrix.io/v1/servers \
  -H "Authorization: Bearer mx_live_..." \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"region":"us2","cpu":6,"ram":12,"disk":200,"image":"ubuntu24"}'

Список, карточка и удаление. Удаление останавливает тарификацию немедленно, не дожидаясь фактического сноса на гипервизоре.

Действия

Тело {"type": "..."}. Доступно: start, stop, restart, reset_password, set_traffic_policy (с полем policy).

curl -X POST https://api.maatrix.io/v1/servers/srv_xxx/actions \
  -H "Authorization: Bearer mx_live_..." \
  -d '{"type":"reset_password"}'

Доступы

Сгенерированный root-пароль отдаётся один раз и доступен 15 минут после установки. Потеряли — сбросьте действием reset_password. SSH-ключи в v1 не поддерживаются.

Аккаунт

Баланс кабинета (в USD-эквиваленте), расход за текущий месяц, квоты и постоянная скидка аккаунта (если назначена поддержкой).

curl -s https://api.maatrix.io/v1/account \
  -H "Authorization: Bearer mx_live_..."

{
  "account": {
    "id": "acc_...",
    "brand": "maatrix",
    "balance_usd": 12.34,
    "currency": "GBP",
    "discount_percent": 30,
    "month_to_date_usd": 1.05,
    "quota": { "servers": { "limit": 20, "used": 1 }, "...": "..." }
  }
}

Поле discount_percent — постоянная скидка на создание и тарификацию серверов через API (0, если скидки нет). Итоговая цена конфигурации со скидкой — в GET /v1/pricing?cpu=&ram=&disk= (см. раздел «Каталог»).

Тарификация

Базовые цены MAATRIX API указаны в GBP: 1 MAAT = 1 GBP. В ответах currency, monthly и hourly обозначают базовую валюту и цену. Поля monthly_usd и hourly_usd содержат эквивалент в долларах по текущему курсу. В MehenHost сохраняется USD и 1 MAAT = 1 USD.

• Почасовая: час = месячная цена ÷ 672.
• Минимум 1 час: списывается при создании, покрывает первые 60 минут.
• Месячный потолок: за календарный месяц не спишется больше месячной цены — сервер, работающий весь месяц, платит ровно месячный тариф.
• Удаление останавливает счётчик сразу.
• Постоянная скидка аккаунта: если назначена, применяется при POST /v1/servers и в quote у GET /v1/pricing. Размер смотрите в GET /v1/account → discount_percent.

Трафик

Включён 1 ТБ/мес на машину (rx+tx). При превышении — политика, которую вы выбираете:

• shape — скорость режется до 10 Мбит/с до конца месяца (по умолчанию, бесплатно);
• bill — доплата $5 за каждый ТБ сверх лимита.

Сменить политику на лету: действие set_traffic_policy. Текущий расход виден в поле traffic карточки сервера.

Лимиты

Ограничение частоты — 120 запросов в минуту на токен (заголовки RateLimit-*). Квоты аккаунта (число серверов, vCPU, RAM, одновременные создания) повышаются через поддержку. Создание отклоняется с 503 no_capacity, если на узле нет физической памяти — так узел с клиентами защищён от перегрузки.

Ошибки

Формат: {"error":{"code","message","request_id"}}.