Как встроить мониторинг доступности в ваше приложение через API

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

Этот гайд проводит вас через интеграцию REST API Nova Uptime — от аутентификации и базовых эндпоинтов до практических примеров кода и шаблонов интеграции.

Зачем интегрировать мониторинг через API#

Автоматизация

Добавление нового домена в мониторинг не должно требовать входа в дашборд. Если ваша платформа провижинит сайты (для клиентов, тенантов или внутренних команд), настройка мониторинга должна быть частью скрипта провижининга. Когда домен выводится из эксплуатации — мониторинг должен сниматься автоматически.

Кастомные дашборды

У вас уже может быть внутренний дашборд или клиентский портал. Вместо того чтобы отправлять пользователей в отдельный инструмент, тяните данные доступности в интерфейс, которым они уже пользуются. Покажите процент uptime, недавние инциденты и текущий статус прямо в своём приложении.

Интеграция с CI/CD#

После выкатки новой версии вы хотите сразу понять, не сломался ли деплой. Интеграция через API может проверить статус мониторинга после деплоя, вытащить недавние инциденты и пометить пост-деплойные проблемы прямо в вашем CI/CD-пайплайне.

Multi-tenant SaaS#

Если у вас SaaS-платформа, где у каждого клиента свой поддомен или кастомный домен, мониторинг нужен в масштабе. API позволяет программно добавлять мониторинг для каждого нового клиента, удалять его при отписке и вытаскивать поклиентские метрики доступности в их аккаунт.

Обзор API Nova Uptime#

Базовый URL#

Все запросы идут на:

https://api.novauptime.com/api/v1

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

В каждом запросе должен быть API-ключ в заголовке X-API-Key. Сгенерировать ключ можно в настройках дашборда Nova Uptime.

X-API-Key: your_api_key_here

API-ключи — это 20-символьные алфавитно-цифровые строки, уникальные для пользователя. У ключа те же права, что и у владельца аккаунта.

Rate limits#

API применяет rate-limit, чтобы избежать злоупотреблений. Стандартные лимиты допускают щедрое количество запросов в минуту для нормальной работы. Если вы превысите лимит, получите 429 Too Many Requests. Реализуйте экспоненциальный backoff, чтобы это обрабатывалось аккуратно.

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

Все ответы в одном формате JSON:

{
  "success": true,
  "message": "Domains retrieved successfully",
  "data": {
    // Response payload
  }
}

Ответы об ошибках содержат описательное сообщение:

{
  "success": false,
  "message": "Domain not found"
}

HTTP-коды стандартные: 200 — успех, 201 — ресурс создан, 400 — ошибка валидации, 401 — ошибка аутентификации, 404 — не найдено, 429 — rate-limit.

Ключевые эндпоинты

Список мониторируемых доменов

Возвращает все домены аккаунта с текущим статусом, данными доступности и конфигурацией.

Запрос:

curl -X GET "https://api.novauptime.com/api/v1/domains" \
  -H "X-API-Key: your_api_key_here"

Ответ (сокращённо):

{
  "success": true,
  "data": {
    "domains": [
      {
        "id": "clx1abc...",
        "url": "https://example.com",
        "status": "up",
        "lastCheckedAt": "2026-02-04T10:30:00Z",
        "responseTime": 245,
        "uptimePercentage": 99.97,
        "sslValid": true,
        "sslExpiresAt": "2026-08-15T00:00:00Z",
        "checkInterval": 300,
        "emailHealthGrade": "A"
      }
    ],
    "pagination": {
      "page": 1,
      "totalPages": 3,
      "total": 28
    }
  }
}

Эндпоинт поддерживает пагинацию через ?page=1. Максимальный размер страницы — 50 доменов.

Детали домена

Возвращает подробную информацию о конкретном домене и его конфигурацию.

Запрос:

curl -X GET "https://api.novauptime.com/api/v1/domains/clx1abc123" \
  -H "X-API-Key: your_api_key_here"

Добавление домена

Добавляет домен в мониторинг. Система нормализует URL (добавляет https://, если нет), валидирует и сразу начинает мониторинг.

Запрос:

curl -X POST "https://api.novauptime.com/api/v1/domains" \
  -H "X-API-Key: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://newsite.example.com",
    "checkInterval": 300
  }'

Ответ:

