# ModbusCloud API

Lesen Sie Daten zu Gateways, Registern, Messwerten und Alarmen und empfangen Sie Ereignisse als Webhooks.

Basis-URL: `https://api.modbuscloud.com/v1`. Dieselbe Dokumentation mit der Schaltfläche Ausprobieren finden Sie unter https://docs.modbuscloud.com/de, das OpenAPI-Dokument unter https://docs.modbuscloud.com/de/openapi.json. Die Beispiele unten verwenden den öffentlichen Sandbox-Schlüssel, Sie können sie also direkt ausführen.

Die ModbusCloud API stellt Ihren eigenen Systemen die Daten bereit, die unsere Gateways aus Modbus-Geräten lesen. Dazu gehören die Gateways, die Modbus-Geräte dahinter, Register mit ihren aktuellen Werten, der Messwertverlauf und Alarme. Webhooks senden Ereignisse an Ihren Endpoint, sobald sie eintreten.

## Schnellstart

Jede Anfrage benötigt einen API-Schlüssel. Um die API sofort auszuprobieren, verwenden Sie den Sandbox-Schlüssel unten. Er hat nur Lesezugriff und gehört zu unserer Demo-Organisation, deren Gateways jede Minute neue Messwerte senden. Alle nutzen diesen Schlüssel gemeinsam, daher erlaubt er 60 Anfragen pro Minute und Besucher.

```
mlk_72718174d83aa7fa5238c5eb8df5adc3e432c72cc80ea3242821f3aaabd9f630
```

Prüfen Sie, ob der Schlüssel funktioniert:

```bash
curl https://api.modbuscloud.com/v1/introspect \
  -H "Authorization: Bearer mlk_72718174d83aa7fa5238c5eb8df5adc3e432c72cc80ea3242821f3aaabd9f630"
```

Rufen Sie die Gateways ab und danach die aktuellen Werte eines Gateways:

```bash
curl https://api.modbuscloud.com/v1/devices \
  -H "Authorization: Bearer mlk_72718174d83aa7fa5238c5eb8df5adc3e432c72cc80ea3242821f3aaabd9f630"

curl https://api.modbuscloud.com/v1/devices/ecc5e4e5-da58-4678-92af-d72b09c2b937/registers \
  -H "Authorization: Bearer mlk_72718174d83aa7fa5238c5eb8df5adc3e432c72cc80ea3242821f3aaabd9f630"
```

Auch die Schaltflächen **Ausprobieren** auf dieser Seite sind bereits mit dem Sandbox-Schlüssel ausgefüllt.

## Begriffe

| Begriff | Bedeutung |
|---|---|
| Gateway | Das ModbusCloud Gateway vor Ort. In den API-Pfaden heißt ein Gateway `device`, zum Beispiel `/devices/{id}`. |
| Modbus-Gerät | Eine Komponente, die das Gateway über Modbus RTU oder Modbus TCP ausliest, etwa ein Klimacomputer, ein Stromzähler oder eine Wärmepumpe. Ein Gateway kann viele davon auslesen. |
| Register | Ein einzelner Wert eines Modbus-Geräts, mit Name, Einheit und Skalierungsfaktor. |
| Messwert | Ein gespeicherter Wert eines Registers zu einem bestimmten Zeitpunkt. |
| Alarm | Wird ausgelöst, wenn eine Regel erfüllt ist, zum Beispiel ein Wert über einem Grenzwert oder ein Gateway, das offline geht. |

**Werte.** `value` und `latest_value` sind in physikalischen Einheiten angegeben, also mit angewendetem Skalierungsfaktor, genau wie im Portal. `raw_value` ist die Zahl, wie sie aus dem Register gelesen wurde.

**Verlauf.** Standardmäßig enthält der Verlauf einen Wert pro Register alle fünf Minuten und höchstens einen pro Minute. Das hängt davon ab, wie oft das Gateway ausliest, und das stellen Sie im Portal ein. Messwerte werden standardmäßig 12 Monate aufbewahrt. Live-Werte im Portal können häufiger aktualisiert werden.

**Zeit.** Alle Zeitstempel sind ISO 8601 in UTC.

## Authentifizierung

Senden Sie den Schlüssel bei jeder Anfrage als Bearer-Token.

```
Authorization: Bearer mlk_...
```

Eigentümer und Administratoren erstellen Schlüssel im Portal unter **Einstellungen, API-Schlüssel**. Ein Schlüssel wird nur einmal angezeigt, speichern Sie ihn also sofort. Jeder Schlüssel gehört zu genau einer Organisation und hat Scopes.

| Scope | Gewährt Zugriff auf |
|---|---|
| `devices:read` | Gateways und ihre Modbus-Geräte |
| `registers:read` | Register, aktuelle Werte und Messwertverlauf |
| `alerts:read` | Alarme |

Schlüssel können ablaufen und lassen sich jederzeit im Portal widerrufen.

