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

Notifly предоставляет REST API для управления каналами, клиентами, сообщениями, мониторингом, метриками и пользователями. Все примеры используют базовый URL https://notifly.ru (можно подставить через переменную $NOTIFLY_URL). Админка (веб-интерфейс) живёт на https://app.notifly.ru/.

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

Notifly использует три типа токенов:

Тип	Префикс	Назначение
App-токен	A	Только отправка сообщений (POST /message, POST /ask)
Client-токен	C	Управление ресурсами и получение сообщений
MCP-код	M	Машинный доступ (read или read+write), см. MCP

Токен можно передать тремя способами:

# 1. Заголовок X-Notifly-Key
curl -H "X-Notifly-Key: CaQw5lL_L.yiRbN" https://notifly.ru/application

# 2. Query-параметр
curl "https://notifly.ru/application?token=CaQw5lL_L.yiRbN"

# 3. Bearer-токен
curl -H "Authorization: Bearer CaQw5lL_L.yiRbN" https://notifly.ru/application

Также поддерживается Basic Auth (логин/пароль) везде, где принимается client-токен.

---

Информация о сервере

Эндпоинты доступны без аутентификации.

GET /health — проверка здоровья

curl https://host/health

{"health": "green", "database": "green"}

GET /version — версия сервера

curl https://host/version

{"version": "ya-1.0.0", "commit": "...", "buildDate": "..."}

GET /serverinfo — флаги сервера

curl https://host/serverinfo

{"version": "ya-1.0.0", "register": false, "oidc": false}

---

Авторизация (сессия)

POST /auth/local/login — вход по логину/паролю

Создаёт клиентскую сессию. Возвращает client-токен и устанавливает cookie.

curl -u admin:admin https://host/auth/local/login \
  -X POST -d "name=my-cli-client"

{
  "id": 1,
  "name": "my-cli-client",
  "token": "CaQw5lL_L.yiRbN",
  "user_id": 1,
  "platform": "web"
}

POST /auth/logout — выход

curl -H "X-Notifly-Key: CaQw5lL_L.yiRbN" \
  https://host/auth/logout -X POST

POST /user/reset-password — запросить сброс пароля

Публичный эндпоинт (без авторизации). Отправляет на указанный email письмо со ссылкой для сброса пароля. Ответ всегда 200, даже если пользователя нет, — чтобы не раскрывать, какие адреса зарегистрированы.

curl https://host/user/reset-password \
  -H "Content-Type: application/json" \
  -d '{"email": "user@example.com"}'

POST /user/reset-password/confirm — подтвердить сброс пароля

Публичный эндпоинт. Принимает token из письма и новый пароль pass.

curl https://host/user/reset-password/confirm \
  -H "Content-Type: application/json" \
  -d '{"token": "<из письма>", "pass": "новый-пароль"}'

GET /user/verify — подтверждение email

Публичный эндпоинт. Открывается по ссылке из письма-подтверждения (/user/verify?token=...) и активирует адрес пользователя.

curl "https://host/user/verify?token=<из письма>"

---

Каналы

Канал (application в URL API — для совместимости с протоколом Gotify) — это источник сообщений. У каждого канала есть свой app-токен для отправки.

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

Все эндпоинты каналов требуют client-токен или Basic Auth.

GET /application — список каналов

curl -u admin:admin https://host/application

[
  {
    "id": 1,
    "token": "AGdjfk_L.dKe8q",
    "name": "Мониторинг",
    "description": "Оповещения от системы мониторинга",
    "internal": false,
    "image": "image/appicon/1.png",
    "defaultPriority": 5,
    "lastUsed": "2025-01-15T12:00:00Z"
  }
]

POST /application — создать канал

curl -u admin:admin https://host/application \
  -H "Content-Type: application/json" \
  -d '{"name": "CI/CD", "description": "Уведомления о сборках", "defaultPriority": 5}'

Поля запроса:

Поле	Тип	Обязательное	Описание
name	string	✓	Название канала
description	string		Описание
defaultPriority	integer		Приоритет по умолчанию

PUT /application/{id} — обновить канал

curl -u admin:admin https://host/application/1 \
  -X PUT -H "Content-Type: application/json" \
  -d '{"name": "CI/CD v2", "description": "Обновлённое описание"}'