{
  "success": true,
  "message": "Domain added successfully",
  "data": {
    "id": "clx2def...",
    "url": "https://newsite.example.com",
    "status": "unknown",
    "checkInterval": 300
  }
}

Изначально статус будет unknown. Первая проверка проходит в течение секунд после добавления, после чего статус обновляется на up, down или degraded.

Заметка: через API на аккаунт действует лимит в 10 доменов (применяются ограничения тарифа). Интервал проверки должен быть не меньше минимально допустимого на вашем тарифе.

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

Удаляет домен из мониторинга. Это soft-delete: домен деактивируется, но историческая статистика сохраняется.

Запрос:

curl -X DELETE "https://api.novauptime.com/api/v1/domains/clx2def456" \
  -H "X-API-Key: your_api_key_here"

Инциденты по домену

Возвращает последние инциденты (события простоя) по конкретному домену.

Запрос:

curl -X GET "https://api.novauptime.com/api/v1/domains/clx1abc123/incidents" \
  -H "X-API-Key: your_api_key_here"

Ответ (сокращённо):

{
  "success": true,
  "data": [
    {
      "id": "inc_001",
      "startedAt": "2026-02-03T14:22:00Z",
      "resolvedAt": "2026-02-03T14:25:30Z",
      "durationSeconds": 210,
      "httpStatus": 503,
      "screenshotUrl": "https://api.novauptime.com/screenshots/inc_001.jpg"
    }
  ]
}

Эндпоинт возвращает 20 последних инцидентов.

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

Возвращает историю результатов проверок для домена. Удобно для построения графиков времени отклика или расчёта своих метрик доступности.

Запрос:

curl -X GET "https://api.novauptime.com/api/v1/domains/clx1abc123/history?hours=24" \
  -H "X-API-Key: your_api_key_here"

Параметр hours задаёт глубину выборки, максимум 720 часов (30 дней) и максимум 500 записей в ответе.

Запуск проверки email health#

Запускает проверку email health любого домена. Проверяет MX-записи, SPF, DKIM, DMARC и статус в blacklist.

Запрос:

curl -X POST "https://api.novauptime.com/api/v1/email-health" \
  -H "X-API-Key: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "domain": "example.com"
  }'

Передайте "fresh": true, чтобы пропустить кэш и запросить свежие данные:

curl -X POST "https://api.novauptime.com/api/v1/email-health" \
  -H "X-API-Key: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "domain": "example.com",
    "fresh": true
  }'

Ответ содержит оценки по каждой категории (MX, SPF, DKIM, DMARC, blacklist), общую оценку, буквенный грейд и actionable-рекомендации.

Примеры кода на JavaScript / Node.js#

Установка API-клиента#

Сделайте переиспользуемый клиент для аутентификации, обработки ошибок и парсинга ответов:

const API_BASE = 'https://api.novauptime.com/api/v1';
const API_KEY = process.env.Nova Uptime_API_KEY;

async function apiRequest(method, path, body = null) {
  const options = {
    method,
    headers: {
      'X-API-Key': API_KEY,
      'Content-Type': 'application/json',
    },
  };

  if (body) {
    options.body = JSON.stringify(body);
  }

  const response = await fetch(`${API_BASE}${path}`, options);
  const json = await response.json();

  if (!json.success) {
    throw new Error(json.message || `API error: ${response.status}`);
  }

  return json.data;
}

Добавление домена

async function addDomainToMonitoring(url, checkInterval = 300) {
  const data = await apiRequest('POST', '/domains', {
    url,
    checkInterval,
  });

  console.log(`Domain added: ${data.id}`);
  return data;
}

// Usage
await addDomainToMonitoring('https://mysite.example.com', 60);

Список всех доменов с пагинацией

async function getAllDomains() {
  const allDomains = [];
  let page = 1;
  let totalPages = 1;

  while (page <= totalPages) {
    const data = await apiRequest('GET', `/domains?page=${page}`);
    allDomains.push(...data.domains);
    totalPages = data.pagination.totalPages;
    page++;
  }

  return allDomains;
}

Проверка недавних инцидентов

async function getRecentIncidents(domainId) {
  const incidents = await apiRequest(
    'GET',
    `/domains/${domainId}/incidents`
  );
  return incidents;
}

