API von Uptime Kuma: was es gibt und was Sie stattdessen nutzen

Kurz gesagt

Uptime Kuma lässt Sie keinen Monitor über HTTP anlegen. Seine gesamte HTTP-Oberfläche besteht aus Status-Badges, Daten öffentlicher Statusseiten, einem Push-Endpunkt und einem Prometheus-Scrape. Alles andere steuert das Dashboard über Socket.IO, eine private Schnittstelle, deren Stabilität das Projekt nie versprochen hat. Jede Bibliothek, die als API für Uptime Kuma angepriesen wird, ist ein Client für diese Schnittstelle.

Sie wollen fünfzig Monitore aus einer CSV-Datei anlegen. Oder einen Check im selben Pull Request hinzufügen, der auch den Dienst hinzufügt. Oder ein Deploy-Skript, das einen Monitor pausiert, solange es läuft, und ihn danach wieder aktiviert. Also suchen Sie die API-Doku und finden sie nicht.

Es gibt sie nicht. Deshalb hier die Oberfläche, wie sie in Version 2.5.3 besteht, am 5. September 2026 aus dem Quellcode herausgelesen.

Jede HTTP-Route, die Uptime Kuma ausliefert

Zwei Express-Router tragen fast alles, dazu ein paar Routen, die direkt an der App registriert sind. Alles, was nicht in dieser Tabelle steht, liefert die Single-Page-App selbst aus, einschließlich des HTML der Statusseite unter /status/:slug, oder es sind hochgeladene Bilder, robots.txt, ein Well-known-Link zum Ändern des Passworts und die Seite zur Datenbankeinrichtung beim ersten Start.

Lesen Sie die Spalte zur Authentifizierung noch einmal. Eine einzige Route schreibt überhaupt etwas, und was sie schreibt, ist ein einzelner Heartbeat. Nichts hier legt einen Monitor an, und nichts hier listet auch nur Ihre Monitore auf, es sei denn, Sie haben sie bereits auf einer öffentlichen Statusseite veröffentlicht.

Die Website oder API, die überwacht werden soll > überwachen

Der API-Schlüssel kann weniger, als der Name verspricht

Uptime Kuma hat eine Funktion für API-Schlüssel, unter „Settings“, mit Ablaufdaten und einem Schalter zum Aktivieren. Man nimmt leicht an, das seien die fehlenden Zugangsdaten für REST.

Der Schlüssel funktioniert auf genau einer Route, dem Prometheus-Scrape unter /metrics. Im Quellcode hängt apiAuth dort und nirgendwo sonst, der Schlüssel kann also überhaupt keinen Monitor anrühren.

Zwei Dinge sollten Sie wissen, bevor Sie darauf aufbauen. Sind API-Schlüssel ausgeschaltet, fällt derselbe Endpunkt auf HTTP Basic mit Benutzernamen und Passwort des Admins zurück, eine Scrape-Konfiguration enthält also entweder einen Schlüssel oder den Login für die ganze Instanz. Und der Pfad über den Schlüssel ist instanzweit auf 60 Anfragen pro Minute begrenzt, der Login-Pfad auf 20.

Die eigentliche Schnittstelle ist Socket.IO

Alles, was die Web-UI tut, tut sie, indem sie Socket.IO-Events an den Server sendet. Die Monitor-Events sind das, was Sie von einer REST-API erwarten würden, nur in der falschen Form:

add             editMonitor      deleteMonitor
pauseMonitor    resumeMonitor    getMonitorList
getMonitor      getMonitorBeats  getTags

Einen Monitor anzulegen ist ein Event, das buchstäblich add heißt.

Um eines davon zu erreichen, melden Sie sich zuerst als Admin über denselben Socket an. Das Login-Event gibt ein JWT zurück, das Sie wiederverwenden können, und wenn für das Konto die Zwei-Faktor-Authentifizierung eingeschaltet ist, muss Ihr Skript außerdem aus dem gemeinsamen Geheimnis einen TOTP-Code erzeugen. Dann senden Sie add mit einem Monitor-Objekt, dessen Form nirgends aufgeschrieben ist, Sie kopieren also entweder, was der Browser sendet, oder stützen sich auf den Wrapper von jemandem, der das schon getan hat.