DELETE /application/{id} — удалить канал

curl -u admin:admin https://host/application/1 -X DELETE

GET /application/{id}/status — сводный статус канала

Возвращает агрегированный статус канала (heartbeat-сводка, последняя активность).

curl -u admin:admin https://host/application/1/status

POST /application/{id}/delivery/test — тест доставки во внешние интеграции

Немедленно (в обход эскалации) отправляет тестовое уведомление через включённые исходящие адаптеры канала (Slack, Telegram, webhook) и возвращает результат по каждому. Опциональное тело {"adapter": "slack"} ограничивает проверку одним адаптером.

curl -u admin:admin https://host/application/1/delivery/test \
  -H "Content-Type: application/json" -d '{"adapter": "telegram"}'

{"results": {"telegram": {"ok": true}, "slack": {"ok": false, "error": "..."}}}

---

Сообщения

POST /message — отправить сообщение

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

Для отправки сообщений используется app-токен (не client-токен!).

curl "https://host/message?token=AGdjfk_L.dKe8q" \
  -H "Content-Type: application/json" \
  -d '{"message": "Сборка #42 завершена", "title": "CI/CD", "priority": 5}'

Или через form-data:

curl "https://host/message?token=AGdjfk_L.dKe8q" \
  -F "title=CI/CD" -F "message=Сборка #42 завершена" -F "priority=5"

Поля запроса:

Поле	Тип	Обязательное	Описание
message	string	✓	Текст сообщения
title	string		Заголовок
priority	integer		Приоритет (0–10)
extras	object		Дополнительные поля для клиентов (см. msgextras)

Пример с extras (markdown-контент):

curl "https://host/message?token=AGdjfk_L.dKe8q" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "**Готово!** Подробности: [ссылка](https://example.com)",
    "title": "Сборка",
    "priority": 5,
    "extras": {
      "client::display": {"contentType": "text/markdown"}
    }
  }'

Ответ:

{
  "id": 123,
  "appid": 1,
  "message": "Сборка #42 завершена",
  "title": "CI/CD",
  "priority": 5,
  "extras": {},
  "date": "2025-06-01T10:30:00Z"
}

GET /message — все сообщения (с пагинацией)

curl -u admin:admin "https://host/message?limit=20"

Параметры:

Параметр	Тип	По умолчанию	Описание
limit	integer	100	Количество сообщений (1–200)
since	integer		Курсор пагинации: вернуть сообщения старше (с ID меньше) указанного. Берётся из paging.next предыдущей страницы

Ответ:

{
  "paging": {
    "size": 20,
    "limit": 20,
    "since": 0,
    "next": "https://host/message?limit=20&since=20"
  },
  "messages": [
    {
      "id": 1,
      "appid": 1,
      "message": "Текст сообщения",
      "title": "Заголовок",
      "priority": 5,
      "extras": {},
      "date": "2025-06-01T10:30:00Z"
    }
  ]
}

GET /application/{id}/message — сообщения канала

curl -u admin:admin "https://host/application/1/message?limit=50"

GET /message/search — полнотекстовый поиск

Ищет по сообщениям пользователя. Параметр q обязателен (минимум 2 символа). Опциональный appId ограничивает поиск одним каналом. Поддерживает пагинацию (limit, since).

curl -u admin:admin "https://host/message/search?q=ошибка&limit=20"
curl -u admin:admin "https://host/message/search?q=deploy&appId=1"

POST /message/read — отметить сообщения прочитанными

Тело: {"ids": [1, 2, 3]} — список ID сообщений.

curl -u admin:admin https://host/message/read \
  -H "Content-Type: application/json" -d '{"ids": [1, 2, 3]}'

POST /application/{id}/message/read — отметить весь канал прочитанным

curl -u admin:admin https://host/application/1/message/read -X POST

DELETE /message — удалить все сообщения

curl -u admin:admin https://host/message -X DELETE

DELETE /message/{id} — удалить сообщение

curl -u admin:admin https://host/message/123 -X DELETE

DELETE /application/{id}/message — удалить все сообщения канала

curl -u admin:admin https://host/application/1/message -X DELETE

---

Клиенты