// Check if any domain has had incidents in the last hour
async function checkAllDomainsForRecentIssues() {
  const domains = await getAllDomains();
  const oneHourAgo = new Date(Date.now() - 60 * 60 * 1000);

  for (const domain of domains) {
    const incidents = await getRecentIncidents(domain.id);
    const recentIncidents = incidents.filter(
      (inc) => new Date(inc.startedAt) > oneHourAgo
    );

    if (recentIncidents.length > 0) {
      console.log(
        `${domain.url}: ${recentIncidents.length} incident(s) in the last hour`
      );
    }
  }
}

Проверка email health#

async function checkEmailHealth(domain) {
  const result = await apiRequest('POST', '/email-health', {
    domain,
    fresh: true,
  });

  console.log(`${domain}: Grade ${result.grade} (${result.score}/100)`);

  if (result.recommendations) {
    const critical = result.recommendations.filter(
      (r) => r.severity === 'critical'
    );
    if (critical.length > 0) {
      console.log(`  Critical issues: ${critical.length}`);
      critical.forEach((r) => console.log(`  - ${r.message}`));
    }
  }

  return result;
}

Типичные шаблоны интеграции

Авто-добавление доменов при деплое

Если ваш пайплайн создаёт или конфигурирует сайты, добавляйте мониторинг как пост-деплойный шаг:

// In your deployment script or CI/CD pipeline
async function postDeployMonitoring(deployedUrl) {
  try {
    // Check if domain is already monitored
    const domains = await getAllDomains();
    const existing = domains.find((d) => d.url === deployedUrl);

    if (!existing) {
      await addDomainToMonitoring(deployedUrl, 300);
      console.log(`Monitoring added for ${deployedUrl}`);
    } else {
      console.log(`${deployedUrl} already monitored (ID: ${existing.id})`);
    }
  } catch (error) {
    // Monitoring failure should not block deployment
    console.error(`Failed to set up monitoring: ${error.message}`);
  }
}

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

Проверка здоровья после деплоя

После деплоя проверьте, отвечает ли сайт корректно:

async function verifyPostDeploy(domainId, waitMinutes = 3) {
  // Wait for a few check cycles to complete
  console.log(`Waiting ${waitMinutes} minutes for health checks...`);
  await new Promise((resolve) =>
    setTimeout(resolve, waitMinutes * 60 * 1000)
  );

  // Check for incidents since the deploy started
  const incidents = await getRecentIncidents(domainId);
  const deployTime = new Date(Date.now() - waitMinutes * 60 * 1000);

  const postDeployIncidents = incidents.filter(
    (inc) => new Date(inc.startedAt) > deployTime
  );

  if (postDeployIncidents.length > 0) {
    console.error('Post-deploy incidents detected:');
    postDeployIncidents.forEach((inc) => {
      console.error(
        `  HTTP ${inc.httpStatus} at ${inc.startedAt}`
      );
    });
    return false;
  }

  console.log('No post-deploy incidents. Deployment looks healthy.');
  return true;
}

Свой статус-дашборд

Тяните данные мониторинга в собственный дашборд:

async function getStatusDashboardData() {
  const domains = await getAllDomains();

  const dashboard = {
    total: domains.length,
    up: domains.filter((d) => d.status === 'up').length,
    down: domains.filter((d) => d.status === 'down').length,
    degraded: domains.filter((d) => d.status === 'degraded').length,
    averageResponseTime:
      domains.reduce((sum, d) => sum + (d.responseTime || 0), 0) /
      domains.length,
    sslExpiringSoon: domains.filter((d) => {
      if (!d.sslExpiresAt) return false;
      const daysLeft =
        (new Date(d.sslExpiresAt) - Date.now()) / (1000 * 60 * 60 * 24);
      return daysLeft < 30;
    }),
    domains: domains.map((d) => ({
      url: d.url,
      status: d.status,
      responseTime: d.responseTime,
      uptime: d.uptimePercentage,
      emailGrade: d.emailHealthGrade,
    })),
  };

  return dashboard;
}

Регулярные аудиты email health#

Запускайте проверки email health по всем доменам по расписанию и помечайте те, что упали ниже порога:

