API-Endpunkte#

WatchGrid bietet eine umfassende REST-API, mit der Sie Agenten verwalten, Konfigurationen anpassen und Benachrichtigungskanäle einrichten können.

Allgemeine Informationen#

Basis-URL#

Alle API-Endpunkte verwenden die folgende Basis-URL:

https://watchgrid.de/api

Authentifizierung#

Alle Anfragen an die API müssen authentifiziert werden. Verwenden Sie dazu das API-Token Ihrer Organisation (zu finden im Dashboard unter Organisation). Übergeben Sie dieses Token im HTTP-Header als Bearer-Token:

Authorization: Bearer <IHR_API_TOKEN>
Accept: application/json

Agenten-Endpunkte (/agent/)#

Diese Endpunkte dienen der Registrierung, Konfiguration und Abfrage von Monitoring-Agenten.

1. Übersicht aller Agenten#

Gibt Basisinformationen zu allen für die Organisation registrierten Agenten zurück.

  • Methode: GET

  • Pfad: /agent/all

  • Response: Liste von Agenten-Objekten (inkl. Hostname, UUID, Version, Betriebssystem, letzter Aktivität und Alarm-Status).

2. Agent registrieren#

Erstellt einen neuen Agenten im System.

  • Methode: POST

  • Pfad: /agent/

  • Response: SuccessResponse mit der generierten UUID des neuen Agenten.

3. Agent löschen#

Löscht einen Agenten und alle zugehörigen historischen Daten unwiderruflich.

  • Methode: DELETE

  • Pfad: /agent/

  • Query-Parameter: agent_id (UUID des Agenten)

  • Response: Success- oder Fehlermeldung.

4. Agenten-Details abrufen#

Gibt die Detailinformationen eines spezifischen Agenten zurück.

  • Methode: GET

  • Pfad: /agent/info

  • Query-Parameter: agent_id (UUID des Agenten)

  • Response: Agenten-Objekt.

5. Systeminformationen aktualisieren (Agent)#

Wird vom Go-Agenten verwendet, um Basisdaten des Hostsystems bei der Registrierung/Start zu übermitteln.

  • Methode: POST

  • Pfad: /agent/info

  • Body: JSON mit Hostname, OS-Typ, OS-Version, Architektur, Uptime sowie Hardware-Details (cpu_cores, ram_total_gb, disk_total_gb).

6. Metrik-Snapshots übermitteln (Agent)#

Wird vom Go-Agenten oder benutzerdefinierten Scripten genutzt, um die periodischen Systemauslastungswerte zu übertragen.

  • Methode: POST

  • Pfad: /agent/metrics

  • Body: JSON mit CPU-Auslastung (%), RAM-Auslastung (%), Festplatten-Auslastung (%) sowie Hardware-Gesamtkapazitäten (cpu_cores, ram_total_gb, disk_total_gb), erfassten Statuswerten für offene Ports und überwachten systemd-Diensten.

7. Agenten-Konfiguration abfragen#

Liefert die für den Agenten gültige Konfiguration. Wenn keine spezifische Konfiguration vorliegt, wird die globale Konfiguration zurückgegeben.

  • Methode: GET

  • Pfad: /agent/config

  • Query-Parameter: agent_id (UUID des Agenten)

  • Response: Schwellenwerte für CPU/RAM/Disk, Intervalle, zu überwachende Ports und Dienste, Update-Anforderungen.

8. Agenten-spezifische Konfiguration erstellen/aktualisieren#

Erstellt oder modifiziert eine benutzerdefinierte Konfiguration für einen einzelnen Agenten.

  • Methoden: POST (erstellen) / PUT (aktualisieren)

  • Pfad: /agent/config

  • Body: JSON mit Reporting-Intervall (Sekunden), Schwellenwerten für Warnung & Alarm (CPU, RAM, Disk), sowie kommaseparierten Whitelist-Ports und systemd-Diensten.

9. Agenten-spezifische Konfiguration löschen#

Entfernt die spezifische Konfiguration eines Agenten. Es gilt ab diesem Zeitpunkt wieder die globale Konfiguration.

  • Methode: DELETE

  • Pfad: /agent/config

  • Query-Parameter: agent_id (UUID des Agenten)

10. Agenten-Stammdaten editieren#

Erlaubt die Aktualisierung von Name/Hostname, Kommentaren oder die Steuerung des Wartungsmodus.

  • Methode: PATCH

  • Pfad: /agent/

  • Query-Parameter: agent_id (UUID des Agenten)

  • Body: JSON mit optionalen Feldern:

    • hostname (String)

    • comment (String)

    • maintenance_active (Boolean)

    • maintenance_minutes (Integer, optional für automatische Deaktivierung)

    • maintenance_start / maintenance_end (ISO-Timestamps)

11. Globale Organisation-Konfiguration abrufen/anpassen#

  • Methoden: GET (abrufen) / PUT (anpassen)

  • Pfad: /agent/global-config

  • Response/Body: CPU/RAM/Disk-Schwellenwerte und Standard-Metrik-Intervalle für alle Agenten der Organisation.

Benachrichtigungs-Endpunkte (/notification/)#

Diese Endpunkte dienen der Konfiguration und dem Testen von Kanälen für Benachrichtigungen bei Warnungen und Alarmen.

1. Alle Kanäle auflisten#

Listet alle konfigurierten Benachrichtigungskanäle der Organisation auf.

  • Methode: GET

  • Pfad: /notification/all

2. Kanal erstellen#

Erstellt einen neuen Benachrichtigungskanal. Standardmäßig ist dieser sofort aktiv.

  • Methode: POST

  • Pfad: /notification/

  • Body: JSON mit:

    • channel_type (z. B. discord, gotify, ntfy, slack, webhook, email, sms)

    • destinations (Liste von Ziel-URLs oder E-Mail-Adressen/Telefonnummern)

    • is_active (Boolean)

3. Kanal aktualisieren#

Passt die Einstellungen eines existierenden Benachrichtigungskanals an.

  • Methode: PUT

  • Pfad: /notification/

  • Query-Parameter: channel_id (UUID des Kanals)

  • Body: JSON analog zur Kanalerstellung.

4. Kanal löschen#

Löscht einen Benachrichtigungskanal unwiderruflich.

  • Methode: DELETE

  • Pfad: /notification/

  • Query-Parameter: channel_id (UUID des Kanals)

5. Kanal-Details abfragen#

Liefert die Konfiguration eines spezifischen Kanals.

  • Methode: GET

  • Pfad: /notification/info

  • Query-Parameter: channel_id (UUID des Kanals)

6. Kanal testen#

Löst eine Testbenachrichtigung auf dem konfigurierten Kanal aus.

  • Methode: GET

  • Pfad: /notification/test

  • Query-Parameter: channel_id (UUID des Kanals)