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

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

Введение

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

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

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

Authorization: Bearer mx_live_xxxxxxxxxxxxxxxxxxxx

Бренд определяется токеном, а не адресом: токен MehenHost, отправленный на api.maatrix.io, всё равно тарифицируется по правилам MehenHost.

Базовый URL

https://api.maatrix.io/v1

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

Каталог

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

Серверы

Создаёт сервер. Отвечает 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":"us1","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 не поддерживаются.

Аккаунт

Баланс, расход за текущий месяц и использование квот.

Тарификация

• Почасовая: час = месячная цена ÷ 672.
• Минимум 1 час: списывается при создании, покрывает первые 60 минут.
• Месячный потолок: за календарный месяц не спишется больше месячной цены — сервер, работающий весь месяц, платит ровно месячный тариф.
• Удаление останавливает счётчик сразу.

Трафик

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

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

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

Лимиты

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

Ошибки

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