API-Übersicht

Mit der Hoppla REST-API steuerst du alles programmatisch: Monitore verwalten, Check-Ergebnisse abrufen, Vorfälle bearbeiten und dein Monitoring-Setup automatisieren. Alles, was im Dashboard geht, geht auch über die API.

Basis-URL

Alle API-Endpoints laufen unter:

https://app.hoppla.dev/api/v1

Authentifizierung

Authentifiziere dich mit einem Bearer-Token im Authorization-Header. Wie du ein Token erstellst, steht unter API-Tokens.

curl -H "Authorization: Bearer YOUR_TOKEN" \
  https://app.hoppla.dev/api/v1/monitors

Tokens sind undurchsichtige Zeichenketten mit einem kurzen Präfix, das den Typ anzeigt -- persönliche API-Tokens beginnen mit sk-…. Behandle die gesamte Zeichenkette als Geheimnis und binde sie niemals in clientseitigen Code ein.

Anfragen ohne gültiges Token bekommen eine 401 Unauthorized-Antwort.

Scopes

Jedes Token trägt eine Reihe von Scopes, die bestimmen, was es darf. Scopes haben das Format resource:action und sind in Familien gruppiert:

• monitors, checks, incidents, notifications, escalation, status-pages, maintenance, team, settings, billing

Jede Familie unterstützt :read, :write und -- wo sinnvoll -- :manage. Ein Token mit monitors:read kann zum Beispiel Monitore auflisten, aber nicht anlegen; mit monitors:write kannst du Monitore erstellen und aktualisieren.

Ein Token enthält in der Regel nur einen Teil aller Scopes -- wähl das Minimum, das deine Integration braucht. Jede Anfrage an einen Endpoint außerhalb der Scopes des Tokens wird mit 403 Forbidden abgelehnt.

Paginierung

Hoppla nutzt zwei Paginierungsarten -- je nach Endpoint.

Offset-Paginierung

Die meisten Listen-Endpoints paginieren nach Seitennummer. Du steuerst das mit diesen Query-Parametern:

Parameter	Standard	Beschreibung
page	1	Seitennummer
per_page	15	Einträge pro Seite (max. 100)

In der Antwort steckt ein meta-Objekt:

{
  "data": [...],
  "meta": {
    "current_page": 1,
    "last_page": 3,
    "per_page": 15,
    "total": 42
  }
}

Cursor-Paginierung

Endpoints mit großen Datenmengen (zum Beispiel Vorfälle) nutzen stattdessen Cursor-Paginierung -- das ist schneller und bleibt stabil, während sich die Daten ändern. Übergib dazu den Cursor aus der vorherigen Antwort:

Parameter	Beschreibung
cursor	Undurchsichtiger Cursor aus meta.next_cursor der vorherigen Seite
per_page	Einträge pro Seite (max. 100)

Die Antwort enthält die Cursor-Infos im meta-Objekt:

{
  "data": [...],
  "meta": {
    "next_cursor": "eyJpZCI6...",
    "prev_cursor": null,
    "has_more": true
  }
}

Frag so lange mit next_cursor weiter, bis has_more auf false steht.

Rate Limiting

Die Rate Limits hängen davon ab, wie die Anfrage authentifiziert ist:

Anfrage	Limit
Nicht authentifiziert (pro IP)	60 Anfragen/Minute
Authentifiziert	300 Anfragen/Minute
Authentifiziert mit Team-Header (X-Tenant)	600 Anfragen/Minute

Die aktuellen Limits findest du in jeder Antwort:

Header	Beschreibung
X-RateLimit-Limit	Maximale Anfragen pro Minute
X-RateLimit-Remaining	Verbleibende Anfragen im aktuellen Zeitfenster

Überschreitest du das Limit, kommt eine 429 Too Many Requests-Antwort. Warte dann einfach, bis das Zeitfenster zurückgesetzt wird.

Fehlerformat

Fehler kommen immer als JSON mit einheitlicher Struktur:

{
  "message": "The given data was invalid.",
  "errors": {
    "url": ["The url field is required."]
  }
}

Die gängigen HTTP-Statuscodes:

Status	Bedeutung
200	Erfolg
201	Ressource erstellt
204	Erfolg, kein Inhalt (z. B. nach Löschungen)
401	Nicht autorisiert (ungültiges oder fehlendes Token)
403	Verboten (unzureichende Berechtigungen)
404	Ressource nicht gefunden
422	Validierungsfehler
429	Rate Limit überschritten
500	Serverfehler

Verfügbare Endpoints

