REST API Documentation

Notifly provides a REST API for managing channels, clients, messages, and users. All examples use the base URL https://your-notifly-domain.com.

Authentication

Notifly uses two types of tokens:

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

A token can be supplied in three ways:

# 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 (username/password) is also supported for all endpoints that require a client token.

---

Server information

Endpoints are available without authentication.

GET /health — health check

curl https://host/health

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

GET /version — server version

curl https://host/version

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

GET /notiflyinfo — server flags

curl https://host/notiflyinfo

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

---

Authentication (session)

POST /auth/local/login — login with username/password

Creates a client session. Returns a client token and sets a 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 — logout

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

---

Applications (channels)

An application (application in the API URL — for compatibility with the Gotify protocol) is a source of messages. Each application has its own app token for sending.

Authentication

All application endpoints require a client token or Basic Auth.

GET /application — list applications

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 — create application

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

Request fields:

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

PUT /application/{id} — update application

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

DELETE /application/{id} — delete application

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

POST /application/{id}/image — upload icon

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

DELETE /application/{id}/image — delete icon

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

---

Messages

POST /message — send message

Authentication

Messages must be sent using an app token (not a client token!).

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

Or via form-data:

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

Request fields:

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

Example with extras (markdown content):

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"}
    }
  }'

Response:

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

GET /message — all messages (with pagination)

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

Parameters:

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

Response:

{
  "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 — application messages

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

DELETE /message — delete all messages

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

DELETE /message/{id} — delete message

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

DELETE /application/{id}/message — delete all messages of an application

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

---

Clients

A client is a device or application that receives messages and manages resources.

GET /client — list clients

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

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

POST /client — create client

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

PUT /client/{id} — update client

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

DELETE /client/{id} — delete client

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

---

Current user

GET /current/user — current user info

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

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

POST /current/user/password — change password

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

---

User management (administrator)

Access

These endpoints are only available to administrators, except POST /user, which is available to everyone if open registration is enabled.

GET /user — list users

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

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

POST /user — create user

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

GET /user/{id} — get user

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

POST /user/{id} — update user

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

DELETE /user/{id} — delete user

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

---

WebSocket — message stream

To receive messages in real time, connect via 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})`);
};

Each incoming event is a JSON object Message:

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

---

Plugins

GET /plugin — list plugins

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

GET /plugin/{id}/config — plugin configuration (YAML)

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

POST /plugin/{id}/config — update configuration

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

GET /plugin/{id}/display — display information

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

POST /plugin/{id}/enable — enable plugin

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

POST /plugin/{id}/disable — disable plugin

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

---

Examples in different languages

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
  }

---

Status codes

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