Справочник API

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

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

API-ключ

Создайте персональный API-ключ в меню профиля. Используйте заголовок X-API-Key:

curl -H "X-API-Key: YOUR_API_KEY" \
  https://pingzen.dev/api/v1/monitors

Чтобы создать API-ключ: Нажмите на профиль → API-ключи → Создать новый ключ

Увеличить

Где X-API-Key работает, а где требуется JWT

Важно

На текущий момент X-API-Key принимают только эндпоинты мониторов (CRUD, pause/resume, reorder, основные статистики, timeline и CSV-экспорт/импорт). Все остальные эндпоинты — /workspaces, /alerts, /incidents, /status-pages, /monitor-groups, /probes, /heartbeats (кроме no-auth /ping/...), /maintenance, /feedback, /dashboard, /web-push, /scheduled-reports, /webhooks, /webhook-checks, /api-checks, /api-keys, /auth/*, /analytics, /telegram-bot, /alert-channel-configs — на текущий момент требуют JWT-токен. Это расхождение с историческим обещанием доки; мы его постепенно закрываем.

Что попадает под X-API-Key прямо сейчас:

Внутри /monitors/* пока требуют JWT (известное расхождение, чиним): GET /:id/stats, POST /:id/check, GET /:id/sla, GET /:id/sla/export/csv|pdf, GET /:id/dnsbl/provider-history, POST /test.

JWT Token

Для веб-приложений и эндпоинтов, не поддерживающих API-ключ, используйте JWT из /auth/login:

# 1. Получить токен (передайте email и пароль)
ACCESS=$(curl -sS -X POST https://pingzen.dev/api/v1/auth/login \
  -H 'Content-Type: application/json' \
  -d '{"email":"you@example.com","password":"…"}' \
  | python3 -c 'import json,sys; print(json.load(sys.stdin)["access_token"])')

# 2. Использовать в Authorization: Bearer
curl -H "Authorization: Bearer $ACCESS" https://pingzen.dev/api/v1/workspaces

Access-токен живёт 15 минут; для долгоживущих интеграций используйте refresh_token из того же ответа и эндпоинт /auth/refresh.

Эндпоинты

Полный список всех доступных API эндпоинтов.

Мониторы

Управление мониторами (22 эндпоинта, сгруппированы по назначению).

CRUD

Управление

Семантика CSV-импорта: обязательна только колонка url (заголовки экспорта StatusCake, bulk-upload шаблона UptimeRobot и HetrixTools принимаются как есть, разделители , и ; определяются автоматически). Дубликаты определяются по URL+протоколу в целевом пространстве. Без ?workspace_id= строки маршрутизируются по колонке workspace (по имени; строки без неё идут в пространство по умолчанию). Имена мониторов уникальны в рамках аккаунта — при импорте копии собственного пространства в другое строки нужно переименовать; конфликты имён попадают в skipped с указанием причины. Импорт доступен в собственные пространства и в общие пространства с ролью editor или owner (viewer получает 403 / построчные ошибки). Понимаются числовые коды типов UptimeRobot (1/2/3/4) и DoNotFind StatusCake; Excel-файлы отклоняются с подсказкой пересохранить как CSV UTF-8. Ответ описывает каждую строку: created / skipped / failed; одна плохая строка никогда не прерывает весь батч.

Статистика и история

Диагностика

Оповещения

Настройка уведомлений.

Инциденты

Управление инцидентами.

Статус-страницы

Публичные статус-страницы.

Рабочие пространства

Управление рабочими пространствами.

Heartbeat (cron)

Мониторинг cron-задач.

API-ключи

Управление API-ключами.

Обслуживание

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

Группы мониторов

Управление группами (12 эндпоинтов, сгруппированы по назначению).

CRUD групп

Связи (мониторы и теги)

Статус и статистика

Telegram группы

Оповещения в Telegram-группы.

Отчёты по расписанию

Автоматические email отчёты.

Конфигурация каналов

Учётные данные каналов (SMTP, Twilio и т.д.).

Панель

Агрегированная статистика.

Вебхуки (исходящие)

Доставка событий через вебхуки (12 эндпоинтов, сгруппированы по назначению).

CRUD вебхуков

Действия

Доставки и DLQ

Справочник

Вебхук-чеки (входящие)

Приём входящих вебхуков от внешних сервисов (10 эндпоинтов + 1 публичный приёмник, сгруппированы по назначению).

CRUD проверок

Управление проверками

События и статистика

Публичный приёмник (без auth)

Обратная связь

Отзывы и запросы на фичи.

Web Push

Push-уведомления в браузере.

Чекеры

Идентификация и IP-адреса чекеров.

Примеры запросов

Детальные примеры с cURL.

List monitors

curl -H "X-API-Key: YOUR_API_KEY" \
  https://pingzen.dev/api/v1/monitors?workspace_id=1

Как узнать ваш workspace_id

Поле workspace_id обязательно в payload’е при создании монитора, оповещения, отчёта и статус-страницы. Получить его можно двумя способами.

Способ 1: через UI (быстрее всего). Откройте страницу рабочих пространств — ID каждого пространства виден в карточке. У большинства пользователей он равен 1.

Способ 2: через API (для CI/скриптов). Эндпоинты /api/v1/workspaces* пока требуют JWT, а не X-API-Key (см. раздел «Где X-API-Key работает» выше). Шаги:

# 1. Логин — получить access_token
ACCESS=$(curl -sS -X POST https://pingzen.dev/api/v1/auth/login \
  -H 'Content-Type: application/json' \
  -d '{"email":"you@example.com","password":"…"}' \
  | python3 -c 'import json,sys; print(json.load(sys.stdin)["access_token"])')

# 2. Воркспейс по умолчанию (тот, что pre-selected в UI)
curl -sS -H "Authorization: Bearer $ACCESS" \
  https://pingzen.dev/api/v1/workspaces/default
# → {"id": 42, "name": "My Workspace", "is_default": true, ...}

# 3. Или короткий список всех (id, name) для дропдаунов
curl -sS -H "Authorization: Bearer $ACCESS" \
  https://pingzen.dev/api/v1/workspaces/summary

Однострочник «логин → достать id default’а» для CI:

ACCESS=$(curl -sS -X POST https://pingzen.dev/api/v1/auth/login \
  -H 'Content-Type: application/json' \
  -d "{\"email\":\"$EMAIL\",\"password\":\"$PASS\"}" \
  | python3 -c 'import json,sys; print(json.load(sys.stdin)["access_token"])')

WORKSPACE_ID=$(curl -sS -H "Authorization: Bearer $ACCESS" \
  https://pingzen.dev/api/v1/workspaces/default \
  | python3 -c 'import json,sys; print(json.load(sys.stdin)["id"])')

echo "$WORKSPACE_ID"   # → 42

Дальше $WORKSPACE_ID подставляется в payload POST /api/v1/monitors ниже (это уже X-API-Key-эндпоинт).

Create a monitor

curl -X POST https://pingzen.dev/api/v1/monitors \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "My Site", "url": "https://example.com", "protocol": "https", "workspace_id": 1, "interval_seconds": 60}'

Get monitor

curl -H "X-API-Key: YOUR_API_KEY" \
  https://pingzen.dev/api/v1/monitors/123

Update monitor

curl -X PATCH https://pingzen.dev/api/v1/monitors/123 \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"interval_seconds": 60, "name": "Updated Name"}'

Минимальный interval_seconds зависит от плана: FREE — 60s, платные — 30s. Значение ниже плана вернёт 422 с подробным сообщением.

Delete monitor

curl -X DELETE https://pingzen.dev/api/v1/monitors/123 \
  -H "X-API-Key: YOUR_API_KEY"

Create a heartbeat monitor

Create a heartbeat monitor for cron jobs and scheduled tasks. Returns a unique ping URL и секрет. /heartbeats CRUD пока требует JWT (см. “Где X-API-Key работает”); workspace_id передаётся как query-параметр, а не в body:

curl -X POST "https://pingzen.dev/api/v1/heartbeats?workspace_id=$WORKSPACE_ID" \
  -H "Authorization: Bearer $ACCESS" \
  -H "Content-Type: application/json" \
  -d '{"name": "Daily Backup", "expected_interval_seconds": 86400, "grace_period_seconds": 600}'

Send heartbeat ping (GET)

Simplest integration — just add to crontab or end of script. No authentication required.

# Simplest: chain with && so ping fires only on success
0 3 * * * /usr/local/bin/backup.sh && curl -fsS -m 10 https://pingzen.dev/api/v1/ping/YOUR_PING_KEY/YOUR_SLUG

# Or just a standalone ping
curl https://pingzen.dev/api/v1/ping/aBcDeFgHiJkLmNoPqR/daily-backup

Heartbeat lifecycle signals

Report job lifecycle signals (start/success/fail) with optional payload and duration. Use X-Secret header for authentication.

# Report success with payload and duration
curl -X POST https://pingzen.dev/api/v1/ping/aBcDeFgHiJkLmNoPqR/daily-backup/success \
  -H "X-Secret: YOUR_SECRET" \
  -H "Content-Type: application/json" \
  -d '{"duration_ms": 45000, "payload": {"rows": 500000}}'

# Report failure — triggers instant alert (no waiting for missed interval)
curl -X POST https://pingzen.dev/api/v1/ping/aBcDeFgHiJkLmNoPqR/daily-backup/fail \
  -H "X-Secret: YOUR_SECRET" \
  -H "Content-Type: application/json" \
  -d '{"payload": {"error": "disk full"}}'

# One-liner for cron: success OR fail
/usr/local/bin/backup.sh \
  && curl -fsS -m 10 https://pingzen.dev/api/v1/ping/aBcDeFgHiJkLmNoPqR/daily-backup/success \
  || curl -fsS -m 10 https://pingzen.dev/api/v1/ping/aBcDeFgHiJkLmNoPqR/daily-backup/fail

Примеры кода

Пример на Python

import requests

# Get your API key from: Profile → API Keys → Create New Key
PINGZEN_API_KEY = "YOUR_API_KEY"
BASE_URL = "https://pingzen.dev/api/v1"

headers = {
    "X-API-Key": PINGZEN_API_KEY,
    "Content-Type": "application/json"
}

# Create a monitor
monitor_data = {
    "name": "My Website",
    "url": "https://example.com",
    "protocol": "https",
    "interval_seconds": 60,
    "workspace_id": 1
}

response = requests.post(
    f"{BASE_URL}/monitors",
    headers=headers,
    json=monitor_data
)

print(response.json())

# Get all monitors (ответ — объект {monitors: [...], total, page, page_size})
data = requests.get(
    f"{BASE_URL}/monitors",
    headers=headers,
    params={"workspace_id": 1},  # scope: ваше пространство
).json()

for monitor in data["monitors"]:
    print(f"{monitor['name']}: {monitor['status']}")

Пример на JavaScript

// Get your API key from: Profile → API Keys → Create New Key
const PINGZEN_API_KEY = 'pz_abc12345_...';
const BASE_URL = 'https://pingzen.dev/api/v1';

const headers = {
  'X-API-Key': PINGZEN_API_KEY,
  'Content-Type': 'application/json'
};

// Create a monitor
async function createMonitor() {
  const response = await fetch(`${BASE_URL}/monitors`, {
    method: 'POST',
    headers: headers,
    body: JSON.stringify({
      name: 'My Website',
      url: 'https://example.com',
      protocol: 'https',
      interval_seconds: 60,
      workspace_id: 1
    })
  });

  const data = await response.json();
  console.log(data);
}

// Get all monitors (ответ — {monitors: [...], total, page, page_size})
async function getMonitors() {
  const response = await fetch(
    `${BASE_URL}/monitors?workspace_id=1`,  // scope: ваше пространство
    { headers: headers },
  );

  const data = await response.json();
  data.monitors.forEach(monitor => {
    console.log(`${monitor.name}: ${monitor.status}`);
  });
}

createMonitor();
getMonitors();

Примеры мониторинга Heartbeat / Cron

Мониторинг cron-задач, запланированных задач и фоновых процессов. Создайте heartbeat-монитор, затем отправляйте пинги из ваших скриптов для подтверждения их выполнения.

Bash / Cron задача

#!/bin/bash
# === Pattern 1: Chain with && (recommended for cron) ===
# curl runs ONLY if backup succeeds (exit code 0)
# If backup fails — no ping — PingZen alerts after grace period
#
# 0 2 * * * /usr/local/bin/backup.sh && curl -fsS -m 10 https://pingzen.dev/api/v1/ping/YOUR_PING_KEY/YOUR_SLUG

# === Pattern 2: Report both success AND failure (best) ===
# /success on success, /fail on failure — instant alert, no waiting
#
# 0 2 * * * /usr/local/bin/backup.sh \
#   && curl -fsS -m 10 https://pingzen.dev/api/v1/ping/YOUR_PING_KEY/YOUR_SLUG/success \
#   || curl -fsS -m 10 https://pingzen.dev/api/v1/ping/YOUR_PING_KEY/YOUR_SLUG/fail

# === Pattern 3: Full script with duration and payload ===
PING_KEY="YOUR_PING_KEY"
SLUG="daily-backup"
SECRET="YOUR_SECRET"
PING_URL="https://pingzen.dev/api/v1/ping/$PING_KEY/$SLUG"
SECONDS=0  # Bash built-in timer

# Your backup logic
pg_dump mydb > /backups/mydb_$(date +%F).sql

if [ $? -eq 0 ]; then
  # Report success with duration
  curl -fsS -m 10 -X POST "$PING_URL/success" \
    -H "X-Secret: $SECRET" \
    -H "Content-Type: application/json" \
    -d "{\"duration_ms\": $((SECONDS * 1000))}"
else
  # Report failure — instant alert
  curl -fsS -m 10 -X POST "$PING_URL/fail" \
    -H "X-Secret: $SECRET" \
    -H "Content-Type: application/json" \
    -d "{\"payload\": {\"error\": \"pg_dump failed\"}}"
fi

Heartbeat на Python

import requests

BASE_URL = "https://pingzen.dev/api/v1"

# CRUD /heartbeats пока требует JWT (X-API-Key ещё не поддержан).
# Логинимся один раз, дальше переиспользуем токен; обновлять через
# /auth/refresh после 15 минут.
login = requests.post(
    f"{BASE_URL}/auth/login",
    json={"email": "you@example.com", "password": "..."},
).json()
ACCESS = login["access_token"]
WORKSPACE_ID = requests.get(
    f"{BASE_URL}/workspaces/default",
    headers={"Authorization": f"Bearer {ACCESS}"},
).json()["id"]

# Создаём heartbeat (workspace_id передаётся как query, не в body)
heartbeat = requests.post(
    f"{BASE_URL}/heartbeats",
    params={"workspace_id": WORKSPACE_ID},
    headers={"Authorization": f"Bearer {ACCESS}", "Content-Type": "application/json"},
    json={
        "name": "Daily Backup",
        "expected_interval_seconds": 86400,
        "grace_period_seconds": 600,
    },
).json()

ping_key = heartbeat["ping_key"]  # ключ пространства
slug = heartbeat["slug"]
secret = heartbeat["secret"]      # показывается ОДИН раз — сохраните
ping_url = f"{BASE_URL}/ping/{ping_key}/{slug}"
print(f"Ping URL: {ping_url}")

# Из cron-скрипта пингуем (для самого пинга авторизация не нужна,
# X-Secret аутентифицирует только lifecycle-сигналы success/fail)
requests.post(
    f"{ping_url}/success",
    headers={"X-Secret": secret, "Content-Type": "application/json"},
    json={"duration_ms": 12000, "payload": {"status": "ok"}},
)

Heartbeat на JavaScript

const BASE_URL = 'https://pingzen.dev/api/v1';

// CRUD /heartbeats currently requires JWT (X-API-Key not yet supported).
// Login once, reuse the token; refresh via /auth/refresh after 15 minutes.
async function login(email, password) {
  const res = await fetch(`${BASE_URL}/auth/login`, {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ email, password }),
  });
  return (await res.json()).access_token;
}

async function defaultWorkspaceId(access) {
  const res = await fetch(`${BASE_URL}/workspaces/default`, {
    headers: { 'Authorization': `Bearer ${access}` },
  });
  return (await res.json()).id;
}

// workspace_id передаётся в query, не в body
async function createHeartbeat(access, workspaceId) {
  const response = await fetch(
    `${BASE_URL}/heartbeats?workspace_id=${workspaceId}`,
    {
      method: 'POST',
      headers: {
        'Authorization': `Bearer ${access}`,
        'Content-Type': 'application/json',
      },
      body: JSON.stringify({
        name: 'Nightly Report',
        expected_interval_seconds: 86400,
        grace_period_seconds: 600,
      }),
    },
  );

  const data = await response.json();
  console.log('Ping URL:', `${BASE_URL}/ping/${data.ping_key}/${data.slug}`);
  console.log('Secret:', data.secret); // показывается один раз — сохраните
  return data;
}

// Из cron'а: пинг не требует JWT, X-Secret аутентифицирует сигнал
async function sendPing(pingKey, slug, secret) {
  await fetch(`${BASE_URL}/ping/${pingKey}/${slug}/success`, {
    method: 'POST',
    headers: {
      'X-Secret': secret,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      duration_ms: 5000,
      payload: { rows_processed: 1000 },
    }),
  });
}

OpenAPI и AI-агенты

PingZen предоставляет машиночитаемые спецификации для интеграции с AI-агентами и инструментами автоматизации.

Лимиты запросов