API-Endpunkte Ab Team-Plan

Überblick über die verfügbaren API-Endpunkte -- keine vollständige Referenz, sondern eine Orientierungshilfe zum Aufbau der API.

Endpunkte nach Bereich

Referenzdaten (nur lesend)

Metadaten, die du brauchst, um gültige Service-Payloads zusammenzustellen -- z.B. welche Standorte und welche Check-Typen es gibt.

GET /v1/probes liefert die aktiven Monitoring-Standorte (Location-Codes). GET /v1/meta/check-types liefert den Katalog aller Check-Typen inklusive ihrer Konfigurations- und Bedingungs-Felder -- praktisch, um beim Anlegen oder Bearbeiten eines Services eine gültige Payload zu bauen. Beide sind reine Lese-Endpunkte und erfordern die Berechtigung Services anzeigen.

Services

Mit ?tag= filterst du die Liste auf einen Tag, z.B. GET /v1/services?tag=kunde:4711.

Tags zuweisen. Im Feld tags gibst du die Tags eines Services als ID oder als Name an, auch gemischt. kunde:4711 und kunde=4711 meinen denselben Tag. Beim Schlüssel spielt Groß- und Kleinschreibung keine Rolle, der Wert muss exakt stimmen. Gibt es einen Namen noch nicht, legt die API den Tag an. Ein Eintrag, der wie eine Tag-ID aussieht (21 Zeichen aus Buchstaben, Ziffern, _ oder -, darunter mindestens ein Großbuchstabe), wird aber nie neu angelegt: Gibt es keinen Tag mit dieser ID oder diesem Namen, antwortet die API mit 422 am Eintrag (z.B. tags.2) und speichert nichts. Beim Bearbeiten ersetzt tags alle Tags des Services. Tags, die der Server-Agent setzt, bleiben.

{
  "name": "Onlineshop",
  "check_type": "http",
  "target": "https://shop.example.com",
  "tags": ["kunde:4711", "env=prod", "kritisch"]
}

Überwachung einrichten. Wie ein Service geprüft wird, legst du im Block settings fest. Schickst du ihn beim Anlegen mit, ist settings.interval_seconds Pflicht, das Prüfintervall in Sekunden. Optional kommen assigned_probes (Standort-Codes aus GET /v1/probes), timeout_seconds, retries und config dazu. Die Felder von config je Check-Typ liefert GET /v1/meta/check-types. Ohne settings legt die API einen Service vom Typ http, tcp, dns, icmp oder ssl zwar an, prüft ihn aber nicht. Die Antwort zeigt dann is_configured: false. Du kannst settings später per PUT oder PATCH nachreichen. Beim Bearbeiten genügt ein Teil von settings, weggelassene Werte bleiben erhalten.

Geheime Werte. Header-Werte und die Zugangsdaten unter config.auth gibt die API nie zurück. An ihrer Stelle steht der Platzhalter __LIVCK_KEEP_UNCHANGED__. Schickst du beim Bearbeiten genau diesen Platzhalter, bleibt der gespeicherte Wert unverändert. Sendest du headers oder auth mit, ersetzt das den ganzen Block. Nimm also alle Header auf, die bleiben sollen, und setze bei ihnen den Platzhalter als Wert ein. Ist für ein Feld noch kein Wert gespeichert, antwortet die API auf den Platzhalter mit 422.

Service löschen. DELETE /v1/services/{id} räumt auch die Vorfälle und Wartungen auf, die den Service betreffen. Betrifft ein Vorfall oder eine Wartung noch andere Services, entfernt LIVCK nur diesen Service daraus. Gehört ein offener Vorfall nur zu diesem Service, wird er mit einem öffentlichen Verlaufseintrag aufgelöst. Eine geplante oder laufende Wartung, die nur diesen Service betrifft, wird abgebrochen. Mit zwei Parametern löschst du sie stattdessen:

Fehlt dem Token die zusätzliche Berechtigung, antwortet die API mit 403.

Tags

Tags ordnen deine Services, etwa env:prod oder ein Tag pro Kunde wie kunde:4711. Ein Tag hat einen Schlüssel und optional einen Wert (kunde:4711) oder besteht nur aus einem Namen (kritisch).

Filter für GET /v1/tags:

Beim Schlüssel spielt Groß- und Kleinschreibung keine Rolle, der Wert muss exakt stimmen. Ein Name ohne Wert (?label=kritisch) findet nur den Tag ohne Wert. Gibt es keinen passenden Tag, ist die Liste leer. Die Tag-Liste liefert standardmäßig 50 Einträge pro Seite.

POST /v1/tags/ensure nimmt dieselben Felder wie das Anlegen (key, optional value und color) und liefert den Tag immer zurück:

POST /v1/tags legt dagegen nur neu an und antwortet mit 422, wenn es den Tag schon gibt.

DELETE /v1/tags/{id} entfernt den Tag von allen Services, die Services selbst bleiben. Solange der Tag noch gebraucht wird, antwortet die API mit 422: wenn er eine Gruppe auf einer Statuspage füllt (sync_tag_id), wenn ein SLA-Ziel, ein Zugriffsbereich, eine Eskalationsrichtlinie oder eine Incident-Richtlinie auf ihm aufbaut oder wenn ein Enrollment-Key, der noch gilt, ihn trägt. Sonst würde sich der nächste Server ohne den Tag anmelden. Tags, die der Server-Agent setzt (source: system), kannst du nicht löschen.

Service-Metriken (nur lesend)

Parameter:

Verlauf eines Services (nur lesend)

Vorfälle und Wartungen filterst du hier wie in den Listen /v1/incidents und /v1/maintenances (siehe unten). Jeder Vorfall enthält zusätzlich service_impact: wie stark er genau diesen Service getroffen hat (impact), ob der Service sich erholt hat (is_recovered) und wann (added_at, recovered_at).

Der Check-Verlauf zeigt die einzelnen Prüfungen, neueste zuerst: Zeitpunkt, Standort, Status, Antwortzeit, HTTP-Code, Fehlermeldung und die Zeiten für DNS, Verbindung, TLS und Gesamt. Inhalte der Antwort (Body, Header) sind nicht enthalten.

Ist meta.next_cursor leer, gibt es keine älteren Einträge. Der Verlauf reicht höchstens 90 Tage zurück, bei kürzerer Datenaufbewahrung in deinem Plan entsprechend weniger. Sind die Messdaten gerade nicht erreichbar, ist die Liste leer.

Berechtigungen: Vorfälle brauchen Services anzeigen und Vorfälle anzeigen, Wartungen Services anzeigen und Wartungen anzeigen, der Check-Verlauf Services anzeigen.

Server (nur lesend)

Ein Server, auf dem der LIVCK-Agent läuft, ist ein Service vom Typ agent. Die API liefert ihn wie jeden anderen Service. Im Feld agent steht zusätzlich, was der Agent über den Server meldet. Bei allen anderen Services ist agent leer (null).

Die Messwerte eines Servers rufst du gesondert ab:

agent-metrics liefert in metrics den letzten Wert jeder Kennzahl. Die Namen sind dieselben wie in den Alarm-Regeln, etwa sys.cpu.total_pct, sys.mem.used_pct oder sys.load.1. Hat der Agent eine Kennzahl seit einem Tag nicht gemeldet, ist ihr Wert leer (null). Dazu kommen Festplatten (disks), Grafikkarten (gpus), SMART-Werte (smart) und die Prüfungen, die der Server selbst ausführt (probes), jeweils mit ihren letzten Werten. reported_at nennt den Zeitpunkt der neuesten Meldung.

agent-metrics/history liefert den Verlauf, wie ihn die Seite Analyse in der Konsole zeigt. Mit range wählst du den Zeitraum bis jetzt: 1h, 6h, 24h, 7d, 30d, 90d oder 365d, Standard 24h. Reicht die Datenaufbewahrung deines Plans nicht so weit zurück, kürzt die API den Zeitraum. window_seconds nennt den Zeitraum, den sie gelesen hat. LIVCK teilt ihn in etwa 240 Abschnitte. Für jede Kennzahl liefert metrics je Abschnitt den Durchschnitt (avg) und den Spitzenwert (max), passend zu den Zeitpunkten in timestamps. Ein leerer Wert heißt, dass der Server in dem Abschnitt nichts gemeldet hat. stats fasst jede Kennzahl über den ganzen Zeitraum zusammen: letzter Wert, Minimum, Durchschnitt, Maximum, die Perzentile 50, 95 und 99 und die Zahl der Meldungen (samples).

