Como integrar monitoramento de uptime ao seu app com uma API

Quando você gerencia mais do que um punhado de sites, ficar clicando num dashboard pra adicionar domínios, conferir status e puxar relatórios deixa de escalar. Você precisa de uma API. Uma API de monitoramento de uptime permite automatizar a gestão de domínios, integrar dados de monitoramento às suas próprias ferramentas e construir fluxos que reagem a incidentes de forma programática.

Este guia mostra como integrar a API REST da Nova Uptime à sua aplicação, da autenticação e endpoints principais até exemplos práticos de código e padrões de integração.

Por que integrar monitoramento via API#

Automação#

Adicionar um novo domínio ao monitoramento não deveria exigir login num dashboard. Se a sua plataforma provisiona sites (para clientes, tenants ou times internos), a configuração do monitoramento deveria fazer parte do script de provisionamento. Quando um domínio é desativado, o monitoramento deveria ser removido automaticamente.

Dashboards customizados#

Você provavelmente já tem um dashboard interno ou um portal de cliente. Em vez de pedir pros usuários conferirem uma ferramenta de monitoramento separada, puxe os dados de uptime pra dentro da interface que eles já usam. Mostre porcentagem de uptime, incidentes recentes e status atual direto na sua aplicação.

Integração com CI/CD#

Depois de implantar uma nova versão da sua aplicação, você quer saber na hora se o deploy quebrou alguma coisa. Uma integração via API pode checar o status de monitoramento após o deploy, puxar incidentes recentes e sinalizar qualquer problema pós-deploy no seu pipeline de CI/CD.

SaaS multi-tenant#

Se você roda uma plataforma SaaS onde cada cliente tem seu próprio subdomínio ou domínio personalizado, precisa de monitoramento em escala. A API permite adicionar monitoramento programaticamente para cada novo cliente, removê-lo quando ele cancelar, e puxar métricas de uptime por cliente para o dashboard da conta dele.

Visão geral da API da Nova Uptime#

URL base#

Todas as requisições da API vão para:

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

Autenticação#

Toda requisição precisa incluir uma chave de API no header X-API-Key. Você pode gerar uma chave de API no dashboard da Nova Uptime, em Configurações.

X-API-Key: your_api_key_here

As chaves de API são strings alfanuméricas de 20 caracteres, únicas por usuário. Cada chave tem as mesmas permissões da conta de usuário à qual pertence.

Limites de taxa#

A API impõe limites de taxa para evitar abuso. Os limites padrão permitem um número generoso de requisições por minuto para operações normais. Se você ultrapassar o limite, recebe uma resposta 429 Too Many Requests. Implemente backoff exponencial na sua integração para lidar com isso de forma elegante.

Formato de resposta#

Todas as respostas seguem uma estrutura JSON consistente:

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

Respostas de erro incluem uma mensagem descritiva:

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

Os códigos de status HTTP seguem convenções padrão: 200 para sucesso, 201 para recursos criados, 400 para erros de validação, 401 para falhas de autenticação, 404 para não encontrado e 429 para rate limiting.

Endpoints principais#

Listar domínios monitorados#

Recupera todos os domínios da sua conta com status atual, dados de uptime e configuração.

Requisição:

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

Resposta (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
    }
  }
}

O endpoint suporta paginação com o parâmetro de query ?page=1. O tamanho máximo de página é 50 domínios.

Obter detalhes de um domínio#

Recupera informações detalhadas sobre um domínio específico, incluindo sua configuração completa.

Requisição:

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

Adicionar um novo domínio#

Adiciona um domínio ao monitoramento. O sistema normaliza a URL (adiciona https:// se faltar), valida e começa a monitorar imediatamente.

Requisição:

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

Resposta:

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

O status do domínio começa como unknown. A primeira verificação de saúde roda em segundos depois que o domínio é adicionado, e então o status muda para up, down ou degraded.

Observação: Existe um limite de 10 domínios via API por conta (limites de plano se aplicam). O intervalo de verificação precisa ser igual ou maior ao mínimo permitido pelo seu plano.

Excluir um domínio#

Remove um domínio do monitoramento. É um soft delete; o domínio é desativado, mas o histórico é preservado.

Requisição:

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

Obter incidentes do domínio#

Recupera os incidentes mais recentes (eventos de downtime) de um domínio específico.

Requisição:

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

Resposta (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"
    }
  ]
}

O endpoint retorna os 20 incidentes mais recentes.

Obter histórico de verificações#

Recupera resultados históricos das verificações de saúde de um domínio. Útil pra montar gráficos de tempo de resposta ou calcular métricas de uptime customizadas.

Requisição:

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

O parâmetro hours controla o período de busca, com máximo de 720 horas (30 dias) e máximo de 500 registros por resposta.

Rodar verificação de saúde de e-mail#

Executa uma verificação de saúde de e-mail em qualquer domínio. Checa registros MX, SPF, DKIM, DMARC e status em blacklists.

