API

Всё, что видно на этих страницах, можно получить запросом без токена. Токен бота нужен, чтобы управлять своими нодами и получать события.

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

Базовый адрес вашего пула плюс путь (в примере он в переменной MTPOOL_URL). Ответы в JSON, время в формате RFC 3339, длительности в секундах. Страницы обновляются раз в 30 секунд, чаще опрашивать API нет смысла. Заголовок ETag экономит трафик: пришлите его в If-None-Match и получите 304, если ничего не изменилось.

curl -s "$MTPOOL_URL/api/v1/nodes" | jq '.[] | {id, state}'

Публичные данные

Токен не нужен

GET /api/v1/nodes

Список нод с состоянием, ролью и последней проверкой.

GET /api/v1/nodes/{id}

Одна нода: голоса сенсоров в последнем раунде.

GET /api/v1/nodes/{id}/history

Проверки ноды за сутки, по 15 минут. Нет корзины значит нет данных.

GET /api/v1/domains

Домены и их текущие мастера.

GET /api/v1/links

Ссылки для подключения и адреса QR-кодов.

GET /api/v1/links/{id}/qr.svg

QR-код ссылки в SVG.

GET /api/v1/bans ?limit&before

История банов, постранично.

GET /api/v1/stats/clients ?range

Клиенты по доменам за период: 10m, 1h, 24h или 7d.

GET /api/v1/stats/series ?range

Ряды для графиков за период.

GET /api/v1/stats/summary ?range

Сводка за период: 24h, 7d или 30d.

GET /api/v1/openapi.json

Описание API в формате OpenAPI 3.

GET /install.sh

Скрипт установки ноды.

GET /releases/{name}

Файл выпуска агента ноды.

Токен для бота

Выдаётся владельцем в панели

Передавайте токен в заголовке Authorization: Bearer. Бот видит только ноды своего владельца и не может менять настройки пула.

curl -s -X POST "$MTPOOL_URL/api/v1/me/nodes/ID/recheck" \
  -H "Authorization: Bearer $MTPOOL_BOT_TOKEN"

GET /api/v1/me

Кто владелец токена и какие у него права.

GET /api/v1/me/nodes

Ноды владельца.

POST /api/v1/me/nodes/{id}/recheck

Запустить внеочередную проверку ноды.

POST /api/v1/me/nodes/{id}/retire

Вывести ноду из пула.

GET /api/v1/me/webhooks

Список вебхуков.

POST /api/v1/me/webhooks

Создать вебхук.

DELETE /api/v1/me/webhooks/{id}

Удалить вебхук.

GET /api/v1/me/webhooks/{id}/deliveries ?limit&before

Журнал доставок.

POST /api/v1/me/webhooks/{id}/test

Отправить проверочное событие.

Вебхуки

Пул сам сообщит о событии

События: node.registered, node.quarantined, node.recovered, node.banned, node.dead, node.pruned, ban.lifted, master.changed.

Каждая доставка подписана: заголовок X-MTPooL-Signature имеет вид t=<время>,v1=<подпись>. Подпись это HMAC-SHA256 от строки <время>.<тело> на секрете вебхука. Проверьте её, прежде чем верить событию.

import hmac, hashlib

def verify(secret: bytes, body: bytes, header: str) -> bool:
    parts = dict(p.split("=", 1) for p in header.split(","))
    signed = parts["t"].encode() + b"." + body
    expected = hmac.new(secret, signed, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, parts["v1"])

Ошибки

Ошибки приходят как application/problem+json. Поле code стабильно, на него можно опираться в коде. Ломающие изменения появляются только в новой версии пути.

{
  "type": "about:blank",
  "title": "Not found",
  "status": 404,
  "code": "not_found",
  "detail": "No node with this id."
}