Mit keys wählst du bis zu 100 Kennzahlen aus, z.B. keys=sys.cpu.total_pct,sys.mem.used_pct. Bei Festplatten, Netzwerk und Prüfungen steht das Gerät im Namen, etwa sys.disk._root.used_pct. Ohne keys kommen die ersten 100 Kennzahlen, die der Server im Zeitraum gemeldet hat, die Werte des Hosts zuerst. available_keys nennt immer alle, so fragst du bei vielen Festplatten oder Schnittstellen den Rest gezielt ab.

Beide Endpunkte brauchen Services anzeigen und gelten nur für Server. Für jeden anderen Service antworten sie mit 404. Sind die Messdaten gerade nicht erreichbar, sind die Werte leer.

Enrollment-Keys

Mit einem Enrollment-Key meldet sich ein neuer Server bei deiner Organisation an. In der Konsole heißt er Enrollment-Token. Die API nennt ihn Key, damit er nicht mit deinem API-Token verwechselt wird. Die Endpunkte brauchen die Berechtigung Server-Agents verwalten.

Beim Erstellen sind alle Felder optional:

Die Antwort (201) enthält den Key im Feld token und den fertigen Installationsbefehl in install_command. Beides bekommst du nur dieses eine Mal. LIVCK speichert den Key nur als Prüfsumme.

curl -X POST https://api.livck.cloud/v1/enrollment-keys \
  -H "Authorization: Bearer dein-api-token" \
  -H "Content-Type: application/json" \
  -d '{"name": "kunde-4711-web-1", "tags": ["kunde:4711"], "agent_tags": false}'

Die Tags des Keys gelten immer. Ein Server kann sie nicht ersetzen. Setzt er bei der Installation einen Tag mit demselben Schlüssel, etwa --tag kunde:4712 bei einem Key mit kunde:4711, bleibt es bei kunde:4711. Den Tag des Servers verwirft LIVCK. Ebenso verwirft LIVCK Tags des Servers mit einem reservierten Schlüssel des Agents, Tags des Servers, die eine Gruppe auf einer Statuspage füllen (sync_tag_id), und neue Tags des Servers, wenn dein Tag-Kontingent voll ist. Die Anmeldung klappt trotzdem. Mit "agent_tags": false bekommt ein Server nur die Tags des Keys. Die Tags, die der Agent selbst setzt, etwa Betriebssystem und Distribution, kommen in jedem Fall dazu.

Ein Key darf auch einen Tag tragen, der eine Gruppe auf einer Statuspage füllt. Der Server bekommt den Tag, erscheint aber nie auf der Statuspage: Gruppen, die sich per Tag füllen, lassen Server aus.

Nach der Installation. status zeigt, ob ein Key noch gilt (active), widerrufen (revoked), aufgebraucht (exhausted) oder abgelaufen (expired) ist. Ein aufgebrauchter Key bleibt exhausted, auch wenn er inzwischen abgelaufen ist. uses zählt die Anmeldungen. services nennt die Server, die sich mit dem Key angemeldet haben, die neuesten zuerst und höchstens 25. Ob dein Server angekommen ist, liest du an services ab. Mit ?status=active listest du nur Keys, die noch gelten. Mehrere Zustände gibst du kommagetrennt an, etwa ?status=exhausted,expired.

Widerrufen. DELETE /v1/enrollment-keys/{id} sperrt den Key sofort. Server, die sich schon angemeldet haben, laufen weiter. Ein zweites Widerrufen ändert nichts. Abgelaufene, aufgebrauchte und widerrufene Keys löscht LIVCK, sobald sie älter als 30 Tage sind. Danach antwortet die API für sie mit 404, und enrollment_key_id am Server ist leer.

Ist die Server-Überwachung für deine Organisation abgeschaltet, antwortet POST /v1/enrollment-keys mit 403.

Incidents

Über POST /v1/incidents/{id}/updates postest du einen Eintrag in den Zeitverlauf des Incidents und kannst dabei den Status ändern.

Filter für GET /v1/incidents:

