---
title: API управления мониторингом — заводим сайты клиентов без рук в дашборде
description: У Pingvera появился write-API — создавать, менять и удалять мониторы, статус-страницы и каналы можно скриптом, по токену pv_..., а не руками в дашборде. Разбираем скоупы, лимиты и примеры curl для онбординга новых клиентов студии.
source: https://pingvera.ru/blog/api-upravleniya-monitoringom.html
---
# API управления мониторингом: заводим сайты клиентов без рук в дашборде

Завели нового клиента студии — и дальше рутина: зайти в дашборд, создать монитор доступности, монитор 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-подписи](https://pingvera.ru/blog/podpisannye-vebhuki.html) возвращается один раз, в поле `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](https://pingvera.ru/blog/cli-pingvera-monitoring-iz-terminala.html) для тех, кто предпочитает командную строку без написания HTTP-запросов, и MCP-сервер (`POST /mcp`) — для ИИ-ассистентов вроде Claude Code, которые сами решают, когда прочитать состояние мониторинга через инструменты. Разные интерфейсы одного контура: дашборд для рук, CLI и [Terraform](https://pingvera.ru/blog/terraform-provider-monitoring-kak-kod.html) для скриптов и инфраструктуры как кода, 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, а не создаёт ресурс сверх плана.