Das Schreiben in Register ist für jedes Gateway ausgeschaltet, bis wir es freischalten. Beantragen Sie es pro Gateway im Tab Steuerung im Portal. Bis dahin wird ein Schreibzugriff auf dieses Gateway mit 403 `write_not_enabled` beantwortet, unabhängig von den Scopes des Schlüssels.

## Paginierung

Gateways und Alarme verwenden `limit` (1 bis 100, Standard 50) und `offset` und liefern `meta.total`.

Register verwenden `limit` (1 bis 1000, Standard 1000) und `offset` und liefern `meta.total`. Ein Gateway mit einem großen BACnet-Gerät kann mehr als 1000 Register haben. Fragen Sie dann mit `offset` die nächste Seite ab, bis Sie `meta.total` Zeilen haben.

Messwerte verwenden einen Cursor, weil der Verlauf groß ist. Jede Seite liefert `meta.has_more` und `meta.next_cursor`. Übergeben Sie `next_cursor` als `cursor`, um die nächste Seite zu erhalten, mit ansonsten denselben Parametern. Zeilen werden nie übersprungen oder doppelt geliefert, auch nicht, während neue Messwerte eintreffen.

```bash
# first page
curl "https://api.modbuscloud.com/v1/devices/{id}/readings?since=2026-10-01T00:00:00Z&until=2026-10-02T00:00:00Z&order=asc&limit=1000" \
  -H "Authorization: Bearer mlk_..."

# next page
curl "https://api.modbuscloud.com/v1/devices/{id}/readings?since=2026-10-01T00:00:00Z&until=2026-10-02T00:00:00Z&order=asc&limit=1000&cursor=MjAyNi0x..." \
  -H "Authorization: Bearer mlk_..."
```

Um eine Kopie des Verlaufs in Ihrer eigenen Datenbank zu führen, fragen Sie mit `order=asc` ab, setzen `since` auf den zuletzt gespeicherten Zeitstempel und folgen `next_cursor`, bis `has_more` false ist.

## Fehler

Fehler verwenden das Problem-Details-Format nach RFC 9457, mit dem Content-Type `application/problem+json`.

```json
{
  "type": "https://docs.modbuscloud.com/errors#insufficient_scope",
  "title": "Insufficient scope",
  "status": 403,
  "detail": "This endpoint requires the 'alerts:read' scope.",
  "code": "insufficient_scope",
  "request_id": "req_4f1c0d2e9a8b4c7d8e6f5a4b3c2d1e0f"
}
```

Werten Sie `code` aus, denn dieser Wert bleibt stabil. `detail` ist für Menschen gedacht und kann sich ändern.

| Status | code | Wann |
|---|---|---|
| 400 | `invalid_parameter` | Ein Query-Parameter fehlt, ist fehlerhaft oder liegt außerhalb des zulässigen Bereichs |
| 400 | `bad_request` | Der Request Body ist kein gültiges JSON, oder ein Feld darin fehlt oder ist ungültig |
| 401 | `missing_api_key` | Kein Header `Authorization: Bearer` |
| 401 | `invalid_api_key` | Der Schlüssel existiert nicht |
| 401 | `api_key_revoked` | Der Schlüssel wurde im Portal widerrufen |
| 401 | `api_key_expired` | Der Schlüssel ist abgelaufen |
| 403 | `insufficient_scope` | Dem Schlüssel fehlt der Scope, den dieser Endpoint benötigt |
| 403 | `write_not_enabled` | Schreiben ist für dieses Gateway nicht freigeschaltet |
| 404 | `not_found` | Das Gateway, das Register oder der Alarm gehört nicht zu Ihrer Organisation |
| 422 | `bacnet_write_unsupported` | Das Register ist ein BACnet-Datenpunkt, und Schreiben auf BACnet-Datenpunkte wird noch nicht unterstützt |
| 429 | `rate_limited` | Mehr als 100 Anfragen in der aktuellen Minute, oder das Schreiblimit des Gateways oder der Organisation. `Retry-After` gibt an, wie viele Sekunden Sie warten müssen |
| 500 | `internal_error` | Auf unserer Seite ist etwas schiefgelaufen |
| 502 | `publish_failed` | Der Schreibbefehl konnte nicht an das Gateway gesendet werden |
| 503 | `gateway_offline` | Das Gateway ist offline, der Schreibbefehl wurde nicht gesendet |

Jede Antwort enthält einen Header `X-Request-Id`. Nennen Sie ihn, wenn Sie uns wegen einer Anfrage kontaktieren.

## Sprache

Fehlermeldungen und Textfelder folgen `Accept-Language` (`en`, `nl`, `de`), Standard ist Englisch. Die Antwort enthält `Content-Language`.

## Rate Limits

Jeder Schlüssel darf 100 Anfragen pro Minute stellen. Das Zeitfenster beginnt zu jeder vollen Minute neu. Der gemeinsame Sandbox-Schlüssel wird pro Besucher gezählt, mit jeweils 60 Anfragen pro Minute. Jede Antwort zeigt Ihnen, wo Sie stehen.

