So integrierst du Uptime Monitoring per API in deine App

Wenn du mehr als eine Handvoll Websites verwaltest, skaliert es nicht mehr, sich durch ein Dashboard zu klicken, um Domains hinzuzufügen, Status zu prüfen und Reports zu ziehen. Du brauchst eine API. Eine Uptime-Monitoring-API lässt dich Domain-Management automatisieren, Monitoring-Daten in deine eigenen Tools integrieren und Workflows bauen, die programmatisch auf Incidents reagieren.

Dieser Guide führt dich durch die Integration der REST API von Nova Uptime in deine Anwendung – von Authentifizierung und Kern-Endpoints bis hin zu praktischen Code-Beispielen und Integrationsmustern.

Warum Monitoring per API integrieren#

Automatisierung#

Eine neue Domain zum Monitoring hinzuzufügen sollte kein Einloggen ins Dashboard erfordern. Wenn deine Plattform Websites provisioniert (für Kunden, Tenants oder interne Teams), sollte das Monitoring-Setup Teil des Provisioning-Skripts sein. Wenn eine Domain abgeschaltet wird, sollte das Monitoring automatisch entfernt werden.

Custom Dashboards#

Vielleicht hast du bereits ein internes Dashboard oder ein Kundenportal. Statt deine Nutzer zu bitten, ein separates Monitoring-Tool zu prüfen, ziehst du die Uptime-Daten direkt in die Oberfläche, die sie ohnehin schon nutzen. Zeige Uptime-Prozentwerte, aktuelle Incidents und den aktuellen Status direkt in deiner Anwendung.

CI/CD-Integration#

Nach dem Deployment einer neuen Version deiner Anwendung willst du sofort wissen, ob das Deployment etwas kaputtgemacht hat. Eine API-Integration kann nach dem Deployment den Monitoring-Status prüfen, aktuelle Incidents abrufen und etwaige Post-Deploy-Probleme in deiner CI/CD-Pipeline flaggen.

Multi-Tenant-SaaS#

Wenn du eine SaaS-Plattform betreibst, bei der jeder Kunde eine eigene Subdomain oder Custom Domain hat, brauchst du Monitoring im großen Stil. Die API lässt dich programmatisch Monitoring für jeden neuen Kunden hinzufügen, es wieder entfernen, wenn er kündigt, und kundenspezifische Uptime-Metriken für sein Account-Dashboard abrufen.

Nova Uptime API – Überblick#

Base URL#

Alle API-Requests gehen an:

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

Authentifizierung#

Jeder Request muss einen API-Key im X-API-Key-Header enthalten. Du kannst einen API-Key im Nova Uptime Dashboard unter Settings generieren.

X-API-Key: your_api_key_here

API-Keys sind 20 Zeichen lange alphanumerische Strings, eindeutig pro Nutzer. Jeder Key hat dieselben Berechtigungen wie das Nutzer-Account, zu dem er gehört.

Rate Limits#

Die API erzwingt Rate Limits, um Missbrauch zu verhindern. Die Standardlimits erlauben eine großzügige Anzahl Requests pro Minute für den normalen Betrieb. Wenn du das Rate Limit überschreitest, bekommst du eine 429 Too Many Requests-Antwort. Implementiere Exponential Backoff in deiner Integration, um das sauber abzufangen.

Response-Format#

Alle Antworten folgen einer einheitlichen JSON-Struktur:

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

Fehler-Antworten enthalten eine beschreibende Nachricht:

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

HTTP-Statuscodes folgen Standardkonventionen: 200 für Erfolg, 201 für angelegte Ressourcen, 400 für Validierungsfehler, 401 für Authentifizierungsfehler, 404 für Not Found und 429 für Rate Limiting.

Wichtige Endpoints#

Monitorisierte Domains auflisten#

Rufe alle Domains in deinem Account inklusive aktuellem Status, Uptime-Daten und Konfiguration ab.

