Cómo integrar el monitoring de uptime en tu app con una API

Cuando gestionas más de un puñado de sitios web, hacer clic en un dashboard para añadir dominios, comprobar el estado y sacar informes deja de escalar. Necesitas una API. Una API de monitoring de uptime te permite automatizar la gestión de dominios, integrar los datos de monitoring en tus propias herramientas y construir flujos de trabajo que respondan a los incidentes de forma programática.

Esta guía explica cómo integrar la REST API de Nova Uptime en tu aplicación, desde la autenticación y los endpoints principales hasta ejemplos prácticos de código y patrones de integración.

Por qué integrar el monitoring vía API#

Automatización#

Añadir un nuevo dominio al monitoring no debería requerir entrar en un dashboard. Si tu plataforma provisiona sitios web (para clientes, inquilinos o equipos internos), la configuración del monitoring debería formar parte del script de provisioning. Cuando se da de baja un dominio, el monitoring debería eliminarse automáticamente.

Dashboards personalizados#

Puede que ya tengas un dashboard interno o un portal de clientes. En lugar de pedir a los usuarios que consulten una herramienta de monitoring aparte, lleva los datos de uptime a la interfaz que ya usan. Muestra el porcentaje de uptime, los incidentes recientes y el estado actual directamente en tu aplicación.

Integración CI/CD#

Después de desplegar una nueva versión de tu aplicación, quieres saber inmediatamente si el deployment ha roto algo. Una integración con la API puede comprobar el estado del monitoring tras el deployment, recuperar los incidentes recientes y marcar cualquier problema post-deploy en tu pipeline de CI/CD.

SaaS multi-tenant#

Si gestionas una plataforma SaaS donde cada cliente tiene su propio subdominio o dominio personalizado, necesitas monitoring a escala. La API te permite añadir programáticamente monitoring para cada nuevo cliente, eliminarlo cuando se da de baja y obtener métricas de uptime por cliente para el dashboard de su cuenta.

Visión general de la API de Nova Uptime#

Base URL#

Todas las peticiones a la API van a:

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

Autenticación#

Toda petición debe incluir una API key en la cabecera X-API-Key. Puedes generar una API key desde el dashboard de Nova Uptime en Settings.

X-API-Key: your_api_key_here

Las API keys son cadenas alfanuméricas de 20 caracteres, únicas por usuario. Cada key tiene los mismos permisos que la cuenta de usuario a la que pertenece.

Límites de uso#

La API aplica límites de uso para evitar abusos. Los límites estándar permiten un número generoso de peticiones por minuto para operaciones normales. Si superas el límite, recibirás una respuesta 429 Too Many Requests. Implementa exponential backoff en tu integración para gestionarlo de forma elegante.

Formato de respuesta#

Todas las respuestas siguen una estructura JSON consistente:

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

Las respuestas de error incluyen un mensaje descriptivo:

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

Los códigos de estado HTTP siguen las convenciones estándar: 200 para éxito, 201 para recursos creados, 400 para errores de validación, 401 para fallos de autenticación, 404 para no encontrado y 429 para rate limiting.

Endpoints clave#

Listar los dominios monitorizados#

Recupera todos los dominios de tu cuenta con su estado actual, datos de uptime y configuración.

Petición:

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

Respuesta (resumida):

{
  "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
    }
  }
}

El endpoint admite paginación con el parámetro ?page=1. El tamaño máximo de página es de 50 dominios.

Obtener detalles de un dominio#

Recupera información detallada sobre un dominio concreto, incluida su configuración completa.

Petición:

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

Añadir un nuevo dominio#

Añade un dominio al monitoring. El sistema normaliza la URL (añade https:// si falta), la valida y empieza a monitorizarla inmediatamente.

Petición:

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
  }'

Respuesta:

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

El estado del dominio será unknown inicialmente. La primera comprobación de salud se ejecuta a los pocos segundos de añadir el dominio, tras lo cual el estado se actualiza a up, down o degraded.

Nota: Hay un límite de 10 dominios vía API por cuenta (se aplican los límites del plan). El intervalo de comprobación debe ser igual o superior al mínimo permitido por tu plan.

Eliminar un dominio#

Elimina un dominio del monitoring. Es un soft delete: el dominio se desactiva pero sus datos históricos se conservan.

Petición:

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

Obtener incidentes de un dominio#

Recupera los incidentes más recientes (eventos de downtime) de un dominio concreto.

Petición:

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

Respuesta (resumida):

{
  "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"
    }
  ]
}

El endpoint devuelve los 20 incidentes más recientes.

Obtener histórico de comprobaciones#

Recupera los resultados históricos de las comprobaciones de salud de un dominio. Útil para construir gráficos de tiempo de respuesta o calcular métricas de uptime personalizadas.

Petición:

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

El parámetro hours controla cuánto retroceder en el tiempo, con un máximo de 720 horas (30 días) y un máximo de 500 registros por respuesta.

Ejecutar una comprobación de Email Health#

