API управления мониторингом: заводим сайты клиентов без рук в дашборде

21 июля 2026 · 7 мин чтения

Завели нового клиента студии — и дальше рутина: зайти в дашборд, создать монитор доступности, монитор SSL, монитор домена, поднять статус-страницу, привязать Telegram-канал. Десяток кликов на каждый сайт, и так на каждого нового клиента. У Pingvera теперь есть способ сделать это одним скриптом: REST API умеет не только читать данные мониторинга, но и управлять им — создавать, менять и удалять мониторы, статус-страницы и каналы доставки.

Что изменилось: от чтения к записи

Публичный API Pingvera (/api/v1) существовал и раньше, но только на чтение — список мониторов, события, метрики хоста. Этого хватало для интеграций «посмотреть», в том числе для MCP-сервера, который подключает мониторинг к ИИ-ассистентам вроде Claude Code. Но завести новый монитор или поправить статус-страницу можно было только руками, в дашборде.

Теперь те же самые ручки, которыми пользуется сам дашборд, доступны и по токену: POST/PATCH/DELETE /monitors, POST/PUT/DELETE /status-pages, POST/DELETE /channels. Это не параллельный урезанный API — это тот же контур, поэтому всё, что можно настроить в интерфейсе, можно настроить и скриптом.

Аутентификация: токен pv_... вместо сессии

Токен создаётся в дашборде: Настройки → API-токены. Секрет вида pv_... показывается один раз — сохраните сразу, восстановить нельзя, только отозвать и выпустить новый. Каждый запрос несёт его в заголовке:

Authorization: Bearer pv_...
Content-Type: application/json

Отозванный токен перестаёт работать мгновенно — проверка идёт в базе на каждый запрос, без кэша.

Организация — из токена, а не из тела запроса

Токен привязан к одной организации в момент создания, и организация всегда берётся из него. Поле org, которое дашборд отправляет по сессии, для токен-запросов просто игнорируется — можно его вообще не передавать. Это же защищает от подмены: токеном одной организации нельзя создать, изменить или удалить ресурс в чужой. Сервер в этом случае вернёт 404 — как для несуществующего ресурса, чтобы не подтверждать даже сам факт существования чужой организации.

Скоупы: read и write раздельно

Список скоупов закрытый — опечатка при создании токена даёт отказ, а не токен-пустышку с непонятными правами:

• read:monitoring — чтение мониторов, событий, аптайма;
• read:hosts, read:metrics — серверы с агентом и их метрики;
• write:monitors — создание/изменение/удаление мониторов (и неявно чтение своих);
• write:status-pages — то же для статус-страниц;
• write:channels — создание и удаление каналов доставки.

Один токен может нести несколько скоупов сразу. Запрос без нужного скоупа возвращает 403, а не молчаливо режет функциональность — сразу видно, чего не хватает. Управляет токенами только сессия дашборда с ролью admin: токеном нельзя выпустить другой токен — это сознательное ограничение против эскалации привилегий через утечку одного секрета.

Онбординг клиента одним скриптом

Практическая причина, по которой write-API важен именно студиям: заводить клиента — не разовая настройка одного сайта, а типовой набор проверок, который повторяется на каждом новом договоре. Создать HTTP-монитор:

curl -s https://app.pingvera.ru/api/v1/monitors \
  -H "Authorization: Bearer pv_..." \
  -H 'Content-Type: application/json' \
  -d '{"type":"http","name":"Главная","target":"https://client-site.ru","interval_s":60}'

Дальше тем же токеном — монитор домена/SSL, статус-страница под клиента, канал уведомлений в его Telegram. Скрипт из пяти-шести таких вызовов делает то, на что руками уходит несколько минут кликов — и делает это одинаково для сотого клиента, как и для первого, без риска что-то забыть в спешке.

Изменить монитор — частичный PATCH, сервер трогает только переданные поля:

curl -s -X PATCH https://app.pingvera.ru/api/v1/monitors/mon_01J... \
  -H "Authorization: Bearer pv_..." \
  -H 'Content-Type: application/json' \
  -d '{"interval_s":30,"fail_threshold":3}'

А когда клиент уходит — снять мониторинг так же скриптом:

curl -s -o /dev/null -w '%{http_code}\n' -X DELETE \
  https://app.pingvera.ru/api/v1/monitors/mon_01J... \
  -H "Authorization: Bearer pv_..."

Тип и цель монитора (type/target) при этом не меняются задним числом — это была бы уже другая проверка со своей историей, поэтому смена цели — это удаление старого монитора и создание нового, а не редактирование существующего.

Статус-страницы и каналы тем же путём

Статус-страница создаётся и обновляется тем же принципом — POST создаёт, PUT заменяет конфигурацию целиком (не частичное изменение, как у мониторов). Канал доставки — тоже одним запросом; для вебхука секрет для HMAC-подписи возвращается один раз, в поле secret ответа, и повторно нигде не отдаётся:

curl -s https://app.pingvera.ru/api/v1/channels \
  -H "Authorization: Bearer pv_..." \
  -H 'Content-Type: application/json' \
  -d '{"type":"webhook","name":"Мой вебхук","config":{"url":"https://example.com/hook"}}'

Для обоих ресурсов отдельного read-скоупа нет: write-скоуп неявно даёт и чтение своего — тем же токеном, которым правите конфигурацию, можно посмотреть текущее состояние перед правкой. Типичный сценарий для скриптов, которые сначала проверяют, что уже есть, и только потом решают, создавать или менять.

Лимиты тарифа работают и здесь

API не открывает обходной путь мимо тарифных ограничений. Квота на число мониторов и сайтов, минимальный интервал проверки, доступность white-label для статус-страниц — те же правила, что действуют в дашборде. Упор в лимит возвращает 402, а не создаёт ресурс сверх плана. Из прочих кодов ошибок: 400 — невалидное тело запроса, 401 — токен не прошёл проверку, 403 — не хватает скоупа, 404 — чужой или несуществующий ресурс, 409 — конфликт уникальности, например занятый slug статус-страницы.

Машиночитаемая спека и что поверх API

Полное описание всех полей и параметров — в GET /api/v1/openapi.json, публичном документе без авторизации. Он же годится как вход для генераторов клиентов на любом языке. Поверх одного и того же write-API у Pingvera уже есть CLI для тех, кто предпочитает командную строку без написания HTTP-запросов, и MCP-сервер (POST /mcp) — для ИИ-ассистентов вроде Claude Code, которые сами решают, когда прочитать состояние мониторинга через инструменты. Разные интерфейсы одного контура: дашборд для рук, CLI и Terraform для скриптов и инфраструктуры как кода, API — фундамент под всеми тремя.

Главное

Write-API не добавляет новую функциональность мониторинга — он убирает необходимость делать рутинные настройки руками. Для студии, которая ведёт не один сайт, а десятки клиентских, это разница между «завести клиента — событие на полчаса» и «завести клиента — команда в терминале». Мониторинг становится частью процесса онбординга, а не отдельной задачей, про которую можно забыть в спешке между двумя другими проектами.

Частые вопросы

Чем write-API отличается от прежнего read-only?

Раньше по токену можно было только читать: список мониторов, события, метрики. Теперь те же токены со скоупами write:monitors, write:status-pages и write:channels создают, изменяют и удаляют ресурсы — POST/PATCH/DELETE на /monitors, POST/PUT/DELETE на /status-pages, POST/DELETE на /channels. Это те же ручки, что использует сам дашборд.

Как токен понимает, в какую организацию писать?

Организация привязана к токену в момент его создания в дашборде и берётся из него на каждый запрос — поле org в теле запроса игнорируется, передавать его не нужно. Попытка обратиться к чужому ресурсу вернёт 404, как для несуществующего — Pingvera не подтверждает и не опровергает существование чужих организаций.

Действуют ли лимиты тарифа через API?

Да, без исключений. Квота на число мониторов/сайтов, минимальный интервал проверки, доступность white-label для статус-страниц — те же ограничения тарифа, что и в дашборде. Упор в лимит возвращает код 402, а не создаёт ресурс сверх плана.

Читайте также: Мониторинг в вашем ИИ-ассистенте: подключаем Claude или Cursor к Pingvera и Как веб-студии следить за сайтами клиентов на абонентке.