API мониторов

API мониторов является частью User API. Он позволяет программно получать список, создавать, читать, обновлять и удалять мониторы, а также извлекать историю проверок, метрики производительности и сводки по uptime. Все эндпоинты этого семейства аутентифицируются пользовательским API-токеном, отправляемым как Bearer-токен.

Базовый URL и аутентификация

https://api.statusradar.dev/v1

Каждый запрос (кроме публичного маршрута uptime ниже) требует пользовательского API-токена:

Authorization: Bearer YOUR_API_TOKEN

Сгенерируйте токен в Dashboard → Settings → API (/dashboard/settings/api). Токен показывается только один раз; если вы его потеряете, сгенерируйте новый. Запросы ограничены командой, которой принадлежит токен — вы можете видеть и управлять только мониторами, которые принадлежат вашей активной команде. См. Аутентификация API.

Операции создания, обновления и удаления также требуют разрешения manage_monitors. Командные роли owner, admin и member обладают им; viewer имеет доступ только на чтение. См. Команды.

Формат ответа

Все ответы используют единообразную JSON-обёртку.

Успех:

{
  "success": true,
  "message": "Success",
  "data": { ... }
}

Ошибка:

{
  "success": false,
  "message": "Monitor not found",
  "errors": []
}

Коды статусов: 200 OK, 201 создано, 400 некорректное тело JSON, 401 не авторизован, 403 запрещено (нет разрешения), 404 монитор не найден, 422 ошибка валидации, 500 ошибка сервера.

Эндпоинты

Типы мониторов и поля

Монитор имеет type, набор общих полей и, в зависимости от типа, несколько полей, специфичных для типа.

Общие поля

Тип монитора. Тип server (метрики хоста на основе агента) не создаётся через этот API — вместо этого установите серверный агент. API принимает http, https, ping, tcp, ssl и dns.

Поля, специфичные для типа

HTTP / HTTPS (type: "http" или "https")

Для HTTP/HTTPS target проверяется на безопасность от SSRF при создании; приватные/loopback-цели отклоняются с 422.

TCP (type: "tcp")

SSL (type: "ssl")

DNS (type: "dns")

Список мониторов

GET /v1/monitors

Возвращает все мониторы, принадлежащие вашей команде, каждый из которых дополнен последним статусом, полученным из VictoriaMetrics.

curl -H "Authorization: Bearer YOUR_API_TOKEN" \
  https://api.statusradar.dev/v1/monitors

Ответ:

{
  "success": true,
  "message": "Success",
  "data": {
    "monitors": [
      {
        "id": 123,
        "type": "https",
        "name": "Marketing site",
        "target": "https://example.com",
        "interval_seconds": 60,
        "timeout_seconds": 30,
        "retry_count": 3,
        "is_active": 1,
        "current_status": "up",
        "last_status": "up",
        "last_response_time": 142,
        "last_checked_at": "2026-06-23T10:15:00Z",
        "status_class": "success",
        "uptime_percentage": 99.98
      }
    ],
    "count": 1
  }
}

last_status равен pending, когда ещё не было выполнено ни одной проверки, и unknown, если метрики временно недоступны.

Создание монитора

POST /v1/monitors

Отправьте тело в формате JSON. name, type и target обязательны. Возвращает 201 с созданным монитором.

curl -X POST https://api.statusradar.dev/v1/monitors \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Marketing site",
    "type": "https",
    "target": "https://example.com",
    "interval_seconds": 60,
    "timeout_seconds": 30,
    "retry_count": 3,
    "method": "GET",
    "expected_status": 200,
    "expected_string": "Welcome",
    "follow_redirects": true,
    "headers": { "User-Agent": "StatusRadar" },
    "probe_servers": [1, 4]
  }'

Ответ:

{
  "success": true,
  "message": "Success",
  "data": {
    "monitor": {
      "id": 123,
      "type": "https",
      "name": "Marketing site",
      "target": "https://example.com"
    },
    "id": 123
  }
}

Ошибки валидации возвращают 422:

{
  "success": false,
  "message": "Validation failed",
  "errors": {
    "type": "Invalid monitor type",
    "target": "Target is required"
  }
}

Пример DNS:

curl -X POST https://api.statusradar.dev/v1/monitors \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "MX record",
    "type": "dns",
    "target": "example.com",
    "dns_record_type": "MX",
    "dns_expected": "mail.example.com"
  }'

Получение монитора

GET /v1/monitors/{id}