async function weeklyEmailHealthAudit() {
  const domains = await getAllDomains();

  const results = [];
  for (const domain of domains) {
    try {
      // Extract just the domain name from the URL
      const domainName = new URL(domain.url).hostname;
      const health = await checkEmailHealth(domainName);
      results.push({
        domain: domainName,
        score: health.score,
        grade: health.grade,
      });

      // Add a small delay between requests to respect rate limits
      await new Promise((resolve) => setTimeout(resolve, 1000));
    } catch (error) {
      results.push({
        domain: domain.url,
        score: null,
        grade: 'Error',
        error: error.message,
      });
    }
  }

  // Flag domains scoring below 70
  const flagged = results.filter((r) => r.score !== null && r.score < 70);
  if (flagged.length > 0) {
    console.log('Domains with email health issues:');
    flagged.forEach((r) => {
      console.log(`  ${r.domain}: ${r.grade} (${r.score}/100)`);
    });
  }

  return results;
}

Лучшие практики

Обработка ошибок

Всегда аккуратно обрабатывайте ошибки API. Случаются сетевые таймауты, rate-limit, серверные ошибки. Реализуйте ретраи с экспоненциальным backoff:

async function apiRequestWithRetry(method, path, body = null, maxRetries = 3) {
  for (let attempt = 1; attempt <= maxRetries; attempt++) {
    try {
      return await apiRequest(method, path, body);
    } catch (error) {
      if (attempt === maxRetries) throw error;

      // Exponential backoff: 1s, 2s, 4s
      const delay = Math.pow(2, attempt - 1) * 1000;
      console.log(
        `Attempt ${attempt} failed. Retrying in ${delay}ms...`
      );
      await new Promise((resolve) => setTimeout(resolve, delay));
    }
  }
}

Пагинация

Никогда не предполагайте, что все данные поместятся в один ответ. Всегда обрабатывайте пагинацию, когда листаете домены или историю:

• Смотрите pagination.totalPages в ответах списков.
• Перебирайте все страницы для полной выборки.
• Уважайте максимальный размер страницы (50 для доменов).

Кэширование

Если вы показываете данные мониторинга в дашборде, который часто обновляется, кэшируйте ответы API на своей стороне. Изменения статуса доменов измеряются минутами, не секундами, поэтому 60-секундный кэш для статуса и 5-минутный — для исторических данных вполне разумны.

Email health меняется ещё реже. TTL кэша в 1 час — нормально для результатов email health.

Уважайте rate limits#

Структурируйте интеграцию так, чтобы минимизировать лишние вызовы:

• Кэшируйте ответы при возможности.
• Используйте параметры пагинации, чтобы тянуть только нужное.
• Не опрашивайте API в плотных циклах. Опрос — с интервалами, подходящими под задачу (1–5 минут на статус, ежечасно/ежедневно — на email health).
• При проверке многих доменов добавляйте небольшую задержку между запросами.

Защитите API-ключ#

• Храните API-ключ в переменных окружения, не в исходниках.
• Не светите ключ в client-side JavaScript. Все вызовы должны идти через ваш бэкенд.
• Если подозреваете утечку — немедленно регенерируйте ключ в настройках Nova Uptime.
• По возможности используйте отдельный ключ под каждое окружение (dev, staging, prod).

Нормализация URL#

API нормализует URL при добавлении (добавляет https://, если нет), но и ваша интеграция должна нормализовать перед запросами, чтобы не плодить дубликаты:

function normalizeUrl(url) {
  if (!url.startsWith('http://') && !url.startsWith('https://')) {
    url = 'https://' + url;
  }
  // Remove trailing slash
  return url.replace(/\/+$/, '');
}

Требования к доступу к API#

API Nova Uptime доступен на всех тарифах, включая Free. На странице цен — полное сравнение тарифов:

• Free: 5 доменов, доступ к API, дашборд, email health.
• Pro: API-доступ до 100 доменов.
• Agency: API-доступ до 1 000 доменов и все возможности.

Сгенерировать API-ключ можно на странице Settings в дашборде Nova Uptime. Полный API-референс с request/response-схемами по каждому эндпоинту — на странице API-документации.

Заключение

Интеграция через API превращает мониторинг из ручной активности в дашборде в автоматизированный, программируемый компонент инфраструктуры. Будь то multi-tenant SaaS, агентство с сотнями клиентских сайтов или автоматизированный пайплайн деплоя — API даёт интерфейс, в котором мониторинг масштабируется.

Начните с базового: добавляйте домены программно и тяните данные о статусе. Затем переходите к продвинутым шаблонам — пост-деплойной проверке, кастомным дашбордам, регулярным аудитам email health.

Полный API-референс с интерактивной площадкой — на api.novauptime.com/api-docs. Полный набор фич Nova Uptime — на странице фич.