Request:

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

Response (gekürzt):

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

Der Endpoint unterstützt Pagination über den Query-Parameter ?page=1. Die maximale Page-Size beträgt 50 Domains.

Domain-Details abrufen#

Rufe detaillierte Informationen zu einer bestimmten Domain ab, inklusive der vollständigen Konfiguration.

Request:

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

Eine neue Domain hinzufügen#

Füge eine Domain zum Monitoring hinzu. Das System normalisiert die URL (ergänzt https://, falls fehlend), validiert sie und startet das Monitoring sofort.

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

Response:

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

Der Status der Domain ist anfangs unknown. Der erste Health-Check läuft innerhalb weniger Sekunden nach dem Hinzufügen, danach wechselt der Status zu up, down oder degraded.

Hinweis: Es gibt ein Limit von 10 Domains pro Account über die API (Plan-Limits gelten). Das Check-Intervall muss mindestens dem für deinen Plan erlaubten Minimum entsprechen.

Eine Domain löschen#

Entferne eine Domain aus dem Monitoring. Das ist ein Soft Delete – die Domain wird deaktiviert, aber ihre historischen Daten bleiben erhalten.

Request:

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

Incidents einer Domain abrufen#

Rufe die jüngsten Incidents (Downtime-Ereignisse) für eine bestimmte Domain ab.

Request:

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

Response (gekürzt):

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

Der Endpoint liefert die 20 jüngsten Incidents zurück.

Check-Historie abrufen#

Rufe historische Health-Check-Ergebnisse für eine Domain ab. Praktisch, um Response-Time-Charts zu bauen oder eigene Uptime-Metriken zu berechnen.

Request:

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

Der Parameter hours steuert, wie weit zurückgeschaut wird – maximal 720 Stunden (30 Tage) und maximal 500 Datensätze pro Antwort.

Email Health Check ausführen#

Führe einen Email Health Check für eine beliebige Domain aus. Dabei werden MX-Records, SPF, DKIM, DMARC und der Blacklist-Status geprüft.

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

Füge "fresh": true hinzu, um den Cache zu umgehen und einen frischen Lookup zu erzwingen:

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

Die Antwort enthält Scores für jede Kategorie (MX, SPF, DKIM, DMARC, Blacklist), einen Gesamtscore, eine Buchstabennote und konkrete Handlungsempfehlungen.

Code-Beispiele in JavaScript / Node.js#

Einen API-Client aufsetzen#

Lege einen wiederverwendbaren API-Client an, der Authentifizierung, Fehlerbehandlung und Response-Parsing übernimmt:

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

Eine Domain hinzufügen#

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

Alle Domains mit Pagination auflisten#

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

Auf jüngste Incidents prüfen#

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

Einen Email Health Check ausführen#

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

Gängige Integrationsmuster#

Domains beim Deploy automatisch hinzufügen#

Wenn deine Deployment-Pipeline Websites anlegt oder konfiguriert, ergänze Monitoring als Post-Deploy-Schritt:

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

Dieses Muster ist besonders praktisch für Plattformen, die Subdomains für Kunden provisionieren. Jeder neue Kunde bekommt automatisch Monitoring – ganz ohne manuelles Eingreifen.

Post-Deploy-Health-Verifikation#

Prüfe nach dem Deployment, ob die Site korrekt antwortet:

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

Ein eigenes Status-Dashboard bauen#

Zieh dir Monitoring-Daten in dein eigenes 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;
}

Geplante Email-Health-Audits#

Lass Email Health Checks für alle deine Domains nach Zeitplan laufen und flagge alle, die unter einen Schwellwert gefallen sind:

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

Best Practices#

Fehlerbehandlung#

Behandle API-Fehler immer sauber. Netzwerk-Timeouts, Rate Limits und Server-Fehler können auftreten. Implementiere Retry-Logik mit 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));
    }
  }
}

Pagination#