Клиент — это устройство или приложение, которое получает сообщения и управляет ресурсами.

GET /client — список клиентов

curl -u admin:admin https://host/client

[
  {
    "id": 1,
    "name": "firefox",
    "token": "CaQw5lL_L.yiRbN",
    "lastUsed": "2025-06-01T10:00:00Z"
  }
]

POST /client — создать клиент

curl -u admin:admin https://host/client \
  -H "Content-Type: application/json" \
  -d '{"name": "my-script"}'

PUT /client/{id} — обновить клиент

curl -u admin:admin https://host/client/1 \
  -X PUT -H "Content-Type: application/json" \
  -d '{"name": "renamed-client"}'

DELETE /client/{id} — удалить клиент

curl -u admin:admin https://host/client/1 -X DELETE

Состояние и подписки устройств

Метод и путь	Описание
GET /client/online	Список client-токенов с активным WS-соединением
PUT /client/{id}/status	Сменить статус устройства, тело {"status": "active|suspended|revoked"}
GET /client/{id}/activity	Журнал активности устройства (?from=&to=&type=&limit=)
GET /client/{id}/subscriptions	Подписки устройства на каналы
PUT /client/{id}/subscriptions	Массовая замена подписок, тело {"channelIds": [1, 2]}

Самообслуживание устройства (аутентификация по device-токену самого устройства):

Метод и путь	Описание
GET /device/me/subscriptions	Свои подписки на каналы
POST /device/me/subscriptions	Подписаться, тело {"channelId": 1}
DELETE /device/me/subscriptions/{channel_id}	Отписаться от канала

---

Текущий пользователь

GET /current/user — информация о текущем пользователе

curl -u admin:admin https://host/current/user

{"id": 1, "email": "admin", "admin": true, "verified": true, "plan": "free", "balanceKopecks": 0}

POST /current/user/password — изменить пароль

curl -u admin:admin https://host/current/user/password \
  -H "Content-Type: application/json" \
  -d '{"pass": "new-secure-password"}'

Тариф, баланс и квоты

Подробности о тарифах и лимитах — на странице Квоты и тарифы.

Метод и путь	Описание
GET /user/quota-breakdown	Детальная разбивка расхода событий за день (?day=YYYY-MM-DD), почасовая и поминутная
POST /current/user/plan	Сменить тариф, тело {"plan": "free|pro|business"}
POST /current/user/topup	Пополнить баланс, тело {"amountRubles": N}

curl -u admin:admin "https://host/user/quota-breakdown?day=2026-06-23"
curl -u admin:admin https://host/current/user/plan \
  -H "Content-Type: application/json" -d '{"plan": "pro"}'

---

Управление пользователями (администратор)

Доступ

Эти эндпоинты доступны только администраторам, кроме POST /user, который доступен всем, если включена открытая регистрация.

GET /user — список пользователей

curl -u admin:admin https://host/user

[
  {"id": 1, "email": "admin", "admin": true, "verified": true, "plan": "free"},
  {"id": 2, "email": "user1@example.com", "admin": false, "verified": true, "plan": "free"}
]

POST /user — создать пользователя

curl -u admin:admin https://host/user \
  -H "Content-Type: application/json" \
  -d '{"email": "newuser@example.com", "pass": "password123", "admin": false}'

DELETE /user/{id} — удалить пользователя

curl -u admin:admin https://host/user/2 -X DELETE

---

Heartbeat-мониторы

Dead-man-switch: внешняя задача (cron, скрипт) периодически шлёт «пинг»; если пинг не приходит вовремя, Notifly присылает алерт. Подробнее — Heartbeat.

Публичный пинг (аутентификация по ping-токену H… в URL, без client-токена):

curl https://host/heartbeat/ping/HxxxxxxxxToken          # GET — удобно из cron
curl -X POST https://host/heartbeat/ping/HxxxxxxxxToken \
  -H "Content-Type: application/json" -d '{"fail_reason": "backup failed"}'

Управление (client-токен):

Метод и путь	Описание
GET /heartbeat	Список heartbeat-ов
POST /heartbeat	Создать
PUT /heartbeat/{id}	Обновить
DELETE /heartbeat/{id}	Удалить
POST /heartbeat/{id}/pause · /resume	Приостановить / возобновить
POST /heartbeat/{id}/test-alert · /test-recovery	Тестовое алерт- / recovery-уведомление