Requisição:

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

Adicione "fresh": true pra ignorar o cache e forçar uma nova consulta:

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

A resposta inclui pontuações para cada categoria (MX, SPF, DKIM, DMARC, blacklist), uma pontuação geral, uma nota em letra e recomendações acionáveis.

Exemplos de código em JavaScript / Node.js#

Configurando um cliente de API#

Crie um cliente de API reutilizável para lidar com autenticação, tratamento de erros e parsing de resposta:

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

Adicionando um domínio#

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

Listando todos os domínios com paginação#

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

Verificando incidentes recentes#

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

Rodando uma verificação de saúde de e-mail#

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

Padrões comuns de integração#

Auto-adicionar domínios no deploy#

Se o seu pipeline de deploy cria ou configura sites, adicione o monitoramento como passo pós-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}`);
  }
}

Esse padrão é especialmente útil para plataformas que provisionam subdomínios de clientes. Cada novo cliente ganha monitoramento automaticamente, sem intervenção manual.

Verificação de saúde pós-deploy#

Depois de implantar, verifique se o site está respondendo corretamente:

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

Construindo um dashboard de status customizado#

Puxe os dados de monitoramento pro seu próprio 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;
}

Auditorias agendadas de saúde de e-mail#

Rode verificações de saúde de e-mail em todos os seus domínios numa agenda e sinalize qualquer um que cair abaixo de um limite:

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

Boas práticas#

Tratamento de erros#

Sempre trate erros da API com cuidado. Timeouts de rede, rate limits e erros de servidor podem acontecer. Implemente lógica de retry com backoff exponencial:

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

Paginação#

Nunca assuma que todos os dados cabem numa única resposta. Sempre lide com paginação ao listar domínios ou recuperar histórico:

• Confira o valor pagination.totalPages nas respostas de listagem.
• Itere por todas as páginas pra obter os dados completos.
• Respeite o tamanho máximo de página (50 para domínios).

Cache#

Se você estiver exibindo dados de monitoramento num dashboard que atualiza com frequência, faça cache das respostas da API do seu lado. Mudanças de status de domínio são medidas em minutos, não em segundos, então um cache de 60 segundos para dados de status e de 5 minutos para dados históricos é razoável.

Os dados de saúde de e-mail mudam ainda menos. Um TTL de cache de 1 hora é apropriado para resultados de saúde de e-mail.

Atenção aos rate limits#

Estruture sua integração para minimizar chamadas desnecessárias à API:

• Faça cache das respostas sempre que possível.
• Use parâmetros de paginação pra buscar só os dados que você precisa.
• Evite ficar fazendo polling da API em loops apertados. Em vez disso, faça polling em intervalos apropriados pro seu caso de uso (a cada 1-5 minutos para status, por hora ou por dia para saúde de e-mail).
• Quando estiver verificando vários domínios, adicione um pequeno delay entre as requisições pra não bater nos rate limits.

Proteja sua chave de API#

• Guarde sua chave de API em variáveis de ambiente, não no código-fonte.
• Não exponha a chave de API em JavaScript do lado do cliente. Todas as chamadas de API devem passar pelo seu backend.
• Se você suspeitar que uma chave foi comprometida, gere outra imediatamente nas configurações do dashboard da Nova Uptime.
• Use uma chave de API separada para cada ambiente (development, staging, production), se possível.

Trate a normalização de URL de domínio#

A API normaliza URLs ao adicionar domínios (adicionando https:// se faltar), mas a sua integração também deveria normalizar antes de fazer requisições, pra evitar criar entradas duplicadas:

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

Requisitos de acesso à API#

A API da Nova Uptime está disponível em todos os planos, inclusive no Free. A página de preços tem uma comparação completa do que cada plano inclui:

• Plano Free: 5 domínios, acesso à API, dashboard, saúde de e-mail.
• Plano Pro: acesso à API com até 100 domínios.
• Plano Agency: acesso à API com até 1.000 domínios e todos os recursos.

Gere sua chave de API na página de Configurações do dashboard da Nova Uptime. A referência completa da API, incluindo schemas de requisição/resposta para cada endpoint, está disponível na página de documentação da API.

Conclusão#

Uma integração via API transforma o monitoramento, que era uma atividade manual baseada em dashboard, num componente automatizado e programável da sua infraestrutura. Seja você construindo uma plataforma SaaS multi-tenant, tocando uma agência com centenas de sites de clientes ou automatizando seu pipeline de deploy, a API é a interface que faz o monitoramento escalar.

Comece pelo básico: adicione domínios programaticamente e puxe dados de status. Depois, evolua para padrões mais avançados, como verificação de saúde pós-deploy, dashboards customizados e auditorias agendadas de saúde de e-mail.

A referência completa da API com playground interativo está disponível em api.novauptime.com/api-docs. Você também pode explorar todo o conjunto de recursos da Nova Uptime na página de recursos.