Kategorie	Endpoints	Beschreibung
Monitore	GET/POST/PATCH/DELETE /monitors	Monitore erstellen, lesen, aktualisieren, löschen
Monitor-Tags	GET /monitors/tags	Alle über Monitore hinweg verwendeten Tags auflisten
Monitor-Checks	GET/POST/DELETE /monitors/{id}/checks	Checks innerhalb eines Monitors verwalten
Check-Aktionen	PATCH /checks/{id}, POST /checks/{id}/request-run, POST /checks/{id}/snooze, POST /checks/{id}/unsnooze, POST /checks/{id}/enable, POST /checks/{id}/disable	Einstellungen ändern, manuelle Läufe auslösen, snoozen/entsnoozen, einzelne Checks aktivieren/deaktivieren
Check-Ergebnisse	GET /checks/{id}/results, GET /checks/{id}/timeseries, POST /checks/timeseries-batch	Check-Ergebnisse, Zeitreihen-Daten und Batch-Zeitreihen abrufen
Monitor-Statistiken	GET /monitors/{id}/uptime, /performance, /certificate, /dns-history, /lighthouse, /domain-expiry, /health, /sitemap, /ping, /tcp, /security-headers, /robots-txt, /dnsbl, /redirect-chain, /mixed-content, /broken-links, /agent	Detaillierte Statistiken pro Monitor und Check-Typ
Crawl-Läufe	GET /monitors/{id}/crawl-runs, GET /monitors/{id}/crawl-runs/{runId}, GET /monitors/{id}/crawl-runs/{runId}/pages	Ergebnisse von Broken-Link-Scans und betroffene Seiten
Vorfälle	GET/POST/PATCH/DELETE /incidents, POST /incidents/{id}/updates, POST /incidents/{id}/acknowledge, POST /incidents/{id}/snooze, POST /incidents/{id}/unsnooze, POST /incidents/{id}/archive, POST /incidents/{id}/unarchive	Vollständiges Lifecycle-Management für Vorfälle
Benachrichtigungskanäle	GET/POST/PATCH/DELETE /notification-channels, POST /notification-channels/{id}/test	Benachrichtigungskanäle verwalten und Zustellung testen
Benachrichtigungsregeln	GET/POST/PATCH/DELETE /notification-rules	Festlegen, welche Ereignisse welche Kanäle auslösen
Benachrichtigungs-Logs	GET /notification-logs, GET /notification-logs/{id}	Zustellverlauf der Benachrichtigungen einsehen
Eskalationsrichtlinien	GET/POST/PATCH/DELETE /escalation-policies, Schritt-Verwaltung	Mehrstufige Eskalationsketten mit Wartezeiten
Bereitschaftspläne	GET/POST/PATCH/DELETE /on-call-schedules, Rotations-Verwaltung, GET /on-call-schedules/{id}/current	Rotationsbasierte Bereitschaftsplanung
Wartungsfenster	GET/POST/PATCH/DELETE /maintenance-windows	Geplante Ausfallzeiten einplanen, um Alarme zu unterdrücken
Statusseiten	GET/POST/PATCH/DELETE /status-pages, Updates-Verwaltung, Verifizierung eigener Domains	Öffentliche Statusseiten mit eigenen Domains
Cron-Monitore	GET/POST/PATCH/DELETE /cron-monitors, POST /cron-monitors/{id}/rotate-url	Cron-Heartbeat-Monitore mit URL-Rotation
Agent-Monitore	GET/POST/PATCH/DELETE /agent-monitors, POST /agent-monitors/{id}/rotate-token, GET /agent-monitors/{id}/metrics	Server-Agent-Monitore mit Token-Rotation und Metriken
Dashboard	GET /dashboard/stats	Aggregierte Monitoring-Statistiken
Profil	GET/PATCH /profile, PUT /profile/password, GET /profile/export, DELETE /profile	Benutzerprofil, Passwortänderung, DSGVO-Export, Kontolöschung
API-Tokens	GET/POST/DELETE /api-tokens	Persönliche API-Tokens verwalten
Teammitglieder	GET /team/members, PATCH /team/members/{id}, DELETE /team/members/{id}	Teammitglieder verwalten
Team-Einladungen	GET/POST /team/invitations, POST /team/invitations/{id}/resend, DELETE /team/invitations/{id}	Team-Einladungen aussprechen und verwalten
Branding	GET/PATCH /branding	White-Label-Branding-Einstellungen
Eigenes SMTP	GET/PATCH/DELETE /smtp-config, POST /smtp-config/test	Eigene SMTP-Konfiguration für E-Mails
SSO-Konfiguration	GET/PATCH /sso/config	OIDC-SSO-Einstellungen
Audit-Log	GET /audit-log, GET /audit-log/filters	Audit-Verlauf des Teams und verfügbare Filterwerte einsehen
Badges	GET /badges/{uuid}, GET /badges/{uuid}/small	Öffentliche SVG-Uptime-Badges (keine Authentifizierung nötig)
Monatsberichte	GET/PATCH /monthly-report/config, POST /monthly-report/preview	Konfiguration und Vorschau der Monatsberichte
Plan	GET /plan	Aktuelle Plan-Limits und Nutzung
Abrechnung	GET /billing, POST /billing/checkout, POST /billing/swap, POST /billing/cancel, POST /billing/resume, GET /billing/transactions	Abo-Verwaltung

Rate Limits nach Operationstyp

Lese-Operationen (GET) teilen sich das Standard-Limit deines Accounts. Schreib-Operationen (POST/PATCH/DELETE) und Endpoints, die Checks auslösen (z. B. request-run), können niedrigere Limits haben. Die Rate-Limit-Header in jeder Antwort zeigen immer das für den jeweiligen Endpoint geltende Limit.