| Header | Bedeutung |
|---|---|
| `X-RateLimit-Limit` | Erlaubte Anfragen pro Minute |
| `X-RateLimit-Remaining` | Verbleibende Anfragen in der aktuellen Minute |
| `X-RateLimit-Reset` | Sekunden bis zum Neustart des Zeitfensters |
| `Retry-After` | Nur bei 429, Sekunden bis zum nächsten Versuch |

Wer die Register von 50 Gateways einmal pro Minute abfragt, verbraucht die Hälfte des Budgets. Nutzen Sie Webhooks für Ereignisse, statt Alarme regelmäßig abzufragen.

## Webhooks

Webhooks senden einen HTTP-POST an Ihren Endpoint, wenn etwas passiert. Eigentümer und Administratoren fügen Endpoints im Portal unter **Einstellungen, Webhooks** hinzu, wählen die Ereignisse aus und kopieren das Signing Secret. Die Ereignisse und ihre Payloads finden Sie unter **Webhooks** im Menü dieser Seite.

Jede Zustellung hat denselben Umschlag.

```json
{
  "id": "msg_2f8c1d0a9b7e4c3d8e1f0a2b3c4d5e6f",
  "type": "alert.triggered",
  "timestamp": "2026-10-05T12:00:00.000Z",
  "data": { "alert_id": "06d56ed5-6ddf-4ffd-9dc9-12d6ad5d51cf", "device_id": "...", "severity": "warning", "value": 67.2 }
}
```

### Signatur prüfen

