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) oder wenn ein SLA-Ziel, ein Zugriffsbereich, eine Eskalationsrichtlinie oder eine Incident-Richtlinie auf ihm aufbaut. 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, antwortet die API mit 503 und Retry-After -- nie mit einer leeren Liste, die wie „keine Ausfälle" aussähe.

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

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