Hoe je uptime monitoring integreert in je app via een API

Wanneer je meer dan een handvol websites beheert, schaalt het doorklikken in een dashboard om domeinen toe te voegen, status te checken en rapporten op te halen niet meer. Je hebt een API nodig. Een uptime-monitoring-API laat je domeinbeheer automatiseren, monitoringdata in je eigen tools integreren en workflows bouwen die programmatisch op incidenten reageren.

Deze gids loopt door het integreren van de REST API van Nova Uptime in je applicatie, van authenticatie en kern-endpoints tot praktische code-voorbeelden en integratiepatronen.

Waarom monitoring via API integreren#

Automatisering#

Een nieuw domein toevoegen aan monitoring zou geen inloggen op een dashboard moeten vereisen. Als je platform websites provisioneert (voor klanten, tenants of interne teams), zou de monitoring-setup deel moeten uitmaken van het provisioning-script. Wanneer een domein wordt afgeschaald, zou monitoring automatisch verwijderd moeten worden.

Custom dashboards#

Misschien heb je al een intern dashboard of een klantportaal. In plaats van gebruikers te vragen een aparte monitoring-tool te checken, trek je uptime-data in de interface die ze al gebruiken. Toon uptime-percentage, recente incidenten en huidige status direct in je applicatie.

CI/CD-integratie#

Na het deployen van een nieuwe versie van je applicatie wil je direct weten of de deployment iets heeft gebroken. Een API-integratie kan na deployment de monitoringstatus checken, recente incidenten ophalen en eventuele post-deploy-issues in je CI/CD-pipeline flaggen.

Multi-tenant SaaS#

Als je een SaaS-platform draait waar elke klant een eigen subdomein of custom domain heeft, heb je monitoring op schaal nodig. De API laat je programmatisch monitoring toevoegen voor elke nieuwe klant, het verwijderen wanneer ze churnen, en per-klant uptime-metrics ophalen voor hun account-dashboard.

Nova Uptime API-overzicht#

Base URL#

Alle API-requests gaan naar:

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

Authenticatie#

Elke request moet een API-key bevatten in de X-API-Key-header. Je kunt een API-key genereren vanuit het Nova Uptime-dashboard onder Settings.

X-API-Key: your_api_key_here

API-keys zijn 20-karakter alfanumerieke strings, uniek per gebruiker. Elke key heeft dezelfde permissies als het gebruikersaccount waaraan hij toebehoort.

Rate limits#

De API hanteert rate limits om misbruik te voorkomen. Standaardlimieten staan een ruim aantal requests per minuut toe voor normale operaties. Als je de rate limit overschrijdt, krijg je een 429 Too Many Requests-response. Implementeer exponential backoff in je integratie om dit netjes af te handelen.

Response-format#

Alle responses volgen een consistente JSON-structuur:

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

Error-responses bevatten een beschrijvend bericht:

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

HTTP-statuscodes volgen standaardconventies: 200 voor success, 201 voor aangemaakte resources, 400 voor validatiefouten, 401 voor authenticatie-failures, 404 voor not found, en 429 voor rate limiting.

Belangrijke endpoints#

Lijst van gemonitorde domeinen#

Haal alle domeinen in je account op met hun huidige status, uptime-data en configuratie.

Request:

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

Response (verkort):

{
  "success": true,
  "data": {
    "domains": [
      {
        "id": "clx1abc...",
        "url": "https://kitepin.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
    }
  }
}

Het endpoint ondersteunt paginatie met ?page=1 query-parameters. De maximale page-size is 50 domeinen.

Domeindetails ophalen#

Haal gedetailleerde informatie op over een specifiek domein, inclusief de volledige configuratie.

Request:

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

Een nieuw domein toevoegen#

Voeg een domein toe aan monitoring. Het systeem normaliseert de URL (voegt https:// toe als die ontbreekt), valideert die en begint direct met monitoren.

Request:

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.kitepin.com",
    "checkInterval": 300
  }'

Response:

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

De status van het domein is initieel unknown. De eerste health check draait binnen seconden na het toevoegen van het domein, waarna de status updatet naar up, down of degraded.

Let op: er is een limiet van 10 domeinen via de API per account (plan-limieten zijn van toepassing). Het check-interval moet gelijk zijn aan of boven het minimum van je plan liggen.

Een domein verwijderen#

Verwijder een domein uit monitoring. Dit is een soft delete; het domein wordt gedeactiveerd, maar zijn historische data blijft behouden.

Request:

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

Incidenten van een domein ophalen#

Haal de meest recente incidenten (downtime-events) voor een specifiek domein op.

Request:

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

Response (verkort):

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

Het endpoint retourneert de 20 meest recente incidenten.

Check-historie ophalen#

Haal historische health check-resultaten voor een domein op. Handig voor het bouwen van response-time-charts of het berekenen van custom uptime-metrics.

Request:

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

De hours-parameter bepaalt hoever terug je kijkt, met een maximum van 720 uur (30 dagen) en een maximum van 500 records per response.

Email Health Check uitvoeren#

Voer een email health check uit op een willekeurig domein. Dit checkt MX-records, SPF, DKIM, DMARC en blacklist-status.

Request:

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": "kitepin.com"
  }'

