Skip to content

Справочник API ​

nxs-anomaly предоставляет две HTTP-поверхности:

  1. Приём алертов — /integrations/v1/*, /v2/alert/pool (аутентификация ключом интеграции в URL)
  2. Управляющий API — /api/v1/* (пользовательская сессия или scoped API key) — нативный контракт

Плюс служебные эндпоинты: /live, /health, /ready, /metrics.

Машиночитаемый контракт: нативная поверхность /api/v1 формализована в openapi.json (OpenAPI 3.1) — схемы аутентификации, общая модель ошибки ({"error": "…"}), конверт пагинации и пополевые схемы основных объектов: identity, пользователь, команда, расписание, цепочка эскалации, интеграция, группа алертов, алерт, уведомление и попытка доставки. В этих схемах required перечисляет ровно те ключи, которые движок пишет безусловно, так что необязательное там действительно может отсутствовать; при этом все они допускают дополнительные свойства, потому что хранение — JSONB.

Фронтенд компилируется против типов, сгенерированных из этого файла (frontend/src/api/schema.d.ts, npm run openapi:types): src/api/types.ts и src/api/client.ts ссылаются на сгенерированные схемы, а не переобъявляют их, поэтому изменение спецификации всплывает как ошибка TypeScript. npm run openapi:check падает, если закоммиченный сгенерированный файл разошёлся со спецификацией.

internal/server/openapi_contract_test.go ловит расхождение в обе стороны: каждый задокументированный маршрут обязан диспетчеризоваться (паникующий обработчик считается провалом, а не успехом), каждый литерал маршрута /api/v1 в роутере обязан посегментно совпасть с задокументированным путём, каждый sub-resource, роутящийся по суффиксу (…/timeline, …/duty-on), обязан завершать задокументированный путь, и каждый префикс авторизации в auth.go обязан вести куда-то задокументированное. Этот текстовый справочник остаётся человекочитаемым представлением того же.


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

Управляющий API (/api/v1/*) по умолчанию закрыт. Люди используют web-сессию после входа по паролю, автоматизация — scoped API key. Без настроенных credentials запросы отклоняются; открытый dev-режим включается только явно NXS_ANOMALY_ALLOW_ANONYMOUS=true.

API key передаётся любым из двух заголовков:

X-API-Key: <token>
Authorization: Bearer <token>

Пользовательские сессии ​

Текущий principal и его presentation-настройки:

МетодПутьНазначение
GET/api/v1/auth/meТекущий principal, permissions, команды, locale и timezone. Для service principal последние два поля пустые.
PUT/api/v1/auth/preferencesИзменить собственные locale и/или timezone. Доступно любой пользовательской роли; права и остальные поля user изменить этим endpoint нельзя.

Поддерживаемые locale: ru-RU, en-US и пустая строка («следовать браузеру»). Timezone задаётся IANA-именем (Europe/Moscow, Asia/Novosibirsk, UTC); неизвестное имя возвращает 400. Пример:

bash
curl -X PUT "$API/api/v1/auth/preferences" \
  -H 'Content-Type: application/json' \
  -d '{"locale":"en-US","timezone":"Europe/Berlin"}'

Люди входят под собой; API-ключи — для автоматизации. Сессия — это HttpOnly-кука с SameSite=Strict: скрипты страницы её не читают, и в теле ответа она не возвращается.

МетодПутьДоступОписание
GET/api/v1/auth/methodsбез аутентификацииКакие способы входа предлагает эта инсталляция.
POST/api/v1/auth/loginбез аутентификации{"login": "...", "password": "..."} → кука сессии. Ограничен по частоте на IP.
POST/api/v1/auth/logoutбез аутентификацииОтзывает предъявленную сессию.
GET/api/v1/auth/meлюбойТекущий субъект, его роль и фактические права.
POST/api/v1/auth/passwordлюбойСмена своего пароля (current_password, new_password). Разлогинивает везде, включая подключённые телефоны.
GET/api/v1/auth/sessionsлюбойСвои живые сессии; собственная строка помечена current.
DELETE/api/v1/auth/sessions/{id}любойОтозвать одну из своих сессий. Чужой id даёт 404.
DELETE/api/v1/users/{id}/sessionsadminРазлогинить пользователя везде — веб-сессии и подключённые телефоны, — не трогая пароль.
PUT/api/v1/users/{id}/passwordadminЗадать пароль другому пользователю. Разлогинивает его везде, включая телефоны.
DELETE/api/v1/users/{id}/passwordadminУдалить пароль пользователя. Разлогинивает его везде, включая телефоны.
GET/api/v1/users/{id}/exportadminВсё, что инсталляция хранит о человеке. Хеш пароля и хеши токенов не выгружаются никогда; факт наличия пароля сообщается. Секции аудита ограничены audit_export_limit, и это число возвращается в ответе.
POST/api/v1/users/{id}/eraseadminУдалить персональные данные человека. Учётные данные, сессии, устройства и ChatOps-каналы удаляются; запись пользователя, адреса доставки и actor_name/request_ip в аудите псевдонимизируются; сами события аудита не трогаются. Ответ — проверка (verified, residue), а не обещание; копии вне базы перечислены в out_of_scope. Идемпотентно.

Для входа нужны и пароль, и роль. Пользователь без роли — это запись в списке: его можно пейджить, но войти он не может. Поскольку поиск сессии читает запись пользователя на каждом запросе, снятие роли или удаление пользователя действует немедленно, не дожидаясь истечения сессии.

Пароли хранятся как PBKDF2-HMAC-SHA256 (600 000 итераций, соль на пользователя); токены сессий — как SHA-256, поэтому дамп базы не содержит пригодных сессий. Минимальная длина пароля — 12 символов.

Переменная окруженияПо умолчаниюОписание
NXS_ANOMALY_BOOTSTRAP_ADMIN_USERNAME—Аварийный администратор: создаётся (или повышается) при каждом старте.
NXS_ANOMALY_BOOTSTRAP_ADMIN_PASSWORD—Его пароль, переустанавливается при каждом старте.
NXS_ANOMALY_SESSION_TTL_SECONDS43200Абсолютное время жизни сессии (12 ч).
NXS_ANOMALY_SESSION_COOKIE_SECUREtruefalse — только для локальной разработки по обычному HTTP.
NXS_ANOMALY_AUDIT_RETENTION_DAYS0Удалять события аудита старше N дней. 0 — хранить всё.
NXS_ANOMALY_NOTIFICATION_RETENTION_DAYS0Удалять завершённые уведомления старше N дней.
NXS_ANOMALY_DELIVERY_ATTEMPT_RETENTION_DAYS0Удалять записи о попытках доставки старше N дней.
NXS_ANOMALY_WEB_SESSION_RETENTION_DAYS0Удалять web-сессии старше N дней.
NXS_ANOMALY_BLOCKED_CHANNELS—Запрещённые каналы доставки, через запятую.
NXS_ANOMALY_EGRESS_ALLOWLIST—Разрешённые адресаты исходящей доставки: хосты и/или CIDR.
NXS_ANOMALY_MOBILE_STREAM_INTERVAL_SECONDS10Как часто перечитывает поток событий телефона: это задержка между алертом и звонком.
NXS_ANOMALY_MOBILE_STREAM_MAX200Сколько потоков держит одна реплика; сверх того — 503 с Retry-After.
NXS_ANOMALY_BLOCK_PRIVATE_WEBHOOKS_EXCEPT—Приватные адресаты, которые SSRF-гейт пропускает: хосты, суффиксы .domain и/или CIDR. Loopback и link-local не исключаются никогда.

Каждое событие несёт request_id запроса — то же значение возвращается в заголовке X-Request-ID и пишется в журнал доступа, — поэтому «всё, что сделал один запрос» достаётся одним запросом: GET /api/v1/audit?request_id=.... События, записанные worker-ом, его не несут: за ними нет запроса. Журнал также доступен для просмотра администраторам на странице /audit.

Retention аудита по умолчанию выключен: ценность журнала в его полноте, поэтому удаление — явное решение с названным горизонтом. Когда он включён, проход worker-а внутри одной транзакции отключает append-only-триггер таблицы, удаляет строки, включает триггер обратно и пишет в журнал, сколько строк ушло. Это намеренная узкая брешь — до неё не дотягивается ни один путь запроса, и схемой сервис всегда владел сам, — сделанная потому, что альтернативой был неограниченный рост с ручным ALTER в качестве незадокументированного способа чистки.

Переменные bootstrap — это ещё и путь восстановления пароля, поэтому они применяются при каждом старте, а не только на пустой базе. Снимите их, когда аварийная учётная запись перестанет быть нужна.

Роли ​

РольМожет
viewerчитать всё
responder+ подтверждать / снимать подтверждение / закрывать / переоткрывать / заглушать
editor+ создавать и менять конфигурацию (интеграции, цепочки, расписания, команды)
admin+ управление доступом, журнал аудита, принудительная эскалация и отладка маршрутов

Роли упорядочены: каждая включает всё, что даёт предыдущая.

Разграничение по командам ​

NXS_ANOMALY_TEAM_SCOPING=true ограничивает вошедшего пользователя объектами его команд плюс объектами без владельца. По умолчанию выключено.

Правило:

  • объект без команды виден всем — поэтому включение флага ничего не меняет на инсталляции, где команды никогда не назначались;
  • объект, принадлежащий команде, виден участникам этой команды;
  • тот, кто не состоит ни в одной команде, видит объекты без владельца и больше ничего. Исключение человека из команды сужает его обзор, но никогда не расширяет;
  • администраторы, API-ключи и worker под разграничение не попадают.

Интеграции несут team_id (миграция 0020); у расписаний и ChatOps-каналов он был и раньше. Алерты и группы алертов разграничиваются через свою интеграцию, а не копированием team_id в каждую строку, поэтому смена владельца интеграции действует немедленно, не оставляя устаревших строк.

Отказы возвращают 403, и сообщение никогда не называет команду-владельца. Массовые действия над алертами фильтруют, а не падают: запрещённые id возвращаются в списке forbidden рядом с acknowledged/resolved/silenced.

Уведомления несут integration_id, денормализованный из своей группы алертов (миграция 0021), и разграничиваются через него. В отличие от скопированного team_id это значение не может устареть: группа алертов никогда не переезжает между интеграциями. Попытки доставки наследуют команду своего уведомления, поэтому разграниченный вызывающий обязан передать notification_id — нефильтрованная лента была бы всеми попытками инсталляции и отклоняется с 400. Неразграниченные вызывающие по-прежнему получают ленту целиком, что и нужно оператору, разбирающему доставку.

API-ключи (автоматизация) ​

Переменная окруженияФорматДействие
NXS_ANOMALY_API_KEYодин токенadmin (полный доступ)
NXS_ANOMALY_API_KEYStok1:admin,tok2:viewerроль на токен

Запись в NXS_ANOMALY_API_KEYS без :роль разрешается в viewer, и сервер предупреждает об этом при старте (api_keys_without_a_role). Раньше это означало admin: учётные данные автоматизации обязаны заявлять, что им можно, а наследование самой широкой роли из умолчания — прямая противоположность этому. Нераспознанная роль деградирует до viewer по той же причине: ошибка в конфигурации развёртывания должна сужать доступ, а не расширять. Дореформенное имя readonly по-прежнему принимается и читается как viewer.

NXS_ANOMALY_API_KEY это не затрагивает, он остаётся admin: весь смысл этой переменной — «единственный admin-ключ», и это явная область, названная прямо в имени.

Без настроенных учётных данных управляющий API отклоняет все запросы.NXS_ANOMALY_ALLOW_ANONYMOUS=true возвращает прежнее открытое поведение для локальной разработки; сервер предупреждает об этом при каждом старте.

Если запрос несёт одновременно куку сессии и API-ключ, побеждает сессия — чтобы в журнале аудита стоял человек, а не общий ключ.


Служебные эндпоинты ​

МетодПутьОписание
GET/liveLiveness — 200, пока процесс обслуживает HTTP; базу не трогает. Для livenessProbe в k8s.
GET/health, /readyReadiness — пинг базы. 503 при недоступной базе. Для readinessProbe.
GET/metricsМетрики Prometheus.

Ответ /health:

json
{
  "status": "ok",
  "db_ok": true,
  "version": "1.2.3",
  "uptime_seconds": 3600,
  "worker_cycles_completed": 720,
  "last_worker_cycle_at": "2026-06-07T12:00:00+00:00"
}

При деградации: status: "degraded" и db_ok: false рядом с db_error.


Приём алертов ​

МетодПутьФормат источника
POST/integrations/v1/webhook/{key}Универсальный алерт nxs-anomaly
POST/integrations/v1/alertmanager/{key}Prometheus Alertmanager v4
POST/integrations/v1/pagerduty/{key}PagerDuty Events v2
POST/integrations/v1/victorops/{key}VictorOps / Splunk On-Call
POST/integrations/v1/grafana-alerting/{key}Webhook Grafana Alerting
POST/integrations/v1/opensearch/{key}OpenSearch Alerting, шаблон канала
POST/integrations/v1/elasticsearch/{key}Kibana Rules, Elasticsearch Watcher
POST/v2/alert/poolLegacy-пул NXS (аутентификация заголовком X-Auth-Key)

{key} — маршрутный ключ интеграции. Опциональная проверка HMAC через X-Hub-Signature-256 или X-Anomaly-Signature действует для /integrations/v1/webhook/{key}, если у интеграции задан webhook_secret: заголовок — hex HMAC-SHA256 тела запроса ровно в том виде, в каком оно отправлено, с префиксом sha256= или без него. Остальные форматы их отправители не подписывают, они аутентифицируются только ключом. Возвращает 202 Accepted (или 200 для victorops и legacy), 404 при неизвестном ключе, 400 при ошибке валидации, 429 при превышении лимита и 503 с Retry-After, когда отправителю надо повторить позже: база недоступна, транзакция столкнулась с другой, у интеграции на этой реплике уже 128 приёмов в очереди, этот приём ждал своей очереди, пока на ответ не осталось только впритык времени, или webhook_secret интеграции — ссылка env:, которую этот экземпляр не может разрешить.

Чтобы закрыть окно повторной отправки, отправитель может добавить X-Anomaly-Timestamp (unix-секунды). Тогда подпись считается по {timestamp}.{body}, а запрос, чей timestamp отличается от часов сервера больше чем на 5 минут, отклоняется с 400 — перехваченный запрос нельзя отправить позже. С NXS_ANOMALY_WEBHOOK_REQUIRE_TIMESTAMP=true (в чарте — extraConfig) отклоняется и подпись только по телу; по умолчанию она по-прежнему принимается. Повтор внутри окна попадает в обычную дедупликацию группы алертов.

Алерты одной интеграции записываются строго по очереди, поэтому одна интеграция принимает порядка 25–100 алертов в секунду в зависимости от базы. Каждая реплика пускает к базе не больше двух приёмов одной интеграции одновременно и держит в очереди ещё до 128, не занимая соединений; сверх этого сразу отвечает 503. Приём ждёт своей очереди до момента, к которому должен быть ответ (начало запроса плюс NXS_ANOMALY_HTTP_WRITE_TIMEOUT_SECONDS, по умолчанию 30 с), за вычетом запаса на собственную работу — 2 с плюс 100 мс на каждый алерт запроса, — и затем тоже получает 503, поэтому таймаут записи не обрывает ответ: одиночный алерт ждёт до ~28 с, пачка Alertmanager из ста алертов — до ~18 с. Шторм в одну интеграцию замедляет только её, а не весь API, и отправитель, повторяющий запрос после 503 (Alertmanager, Grafana, большинство вебхук-клиентов), ничего не теряет.


Управляющий API (/api/v1) ​

Стандартные списочные эндпоинты принимают ?limit= (по умолчанию 100, максимум 1000) и ?offset=. Ответ списка: {"items": [...], "total": N, "limit": L, "offset": O}.

Сортировка. ?sort=<колонка>&order=asc|desc. По умолчанию списки, которые читают по времени, отдаются свежим вперёд: алерт-группы по last_received_at, алерты по received_at, уведомления по created_at; остальные — по id. Колонка проверяется по списку колонок самой коллекции (её типизированные колонки плюс id, created_at, updated_at), неизвестное имя — 400, а не молча проигнорированный параметр. Последним ключом сортировки всегда идёт id: без такого тай-брейка страница по OFFSET может показать одну строку дважды и не показать другую. severity сортируется по важности, а не по алфавиту (critical > error > warning > info > debug).

Объекты, созданные провизионером. Если у объекта есть provisioned_by (например "terraform"), его PUT/PATCH/DELETE отвечают 403 всем, кроме запроса от того же провизионера — им считается запрос с User-Agent, в котором есть terraform, либо с заголовком X-Nxs-Anomaly-Provisioner: <имя>. Подробнее — в CONFIGURATION.md.

Пагинация, выбор ID и поиск справочников ​

Поле total относится к результату с учётом фильтров, а не к размеру текущей страницы. Пустой список возвращает items: [], а не null. До 10 000 записей сервер считает точное количество; для больших наборов использует оценку и возвращает total_estimated: true. Дополнительное total_lower_bound: true означает, что число — только нижняя граница (например, 10 001 означает «более 10 000»). Это оценка или нижняя граница, а не обещание, что последняя страница уже известна. При полном обходе продолжайте запрашивать страницы, пока не получите неполную; не завершайте обход только по оценке total.

?ids=id1,id2 выбирает указанный набор объектов одним запросом с сохранением обычных ролевых и командных ограничений. С этим параметром максимальный limit равен 500. Явно переданный непустой, но состоящий только из запятых и пробелов список возвращает пустую выдачу, а не всю коллекцию. Для большего числа ID разбивайте запрос на партии.

Параметр q поддерживается на /users, /teams, /schedules, /escalation-chains, /integrations и /maintenance-windows внутри /api/v1. Поиск регистронезависимый, по буквальной подстроке: % и _ не являются шаблонами SQL. У пользователей ищутся name, username, email; у остальных справочников — name. Пробелы по краям обрезаются; непустой запрос длиннее 256 байт возвращает 400. На неподдерживаемой коллекции непустой q также возвращает 400. Поиск сочетается с пагинацией, ids и серверной проверкой прав.

/api/v1/escalation-chains?has_steps=true выбирает цепочки с непустым массивом steps, has_steps=false — без шагов. Иные значения и применение параметра к другой коллекции возвращают 400.

bash
curl -sS "$API/api/v1/users?q=anna%40example.com&limit=50&offset=0" \
  -H "X-API-Key: $KEY"
curl -sS "$API/api/v1/teams?ids=team_1,team_2&limit=500" \
  -H "X-API-Key: $KEY"

Веб-таблицы справочников загружают по 50 строк. Поля выбора запрашивают первые 50 совпадений удалённого поиска и отдельно разрешают уже выбранные ID; чтобы найти объект за пределами первой выдачи, уточните запрос. Отсутствие объекта в открытом списке вариантов само по себе не означает, что его нет в базе.

Обзор инсталляции ​

GET /api/v1/overview возвращает данные главного экрана одним HTTP-ответом:

ПолеСодержимое
openСтраница открытых групп, до 10 объектов и total
acknowledgedСтраница подтверждённых групп, до 1 объекта и total
failedСтраница окончательно не доставленных уведомлений, до 1 объекта и total
retryingСтраница уведомлений retry_scheduled, до 1 объекта и total
integrationsСтраница интеграций, до 8 объектов и total
on_callТекущее дежурство в формате /api/v1/on-call

Обычные права и командное разграничение действуют для каждой секции. Если одна секция не загружается, весь запрос завершается ошибкой: частичный результат не выдаётся как свежий. Это единый ответ, но не транзакционный снимок PostgreSQL: секционные запросы выполняются последовательно. Главный экран обновляет обзор каждые 15 секунд; при отказе сохраняет предыдущие данные, явно сообщает об ошибке и предлагает повторить запрос.

Пользователи ​

МетодПуть
GET/POST/api/v1/users
GET/PUT/PATCH/DELETE/api/v1/users/{id}
POST/api/v1/users/{id}/duty-on, /duty-off
POST/api/v1/users/{id}/test-notification — доставить одно тестовое уведомление через настоящего провайдера и вернуть вердикт ({status, provider_status, provider_code?, response?, error?, configured}); тело {channel?}, по умолчанию берётся первый шаг политики default пользователя, иначе log. Только admin.
POST/api/v1/users/migrate-notification-policies — создать политику default из legacy-notification_targets для всех пользователей, у которых её нет (идемпотентно). Только admin.

Личные политики уведомлений (BETA-031). У пользователя может быть notification_policies: { default?: Step[], important?: Step[] }, где каждый Step — это { channel: telegram|email|webhook|call|log, target?: string, wait_minutes: int }. Если политика задана, пейджинг выполняет последовательность — уведомить канал, подождать, перейти к следующему — вместо одновременной отправки во все цели, и останавливается в момент подтверждения или закрытия группы. Шаг эскалации NOTIFY_USER может выбрать политику через notify_policy: "important"|"default" (по умолчанию default). Пользователи без политики сохраняют прежнее поведение (все цели отправляются разом).

Практическое руководство по настройке — CONFIGURATION.md.

Команды, расписания, цепочки эскалации, интеграции ​

МетодПуть
GET/POST/api/v1/teams, /api/v1/schedules, /api/v1/escalation-chains, /api/v1/integrations
GET/PUT/DELETE…/{id}
GET/api/v1/on-call — кто дежурит прямо сейчас по всем включённым расписаниям: items (user_id, name, username, schedule_id, schedule_name, source) и at. Считается по расписаниям, а не по ручному флагу on_duty
GET/api/v1/schedules/{id}/on-call?at=<ISO> — плюс source и сегмент next
GET/api/v1/schedules/{id}/preview?from=<ISO>&to=<ISO> — интервалы, пробелы, пересечения, unknown_users, покрытие (по умолчанию — ближайшие 4 недели)
GET/api/v1/schedules/coverage — постоянная проверка по видимым расписаниям: какие деградировали, какие цепочки через них пейджат, принял ли это шаг. Разграничивается по командам, как и список расписаний.
POST/api/v1/schedules/{id}/override (синоним: /overrides)
PUT/PATCH/DELETE/api/v1/schedules/{id}/overrides/{override_id}
POST/api/v1/integrations/{id}/rotate-key

webhook_secret интеграции в ответах не возвращается: вместо него есть webhook_secret_set (ссылка env: показывается как есть). Чтобы сменить секрет, отправьте новое значение, чтобы удалить — null. key и routing_key — право присылать алерты — видят editor и admin, для остальных ролей они замаскированы.

DELETE пользователя, команды, расписания или цепочки эскалации отвечает 409, пока от объекта зависит пейджинг: шаг цепочки, ротация, текущая или будущая смена или подмена, маршрут или политика уведомлений интеграции. Ошибка перечисляет все зависимые объекты; отвяжите их и удалите снова. Прошедшие смены и подмены не мешают и удаляются вместе с пользователем.

Окна обслуживания ​

МетодПуть
GET/POST/api/v1/maintenance-windows
GET/PUT/DELETE/api/v1/maintenance-windows/{id}

Окно требует name, starts_at, ends_at и хотя бы одну интеграцию. Границы — RFC 3339, starts_at < ends_at. Пока окно активно, новые группы указанных интеграций создаются silenced до его окончания: алерты сохраняются, но пейджинг и heartbeat SourceSilent подавлены. Уже эскалирующая группа не замолкает задним числом. Пересекающиеся окна разрешены; действует самое позднее ends_at.

Окно — это интервал (starts_at, ends_at), в течение которого перечисленные в integration_ids интеграции считаются плановыми работами: группы алертов, которые они открывают в это время, записываются полностью, но сразу переводятся в статус silenced до конца окна, поэтому воркер их не эскалирует и никого не будят. Уже эскалирующаяся группа не трогается — за неё кого-то уже подняли.

Отдельно окно отключает dead-man switch по этим интеграциям: источник, выключенный на плановые работы, — это молчащий источник, и без окна каждое обслуживание поднимало бы SourceSilent ровно тогда, когда отвечать на него некому: люди заняты этими же работами.

integration_ids обязан называть хотя бы одну интеграцию. «Пусто = все» здесь сознательно не поддержано: одна опечатка заглушила бы всю инсталляцию, а единственный симптом этого — что никого не будят.

Окно с непарсящимися границами не подавляет ничего: строка, которую никто не может прочитать, не должна молча съедать оповещения.

DELETE интеграции — мягкое удаление (проставляется deleted_at; интеграция исключается из списков и приёма, но остаётся доступной по ID).

Входящий ChatOps (с подписью) ​

МетодПутьАутентификация
POST/integrations/v1/chatops/slackSigning secret Slack (X-Slack-Signature, v0 HMAC-SHA256 по сырому телу; запросы старше 5 минут отклоняются)
POST/integrations/v1/chatops/telegramX-Telegram-Bot-Api-Secret-Token, сравнение за постоянное время
POST/integrations/v1/chatops/slack/interactiveТа же подпись Slack; тело — form-encoded с JSON в поле payload
POST/integrations/v1/chatops/mattermostСекрет в context.token кнопки, сравнение за постоянное время (Mattermost свои callback'и не подписывает)

Оба эндпоинта ограничены по частоте на адрес клиента, как и любой другой публичный маршрут. Slack получает ответ вида {"response_type":"ephemeral","text":…}, чтобы человек, набравший команду, увидел результат.

Не настроено (NXS_ANOMALY_SLACK_SIGNING_SECRET / NXS_ANOMALY_TELEGRAM_WEBHOOK_SECRET) → 501; неподписанную команду эти эндпоинты не принимают никогда. Канал определяется по external_id (для Telegram есть откат на name — именно там существующие инсталляции держат chat id).

Чат без канала. Личные уведомления приходят в личку с ботом, и кнопки под ними возвращают chat id, который ничьим ChatOps-каналом не является. Команда из такого чата выполняется, если отправитель опознан по telegram_id — от его имени, под его ролью и командами, без командной границы канала (её просто нет). Неопознанный отправитель в непривязанном чате получает отказ: он откатывается на сервисного принципала платформы, и разрешить тому команды из любого чата означало бы отдать право подтверждать алерты каждому, кто добавит бота куда угодно. Для общего чата канал по-прежнему обязателен — он и адрес рассылки, и та самая командная граница.

Кто выполняет команду. Telegram-id отправителя сопоставляется с telegram_id пользователя. Найденный пользователь действует от себя: его роль решает, что можно, его команды ограничивают, что видно, и запись в аудите называет его. Отправитель, за которым не стоит известный пользователь, выполняет команду от имени chatops:<платформа> с ролью responder — общий дежурный чат остаётся рабочим сценарием. Известный пользователь со снятой ролью получает 403: откат к сервисному принципалу вернул бы права, которые сняли намеренно. Slack идентификацию не использует — его идентификаторы пользователей сервис не хранит.

Что можно затронуть. Группа доступна команде, если её пропускают обе границы: команды актора и команда, к которой привязан канал. Чат — это контекст: членство в двух командах не делает чат одной из них входом в другую. Владелец берётся из интеграции группы; группа с пропавшей интеграцией отклоняется. Интеграции без команды остаются доступны всем.

Команды. status (сколько открыто; через API ответ ещё перечисляет 50 самых свежих как id/title/severity/status, с open_count и truncated), alerts [страница] (список с кнопкой на каждую группу), ack <id>, resolve <id>, duty on|off, duty take [id расписания] [часы], priority [username] <high|medium|low>, oncall <id расписания>, help. Ответ в Telegram возвращается как вызов метода sendMessage в теле ответа на вебхук — иначе Telegram его игнорирует, и набранная команда не отвечает ничего. Второй запрос к Bot API при этом не нужен.

Список алертов. alerts выдаёт открытые группы, доступные вызвавшему, новее первыми, по 5 на страницу. Номер страницы едет в callback_data (alerts:2), а не в серверной сессии: список читают несколько секунд, а сессия пережила бы причину своего существования. Нажатие на «Next» перерисовывает то же сообщение через editMessageText, а не присылает новую копию списка. Страница за пределами диапазона зажимается к последней — страницы сокращаются, пока их читают, и устаревшее нажатие должно показать последнюю, а не ошибку.

Заступил / сдал смену (duty on|off). Расписание решает, кто должен дежурить; флаг on_duty фиксирует, кто это подтвердил. Команда требует отправителя, опознанного по telegram_id: сервисный принципал общего чата — не человек, и разрешить ему отметиться значило бы поставить на дежурство весь чат.

Чек-ин истекает сам — в конце смены, которую человек реально покрывает, либо через 12 часов, если ни одно расписание его сейчас не назначает (подмена в аварии). Фиксированный таймаут был бы либо длиннее смены — и флаг пережил бы её, а NOTIFY_DUTY_USERS продолжил будить того, кто последним вспомнил написать «duty on», — либо короче, и снимался бы посреди смены. on_duty, выставленный через API или веб-интерфейс, эта механика не трогает: это постоянное назначение, а не подтверждение смены.

Принять дежурство в ЧП (duty take [id расписания] [часы]). Пишет override расписания, а не флаг. Флаг движку расписаний не виден, поэтому переключение им оставило бы NOTIFY_SCHEDULE, отчёт покрытия и preview по-прежнему называющими заменяемого — два ответа разошлись бы ровно тогда, когда это важно. По умолчанию 2 часа, максимум 24: дольше — это уже изменение расписания, и его место в расписании, где его видит команда, а не в сообщении чата, к которому никто не прокрутится. Если доступное расписание одно, оно выбирается само (искать id ночью — последнее, чем стоит заниматься); если их несколько, бот перечисляет кандидатов и просит назвать одно. Одновременно ставится чек-ин на то же окно, чтобы он истёк вместе с override.

Приоритет (priority [username] <high|medium|low>). Определяет, до кого NOTIFY_DUTY_USERS дойдёт первым среди дежурящих. Свой — уровень responder, чужой — editor: расставлять себя в очереди можно самому, а решать, когда зазвонит телефон коллеги, — уже нет. Обе команды подчиняются тем же двум границам, что и действия с группами.

Расхождение видно в метриках: nxs_anomaly_duty_on_call и nxs_anomaly_duty_without_checkin. Расписание может быть полностью покрыто на бумаге, притом что смену никто не подтвердил, — до этого такая ситуация не была видна нигде.

Кнопки. К уведомлению об алерте в Telegram прикладываются inline-кнопки Acknowledge и Resolve с callback_data вида <действие>:<id группы>. Нажатие приходит на тот же эндпоинт как callback_query и выполняется тем же путём, что и набранная команда, — границы совпадают по построению. Эндпоинт всегда отвечает 200: отказ здесь окончателен, а не временен, и не-2xx заставил бы Telegram переслать нажатие и выполнить команду повторно; вердикт человек получает через answerCallbackQuery. Если callback_data не умещается в лимит Telegram (64 байта), кнопки не прикладываются — сообщение об алерте важнее ярлыка к нему.

После использованной кнопки сообщение переписывается: к тексту дописывается вердикт, клавиатура снимается. Иначе подтверждённый алерт продолжал бы предлагать «Acknowledge» — всплывающее подтверждение исчезает через секунды, а на экране остаётся кнопка, намекающая, что работа ещё ждёт. Отклонённое нажатие ничего не меняет и кнопки оставляет.

К уведомлению о начале смены прикладывается кнопка «I am on duty» (duty:on) — чек-ин тапом вместо набора команды.

Кнопки на всех трёх платформах. Slack получает blocks с кнопками (простой text сохраняется рядом — это то, что покажет превью на экране блокировки), Mattermost — attachments с actions. Действия у всех платформ берутся из одной таблицы, поэтому кнопка, добавленная на одной, не может означать другое на второй; это закреплено тестом.

Нажатие в Slack заменяет сообщение (replace_original), в Mattermost — обновляет пост и очищает attachments; отказ ничего не меняет и кнопки оставляет, чтобы следующий читающий мог действовать. В Slack и Mattermost команда выполняется от сервисного принципала: идентификаторов их пользователей сервис не хранит, поэтому опознать человека нечем — то же ограничение, что и у набранной команды в Slack.

Кнопки Mattermost требуют NXS_ANOMALY_PUBLIC_URL и NXS_ANOMALY_MATTERMOST_ACTION_SECRET: их callback идёт на абсолютный адрес, а подписи у него нет, поэтому секрет в контексте кнопки — единственное, что отличает настоящее нажатие от постороннего запроса. Без любого из двух алерт уходит без кнопок: кнопка, ведущая туда, где никто не отвечает, хуже её отсутствия.

МетодПутьОписание
POST/api/v1/users/{id}/test-pushОтправляет настоящий push через relay и возвращает вердикт провайдера по каждому устройству; push_configured: false, если relay не настроен. Только admin, как и прочие записи в /users.

Чтения маскируют поля, похожие на учётные данные: push_token устройства — всегда, webhook_url ChatOps-канала и значения headers ChatOps-канала и шага TRIGGER_WEBHOOK, а также inline-token шага CREATE_ISSUE — для всех, кому нельзя менять конфигурацию; значения заголовков и токен трекера в уведомлении — для всех. Доставка читает те же строки через store и это не затрагивает.

ChatOps и мобильные клиенты ​

МетодПуть
GET/POST/api/v1/chatops/channels
GET/PUT/DELETE/api/v1/chatops/channels/{id}
GET/api/v1/chatops/messages (с пагинацией)
POST/api/v1/chatops/commands
GET/POST/api/v1/mobile/devices — POST регистрирует устройство любому пользователю: только admin
POST/api/v1/mobile/sessions — выдаёт сессию на устройство любого пользователя: только admin (свой телефон человек подключает через pairing ниже)
POST/api/v1/mobile/pairing — одноразовый код для входа телефона
POST/api/v1/mobile/pairing/redeem — обмен кода на сессию (без аутентификации)
DELETE/api/v1/mobile/sessions/current — выход с телефона
GET/api/v1/mobile/sessions — свои подключённые телефоны
DELETE/api/v1/mobile/sessions/{id} — отключить свой телефон (например, потерянный)
GET/api/v1/mobile/events — поток групп, которые касаются вызывающего
GET/api/v1/mobile/dashboard (мобильная сессия) — группы, которые касаются вызывающего, строками списка, без logs и alert_ids (их отдаёт сама группа)
POST/api/v1/mobile/alert-groups/{id}/acknowledge, /resolve (мобильная сессия)

Поток событий (GET /api/v1/mobile/events) — то, как телефон узнаёт об алерте за секунды без push-сервиса. Это Server-Sent Events: приложение держит соединение открытым, и на каждом тике (NXS_ANOMALY_MOBILE_STREAM_INTERVAL_SECONDS, по умолчанию 10) сервер присылает весь набор групп, которые касаются этого человека, и отдельно — какие из них added или changed с прошлого тика. Первый тик помечен baseline и не объявляет ничего: иначе телефон, переподключившийся после обрыва сети, звонил бы по всему, что уже знает. Ошибка чтения отправляется событием error, соединение остаётся — перезапуск базы не должен отправлять все телефоны в цикл переподключений. SSE-комментарии раз в 20 секунд не дают прокси закрыть простаивающее соединение, а заголовок X-Accel-Buffering: no нужен потому, что nginx иначе придержит события до заполнения буфера. NXS_ANOMALY_MOBILE_STREAM_MAX ограничивает число потоков на одну реплику. API-ключ получает 400: для него нет понятия «меня касается». Первое событие, hello, несёт interval_seconds и can_respond — может ли этот человек подтверждать и закрывать группы: телефон показывает эти кнопки только тому, чьё нажатие не будет отклонено.

Учётные данные, которые нельзя проверить, потому что база не отвечает, получают 503 с Retry-After, а не 401: приложение считает 401 выходом и забывает сессию, поэтому перезапуск базы раньше отключал все подключённые телефоны.

Мобильная сессия — самостоятельный способ аутентификации: заголовок Authorization: Bearer nxm_… или X-Mobile-Session. Телефон подключают в «Настройки → Мобильное приложение»: POST /mobile/pairing от имени вошедшего пользователя выдаёт код XXXXX-XXXXX (одноразовый, 5 минут), приложение обменивает его в POST /mobile/pairing/redeem на токен. Погашение кода расходует тот же лимит, что и вход по паролю. Сессия действует как её пользователь — с его командами — но с ролью не выше responder: с телефона отвечают на алерты, а не меняют конфигурацию. Поэтому приложение ходит в обычные /api/v1/alert-groups/*, а не в отдельные мобильные дубли. Хранится только SHA-256 токена; сессия, не использованная 30 дней, истекает, при использовании срок продлевается. Неверный мобильный токен — это отказ (401), даже если рядом есть действующий cookie. Телефону нужен пользователь с ролью: заведённый без роли — например, только как получатель уведомлений — не входит ни в веб, ни с телефона, и его мобильная сессия тоже отвечает 401.

external_id канала — это то, чем входящая команда себя называет, поэтому на платформе его может нести только один канал: второй получает 409. Команды из общего чата — группы Telegram, канала Slack или Mattermost — выполняются только если этот чат привязан к каналу здесь, кем бы они ни были отправлены; личному чату с ботом канал не нужен, там границей выступает сам человек.

Группы алертов ​

МетодПуть
GET/api/v1/alert-groups
GET/api/v1/alert-groups/{id}
GET/api/v1/alert-groups/{id}/timeline
POST/api/v1/alert-groups/{id}/acknowledge, /unacknowledge, /resolve, /unresolve
POST/api/v1/alert-groups/{id}/silence — тело или ?duration_minutes= (по умолчанию 60; 0 и меньше — без срока)
POST/api/v1/alert-groups/bulk-resolve, /bulk-acknowledge, /bulk-silence

Массовые эндпоинты принимают {"group_ids": ["...", "..."]}. bulk-silence дополнительно принимает duration_minutes (в теле или как ?duration_minutes=, по умолчанию 60). В ответах есть silenced/acknowledged/resolved, not_found, skipped.

Silence с длительностью заканчивается сам: в silenced_until worker возвращает группу в open и запускает её цепочку эскалации заново с первого шага — так же, как по окончании окна обслуживания. POST /api/v1/alert-groups/{id}/unacknowledge тоже запускает цепочку заново с первого шага. POST /api/v1/alert-groups/{id}/unresolve открывает закрытую группу заново: она возвращается в open, начинает новый эпизод (время реакции первого не перезаписывается) и проходит цепочку с первого шага сразу, не дожидаясь интервала опроса.

Алерты, уведомления, история, отладка ​

МетодПуть
GET/api/v1/alerts, /api/v1/notifications
GET/api/v1/delivery-attempts?notification_id=<id>&limit=&offset= (с пагинацией, как остальные списки)
GET/api/v1/history?from=&to=&integration=&severity=&status=&channel=&user=&team=
GET/api/v1/insights/summary?from=&to=&integration_id= — сводка страницы Insights: группы по статусу и уровню, уведомления по состоянию и дневной тренд (opened, resolved, delivered, failed). По умолчанию последние 7 дней, не больше 92; разграничивается по командам, как история
POST/api/v1/routes/debug/{key} — предпросмотр маршрутизации и уведомлений для payload
POST/api/v1/escalations/run — вручную выполнить проход по назревшим эскалациям

Готовность к работе ​

МетодПуть
GET/api/v1/readiness — способна ли эта инсталляция вообще кого-то разбудить?
POST/api/v1/readiness/acknowledge — принять текущие блокеры (admin)
POST/api/v1/backups/report — зафиксировать завершённое резервное копирование (admin; см. BACKUP_RESTORE.md)
GET/api/v1/capabilities — edition и возможности, зависящие от издания или настройки (sso, team_scoping, analytics_stream, oncall_reports), каждая в состоянии available, not_configured (настройте — заработает) или unavailable_in_edition (настройкой не исправить), с пояснением в detail

Отчёт выполняет десять проверок — база, worker, интеграции, маршрутизация, цели уведомлений, покрытие расписаний, граница команд, политика каналов, retention и возраст резервной копии — и оценивает каждую как ok, warning или blocker. Блокер означает, что алерты могут приходить и не будить никого; проверка, которая не смогла выполниться, сообщается как блокер, а не как успех.

Два флага различаются намеренно. ready истинен, только когда не мешает ничего. production_ready — более слабое утверждение, используемое гейтом активации: истинно, когда не мешает ничего или названный администратор принял ровно перечисленные блокеры. Это подтверждение хранит отпечаток набора блокеров, поэтому перестаёт действовать в момент их изменения — это решение по известным проблемам, а не вечное отключение предупреждения.

Два входных значения нельзя вывести из доменного состояния, и они хранятся как метаданные инсталляции: heartbeat worker-а (пишет сам worker, поэтому ответ не зависит от того, работают API и worker в одном процессе или в двух) и последняя сообщённая резервная копия.


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

Все ошибки: {"error": "сообщение"}. Коды: 400 — валидация, 401 — нужна аутентификация, 403 — запись при доступе только на чтение, 404 — не найдено, 429 — превышен лимит, 500 — внутренняя ошибка, 503 — база недоступна.

Каждый ответ несёт заголовок X-Request-ID (переданный в запросе или сгенерированный) для сопоставления со структурированными логами.

nxs-anomaly · Documentation