Badges (öffentlich)

Einbettbare SVG-Badges zeigen den Live-Uptime-Status eines Monitors. Diese Endpoints sind öffentlich -- keine Authentifizierung nötig. Badges spiegeln nur den Status des Uptime-Checks wider (nicht GEO, Security-Header etc.).

Standard-Badge

GET /api/badges/{monitor_uuid}

Liefert ein SVG-Badge im shields.io-Stil mit Label ("uptime") und Wert (Prozentzahl oder "down").

Kleines Badge

GET /api/badges/{monitor_uuid}/small

Liefert ein kompaktes SVG mit farbigem Punkt und Prozenttext.

Query-Parameter

Parameter	Standard	Beschreibung
label_color	555	Hex-Farbe für den Label-Hintergrund (z. B. 2d333b für Dark Mode)
text_color	fff	Hex-Farbe für den Badge-Text
style	default	Badge-Stil: default (Verlauf) oder flat

Beispiel

<!-- Light Mode -->
<img src="https://app.hoppla.dev/api/badges/YOUR-MONITOR-UUID" alt="Uptime">

<!-- Dark Mode -->
<img src="https://app.hoppla.dev/api/badges/YOUR-MONITOR-UUID?label_color=2d333b&style=flat" alt="Uptime">

Caching

Badges werden auf CDN-Ebene (5 Minuten) und Browser-Ebene (1 Minute) gecacht. Rate-Limit: 120 Anfragen/Minute pro IP.

---

Audit-Log

Audit-Ereignisse auflisten

GET /api/v1/audit-log

Liefert eine paginierte Liste der Audit-Log-Einträge des aktuellen Teams.

Query-Parameter:

Parameter	Typ	Beschreibung
action	string	Nach Aktion(en) filtern. Mehrere durch Komma getrennt (z. B. check_snoozed,check_unsnoozed)
entity_type	string	Nach Entitätstyp filtern. Einer von: monitor, check, notification_channel, notification_rule, status_page, maintenance_window, incident, user, tenant, managed_tenant, personal_access_token, team_invitation, escalation_policy, escalation_step, on_call_schedule, on_call_rotation
entity_id	uuid	Nach einer bestimmten Entitäts-ID filtern
user_id	uuid	Nach dem Benutzer filtern, der die Aktion ausgeführt hat

Verfügbare Filter abrufen

GET /api/v1/audit-log/filters

Liefert die im Audit-Log deines Teams tatsächlich vorkommenden actions und entity_types -- praktisch, um dynamische Filter-Dropdowns zu bauen.

Antwort (200):

{
  "data": {
    "actions": ["check_snoozed", "check_unsnoozed", "monitor_created", "..."],
    "entity_types": ["check", "monitor", "incident", "..."]
  }
}

---

Check snoozen / entsnoozen

Einen Check snoozen

POST /api/v1/checks/{id}/snooze

Unterdrückt Benachrichtigungen für den Check für die angegebene Dauer.

Request-Body:

Feld	Typ	Erforderlich	Beschreibung
minutes	integer	ja	Dauer in Minuten (1–1440)

Einen Check entsnoozen

POST /api/v1/checks/{id}/unsnooze

Entfernt den Snooze sofort und aktiviert die Benachrichtigungen wieder.

Antwort (200): Liefert die aktualisierte Check-Ressource zurück.

---

OpenAPI-Spezifikation

Durchsuche die vollständige, interaktive API-Referenz — API-Referenz — oder lade die maschinenlesbare OpenAPI-3.1-Spezifikation herunter:

• Interaktive Referenz: docs.hoppla.dev/de/api/reference
• Spezifikation herunterladen: api-documentation.json
• Live-Spezifikation (Hoppla Cloud): https://app.hoppla.dev/api/v1/openapi.json

Importiere die Spezifikation in Postman, Insomnia oder jedes andere OpenAPI-kompatible Tool, um die Endpoints interaktiv zu erkunden und zu testen.

Self-Hosted

Bei einer selbstgehosteten Instanz werden beide von deiner eigenen Domain ausgeliefert (ohne externe Abhängigkeiten):

• Interaktive Referenz: https://<deine-domain>/api/docs
• OpenAPI-Spezifikation: https://<deine-domain>/api/v1/openapi.json

Die servers-URL der Spezifikation wird automatisch auf die Basis-URL deiner Instanz gesetzt.

MCP-Server (KI-Integration)

Du kannst KI-Assistenten wie Claude Desktop, Claude Code oder Cursor direkt mit deinen Hoppla-Daten verbinden -- über das Model Context Protocol. Frag einfach nach Monitoren, Vorfällen, Uptime-Statistiken und mehr in natürlicher Sprache. Alle Details findest du in der MCP-Server-Dokumentation.

Reseller-API

Bist du ein Hosting-Provider oder eine Agentur, die Kunden-Teams verwaltet? Die Reseller-API bietet dir zusätzliche Endpoints für die programmatische Bereitstellung und Verwaltung von Teams. Schau dir die Reseller-API-Referenz an.