---

Мониторы

Активные проверки доступности и контента. Каждый тип имеет свою страницу с деталями.

Универсальный монитор (HTTP / TCP) → /docs/monitor/

Метод и путь	Описание
GET /monitor · POST /monitor	Список / создать
POST /monitor/test	Проверить настройки без сохранения
PUT /monitor/{id} · DELETE /monitor/{id}	Обновить / удалить
POST /monitor/{id}/pause · /resume	Приостановить / возобновить

HTTP-монитор → /docs/http-monitor/

Метод и путь	Описание
GET /http-monitor · POST /http-monitor	Список / создать
POST /http-monitor/test	Проверить запрос
PUT /http-monitor/{id} · DELETE /http-monitor/{id}	Обновить / удалить
POST /http-monitor/{id}/pause · /resume	Приостановить / возобновить

Монитор контента → /docs/content-monitor/

Метод и путь	Описание
GET /content-monitor · POST /content-monitor	Список / создать
POST /content-monitor/suggest-selector	ИИ-подбор CSS-селектора
POST /content-monitor/test-rule	Проверить правило
PUT /content-monitor/{id} · DELETE /content-monitor/{id}	Обновить / удалить
POST /content-monitor/{id}/pause · /resume	Приостановить / возобновить

Монитор портов → /docs/port-monitor/

Метод и путь	Описание
GET /port-monitor · POST /port-monitor	Список / создать
POST /port-monitor/test	Проверить порт
PUT /port-monitor/{id} · DELETE /port-monitor/{id}	Обновить / удалить
POST /port-monitor/{id}/pause · /resume	Приостановить / возобновить

Сканирование портов → /docs/port-scan/

Метод и путь	Описание
GET /port-scan · GET /port-scan/{id}	Список / один скан
POST /port-scan	Запустить скан
PATCH /port-scan/{id} · DELETE /port-scan/{id}	Обновить / удалить
POST /port-scan/{id}/cancel · /restart	Отменить / перезапустить
POST /port-scan/{id}/to-monitor	Превратить найденный порт в монитор

Workflow-монитор → /docs/workflow-monitor/

Метод и путь	Описание
GET /workflow-monitor · POST /workflow-monitor	Список / создать
POST /workflow-monitor/build-step	ИИ-сборка шага
POST /workflow-monitor/test	Прогнать сценарий
PUT /workflow-monitor/{id} · DELETE /workflow-monitor/{id}	Обновить / удалить
POST /workflow-monitor/{id}/pause · /resume	Приостановить / возобновить

Браузерный workflow → /docs/browser-workflow/

Метод и путь	Описание
GET /browser-workflow · POST /browser-workflow	Список / создать
POST /browser-workflow/build-step	ИИ-подбор действия
POST /browser-workflow/login	Захват cookie авторизации
POST /browser-workflow/test-step	Проверить шаг
PUT /browser-workflow/{id} · DELETE /browser-workflow/{id}	Обновить / удалить
POST /browser-workflow/{id}/pause · /resume	Приостановить / возобновить

Подтверждённые хосты → /docs/verified-host/

Подтверждение владения хостом перед сканированием/мониторингом.

Метод и путь	Описание
GET /verified-host	Список
POST /verified-host/start · /check	Начать / проверить подтверждение
DELETE /verified-host/{id}	Удалить

История проверок мониторов

{kind} — тип монитора (monitor, http-monitor, content-monitor, port-monitor и т. д.).

Метод и путь	Описание
GET /monitor-history/{kind}/{id}	Uptime %, время отклика, агрегаты
GET /monitor-history/{kind}/{id}/log	Подробный лог отдельных проверок

---

Почтовые ящики (Email Inbox)

Входящее письмо на адрес ящика превращается в уведомление. Подробнее — Email Inbox.