Zustellungen werden nach der Spezifikation von [Standard Webhooks](https://www.standardwebhooks.com) signiert, Sie können deren Bibliotheken also direkt verwenden.

| Header | Inhalt |
|---|---|
| `webhook-id` | Eindeutige ID der Nachricht. Bei jedem erneuten Versuch gleich. |
| `webhook-timestamp` | Unix-Zeit in Sekunden dieses Versuchs |
| `webhook-signature` | `v1,` gefolgt von der Base64-kodierten HMAC-SHA256-Signatur |
| `X-ModbusCloud-Event` | Der Ereignistyp, identisch mit `type` im Body |

Node.js mit `npm install standardwebhooks`:

```js
import { Webhook } from 'standardwebhooks'

const wh = new Webhook(process.env.MODBUSCLOUD_WEBHOOK_SECRET) // whsec_...

app.post('/webhooks/modbuscloud', express.raw({ type: 'application/json' }), (req, res) => {
  let event
  try {
    event = wh.verify(req.body.toString('utf8'), req.headers)
  } catch {
    return res.status(400).end()
  }
  res.status(200).end()      // answer first
  queueForProcessing(event)  // then do the work
})
```

Python mit `pip install standardwebhooks`:

```python
from standardwebhooks.webhooks import Webhook

wh = Webhook(os.environ["MODBUSCLOUD_WEBHOOK_SECRET"])  # whsec_...

@app.post("/webhooks/modbuscloud")
def receive():
    try:
        event = wh.verify(request.get_data(as_text=True), dict(request.headers))
    except Exception:
        return "", 400
    queue_for_processing(event)
    return "", 200
```

In jeder anderen Sprache berechnen Sie HMAC-SHA256 über `{webhook-id}.{webhook-timestamp}.{raw body}` mit dem Secret als Schlüssel. Der Schlüssel ist der Teil nach `whsec_`, Base64-dekodiert. Kodieren Sie das Ergebnis in Base64 und vergleichen Sie es in konstanter Zeit mit dem Wert nach `v1,`. Lehnen Sie Nachrichten ab, deren Zeitstempel mehr als fünf Minuten von Ihrer Uhr abweicht.

Prüfen Sie immer gegen den Raw Body, so wie er empfangen wurde. Wenn Sie das JSON vorher parsen und neu serialisieren, ändern sich die Bytes und die Signatur stimmt nicht mehr.

### Zustellung und Wiederholungen

- Antworten Sie innerhalb von 10 Sekunden mit einem beliebigen 2xx-Status. Verarbeiten Sie das Ereignis erst, nachdem Sie geantwortet haben.
- Eine Zustellung schlägt fehl bei einem Status außerhalb von 2xx, einem Timeout oder einer Weiterleitung. Weiterleitungen werden nicht verfolgt.
- Fehlgeschlagene Zustellungen werden nach 30 Sekunden, 2 Minuten, 10 Minuten, 1 Stunde und 6 Stunden wiederholt. Das sind sechs Versuche in etwas mehr als sieben Stunden.
- Wiederholungen tragen dieselbe `webhook-id`. Speichern Sie die verarbeiteten IDs und überspringen Sie Duplikate.
- Die Reihenfolge der Zustellungen ist nicht garantiert. Bestimmen Sie anhand von `timestamp` und dem `status` des Alarms, was aktuell ist.
- Nach zehn Zustellungen in Folge, bei denen jeder Versuch fehlschlug, wird der Endpoint pausiert. Schalten Sie ihn im Portal wieder ein.
- Endpoints müssen über das öffentliche Internet per http oder https erreichbar sein. Verwenden Sie https.

## Versionierung

Dies ist Version 1. Wir ergänzen Endpoints, Felder und Ereignisse ohne Ankündigung, ignorieren Sie also Felder, die Sie nicht kennen. Änderungen, die eine Integration brechen könnten, erscheinen als neue Version und werden vorab angekündigt.

## Support

Fragen, oder funktioniert etwas nicht? Schreiben Sie an [info@modbuscloud.com](mailto:info@modbuscloud.com) und geben Sie die `X-Request-Id` an.

## Endpoints

### Schlüssel

Prüfen Sie den Schlüssel, den Sie verwenden.

#### API-Schlüssel prüfen

`GET /introspect`

Liefert den Namen des Schlüssels, seine Scopes und die Organisation, zu der er gehört. Jeder gültige Schlüssel darf diesen Endpoint aufrufen.

| Status | Bedeutung |
|---|---|
| 200 | Der Schlüssel und seine Organisation. |
| 401 | Ungültiger API-Schlüssel |
| 403 | Unzureichender Scope |
| 429 | Rate Limit überschritten |
| 500 | Interner Serverfehler |

```bash
curl "https://api.modbuscloud.com/v1/introspect" \
  -H "Authorization: Bearer mlk_72718174d83aa7fa5238c5eb8df5adc3e432c72cc80ea3242821f3aaabd9f630"
```

### Gateways

Gateways und die Modbus-Geräte dahinter. In den Pfaden heißt ein Gateway `device`.

#### Gateways auflisten

`GET /devices`

Alle Gateways Ihrer Organisation, zuletzt gesehene zuerst. Scope `devices:read`.

| Parameter | In | Typ | Pflicht | Beschreibung |
|---|---|---|---|---|
| `status` | query | string: `online`, `offline`, `pending`, `error` | nein | Nur Gateways mit diesem Status. |
| `limit` | query | integer, Standard `50` | nein | Seitengröße, 1 bis 100. |
| `offset` | query | integer, Standard `0` | nein | Anzahl der zu überspringenden Zeilen. |

| Status | Bedeutung |
|---|---|
| 200 | Eine Seite mit Gateways. |
| 401 | Ungültiger API-Schlüssel |
| 403 | Unzureichender Scope |
| 429 | Rate Limit überschritten |
| 500 | Interner Serverfehler |

```bash
curl "https://api.modbuscloud.com/v1/devices" \
  -H "Authorization: Bearer mlk_72718174d83aa7fa5238c5eb8df5adc3e432c72cc80ea3242821f3aaabd9f630"
```

#### Gateway abrufen

`GET /devices/{id}`

Ein Gateway mit seinem Kunden und den Modbus-Geräten, die es ausliest. Scope `devices:read`.

| Parameter | In | Typ | Pflicht | Beschreibung |
|---|---|---|---|---|
| `id` | path | string (uuid) | ja | ID des Gateways, aus `GET /devices`. |

| Status | Bedeutung |
|---|---|
| 200 | Das Gateway. |
| 401 | Ungültiger API-Schlüssel |
| 403 | Unzureichender Scope |
| 404 | Nicht gefunden |
| 429 | Rate Limit überschritten |
| 500 | Interner Serverfehler |

```bash
curl "https://api.modbuscloud.com/v1/devices/ecc5e4e5-da58-4678-92af-d72b09c2b937" \
  -H "Authorization: Bearer mlk_72718174d83aa7fa5238c5eb8df5adc3e432c72cc80ea3242821f3aaabd9f630"
```

### Register

Register eines Gateways mit ihren aktuellen Werten.

#### Register mit aktuellen Werten auflisten

`GET /devices/{id}/registers`

Die Register des Gateways mit ihrem aktuellen Wert, seitenweise sortiert nach Anzeigereihenfolge und Adresse. Fragen Sie diesen Endpoint regelmäßig ab, um den aktuellen Zustand zu erhalten. Auch BACnet-Datenpunkte sind Register, mit ausgefüllten `bacnet_*`-Feldern. Scope `registers:read`.

| Parameter | In | Typ | Pflicht | Beschreibung |
|---|---|---|---|---|
| `id` | path | string (uuid) | ja | ID des Gateways, aus `GET /devices`. |
| `modbus_device_id` | query | string (uuid) | nein | Nur Register dieses Modbus- oder BACnet-Geräts. |
| `limit` | query | integer, Standard `1000` | nein | Seitengröße, 1 bis 1000. |
| `offset` | query | integer, Standard `0` | nein | Anzahl der zu überspringenden Zeilen. |

| Status | Bedeutung |
|---|---|
| 200 | Eine Seite mit Registern des Gateways. |
| 401 | Ungültiger API-Schlüssel |
| 403 | Unzureichender Scope |
| 404 | Nicht gefunden |
| 429 | Rate Limit überschritten |
| 500 | Interner Serverfehler |

```bash
curl "https://api.modbuscloud.com/v1/devices/ecc5e4e5-da58-4678-92af-d72b09c2b937/registers" \
  -H "Authorization: Bearer mlk_72718174d83aa7fa5238c5eb8df5adc3e432c72cc80ea3242821f3aaabd9f630"
```

### Messwerte

Messwertverlauf eines Gateways, seitenweise mit einem Cursor.

#### Messwerte auflisten

`GET /devices/{id}/readings`

Messwertverlauf des Gateways in einem Zeitfenster, neueste zuerst, außer bei `order=asc`. Das Zeitfenster reicht von `since` (inklusive) bis `until` (exklusive) und umfasst standardmäßig die letzten 24 Stunden. Es darf höchstens 7 Tage umfassen, oder 366 Tage, wenn Sie genau eine `register_id` übergeben. Folgen Sie `meta.next_cursor` für die nächste Seite. Scope `registers:read`.

| Parameter | In | Typ | Pflicht | Beschreibung |
|---|---|---|---|---|
| `id` | path | string (uuid) | ja | ID des Gateways, aus `GET /devices`. |
| `register_id` | query | string | nein | Eine Register-ID oder mehrere, durch Kommas getrennt. |
| `since` | query | string (date-time) | nein | Beginn des Zeitfensters, inklusive. Standard `until` minus 24 Stunden. |
| `until` | query | string (date-time) | nein | Ende des Zeitfensters, exklusive. Standard jetzt. |
| `order` | query | string: `desc`, `asc`, Standard `desc` | nein | Sortierung nach Zeit. |
| `limit` | query | integer, Standard `100` | nein | Seitengröße, 1 bis 1000. |
| `cursor` | query | string | nein | `meta.next_cursor` der vorherigen Seite. |

| Status | Bedeutung |
|---|---|
| 200 | Eine Seite mit Messwerten. |
| 400 | Ungültiger Parameter |
| 401 | Ungültiger API-Schlüssel |
| 403 | Unzureichender Scope |
| 404 | Nicht gefunden |
| 429 | Rate Limit überschritten |
| 500 | Interner Serverfehler |

```bash
curl "https://api.modbuscloud.com/v1/devices/ecc5e4e5-da58-4678-92af-d72b09c2b937/readings" \
  -H "Authorization: Bearer mlk_72718174d83aa7fa5238c5eb8df5adc3e432c72cc80ea3242821f3aaabd9f630"
```

### Alarme

Alarme Ihrer Organisation.

#### Alarme auflisten

`GET /alerts`

Alarme Ihrer Organisation, zuletzt ausgelöste zuerst. Scope `alerts:read`.

| Parameter | In | Typ | Pflicht | Beschreibung |
|---|---|---|---|---|
| `status` | query | string: `active`, `returned`, `acknowledged`, `resolved` | nein | Nur Alarme mit diesem Status. |
| `severity` | query | string: `critical`, `warning`, `info` | nein | Nur Alarme mit diesem Schweregrad. |
| `device_id` | query | string (uuid) | nein | Nur Alarme dieses Gateways. |
| `limit` | query | integer, Standard `50` | nein | Seitengröße, 1 bis 100. |
| `offset` | query | integer, Standard `0` | nein | Anzahl der zu überspringenden Zeilen. |

| Status | Bedeutung |
|---|---|
| 200 | Eine Seite mit Alarmen. |
| 401 | Ungültiger API-Schlüssel |
| 403 | Unzureichender Scope |
| 429 | Rate Limit überschritten |
| 500 | Interner Serverfehler |

```bash
curl "https://api.modbuscloud.com/v1/alerts" \
  -H "Authorization: Bearer mlk_72718174d83aa7fa5238c5eb8df5adc3e432c72cc80ea3242821f3aaabd9f630"
```

## Webhook-Ereignisse

Jedes Ereignis ist ein POST an Ihren Endpoint, mit dem Umschlag und der Signatur, die oben unter Webhooks beschrieben sind.

### device.online

Ein Gateway meldet sich wieder, auch wenn es zurückkommt, nachdem es als offline markiert war.

```json
{
  "id": "msg_2f8c1d0a9b7e4c3d8e1f0a2b3c4d5e6f",
  "type": "device.online",
  "timestamp": "2026-10-05T12:00:00.000Z",
  "data": {
    "device_id": "ecc5e4e5-da58-4678-92af-d72b09c2b937",
    "serial": "MCG-9V63A8M1",
    "status": "online",
    "previous_status": "offline",
    "last_seen": "2026-10-05T12:00:00.000Z"
  }
}
```

### device.offline

Ein Gateway meldet sich nicht mehr, weil die Verbindung getrennt wurde oder weil es länger still war als sein Heartbeat-Intervall.

```json
{
  "id": "msg_2f8c1d0a9b7e4c3d8e1f0a2b3c4d5e6f",
  "type": "device.offline",
  "timestamp": "2026-10-05T12:00:00.000Z",
  "data": {
    "device_id": "ecc5e4e5-da58-4678-92af-d72b09c2b937",
    "serial": "MCG-9V63A8M1",
    "status": "offline",
    "previous_status": "online",
    "last_seen": "2026-10-05T11:56:30.000Z"
  }
}
```

### alert.triggered

Eine Regel wurde erfüllt und ein Alarm geöffnet, oder ein offener Alarm wurde erneut ausgelöst. Bei Offline-Alarmen ist `condition` gleich `offline` und die Wertfelder fehlen.

```json
{
  "id": "msg_2f8c1d0a9b7e4c3d8e1f0a2b3c4d5e6f",
  "type": "alert.triggered",
  "timestamp": "2026-10-05T12:00:00.000Z",
  "data": {
    "alert_id": "06d56ed5-6ddf-4ffd-9dc9-12d6ad5d51cf",
    "rule_id": "bacb8015-2c7c-49dc-bbd9-7ca2da90b6de",
    "rule_name": "Sludge temperature too high",
    "device_id": "ecc5e4e5-da58-4678-92af-d72b09c2b937",
    "severity": "warning",
    "value": 45.1,
    "threshold": 45,
    "condition": "gt",
    "message": "Sludge temperature too high: 45.1 C",
    "source": "rule",
    "register_id": "a8607f2a-6979-4aa4-96a9-ffb5f1ab49b1",
    "modbus_device_id": "d82b9a58-92b0-4653-b869-19fe9d6c2f24"
  }
}
```

### alert.returned

Der Wert liegt wieder innerhalb des Grenzwerts, oder das Gateway ist wieder online. Der Alarm bleibt offen, bis ihn jemand löst.

```json
{
  "id": "msg_2f8c1d0a9b7e4c3d8e1f0a2b3c4d5e6f",
  "type": "alert.returned",
  "timestamp": "2026-10-05T12:00:00.000Z",
  "data": {
    "alert_id": "06d56ed5-6ddf-4ffd-9dc9-12d6ad5d51cf",
    "rule_id": "bacb8015-2c7c-49dc-bbd9-7ca2da90b6de",
    "rule_name": "Sludge temperature too high",
    "device_id": "ecc5e4e5-da58-4678-92af-d72b09c2b937",
    "severity": "warning",
    "value": 43.8,
    "source": "rule"
  }
}
```

### alert.acknowledged

Jemand hat den Alarm im Portal bestätigt.

```json
{
  "id": "msg_2f8c1d0a9b7e4c3d8e1f0a2b3c4d5e6f",
  "type": "alert.acknowledged",
  "timestamp": "2026-10-05T12:00:00.000Z",
  "data": {
    "alert_id": "06d56ed5-6ddf-4ffd-9dc9-12d6ad5d51cf",
    "device_id": "ecc5e4e5-da58-4678-92af-d72b09c2b937",
    "rule_id": "bacb8015-2c7c-49dc-bbd9-7ca2da90b6de",
    "severity": "warning",
    "message": "Sludge temperature too high: 45.1 C",
    "status": "acknowledged",
    "value": 45.1,
    "acknowledged_at": "2026-10-05T12:04:10.000Z",
    "resolved_at": null,
    "note": "Checking the heat exchanger"
  }
}
```

### alert.resolved

Der Alarm wurde geschlossen.

```json
{
  "id": "msg_2f8c1d0a9b7e4c3d8e1f0a2b3c4d5e6f",
  "type": "alert.resolved",
  "timestamp": "2026-10-05T12:00:00.000Z",
  "data": {
    "alert_id": "06d56ed5-6ddf-4ffd-9dc9-12d6ad5d51cf",
    "device_id": "ecc5e4e5-da58-4678-92af-d72b09c2b937",
    "rule_id": "bacb8015-2c7c-49dc-bbd9-7ca2da90b6de",
    "severity": "warning",
    "message": "Sludge temperature too high: 45.1 C",
    "status": "resolved",
    "value": 45.1,
    "acknowledged_at": "2026-10-05T12:04:10.000Z",
    "resolved_at": "2026-10-05T13:30:00.000Z",
    "note": "Valve replaced"
  }
}
```

### automation.triggered

Eine Automatisierung mit einer Webhook-Aktion wurde ausgeführt.

```json
{
  "id": "msg_2f8c1d0a9b7e4c3d8e1f0a2b3c4d5e6f",
  "type": "automation.triggered",
  "timestamp": "2026-10-05T12:00:00.000Z",
  "data": {
    "rule_id": "9b1d2c3e-4f50-4a61-8b72-9c83d4e5f6a7",
    "rule_name": "Notify ERP on high load",
    "actions": [
      {
        "type": "webhook"
      }
    ]
  }
}
```

## Schemas

### Problem

Fehler im Problem-Details-Format nach RFC 9457.

| Feld | Typ | Beschreibung |
|---|---|---|
| `type` (Pflicht) | string (uri) |  |
| `title` (Pflicht) | string |  |
| `status` (Pflicht) | integer |  |
| `detail` | string |  |
| `code` (Pflicht) | string: `invalid_parameter`, `bad_request`, `missing_api_key`, `invalid_api_key`, `api_key_revoked`, `api_key_expired`, `insufficient_scope`, `write_not_enabled`, `bacnet_write_unsupported`, `not_found`, `conflict`, `rate_limited`, `internal_error`, `publish_failed`, `gateway_offline` |  |
| `request_id` (Pflicht) | string |  |

### OffsetMeta

| Feld | Typ | Beschreibung |
|---|---|---|
| `total` | integer |  |
| `limit` | integer |  |
| `offset` | integer |  |

### CursorMeta

| Feld | Typ | Beschreibung |
|---|---|---|
| `since` | string (date-time) |  |
| `until` | string (date-time) |  |
| `order` | string: `asc`, `desc` |  |
| `limit` | integer |  |
| `has_more` | boolean |  |
| `next_cursor` | string, oder null | Als `cursor` für die nächste Seite übergeben. Null auf der letzten Seite. |

### Introspection

| Feld | Typ | Beschreibung |
|---|---|---|
| `key` | object |  |
| `organization` | object |  |
| `stats` | object |  |

### Customer

Der Standort oder Kunde, dem ein Gateway zugeordnet ist.

| Feld | Typ | Beschreibung |
|---|---|---|
| `id` | string (uuid) |  |
| `name` | string |  |
| `address` | string, oder null | Adresse des Standorts. Nur in `GET /devices/{id}`. |
| `city` | string, oder null |  |

### Gateway

| Feld | Typ | Beschreibung |
|---|---|---|
| `id` | string (uuid) |  |
| `serial` | string |  |
| `name` | string |  |
| `status` | string: `online`, `offline`, `pending`, `error` |  |
| `firmware_ver` | string, oder null |  |
| `ip_eth` | string, oder null | Adresse im kabelgebundenen Netzwerk. |
| `ip_wifi` | string, oder null |  |
| `ip_4g` | string, oder null | Adresse im 4G-Netz. |
| `signal_4g` | integer, oder null | Signalstärke in dBm. |
| `last_seen` | string (date-time), oder null |  |
| `created_at` | string (date-time) |  |
| `customer` | Customer |  |

### ModbusDevice

Ein Modbus-Gerät (`rtu`, `tcp`) oder BACnet/IP-Gerät (`bacnet_ip`) hinter dem Gateway.

| Feld | Typ | Beschreibung |
|---|---|---|
| `id` | string (uuid) |  |
| `name` | string, oder null |  |
| `slave_id` | integer | Modbus Unit ID. Bei bacnet_ip ein interner Slot 300..999. |
| `protocol` | string: `rtu`, `tcp`, `bacnet_ip` |  |
| `ip_address` | string, oder null | Für Modbus TCP und BACnet/IP. Hinter einem BACnet-Router die Adresse des Routers. |
| `port` | integer, oder null | Für Modbus TCP und BACnet/IP (Standard 47808). |
| `poll_interval_ms` | integer, oder null |  |
| `bacnet_device_instance` | integer, oder null | BACnet Device Instance, 0 bis 4194302. Nur bei bacnet_ip. |
| `bacnet_network` | integer, oder null | BACnet-Netzwerknummer hinter einem BACnet-Router (1 bis 65534), sonst null. |
| `bacnet_mac` | string, oder null | BACnet-MAC-Adresse hinter diesem Router, hexadezimal in Kleinbuchstaben (MS/TP-Adresse 10 ist `0a`), sonst null. |
| `template` | object, oder null |  |

### GatewayDetail

Alle Felder von Gateway, zusätzlich:

| Feld | Typ | Beschreibung |
|---|---|---|
| `claimed_at` | string (date-time), oder null |  |
| `modbus_devices` | Array von ModbusDevice |  |

### Register

| Feld | Typ | Beschreibung |
|---|---|---|
| `id` | string (uuid) |  |
| `modbus_device_id` | string (uuid) |  |
| `modbus_device_name` | string, oder null |  |
| `name` | string |  |
| `address` | integer | Registeradresse. Bei einem BACnet-Datenpunkt eine interne Nummer, eindeutig auf dem Gateway. |
| `function_code` | integer, oder null | 3 Holding Register, 4 Input Register. Null bei einem BACnet-Datenpunkt. |
| `data_type` | string |  |
| `unit` | string, oder null |  |
| `scale_factor` | number, oder null | value = raw_value × scale_factor |
| `is_writable` | boolean |  |
| `description` | string, oder null |  |
| `bacnet_object_type` | integer, oder null | BACnet-Objekttyp, zum Beispiel 0 analog-input, 3 binary-input, 13 multi-state-input. Null bei Modbus. |
| `bacnet_object_instance` | integer, oder null | BACnet-Objektinstanz. Null bei Modbus. |
| `bacnet_property_id` | integer, oder null | Gelesene BACnet-Property, 85 ist Present_Value. Null bei Modbus. |
| `bacnet_array_index` | integer, oder null | Array-Index dieser Property, oder null für den gesamten Wert. |
| `bacnet_write_priority` | integer, oder null | BACnet-Schreibpriorität. Vorerst immer null, weil BACnet-Datenpunkte nur gelesen werden. |
| `latest_value` | number, oder null | Aktueller Wert in physikalischen Einheiten. |
| `latest_raw_value` | number, oder null | Aktueller Wert, wie er aus dem Register gelesen wurde. |
| `latest_ts` | string (date-time), oder null |  |

### Reading

| Feld | Typ | Beschreibung |
|---|---|---|
| `register_id` | string (uuid) |  |
| `modbus_device_id` | string (uuid), oder null |  |
| `name` | string, oder null |  |
| `unit` | string, oder null |  |
| `value` | number, oder null | In physikalischen Einheiten, mit angewendetem Skalierungsfaktor. |
| `raw_value` | number, oder null | Wie aus dem Register gelesen. |
| `ts` | string (date-time) |  |

### Alert

| Feld | Typ | Beschreibung |
|---|---|---|
| `id` | string (uuid) |  |
| `device_id` | string (uuid), oder null |  |
| `rule_id` | string (uuid), oder null |  |
| `severity` | string: `critical`, `warning`, `info` |  |
| `message` | string, oder null |  |
| `status` | string: `active`, `returned`, `acknowledged`, `resolved` |  |
| `value` | number, oder null |  |
| `created_at` | string (date-time) |  |
| `last_triggered_at` | string (date-time), oder null |  |
| `returned_at` | string (date-time), oder null |  |
| `ack_at` | string (date-time), oder null |  |
| `ack_by` | string (uuid), oder null | ID des Benutzers, der den Alarm bestätigt hat. |
| `ack_note` | string, oder null |  |
| `resolved_at` | string (date-time), oder null |  |
| `resolved_by` | string (uuid), oder null | ID des Benutzers, der den Alarm gelöst hat. |
| `resolve_note` | string, oder null |  |
| `entry_count` | integer | Wie oft der Alarm ausgelöst wurde, während er offen war. |
| `reminder_at` | string (date-time), oder null | Zeitpunkt, zu dem eine im Portal gesetzte Erinnerung fällig ist. Null ohne Erinnerung. |
| `reminder_sent` | boolean, oder null | Ob diese Erinnerung bereits gesendet wurde. |

### DeviceStatusEvent

| Feld | Typ | Beschreibung |
|---|---|---|
| `device_id` | string (uuid) |  |
| `serial` | string |  |
| `status` | string: `online`, `offline` |  |
| `previous_status` | string, oder null |  |
| `last_seen` | string (date-time), oder null | Letzte Meldung des Gateways. |

### AlertTriggeredEvent

| Feld | Typ | Beschreibung |
|---|---|---|
| `alert_id` | string (uuid) |  |
| `rule_id` | string (uuid) |  |
| `rule_name` | string |  |
| `device_id` | string (uuid) |  |
| `severity` | string: `critical`, `warning`, `info` |  |
| `value` | number |  |
| `threshold` | number |  |
| `condition` | string | Vergleich der Regel, oder `offline`. |
| `message` | string |  |
| `source` | string: `rule`, `detector` |  |
| `register_id` | string (uuid), oder null |  |
| `modbus_device_id` | string (uuid), oder null |  |

### AlertReturnedEvent

| Feld | Typ | Beschreibung |
|---|---|---|
| `alert_id` | string (uuid) |  |
| `rule_id` | string (uuid) |  |
| `rule_name` | string |  |
| `device_id` | string (uuid) |  |
| `severity` | string |  |
| `value` | number |  |
| `condition` | string | `offline`, wenn das Gateway wieder online ist. |
| `source` | string: `rule`, `detector` |  |

### AlertStatusEvent

| Feld | Typ | Beschreibung |
|---|---|---|
| `alert_id` | string (uuid) |  |
| `device_id` | string (uuid), oder null |  |
| `rule_id` | string (uuid), oder null |  |
| `severity` | string |  |
| `message` | string |  |
| `status` | string: `acknowledged`, `resolved` |  |
| `value` | number, oder null |  |
| `acknowledged_at` | string (date-time), oder null |  |
| `resolved_at` | string (date-time), oder null |  |
| `note` | string, oder null |  |

### AutomationEvent

| Feld | Typ | Beschreibung |
|---|---|---|
| `rule_id` | string (uuid) |  |
| `rule_name` | string |  |
| `actions` | Array von object |  |
