Перейти к содержимому

Создание сообщения POST ​

Отправьте push-уведомление на ваши устройства.

Эндпоинт ​

POST https://api.pocketalert.app/v1/messages

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

Обязательно

Добавьте в запрос один из этих заголовков:

  • Token: <your-api-key> — получить можно в разделе API-ключи
  • Authorization: Bearer <jwt-token> — из входа

Запрос ​

Заголовки ​

ЗаголовокОбязательныйОписание
Content-Type✅application/json
Token✅Ваш API-ключ
Authorization✅Bearer <jwt-token>

* Один из заголовков Token или Authorization обязателен

Параметры тела запроса ​

ПараметрТипОбязательныйОписание
titlestring✅Заголовок уведомления
messagestring✅Текст уведомления
application_idstring❌TID приложения для категоризации сообщения
device_idstring❌TID конкретного устройства, не указывайте, чтобы отправить на все устройства
levelstring | int❌Уровень приоритета, определяющий способ доставки push-уведомления. Принимает название или целое число (-2..2). Синоним — priority. По умолчанию используется уровень приложения, а если он не задан — default.
actionsarray❌До 3 кнопок действий в уведомлении. См. Кнопки действий.
send_atstring | int❌Доставить в указанное время вместо немедленной отправки. RFC3339, Unix timestamp или YYYY-MM-DD HH:MM. См. Отложенная отправка.
delaystring❌Доставить с относительной задержкой — 30m, 2h или просто секунды. Взаимоисключает send_at.

Кнопки действий ​

Каждое уведомление может содержать до 3 кнопок действий. Они работают, когда приложение открыто, в фоне или закрыто. actions — это массив объектов, размер которого после JSON-кодирования не должен превышать 2048 байт (он передаётся внутри push-уведомления, ограниченного 4 КБ; длинное message будет сокращено, чтобы освободить место):

ПолеТипОбязательноеОписание
typestring✅view (открыть URL), http (выполнить HTTP-запрос) или copy (скопировать текст в буфер обмена)
labelstring✅Текст кнопки, отображается как есть на Android и iOS
valuestring✅Зависит от type — см. ниже

value по типам:

  • view — URL для открытия, например "https://pocketalert.app".
  • http — JSON-строка с описанием запроса: {"url":"https://…","method":"POST","headers":{…},"body":"…"}. Обязателен только url; method по умолчанию GET. Запрос выполняется с устройства в фоне без открытия приложения, поэтому может обращаться к хостам в локальной сети телефона. Если запрос не удался (статус не 2xx/3xx или ошибка сети), показывается уведомление с кнопкой Retry; повторно он никогда не отправляется автоматически, если мог дойти до сервера.
  • copy — текст, который будет помещён в буфер обмена.

Человек в контуре

Две кнопки типа http (например, Approve / Decline) превращаются в панель управления в одно нажатие — это удобно для подтверждения действий LLM-агентов прямо из уведомления.

Платная функция

На бесплатных тарифах кнопки действий удаляются: сообщение доставляется без них, а actions не проверяется.

Ограничения, валидацию и шаблоны вебхуков см. в разделе Кнопки действий.

Уровни приоритета ​

УровеньСинонимыПоведение
silentmin, -2Доставляется только в шторку — без звука и вибрации
low-1Тихо, без прерывания
defaultnormal, 0 (или не указан)Стандартный баннер и звук
high1Важное по времени — пробивается через Фокусирование / плановую сводку
criticalmax, urgent, 2Пробуждает устройство через переключатель режима тишины и режим «Не беспокоить». См. Уровни приоритета

WARNING

critical — функция платного тарифа. На бесплатных тарифах он автоматически понижается до high. Некорректные значения (неизвестное название или целое число вне диапазона) возвращают 400.

Как каждый уровень работает на iOS и Android, см. в разделе Уровни приоритета.

Отложенная отправка ​

Добавьте send_at или delay — но никогда оба сразу — и сообщение будет храниться в зашифрованном виде до времени доставки вместо немедленной отправки.

ПараметрПринимаетПримеры
send_atRFC3339, Unix timestamp или YYYY-MM-DD HH:MM2026-08-15T09:00:00Z, 1786867200
delayДлительность в формате Go или просто секунды30m, 2h, 3600

Время без смещения читается в часовом поясе вашего аккаунта. Горизонт планирования — 30 дней; send_at в прошлом возвращает 400 (с допуском 60 секунд на расхождение часов).