Метод и путь	Описание
GET /email-inbox · POST /email-inbox	Список / создать ящик
PUT /email-inbox/{id} · DELETE /email-inbox/{id}	Обновить / удалить
GET /email-inbox/{id}/rules · POST /email-inbox/{id}/rules	Правила обработки писем
PUT /email-inbox/{id}/rules/{rid} · DELETE /email-inbox/{id}/rules/{rid}	Обновить / удалить правило
GET /email-inbox/event	История входящих писем
GET /email-inbox/event/{eid} · DELETE /email-inbox/event/{eid}	Письмо / удалить
POST /email-inbox/rule/from-event/{eid}	ИИ-подсказка правила по письму

---

Web-скрипты

JS-сниппеты для сайта: трекинг ошибок (console_errors), события и т. п. Подробнее — Web-скрипт.

Публичный ingest (аутентификация по токену в URL, отправка из браузера):

curl -X POST https://host/script/<token> \
  -H "Content-Type: application/json" -d '{ ... }'

Управление (client-токен):

Метод и путь	Описание
GET /web-script · POST /web-script	Список / создать
PUT /web-script/{id} · DELETE /web-script/{id}	Обновить / удалить
GET /web-script/{id}/sourcemaps · POST /web-script/{id}/sourcemaps	Source maps
DELETE /web-script/{id}/sourcemaps/{smid}	Удалить source map
GET /web-script/{id}/issues	Сгруппированные ошибки (issues)
POST /web-script/{id}/issues/{iid}/resolve	Пометить issue решённым
DELETE /web-script/{id}/issues/{iid}	Удалить issue

---

Webhook-роутер

Принимает входящие вебхуки и маршрутизирует их по правилам в каналы. Это singleton на пользователя с path-based маршрутизацией. Подробнее — Webhook-роутер.

Публичный приём (аутентификация по токену в URL, любой путь после токена):

curl -X POST https://host/router/<token>/любой/путь \
  -H "Content-Type: application/json" -d '{ ... }'

Управление (client-токен):

Метод и путь	Описание
GET /webhook-router · PUT /webhook-router	Получить / обновить роутер
POST /webhook-router/rotate-token	Сменить публичный токен
GET /webhook-router/rule · POST /webhook-router/rule	Правила маршрутизации
PUT /webhook-router/rule/{rid} · DELETE /webhook-router/rule/{rid}	Обновить / удалить правило
GET /webhook-router/event · GET /webhook-router/event/{eid}	История событий
DELETE /webhook-router/event/{eid}	Удалить событие
GET /webhook-router/message · DELETE /webhook-router/message/{mid}	Маршрутизированные сообщения
POST /webhook-router/rule/from-event/{eid}	ИИ-подсказка правила по событию

---

Метрики

Числовые временные ряды с алертами. Подробнее — Метрики.

Публичный приём метрики (аутентификация по токену M… в URL):

curl -X POST https://host/metric/<token> \
  -H "Content-Type: application/json" -d '{ ... }'

Управление (client-токен):

Метод и путь	Описание
GET /metric-source · POST /metric-source	Источники метрик
PUT /metric-source/{id} · DELETE /metric-source/{id}	Обновить / удалить источник
GET /metric-source/{id}/metrics	Метрики источника
PATCH /metric-source/{id}/metrics/{mid} · DELETE /metric-source/{id}/metrics/{mid}	Тип / удалить метрику
GET /metric-source/{id}/metrics/{mid}/series	Временной ряд значений
GET /metric-source/{id}/alerts · POST /metric-source/{id}/alerts	Алерты по метрике
PUT /metric-source/{id}/alerts/{aid} · DELETE /metric-source/{id}/alerts/{aid}	Обновить / удалить алерт

---

Делегированный доступ (Channel Shares)

Предоставление другим пользователям доступа к каналу по email. Подробнее — Доступ к каналам.

Метод и путь	Описание
GET /application/{id}/share · POST /application/{id}/share	Список / создать шару на канал
PUT /share/{id} · DELETE /share/{id}	Обновить / отозвать шару
GET /share/incoming	Шары, предоставленные мне
GET /share/recipients	Адреса, с кем я уже делился (подсказки)
POST /share/{id}/accept · /decline	Принять / отклонить шару
POST /share/join	Присоединиться по токену

---

MCP-токены

Токены машинного доступа (M…) для интеграции через MCP. Генерируются из админки.

Метод и путь	Описание
GET /mcp/token · POST /mcp/token	Список / создать токен
PUT /mcp/token/{id} · DELETE /mcp/token/{id}	Обновить / удалить токен

