everRun API v1

Normalisierter REST-Endpunkt für die Integration in Leitwarten, BMS und externe Monitoring-Systeme (Johnson Controls MXI, Siemens WinCC, Zabbix, PRTG usw.).

Das Dashboard übersetzt SNMP-Rohdaten aus everRun-Systemen in ein einheitliches JSON-Schema — der Integrator muss everRun nicht kennen.

Basis-URL

http://<dashboard-ip>:3000/api/v1

Alle Endpunkte

Authentifizierung

Alle Status- und Alert-Endpunkte erfordern einen API-Key. Beim ersten Start wird automatisch ein Schlüssel erzeugt und im Container-Log ausgegeben.

API-Key übergeben

Als HTTP-Header (empfohlen):

X-API-Key: <ihr-api-key>

Oder als Query-Parameter (z. B. für einfache Tests):

GET /api/v1/status?apiKey=<ihr-api-key>

Ersten Key abrufen

Der beim ersten Start erzeugte Key steht im Container-Log:

docker logs everrun-dashboard | grep "API-Key erzeugt"

Oder direkt über den Keys-Endpunkt (ohne Auth, da intern):

POST http://172.30.1.8:3000/api/v1/apikeys

Fehlercodes

Response-Schema

Alle Werte sind normalisiert — keine everRun-internen Enums, keine rohen Integer-Codes.

Status-Werte

Offline-Verhalten

Ist ein System nicht erreichbar, antwortet die API trotzdem mit HTTP 200 — status ist dann "unknown" und ein error-Feld erklärt den Grund:

{
  "id":     "sys_1791962096503",
  "name":   "everRun-Demo-System",
  "status": "unknown",
  "error":  "Request timed out",
  "timestamp": "2026-10-14T15:06:05.452Z"
}

System-Objekt

{
  "id":         "sys_1791962096503",   // interne ID (String)
  "name":       "everRun-Demo",
  "ip":         "172.30.1.5",
  "status":     "ok",                  // ok | warning | fault | unknown
  "model":      "AV100",
  "license":    "ee_p_52214",
  "vcpus":      8,
  "ramGb":      32,
  "alertCount": 0,
  "nodes":      [ /* Node-Objekte */ ],
  "vms":        [ /* VM-Objekte */ ],
  "alerts":     [ /* Alert-Objekte */ ],
  "timestamp":  "2026-10-14T14:30:00Z"
}

Node-Objekt

{
  "name":     "node0",
  "role":     "primary",    // primary | secondary
  "state":    "Normal",
  "activity": "Läuft",
  "status":   "ok"          // ok | warning | fault
}

VM-Objekt

{
  "name":        "DC01",
  "protection":  "FT",      // FT | HA | Unprotected
  "runningNode": "node0",
  "state":       "Normal",
  "activity":    "Läuft",
  "running":     true,
  "status":      "ok"
}

Alert-Objekt

{
  "systemId":   "sys_1791962096503",
  "systemName": "everRun-Demo",
  "severity":   "Kritisch",   // Behoben|Info|Warnung|Gering|Schwerwiegend|Kritisch
  "severityNum": 5,
  "message":    "Node0 nicht erreichbar",
  "timestamp":  null
}

Alle Systeme

curl -H "X-API-Key: ihr-key" \
     http://172.30.1.8:3000/api/v1/status

{
  "systems": [
    {
      "id": "sys_1791962096503",
      "name": "everRun-Demo",
      "ip": "172.30.1.5",
      "status": "ok",
      "model": "AV100",
      "license": "ee_p_52214",
      "vcpus": 8,
      "ramGb": 32,
      "alertCount": 0,
      "nodes": [
        { "name": "node0", "role": "primary",   "state": "Normal", "activity": "Läuft", "status": "ok" },
        { "name": "node1", "role": "secondary", "state": "Normal", "activity": "Läuft", "status": "ok" }
      ],
      "vms": [
        { "name": "DC01", "protection": "FT", "runningNode": "node0",
          "state": "Normal", "activity": "Läuft", "running": true, "status": "ok" }
      ],
      "alerts": [],
      "timestamp": "2026-10-14T14:30:00Z"
    }
  ],
  "timestamp": "2026-10-14T14:30:00Z"
}

Alerts

curl -H "X-API-Key: ihr-key" \
     http://172.30.1.8:3000/api/v1/alerts

{
  "alerts": [
    {
      "systemId":    "sys_1791962096503",
      "systemName":  "everRun-Demo",
      "severity":    "Kritisch",
      "severityNum": 5,
      "message":     "Node0 nicht erreichbar",
      "timestamp":   null
    }
  ],
  "count":     1,
  "timestamp": "2026-10-14T14:30:00Z"
}

API-Key-Verwaltung

Diese Endpunkte benötigen keinen API-Key — sie sind für die interne Verwaltung gedacht. Im Produktionsbetrieb per Firewall auf das lokale Netz einschränken.

curl http://172.30.1.8:3000/api/v1/apikeys

# Response:
{ "count": 1, "keys": ["ab12…ef34"] }