Ohne Filter liefert die Liste alle Vorfälle, auch interne. Unbekannte oder fremde IDs in service_ids werden ignoriert; bleibt keine übrig, ist die Liste leer.

Wartungen

Filter für GET /v1/maintenances:

Statuspages

Die Statuspage eines Kunden findest du über ihren Slug: GET /v1/statuspages?slug=kunde-4711 liefert genau diese Seite oder eine leere Liste.

Jede Statuspage nennt in url ihre öffentliche Adresse: die eigene Domain, sobald sie verifiziert ist, sonst https://{slug}.statuspage.de. Hast du mehrere eigene Domains, zählt die zuerst angelegte. Auch eine unveröffentlichte Statuspage liefert ihre Adresse. Dort antwortet die Seite mit 404, bis du sie veröffentlichst.

Komponenten liefern neben status auch effective_status. Das ist der Status, den Besucher auf der Statuspage sehen. Er ergibt sich aus einer laufenden Wartung, einem offenen veröffentlichten Vorfall oder dem verknüpften Service, bei einer Gruppe aus den sichtbaren Komponenten darin. status ist nur ein gespeicherter Wert, den die Statuspage nicht anzeigt. Ist eine Komponente ausgeblendet oder liegt sie in einer ausgeblendeten Gruppe, ist effective_status leer (null).

Eine Komponenten-Gruppe mit sync_tag_id füllt sich selbst: Sie zeigt automatisch jeden Service mit diesem Tag, auch Services, die du später anlegst. So bekommt jeder Kunde eine Statuspage, die du nicht von Hand pflegen musst.

Beim Anlegen einer eigenen Domain liefert die Antwort die DNS-Einträge (CNAME und TXT), die du bei deinem DNS-Anbieter setzen musst. Die Prüfung läuft danach automatisch. Jede Domain nennt in statuspage_id die Statuspage, zu der sie gehört.

Beispiel-Anfrage

So listest du alle deine Services auf:

curl -X GET https://api.livck.cloud/v1/services \
  -H "Authorization: Bearer dein-api-token" \
  -H "Accept: application/json"

Antwort:

{
  "data": [
    {
      "id": "abc123",
      "name": "Unternehmens-Website",
      "status": "up",
      "check_type": "http",
      "target": "https://example.com"
    }
  ],
  "meta": { "current_page": 1, "last_page": 3, "total": 42 }
}

Paginierung

Endpunkte mit Listen sind paginiert:

Beispiel: GET /v1/services?page=2&per_page=25. Die Antwort enthält neben data die Objekte links (erste/letzte/vorherige/nächste Seite) und meta (aktuelle Seite, Gesamtanzahl, letzte Seite).

Fehlerbehandlung

Die API nutzt Standard-HTTP-Statuscodes:

Bei Fehlern enthält die Antwort immer ein message-Feld:

{
  "message": "The requested resource was not found."
}

Bei Validierungsfehlern (422) kommt zusätzlich ein errors-Objekt mit feldbezogenen Details hinzu:

{
  "message": "The name field is required.",
  "errors": {
    "name": ["The name field is required."]
  }
}

Fehlermeldungen sind immer englisch.

Liegt ein 403 oder 402 an deinem Plan, enthält die Antwort ein upsell-Objekt. Bei einem erreichten Limit steht in upsell.reason der Wert limit und in upsell.key das betroffene Limit. Wo vorhanden, nennen limit und usage dein Kontingent und deinen aktuellen Stand:

{
  "message": "Your plan's service limit has been reached.",
  "limit": 150,
  "usage": 150,
  "upsell": { "reason": "limit", "key": "services" }
}

Fehlt deinem Plan eine Funktion, steht in upsell.reason der Wert feature. Einige Limits meldet die API als Validierungsfehler 422 am betroffenen Feld, etwa die Zahl der Tags oder der veröffentlichten Statuspages.

Ratenbegrenzung

Pro Token sind 120 Anfragen pro Minute erlaubt. Die aktuellen Limits liefert jeder Response als Header mit:

Vollständige API-Referenz

Weiterführende Themen

• API-Übersicht -- Was ist die LIVCK API?
• API-Tokens -- Tokens erstellen und verwalten
• Fehlerbehebung -- Lösungen für häufige API-Probleme