Das ist aus drei Gründen wichtig. Die Zugangsdaten sind die ganze Instanz: Es gibt kein Token nur zum Lesen und keinen Scope pro Monitor, ein Deploy-Skript, das einen Monitor pausiert, hält also den Login, mit dem sich alle löschen und das Admin-Passwort ändern ließen. Die Form des Payloads ist kein Vertrag, sondern das, was die aktuelle UI gerade sendet, ein Feld kann also in einem Minor-Release umbenannt werden, ohne dass das Projekt etwas kaputt gemacht hätte, denn nichts außerhalb der UI sollte sich darauf verlassen. Und nichts davon ist dokumentiert, Sie lernen es also, indem Sie server/server.js lesen oder den Wrapper von jemand anderem.

Das ist Absicht, und das Projekt sagt es auch

Hier lohnt es sich, Uptime Kuma gegenüber fair zu sein. Das ist keine Nachlässigkeit. Das README nennt die Beweggründe des Projekts, und einer davon lautet:

Try to use WebSocket with SPA instead of a REST API.

Uptime Kuma wollte von Anfang an eine Single-Page-App mit einem Live-Socket dahinter sein, was gut zu einem Dashboard passt, das Sie den ganzen Tag offen haben. Eine REST-API war nie das Ziel, wer eine verlangt, verlangt also ein anderes Produkt.

Ignoriert wird der Wunsch auch nicht. Issue 118, „API functionality“, ist seit Juli 2021 offen, mit 776 Reaktionen und 77 Kommentaren, und damit das offene Issue mit den meisten Reaktionen im Repository. Der Maintainer hat es nicht nur zur Kenntnis genommen. Im Oktober 2023 eröffnete er zu diesem Issue einen Pull Request, Nummer 3854, mit dem Titel „Document the Socket.io API and try to convert it to a HTTP request“. Er ist noch ein Entwurf, und sowohl er als auch das Issue waren offen, als dieser Text geschrieben wurde.

Das Ökosystem der Wrapper, mit Datumsangaben

Jede Bibliothek, die sich API für Uptime Kuma nennt, ist ein Socket.IO-Client in einem schöneren Mantel. Die Sternezahlen und Commit-Daten unten stammen vom 5. September 2026 aus der GitHub-API, nicht von den Projektseiten, denn ein Repository kann durch einen Dependabot-Branch lebendig wirken, während seit zwei Jahren niemand den Code angefasst hat.

Der Client, auf den fast alle verlinken, stammt also komplett aus der Zeit vor Uptime Kuma 2, und die Forks, die Version 2 abdecken, sind winzig. Zwei davon verfolgen dieselbe Idee, im Abstand von einem Jahr von verschiedenen Leuten begonnen, mit je elf Sternen. Das passiert, wenn das Protokoll darunter weder stabil noch aufgeschrieben ist: Man baut denselben Wrapper neu, statt gemeinsam einen zu pflegen.

Was Sie heute tun können

Wenn Sie bei Uptime Kuma bleiben, hier die Möglichkeiten, grob danach geordnet, wie viel Schlaf sie Sie kosten werden.

Push-Monitore sind die eine Automatisierungsschnittstelle, die das Projekt bewusst unterstützt. Ihr Job ruft nach Abschluss eine Token-URL auf, und der Endpunkt nimmt status=up oder status=down entgegen, dazu optional die Parameter msg und ping. Das deckt Cronjobs und Batch-Arbeit ab, ohne dem Socket nahe zu kommen. Es ist dieselbe Idee wie bei Heartbeat-Checks für Cronjobs, und dieselbe Idee steht hinter unserem Beitrag dazu, warum Cronjobs still scheitern.

Um den Zustand zu lesen, scrapen Sie /metrics mit einem API-Schlüssel und fragen die Daten dort ab. Das ist der unterstützte Lesepfad, und er ist stabil. Wenn die Daten ohnehin öffentlich sind, liefert /api/status-page/heartbeat/:slug echte Heartbeats ohne Zugangsdaten, beschränkt auf die Monitore, die Sie veröffentlichen wollten.

