IT-Doku Agent API — Geräte-Inventar & Monitoring

Der IT-Doku Agent läuft auf Windows-, macOS- und Linux-Geräten und übermittelt automatisch Hardware-Inventar, Software-Listen, Monitoring-Ergebnisse, Backup-Status und Windows-Update-Informationen.

1. Authentifizierung

Die Agent-API nutzt zwei Token-Typen, die als Parameter im Request-Body (POST) oder als Query-Parameter (GET) übergeben werden:

2. POST /api/agent/register

Registriert ein neues Gerät und gibt einen einmaligen Agent-Token zurück.

Request

Antwort (Erfolg, 200)

{
  "success": true,
  "message": "Device registered successfully",
  "agent_token": "a1b2c3d4...64 Zeichen",
  "device_id": 123
}

Device-Matching

Beim Registrieren wird nach einem bestehenden Gerät gesucht (Reihenfolge):

1. Hostname-Match innerhalb des Kunden
2. IP-Adress-Match
3. MAC-Adress-Match

Wird ein Gerät ohne Token gefunden (z. B. durch Network Discovery erstellt), wird es mit dem Agent verknüpft.

3. POST /api/agent/checkin

Haupt-Heartbeat: Überträgt das komplette Hardware-Inventar und empfängt Tasks + Monitoring-Konfiguration. Standard-Intervall: 15 Minuten.

Request

system-Objekt

Felder: hostname (Pflicht), os_name, os_version, os_build, os_architecture, manufacturer, model, serial_number, cpu_name, cpu_cores, cpu_threads, ram_bytes, primary_ip, primary_mac, is_virtual, hypervisor_type, domain

Antwort (Erfolg, 200)

{
  "success": true,
  "message": "Checkin successful",
  "device_id": 123,
  "next_checkin": 900,
  "tasks": [
    { "id": 456, "type": "restart_service", "payload": { "service": "Spooler" } }
  ],
  "monitoring": {
    "enabled": true,
    "checks": [ { "id": 1, "type": "cpu", "threshold": 90, "operator": ">" } ]
  }
}

4. GET /api/agent/tasks

Schnelles Task-Polling ohne vollständigen Checkin. Gibt bis zu 10 ausstehende Tasks zurück.

Request

GET /api/agent/tasks?agent_token=abc123...

Antwort (200)

{
  "success": true,
  "tasks": [
    { "id": 456, "type": "restart_service", "payload": { "service": "Spooler" } }
  ]
}

5. POST /api/agent/task-result

Meldet das Ergebnis eines ausgeführten Tasks zurück.

6. POST /api/agent/monitoring-result

Übermittelt Monitoring-Check-Ergebnisse. Nur verfügbar, wenn Monitoring für das Gerät aktiviert ist.

Automatische Aktionen

• Alert erstellen: Bei triggered: true wird ein Monitoring-Alert erzeugt (dedupliziert)
• Auto-Restart: Bei Dienst-Checks kann automatisch ein Neustart-Task erstellt werden
• Auto-Remediation: Bei konfiguriertem Script wird AutoRemediationService ausgeführt
• Alert auflösen: Bei triggered: false werden offene Alerts geschlossen

7. POST /api/agent/backup-status

Meldet Backup-Job-Status von TERRA Cloud, Veeam, Windows Server Backup, Synology ABB oder Custom-Providern.

8. Windows Update Endpoints

POST /api/agent/update-status

Überträgt Windows-Update-Scan-Ergebnisse (verfügbare Updates, Status).

Die Antwort enthält ggf. tasks mit windows_update_install-Aufträgen, falls genehmigte Updates anstehen und das Wartungsfenster es erlaubt.

POST /api/agent/update-install-result

Meldet das Ergebnis einer Update-Installation zurück.

9. MeshCentral-Integration

GET /api/agent/meshcentral-config

Ruft die MeshCentral-Installationskonfiguration ab, um den MeshCentral-Agent auf dem Gerät einzurichten.

GET /api/agent/meshcentral-config?agent_token=abc123&platform=windows64

Mögliche platform-Werte: windows64, linux64, linux-arm64, macos, macos-arm64

POST /api/agent/meshcentral-registered

Meldet, dass der MeshCentral-Agent installiert wurde. Triggert automatisches Device-Linking.

10. Agent Auto-Update

GET /api/agent/check-update

Prüft, ob eine neuere Version des Agent-Scripts verfügbar ist.

GET /api/agent/check-update?agent_token=abc123&hash=a1b2c3d4e5f6g7h8

Antwort (200)

{
  "success": true,
  "latest_hash": "a1b2c3d4e5f6g7h8",
  "update_available": true,
  "download_url": "https://it-dashboard.de/api/agent/download-script"
}

GET /api/agent/download-script

Lädt das aktuelle Agent-Script für das OS des Geräts herunter (erfordert agent_token).

11. Agent-Download (öffentlich)

Öffentlicher Endpunkt, keine Authentifizierung erforderlich. Die Scripts enthalten keine Geheimnisse.

GET /api/agent/download-agent?os=windows
GET /api/agent/download-agent?os=macos
GET /api/agent/download-agent?os=linux
GET /api/agent/download-agent?type=synology-backup

12. Fehlercodes

Alle Fehler folgen dem Format:

{ "success": false, "message": "Fehlerbeschreibung" }