Voeg "fresh": true toe om de cache te omzeilen en een verse lookup te forceren:

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": "kitepin.com",
    "fresh": true
  }'

De response bevat scores voor elke categorie (MX, SPF, DKIM, DMARC, blacklist), een overall score, een lettercijfer en concrete aanbevelingen.

Code-voorbeelden in JavaScript / Node.js#

Een API-client opzetten#

Maak een herbruikbare API-client om authenticatie, error-handling en response-parsing af te handelen:

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

Een domein toevoegen#

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

  console.log(`Domein toegevoegd: ${data.id}`);
  return data;
}

// Gebruik
await addDomainToMonitoring('https://mysite.kitepin.com', 60);

Alle domeinen listen met paginatie#

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

Checken op recente incidenten#

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

// Check of er domeinen incidenten hadden in het laatste uur
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(en) in het laatste uur`
      );
    }
  }
}

Een Email Health Check uitvoeren#

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

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

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

  return result;
}

Veelvoorkomende integratiepatronen#

Domeinen automatisch toevoegen bij deploy#

Als je deployment-pipeline websites aanmaakt of configureert, voeg dan monitoring toe als post-deploy-stap:

// In je deployment-script of CI/CD-pipeline
async function postDeployMonitoring(deployedUrl) {
  try {
    // Check of domein al wordt gemonitord
    const domains = await getAllDomains();
    const existing = domains.find((d) => d.url === deployedUrl);

    if (!existing) {
      await addDomainToMonitoring(deployedUrl, 300);
      console.log(`Monitoring toegevoegd voor ${deployedUrl}`);
    } else {
      console.log(`${deployedUrl} wordt al gemonitord (ID: ${existing.id})`);
    }
  } catch (error) {
    // Een monitoring-failure mag deployment niet blokkeren
    console.error(`Monitoring instellen mislukt: ${error.message}`);
  }
}

Dit patroon is bijzonder nuttig voor platforms die klant-subdomeinen provisioneren. Elke nieuwe klant krijgt automatisch monitoring zonder handmatige interventie.

Health-verificatie na deploy#

Check na deploy of de site correct reageert:

async function verifyPostDeploy(domainId, waitMinutes = 3) {
  // Wacht een paar check-cycli
  console.log(`${waitMinutes} minuten wachten op health checks...`);
  await new Promise((resolve) =>
    setTimeout(resolve, waitMinutes * 60 * 1000)
  );

  // Check op incidenten sinds de deploy startte
  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-incidenten gedetecteerd:');
    postDeployIncidents.forEach((inc) => {
      console.error(
        `  HTTP ${inc.httpStatus} om ${inc.startedAt}`
      );
    });
    return false;
  }

  console.log('Geen post-deploy-incidenten. Deployment ziet er gezond uit.');
  return true;
}

Een custom status-dashboard bouwen#

Trek monitoringdata in je eigen 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;
}

Geplande email-health-audits#

Voer email health checks uit over al je domeinen volgens een schema en flag eventuele die onder een drempel zijn gezakt:

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

  const results = [];
  for (const domain of domains) {
    try {
      // Haal alleen de domeinnaam uit de URL
      const domainName = new URL(domain.url).hostname;
      const health = await checkEmailHealth(domainName);
      results.push({
        domain: domainName,
        score: health.score,
        grade: health.grade,
      });

      // Voeg een kleine delay toe tussen requests om rate limits te respecteren
      await new Promise((resolve) => setTimeout(resolve, 1000));
    } catch (error) {
      results.push({
        domain: domain.url,
        score: null,
        grade: 'Error',
        error: error.message,
      });
    }
  }

  // Flag domeinen met score onder 70
  const flagged = results.filter((r) => r.score !== null && r.score < 70);
  if (flagged.length > 0) {
    console.log('Domeinen met email-health-issues:');
    flagged.forEach((r) => {
      console.log(`  ${r.domain}: ${r.grade} (${r.score}/100)`);
    });
  }

  return results;
}

Best practices#

Error handling#

Handel API-errors altijd netjes af. Netwerk-timeouts, rate limits en server-errors kunnen voorkomen. Implementeer retry-logica met 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(
        `Poging ${attempt} mislukt. Opnieuw proberen over ${delay}ms...`
      );
      await new Promise((resolve) => setTimeout(resolve, delay));
    }
  }
}

Paginatie#

Ga er nooit van uit dat alle data in één response past. Handel paginatie altijd af bij het listen van domeinen of het ophalen van historie:

• Check de pagination.totalPages-waarde in list-responses.
• Itereer door alle pagina's om complete data te krijgen.
• Respecteer de maximale page-size (50 voor domeinen).

Caching#

Als je monitoringdata in een dashboard toont dat regelmatig ververst, cache dan de API-responses aan jouw kant. Statuswijzigingen van domeinen worden gemeten in minuten, niet in seconden, dus een 60-seconde-cache voor statusdata en een 5-minuten-cache voor historische data is redelijk.

Email-health-data verandert nog minder vaak. Een cache-TTL van 1 uur is passend voor email-health-resultaten.

Bewust omgaan met rate limits#

Structureer je integratie om onnodige API-calls te minimaliseren:

• Cache responses waar mogelijk.
• Gebruik paginatie-parameters om alleen de data op te halen die je nodig hebt.
• Vermijd polling van de API in tight loops. Pollen op intervallen die passen bij je use case (elke 1-5 minuten voor status, uurlijks of dagelijks voor email health).
• Wanneer je meerdere domeinen checkt, voeg een kleine delay toe tussen requests om rate limits te vermijden.

Beveilig je API-key#

• Sla je API-key op in environment variables, niet in source code.
• Stel de API-key niet bloot in client-side JavaScript. Alle API-calls moeten via je backend gaan.
• Als je vermoedt dat een key is gecompromitteerd, regenereer hem direct via de Nova Uptime-dashboard-instellingen.
• Gebruik indien mogelijk een aparte API-key per environment (development, staging, production).

Handel domein-URL-normalisatie af#

De API normaliseert URL's bij het toevoegen van domeinen (voegt https:// toe als die ontbreekt), maar je integratie zou ook moeten normaliseren vóór het maken van requests om dubbele entries te voorkomen:

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

Vereisten voor API-toegang#

De API van Nova Uptime is beschikbaar op alle plannen, inclusief Free. De pricing-pagina heeft een volledige vergelijking van wat elk plan bevat:

• Free-plan: 5 domeinen, API-toegang, dashboard, email health.
• Pro-plan: API-toegang met tot 100 domeinen.
• Agency-plan: API-toegang met tot 1.000 domeinen en alle features.

Genereer je API-key vanuit de Settings-pagina in het Nova Uptime-dashboard. De volledige API-referentie, inclusief request/response-schema's voor elk endpoint, is beschikbaar op de API-documentatiepagina.

Conclusie#

Een API-integratie verandert monitoring van een handmatige, dashboard-gebaseerde activiteit in een geautomatiseerde, programmeerbare component van je infrastructuur. Of je nu een multi-tenant SaaS-platform bouwt, een agency runt met honderden klant-sites, of je deployment-pipeline automatiseert: de API is de interface die monitoring laat schalen.

Begin met de basics: domeinen programmatisch toevoegen en statusdata ophalen. Bouw daarna door naar geavanceerdere patronen zoals post-deploy health-verificatie, custom dashboards en geplande email-health-audits.

De volledige API-referentie met interactieve playground is beschikbaar op api.novauptime.com/api-docs. Je kunt ook de complete feature-set van Nova Uptime verkennen op de features-pagina.