Ein Socket-Wrapper ist in Ordnung für Arbeit, die Sie beobachten, etwa einen einmaligen Import von fünfzig Monitoren, den Sie einmal ausführen und von Hand prüfen. Pinnen Sie die Version des Wrappers, pinnen Sie Ihre Kuma-Version, und halten Sie ihn aus jeder Pipeline heraus, auf die niemand schaut.

Direkt in die Datenbank zu schreiben ist das, was Sie lassen sollten. Manche tun es trotzdem. Kuma hält Zustand im Arbeitsspeicher und schreibt fortlaufend Heartbeats, ein Schreibzugriff hinter seinem Rücken ist also eine beschädigte Instanz, die auf den nächsten Neustart wartet.

Wenn Sie Überwachung als Code brauchen

An diesem Punkt passen Tool und Aufgabe nicht mehr zusammen. Wenn Ihre Monitore in Git liegen, in einem Pull Request geprüft und von einem Dienstkonto angelegt werden müssen, das sie nicht auch löschen kann, verlangen Sie von einem Tool, das vom Dashboard her gedacht ist, sich wie eines zu verhalten, das von der API her gedacht ist.

Um genau diese Lücke herum haben wir Uptimepage gebaut. Monitore werden in einem Terraform-Provider definiert oder über eine dokumentierte REST-API mit eingeschränkten Tokens angelegt, sodass ein CI-Job einen Check hinzufügen kann, ohne die Schlüssel zum Konto zu halten. Es gibt auch einen MCP-Server, falls das, was Monitore anlegt, ein Agent ist und keine Pipeline. Der direkte Vergleich ist die Kurzfassung.

Für viele Homelabs und kleine Teams ist Kuma weiterhin die richtige Antwort, und unser Überblick über selbst gehostete Uptime-Monitore sagt das auch. Das hier ist eine bestimmte Grenze, und es ist die, an die die meisten als zweite stoßen, gleich nach dem einzigen gemeinsamen Login.

Häufige Fragen

Hat Uptime Kuma eine REST-API?

Uptime Kuma hat keine REST-API zur Verwaltung von Monitoren. Die HTTP-Routen, die es anbietet, sind Badges zum Lesen, das JSON der öffentlichen Statusseite, der Push-Endpunkt für Heartbeat-Monitore und ein Endpunkt für Prometheus-Metriken. Monitore anlegen, bearbeiten, pausieren und löschen läuft stattdessen komplett über Socket.IO.

Wie lege ich in Uptime Kuma per Skript einen Monitor an?

Sie öffnen eine Socket.IO-Verbindung, melden sich mit dem Benutzernamen und Passwort des Admins an und senden das Event add mit einem Monitor-Objekt. Für dieses Objekt gibt es kein dokumentiertes Schema, in der Praxis kopieren Sie also, was die Web-UI sendet, oder Sie nutzen einen Community-Wrapper, der das schon getan hat.

Was kann ein API-Schlüssel von Uptime Kuma?

Ein API-Schlüssel authentifiziert genau einen Endpunkt, die Prometheus-Metriken unter /metrics. Er kann keinen Monitor anlegen, bearbeiten, pausieren oder löschen, und er ist kein allgemeines Zugriffstoken für den Rest der App.

Wird die Python-Bibliothek uptime-kuma-api noch gepflegt?

Der ursprüngliche Python-Wrapper hat seit September 2023 keinen Commit mehr bekommen, und seine eigene Kompatibilitätstabelle endet bei Uptime Kuma 1.23.2. Version 2 ist die aktuelle Reihe, daher hat sich das Ökosystem in mehrere kleine Forks aufgespalten, statt sich um ein gepflegtes Paket zu sammeln.

Wie automatisiert man Uptime Kuma heute am sichersten?

Push-Monitore sind die eine Automatisierungsschnittstelle, die Uptime Kuma bewusst unterstützt. Ihr Job ruft nach Abschluss eine Token-URL auf, was Cronjobs und Batch-Arbeit abdeckt, ohne die private Socket.IO-Schnittstelle überhaupt anzusprechen.