Отложенные запросы возвращают 201 с "scheduled": true, status, deliver_at и deliver_at_utc вместо доставленного сообщения. Список можно получить через GET /v1/messages/scheduled, отменить — через DELETE /v1/messages/scheduled/{tid}. См. Отложенная отправка.

WARNING

Отложенная отправка — функция платного тарифа. Запросы с send_at или delay на бесплатном тарифе возвращают 403.

Пример запроса ​

bash
curl -X POST "https://api.pocketalert.app/v1/messages" \
  -H "Token: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Server Alert",
    "message": "CPU usage exceeded 90%",
    "application_id": "qm47b9pzxzxg",
    "level": "critical",
    "actions": [
      { "type": "view", "label": "Dashboard", "value": "https://status.example.com" },
      { "type": "http", "label": "Restart", "value": "{\"url\":\"https://ops.example.com/restart\",\"method\":\"POST\"}" },
      { "type": "copy", "label": "Copy ID", "value": "incident-4821" }
    ]
  }'
javascript
const response = await fetch('https://api.pocketalert.app/v1/messages', {
  method: 'POST',
  headers: {
    'Token': 'your-api-key',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    title: 'Server Alert',
    message: 'CPU usage exceeded 90%',
    application_id: 'qm47b9pzxzxg'
  })
});

const data = await response.json();
console.log(data);
python
import requests

response = requests.post(
    'https://api.pocketalert.app/v1/messages',
    headers={
        'Token': 'your-api-key',
        'Content-Type': 'application/json'
    },
    json={
        'title': 'Server Alert',
        'message': 'CPU usage exceeded 90%',
        'application_id': 'qm47b9pzxzxg'
    }
)

print(response.json())
php
$response = Http::withHeaders([
    'Token' => 'your-api-key',
])->post('https://api.pocketalert.app/v1/messages', [
    'title' => 'Server Alert',
    'message' => 'CPU usage exceeded 90%',
    'application_id' => 'qm47b9pzxzxg',
]);

return $response->json();

Ответ ​

Успешный ответ ​

201 Created

Сообщение успешно создано

ПолеТипОписание
tidstringУникальный идентификатор сообщения
titlestringЗаголовок сообщения
messagestringТекст сообщения
applicationstringНазвание приложения (если указано)
devicestringНазвание устройства-получателя
actionsarrayКнопки действий в ответе (только если были переданы)
created_atstringВремя создания
json
{
  "tid": "jb4xw9elz28g",
  "title": "Server Alert",
  "message": "CPU usage exceeded 90%",
  "application": "Monitoring",
  "device": "iPhone",
  "actions": [
    { "type": "view", "label": "Dashboard", "value": "https://status.example.com" }
  ],
  "created_at": "18.01.2026 15:35:35"
}

Заголовки квоты ​

Ответы содержат текущее использование дневного лимита (не возвращаются на тарифах без лимита):

ЗаголовокОписание
X-PA-Daily-LimitКоличество сообщений в день по вашему тарифу
X-PA-Daily-RemainingСколько сообщений осталось на сегодня, включая этот
X-PA-Daily-ResetUnix timestamp (в секундах) следующего сброса, 00:00 UTC

Ответы с ошибками ​

СтатусОписание
400Bad Request — отсутствуют title или message, некорректный level или, на платных тарифах, некорректные actions
401Unauthorized — токен неверный или отсутствует
403Forbidden — send_at или delay на бесплатном тарифе
404Not Found — application_id или device_id не существует
429Достигнут дневной лимит — сообщение не сохранено и не отправлено. Подождите Retry-After секунд или перейдите на другой тариф. См. Дневные лимиты сообщений.
json
{
  "error": "Validation failed",
  "details": {
    "title": ["The title field is required"]
  }
}

Достигнут дневной лимит ​

Когда квота на сегодня исчерпана, сообщение отклоняется — не ставится в очередь — до 00:00 UTC. В Retry-After указано количество секунд до сброса.

http
HTTP/1.1 429 Too Many Requests
Retry-After: 30142
X-PA-Daily-Limit: 50
X-PA-Daily-Remaining: 0
X-PA-Daily-Reset: 1790035200
json
{
  "error": "Daily message limit reached (50/50). New messages are rejected until 00:00 UTC. Upgrade your plan to raise the limit.",
  "limit": 50,
  "used": 50,
  "resets_at": "2026-09-22T00:00:00Z",
  "upgrade_url": "https://pocketalert.app/pricing"
}

Удаление сообщений не освобождает квоту. Проверить сегодняшнее использование можно через GET /v1/messages/usage.

Документация Pocket Alert