---

Вопросы канала (Ask)

Интерактивные вопросы: канал спрашивает — пользователь отвечает из интерфейса. Подробнее — Ask.

Отправка вопроса использует app-токен:

Метод и путь	Аутентификация	Описание
POST /ask	app-токен	Задать вопрос от имени канала
GET /ask/pending-answers	app-токен	Забрать готовые ответы
POST /ask/ack	app-токен	Подтвердить получение ответов
GET /ask-question/{id}	app-токен	Узнать ответ на конкретный вопрос
POST /ask-question/{id}/answer	client-токен	Ответить на вопрос из UI
DELETE /ask-question/{id}	client-токен	Отменить вопрос
POST /message/{id}/answer	client-токен	Ответить на вопрос из сообщения

---

ИИ-ассистент

Чат-копайлот для онбординга и помощи. Подробнее — Ассистент.

Метод и путь	Описание
GET /assistant/threads	Список бесед
GET /assistant/threads/{id}/messages	История сообщений беседы
DELETE /assistant/threads/{id}	Удалить беседу
POST /assistant/chat	Отправить сообщение ассистенту

---

Поток сообщений в реальном времени

Есть два независимых канала live-обновлений. Подробнее — на странице WebSocket.

WebSocket (/ws)

Основной канал доставки push-сообщений в реальном времени. Подключение — по client-токену в query-параметре token:

# С помощью wscat
wscat -c "wss://host/ws?token=CaQw5lL_L.yiRbN"

const ws = new WebSocket("wss://host/ws?token=CaQw5lL_L.yiRbN");
ws.onmessage = (event) => {
  const msg = JSON.parse(event.data);
  console.log(`[${msg.title}] ${msg.message} (приоритет: ${msg.priority})`);
};

Каждое входящее событие — JSON-объект Message:

{
  "id": 124,
  "appid": 1,
  "message": "Новое сообщение",
  "title": "Заголовок",
  "priority": 5,
  "extras": {},
  "date": "2025-06-01T10:31:00Z"
}

SSE (/stream)

Отдельный эндпоинт Server-Sent Events (GET /stream, Content-Type: text/event-stream) для live-обновления интерфейсов. Это обычный HTTP-GET-стрим — используйте EventSource в браузере (аутентификация через cookie-сессию или client-токен). Сервер шлёт именованные события (например connected, channel:status_changed) и периодические keepalive-комментарии.

const es = new EventSource("https://host/stream", { withCredentials: true });
es.addEventListener("connected", () => console.log("подключено"));
es.onmessage = (event) => console.log(event.data);

---

Примеры на разных языках

Python

import requests

# Отправить сообщение
requests.post("https://host/message?token=AGdjfk_L.dKe8q", json={
    "title": "Бэкап",
    "message": "Резервное копирование завершено",
    "priority": 2,
})

# Получить все сообщения
resp = requests.get("https://host/message", auth=("admin", "admin"))
for msg in resp.json()["messages"]:
    print(f"[{msg['title']}] {msg['message']}")

Go

package main

import (
    "net/http"
    "net/url"
)

func main() {
    http.PostForm("https://host/message?token=AGdjfk_L.dKe8q",
        url.Values{
            "title":   {"Deploy"},
            "message": {"Версия 2.0 развёрнута"},
        })
}

JavaScript (Node.js)

// Отправить сообщение
const resp = await fetch("https://host/message?token=AGdjfk_L.dKe8q", {
  method: "POST",
  headers: {"Content-Type": "application/json"},
  body: JSON.stringify({
    title: "CI",
    message: "Тесты пройдены",
    priority: 3,
  }),
});
console.log(await resp.json());

PowerShell

# Отправить сообщение
Invoke-RestMethod -Uri "https://host/message?token=AGdjfk_L.dKe8q" `
  -Method POST -Body @{
    title    = "Отчёт"
    message  = "Ежедневный отчёт сгенерирован"
    priority = 1
  }

---

Коды ответов

Код	Значение
200	Успешно
400	Некорректный запрос (неверные параметры)
401	Не авторизован (отсутствует или невалидный токен)
403	Запрещено (недостаточно прав)
404	Ресурс не найден