Возвращает монитор плюс uptime за 24ч/7д/30д и среднее время ответа за 24ч.

curl -H "Authorization: Bearer YOUR_API_TOKEN" \
  https://api.statusradar.dev/v1/monitors/123

Ответ:

{
  "success": true,
  "message": "Success",
  "data": {
    "monitor": {
      "id": 123,
      "name": "Marketing site",
      "type": "https",
      "target": "https://example.com",
      "last_status": "up",
      "last_response_time": 142,
      "last_checked_at": "2026-06-23T10:15:00Z"
    },
    "uptime": {
      "24h": 100.0,
      "7d": 99.95,
      "30d": 99.98
    },
    "avg_response_time_ms": 138
  }
}

Возвращает 404, если монитор не существует или не принадлежит вашей команде.

Обновление монитора

PUT /v1/monitors/{id}

Отправляйте только те поля, которые хотите изменить. type монитора изменить нельзя; поля, специфичные для типа, применяются к существующему типу. Возвращает обновлённый монитор.

curl -X PUT https://api.statusradar.dev/v1/monitors/123 \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Marketing site (prod)",
    "interval_seconds": 120,
    "is_active": false
  }'

Ответ:

{
  "success": true,
  "message": "Success",
  "data": {
    "monitor": {
      "id": 123,
      "name": "Marketing site (prod)",
      "interval_seconds": 120,
      "is_active": 0
    }
  }
}

Обновляемые общие поля: name, group_name, interval_seconds, timeout_seconds, retry_count, is_active, notify_on_failure, notify_on_recovery, а также поля, специфичные для существующего типа монитора.

Удаление монитора

DELETE /v1/monitors/{id}

curl -X DELETE https://api.statusradar.dev/v1/monitors/123 \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Ответ:

{
  "success": true,
  "message": "Success",
  "data": {
    "message": "Monitor deleted successfully"
  }
}

История проверок

GET /v1/monitors/{id}/checks?hours=24

Возвращает недавние результаты проверок (по умолчанию за последние 24 часа), новейшие первыми. Обеспечивается VictoriaMetrics с разрешением 5 минут.

curl -H "Authorization: Bearer YOUR_API_TOKEN" \
  "https://api.statusradar.dev/v1/monitors/123/checks?hours=48"

Ответ:

{
  "success": true,
  "message": "Success",
  "data": {
    "checks": [
      {
        "status": "up",
        "response_time_ms": 142,
        "status_code": 200,
        "error_message": null,
        "checked_at": "2026-06-23T10:15:00Z"
      }
    ],
    "count": 1
  }
}

Метрики

GET /v1/monitors/{id}/metrics?hours=24

Возвращает временные ряды времени ответа и статуса (по умолчанию за последние 24 часа, шаг 5 минут).

curl -H "Authorization: Bearer YOUR_API_TOKEN" \
  "https://api.statusradar.dev/v1/monitors/123/metrics?hours=24"

Ответ:

{
  "success": true,
  "message": "Success",
  "data": {
    "monitor_id": "123",
    "hours": 24,
    "response_time": [
      { "time": "2026-06-23T10:00:00Z", "value": 138 }
    ],
    "status": [
      { "time": "2026-06-23T10:00:00Z", "status": "up" }
    ]
  }
}

Сводка по uptime

GET /v1/monitors/{id}/uptime

Возвращает проценты uptime за 24ч, 7д, 30д и 90д.

curl -H "Authorization: Bearer YOUR_API_TOKEN" \
  https://api.statusradar.dev/v1/monitors/123/uptime

Ответ:

{
  "success": true,
  "message": "Success",
  "data": {
    "monitor_id": "123",
    "uptime": {
      "24h": 100.0,
      "7d": 99.95,
      "30d": 99.98,
      "90d": 99.97
    }
  }
}

Публичный эндпоинт uptime

GET /v1/monitors/{id}/uptime

Также доступен публичный вариант эндпоинта uptime без аутентификации для встраивания показателей uptime на внешние страницы. Он возвращает ту же структуру сводки по uptime без необходимости в Bearer-токене. Для программного доступа к собственным мониторам используйте аутентифицированный маршрут User API выше.

Дальнейшие шаги

• Обзор API — полная поверхность API и соглашения
• Аутентификация API — типы токенов и как их отправлять
• Установка агента — настройка мониторинга серверов (агентом)
• Обзор оповещений — направление сбоев мониторов в каналы
• Обзор OTLP — бэкенд-traces, logs и metrics