Geh nie davon aus, dass alle Daten in eine einzelne Response passen. Behandle Pagination immer sauber, wenn du Domains auflistest oder Historie abrufst:

• Prüfe den Wert pagination.totalPages in List-Antworten.
• Iteriere durch alle Seiten, um die kompletten Daten zu bekommen.
• Respektiere die maximale Page-Size (50 für Domains).

Caching#

Wenn du Monitoring-Daten in einem Dashboard zeigst, das häufig refresht, cache die API-Antworten auf deiner Seite. Statusänderungen einer Domain werden in Minuten gemessen, nicht in Sekunden – ein 60-Sekunden-Cache für Statusdaten und ein 5-Minuten-Cache für historische Daten ist sinnvoll.

Email-Health-Daten ändern sich noch seltener. Eine Cache-TTL von 1 Stunde ist für Email-Health-Ergebnisse angemessen.

Bewusster Umgang mit Rate Limits#

Strukturiere deine Integration so, dass unnötige API-Calls minimiert werden:

• Cache Antworten, wo es geht.
• Nutze Pagination-Parameter, um nur die Daten zu holen, die du wirklich brauchst.
• Vermeide enges Polling der API. Polle stattdessen in Intervallen, die zu deinem Use Case passen (alle 1–5 Minuten für Status, stündlich oder täglich für Email Health).
• Wenn du mehrere Domains prüfst, baue eine kleine Verzögerung zwischen den Requests ein, um nicht ins Rate Limit zu laufen.

Sichere deinen API-Key#

• Speichere deinen API-Key in Environment-Variablen, nicht im Quellcode.
• Lege den API-Key nicht in clientseitigem JavaScript offen. Alle API-Calls sollten über dein Backend laufen.
• Wenn du den Verdacht hast, dass ein Key kompromittiert wurde, regeneriere ihn sofort in den Settings des Nova Uptime Dashboards.
• Verwende nach Möglichkeit für jede Umgebung (Development, Staging, Production) einen eigenen API-Key.

Domain-URL-Normalisierung handhaben#

Die API normalisiert URLs beim Hinzufügen von Domains (sie ergänzt https://, falls fehlend), aber deine Integration sollte ebenfalls normalisieren, bevor sie Requests stellt – so vermeidest du Doppel-Einträge:

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

Voraussetzungen für den API-Zugriff#

Die API von Nova Uptime ist in allen Plänen verfügbar, auch im Free-Plan. Die Pricing-Seite bietet einen vollständigen Vergleich, was jeder Plan enthält:

• Free-Plan: 5 Domains, API-Zugriff, Dashboard, Email Health.
• Pro-Plan: API-Zugriff mit bis zu 100 Domains.
• Agency-Plan: API-Zugriff mit bis zu 1.000 Domains und allen Features.

Generiere deinen API-Key auf der Settings-Seite im Nova Uptime Dashboard. Die vollständige API-Referenz inklusive Request-/Response-Schemas für jeden Endpoint findest du auf der API-Dokumentationsseite.

Fazit#

Eine API-Integration macht aus Monitoring eine automatisierte, programmierbare Komponente deiner Infrastruktur – statt einer manuellen, dashboardgetriebenen Aktivität. Egal, ob du eine Multi-Tenant-SaaS-Plattform baust, eine Agentur mit hunderten Kundensites führst oder deine Deployment-Pipeline automatisierst: Die API ist die Schnittstelle, die Monitoring skalierbar macht.

Fang mit den Basics an: Domains programmatisch hinzufügen und Statusdaten abrufen. Dann baue auf bis zu fortgeschritteneren Mustern wie Post-Deploy-Health-Verifikation, eigenen Dashboards und geplanten Email-Health-Audits.

Die vollständige API-Referenz inklusive interaktivem Playground findest du unter api.novauptime.com/api-docs. Du kannst dir auch das komplette Feature-Set von Nova Uptime auf der Features-Seite anschauen.