Realiza una comprobación de email health en cualquier dominio. Comprueba registros MX, SPF, DKIM, DMARC y el estado de blacklist.

Petición:

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"
  }'

Añade "fresh": true para saltarte la caché y forzar una consulta nueva:

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
  }'

La respuesta incluye puntuaciones para cada categoría (MX, SPF, DKIM, DMARC, blacklist), una puntuación global, una nota en formato letra y recomendaciones accionables.

Ejemplos de código en JavaScript / Node.js#

Configurar un cliente de API#

Crea un cliente de API reutilizable para gestionar la autenticación, los errores y el parseo de respuestas:

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;
}

Añadir un dominio#

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);

Listar todos los dominios con paginación#

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;
}

Comprobar incidentes recientes#

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`
      );
    }
  }
}

Ejecutar una comprobación de 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;
}

Patrones comunes de integración#

Añadir dominios automáticamente al desplegar#

Si tu pipeline de despliegue crea o configura sitios web, añade el monitoring como paso post-deploy:

// 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}`);
  }
}

Este patrón es especialmente útil para plataformas que provisionan subdominios de cliente. Cada nuevo cliente recibe monitoring automáticamente sin intervención manual.

Verificación de salud post-deploy#

Después de desplegar, comprueba si el sitio responde correctamente:

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;
}

Construir un dashboard de estado personalizado#

Lleva los datos de monitoring a tu propio dashboard:

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;
}

Auditorías de Email Health programadas#

Ejecuta comprobaciones de email health en todos tus dominios de forma programada y marca los que hayan caído por debajo de un umbral:

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;
}

Buenas prácticas#

Gestión de errores#

Gestiona siempre los errores de la API con elegancia. Pueden producirse timeouts de red, rate limits y errores de servidor. Implementa lógica de reintentos con exponential 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));
    }
  }
}

Paginación#

Nunca des por hecho que todos los datos caben en una sola respuesta. Gestiona siempre la paginación al listar dominios o recuperar el histórico:

• Comprueba el valor pagination.totalPages en las respuestas de listado.
• Itera por todas las páginas para obtener los datos completos.
• Respeta el tamaño máximo de página (50 para dominios).

Caché#

Si muestras datos de monitoring en un dashboard que se refresca con frecuencia, cachea las respuestas de la API por tu lado. Los cambios de estado de un dominio se miden en minutos, no en segundos, así que una caché de 60 segundos para el estado y de 5 minutos para los datos históricos es razonable.

Los datos de email health cambian todavía con menos frecuencia. Un TTL de caché de 1 hora es apropiado para los resultados de email health.

Conciencia del rate limit#

Estructura tu integración para minimizar las llamadas innecesarias a la API:

• Cachea las respuestas siempre que puedas.
• Usa los parámetros de paginación para obtener solo los datos que necesitas.
• Evita hacer polling de la API en bucles ajustados. En su lugar, haz polling en intervalos apropiados para tu caso de uso (cada 1-5 minutos para el estado, cada hora o cada día para email health).
• Cuando compruebes varios dominios, añade un pequeño retardo entre peticiones para no chocar con los rate limits.

Protege tu API key#

• Guarda tu API key en variables de entorno, no en el código fuente.
• No expongas la API key en JavaScript del lado del cliente. Todas las llamadas a la API deberían pasar por tu backend.
• Si sospechas que una key se ha visto comprometida, regenérala inmediatamente desde los ajustes del dashboard de Nova Uptime.
• Usa una API key separada para cada entorno (desarrollo, staging, producción) si es posible.

Gestiona la normalización de URLs de dominio#

La API normaliza las URLs al añadir dominios (añade https:// si falta), pero tu integración también debería normalizarlas antes de hacer peticiones para evitar crear entradas duplicadas:

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

Requisitos de acceso a la API#

La API de Nova Uptime está disponible en todos los planes, incluido el Free. La página de precios tiene una comparación completa de lo que incluye cada plan:

• Plan Free: 5 dominios, acceso a la API, dashboard, email health.
• Plan Pro: acceso a la API con hasta 100 dominios.
• Plan Agency: acceso a la API con hasta 1.000 dominios y todas las funciones.

Genera tu API key desde la página de Settings en el dashboard de Nova Uptime. La referencia completa de la API, con esquemas de petición/respuesta para cada endpoint, está disponible en la página de documentación de la API.

Conclusión#

Una integración con la API convierte el monitoring de una actividad manual basada en un dashboard en un componente automatizado y programable de tu infraestructura. Tanto si estás construyendo una plataforma SaaS multi-tenant, como gestionando una agencia con cientos de sitios de cliente o automatizando tu pipeline de despliegue, la API es la interfaz que hace que el monitoring escale.

Empieza por lo básico: añade dominios programáticamente y obtén datos de estado. Luego ve construyendo patrones más avanzados como la verificación de salud post-deploy, dashboards personalizados y auditorías de email health programadas.

La referencia completa de la API con playground interactivo está disponible en api.novauptime.com/api-docs. También puedes explorar el conjunto completo de funciones de Nova Uptime en la página de funciones.