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

Notifly предоставляет REST API для управления каналами, клиентами, сообщениями и пользователями. Все примеры используют базовый URL https://your-notifly-domain.com.

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

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

Тип	Префикс	Назначение
App-токен	A	Только отправка сообщений (POST /message)
Client-токен	C	Управление ресурсами, получение сообщений

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

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

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

# 3. Bearer-токен
curl -H "Authorization: Bearer CaQw5lL_L.yiRbN" https://host/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 /notiflyinfo — флаги сервера

curl https://host/notiflyinfo

{"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",
  "lastUsed": null
}

POST /auth/logout — выход

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

---

Каналы

Канал (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

POST /application/{id}/image — загрузить иконку

curl -u admin:admin https://host/application/1/image \
  -F "file=@icon.png"

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

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

---

Сообщения

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": {
    "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"

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 /current/user — информация о текущем пользователе

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

{"id": 1, "name": "admin", "admin": true}

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

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

---

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

Доступ

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

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

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

[
  {"id": 1, "name": "admin", "admin": true},
  {"id": 2, "name": "user1", "admin": false}
]

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

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

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

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

POST /user/{id} — обновить пользователя

curl -u admin:admin https://host/user/2 \
  -H "Content-Type: application/json" \
  -d '{"name": "user1", "admin": true}'

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

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

---

WebSocket — поток сообщений

Для получения сообщений в реальном времени подключитесь по WebSocket:

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

// JavaScript
const ws = new WebSocket("wss://host/stream?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"
}

---

Плагины

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

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

GET /plugin/{id}/config — конфигурация плагина (YAML)

curl -u admin:admin https://host/plugin/1/config

POST /plugin/{id}/config — обновить конфигурацию

curl -u admin:admin https://host/plugin/1/config \
  -H "Content-Type: text/x-yaml" \
  -d 'key: value'

GET /plugin/{id}/display — отображаемая информация

curl -u admin:admin https://host/plugin/1/display

POST /plugin/{id}/enable — включить плагин

curl -u admin:admin https://host/plugin/1/enable -X POST

POST /plugin/{id}/disable — выключить плагин

curl -u admin:admin https://host/plugin/1/disable -X POST

---

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

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	Ресурс не найден