{"openapi":"3.1.0","info":{"title":"ModbusCloud API","version":"1.0.0","summary":"Lesen Sie Daten zu Gateways, Registern, Messwerten und Alarmen und empfangen Sie Ereignisse als Webhooks.","description":"\nDie 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.\n\n## Schnellstart\n\nJede 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.\n\n```\nmlk_72718174d83aa7fa5238c5eb8df5adc3e432c72cc80ea3242821f3aaabd9f630\n```\n\nPrüfen Sie, ob der Schlüssel funktioniert:\n\n```bash\ncurl https://api.modbuscloud.com/v1/introspect \\\n  -H \"Authorization: Bearer mlk_72718174d83aa7fa5238c5eb8df5adc3e432c72cc80ea3242821f3aaabd9f630\"\n```\n\nRufen Sie die Gateways ab und danach die aktuellen Werte eines Gateways:\n\n```bash\ncurl https://api.modbuscloud.com/v1/devices \\\n  -H \"Authorization: Bearer mlk_72718174d83aa7fa5238c5eb8df5adc3e432c72cc80ea3242821f3aaabd9f630\"\n\ncurl https://api.modbuscloud.com/v1/devices/ecc5e4e5-da58-4678-92af-d72b09c2b937/registers \\\n  -H \"Authorization: Bearer mlk_72718174d83aa7fa5238c5eb8df5adc3e432c72cc80ea3242821f3aaabd9f630\"\n```\n\nAuch die Schaltflächen **Ausprobieren** auf dieser Seite sind bereits mit dem Sandbox-Schlüssel ausgefüllt.\n\n## Begriffe\n\n| Begriff | Bedeutung |\n|---|---|\n| Gateway | Das ModbusCloud Gateway vor Ort. In den API-Pfaden heißt ein Gateway `device`, zum Beispiel `/devices/{id}`. |\n| 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. |\n| Register | Ein einzelner Wert eines Modbus-Geräts, mit Name, Einheit und Skalierungsfaktor. |\n| Messwert | Ein gespeicherter Wert eines Registers zu einem bestimmten Zeitpunkt. |\n| Alarm | Wird ausgelöst, wenn eine Regel erfüllt ist, zum Beispiel ein Wert über einem Grenzwert oder ein Gateway, das offline geht. |\n\n**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.\n\n**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.\n\n**Zeit.** Alle Zeitstempel sind ISO 8601 in UTC.\n\n## Authentifizierung\n\nSenden Sie den Schlüssel bei jeder Anfrage als Bearer-Token.\n\n```\nAuthorization: Bearer mlk_...\n```\n\nEigentü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.\n\n| Scope | Gewährt Zugriff auf |\n|---|---|\n| `devices:read` | Gateways und ihre Modbus-Geräte |\n| `registers:read` | Register, aktuelle Werte und Messwertverlauf |\n| `alerts:read` | Alarme |\n\nSchlüssel können ablaufen und lassen sich jederzeit im Portal widerrufen.\n\nDas 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.\n\n## Paginierung\n\nGateways und Alarme verwenden `limit` (1 bis 100, Standard 50) und `offset` und liefern `meta.total`.\n\nRegister 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.\n\nMesswerte 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.\n\n```bash\n# first page\ncurl \"https://api.modbuscloud.com/v1/devices/{id}/readings?since=2026-10-01T00:00:00Z&until=2026-10-02T00:00:00Z&order=asc&limit=1000\" \\\n  -H \"Authorization: Bearer mlk_...\"\n\n# next page\ncurl \"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...\" \\\n  -H \"Authorization: Bearer mlk_...\"\n```\n\nUm 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.\n\n## Fehler\n\nFehler verwenden das Problem-Details-Format nach RFC 9457, mit dem Content-Type `application/problem+json`.\n\n```json\n{\n  \"type\": \"https://docs.modbuscloud.com/errors#insufficient_scope\",\n  \"title\": \"Insufficient scope\",\n  \"status\": 403,\n  \"detail\": \"This endpoint requires the 'alerts:read' scope.\",\n  \"code\": \"insufficient_scope\",\n  \"request_id\": \"req_4f1c0d2e9a8b4c7d8e6f5a4b3c2d1e0f\"\n}\n```\n\nWerten Sie `code` aus, denn dieser Wert bleibt stabil. `detail` ist für Menschen gedacht und kann sich ändern.\n\n| Status | code | Wann |\n|---|---|---|\n| 400 | `invalid_parameter` | Ein Query-Parameter fehlt, ist fehlerhaft oder liegt außerhalb des zulässigen Bereichs |\n| 400 | `bad_request` | Der Request Body ist kein gültiges JSON, oder ein Feld darin fehlt oder ist ungültig |\n| 401 | `missing_api_key` | Kein Header `Authorization: Bearer` |\n| 401 | `invalid_api_key` | Der Schlüssel existiert nicht |\n| 401 | `api_key_revoked` | Der Schlüssel wurde im Portal widerrufen |\n| 401 | `api_key_expired` | Der Schlüssel ist abgelaufen |\n| 403 | `insufficient_scope` | Dem Schlüssel fehlt der Scope, den dieser Endpoint benötigt |\n| 403 | `write_not_enabled` | Schreiben ist für dieses Gateway nicht freigeschaltet |\n| 404 | `not_found` | Das Gateway, das Register oder der Alarm gehört nicht zu Ihrer Organisation |\n| 422 | `bacnet_write_unsupported` | Das Register ist ein BACnet-Datenpunkt, und Schreiben auf BACnet-Datenpunkte wird noch nicht unterstützt |\n| 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 |\n| 500 | `internal_error` | Auf unserer Seite ist etwas schiefgelaufen |\n| 502 | `publish_failed` | Der Schreibbefehl konnte nicht an das Gateway gesendet werden |\n| 503 | `gateway_offline` | Das Gateway ist offline, der Schreibbefehl wurde nicht gesendet |\n\nJede Antwort enthält einen Header `X-Request-Id`. Nennen Sie ihn, wenn Sie uns wegen einer Anfrage kontaktieren.\n\n## Sprache\n\nFehlermeldungen und Textfelder folgen `Accept-Language` (`en`, `nl`, `de`), Standard ist Englisch. Die Antwort enthält `Content-Language`.\n\n## Rate Limits\n\nJeder 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.\n\n| Header | Bedeutung |\n|---|---|\n| `X-RateLimit-Limit` | Erlaubte Anfragen pro Minute |\n| `X-RateLimit-Remaining` | Verbleibende Anfragen in der aktuellen Minute |\n| `X-RateLimit-Reset` | Sekunden bis zum Neustart des Zeitfensters |\n| `Retry-After` | Nur bei 429, Sekunden bis zum nächsten Versuch |\n\nWer 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.\n\n## Webhooks\n\nWebhooks 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.\n\nJede Zustellung hat denselben Umschlag.\n\n```json\n{\n  \"id\": \"msg_2f8c1d0a9b7e4c3d8e1f0a2b3c4d5e6f\",\n  \"type\": \"alert.triggered\",\n  \"timestamp\": \"2026-10-05T12:00:00.000Z\",\n  \"data\": { \"alert_id\": \"06d56ed5-6ddf-4ffd-9dc9-12d6ad5d51cf\", \"device_id\": \"...\", \"severity\": \"warning\", \"value\": 67.2 }\n}\n```\n\n### Signatur prüfen\n\nZustellungen werden nach der Spezifikation von [Standard Webhooks](https://www.standardwebhooks.com) signiert, Sie können deren Bibliotheken also direkt verwenden.\n\n| Header | Inhalt |\n|---|---|\n| `webhook-id` | Eindeutige ID der Nachricht. Bei jedem erneuten Versuch gleich. |\n| `webhook-timestamp` | Unix-Zeit in Sekunden dieses Versuchs |\n| `webhook-signature` | `v1,` gefolgt von der Base64-kodierten HMAC-SHA256-Signatur |\n| `X-ModbusCloud-Event` | Der Ereignistyp, identisch mit `type` im Body |\n\nNode.js mit `npm install standardwebhooks`:\n\n```js\nimport { Webhook } from 'standardwebhooks'\n\nconst wh = new Webhook(process.env.MODBUSCLOUD_WEBHOOK_SECRET) // whsec_...\n\napp.post('/webhooks/modbuscloud', express.raw({ type: 'application/json' }), (req, res) => {\n  let event\n  try {\n    event = wh.verify(req.body.toString('utf8'), req.headers)\n  } catch {\n    return res.status(400).end()\n  }\n  res.status(200).end()      // answer first\n  queueForProcessing(event)  // then do the work\n})\n```\n\nPython mit `pip install standardwebhooks`:\n\n```python\nfrom standardwebhooks.webhooks import Webhook\n\nwh = Webhook(os.environ[\"MODBUSCLOUD_WEBHOOK_SECRET\"])  # whsec_...\n\n@app.post(\"/webhooks/modbuscloud\")\ndef receive():\n    try:\n        event = wh.verify(request.get_data(as_text=True), dict(request.headers))\n    except Exception:\n        return \"\", 400\n    queue_for_processing(event)\n    return \"\", 200\n```\n\nIn 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.\n\nPrü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.\n\n### Zustellung und Wiederholungen\n\n- Antworten Sie innerhalb von 10 Sekunden mit einem beliebigen 2xx-Status. Verarbeiten Sie das Ereignis erst, nachdem Sie geantwortet haben.\n- Eine Zustellung schlägt fehl bei einem Status außerhalb von 2xx, einem Timeout oder einer Weiterleitung. Weiterleitungen werden nicht verfolgt.\n- 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.\n- Wiederholungen tragen dieselbe `webhook-id`. Speichern Sie die verarbeiteten IDs und überspringen Sie Duplikate.\n- Die Reihenfolge der Zustellungen ist nicht garantiert. Bestimmen Sie anhand von `timestamp` und dem `status` des Alarms, was aktuell ist.\n- Nach zehn Zustellungen in Folge, bei denen jeder Versuch fehlschlug, wird der Endpoint pausiert. Schalten Sie ihn im Portal wieder ein.\n- Endpoints müssen über das öffentliche Internet per http oder https erreichbar sein. Verwenden Sie https.\n\n## Versionierung\n\nDies 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.\n\n## Support\n\nFragen, oder funktioniert etwas nicht? Schreiben Sie an [info@modbuscloud.com](mailto:info@modbuscloud.com) und geben Sie die `X-Request-Id` an.\n","contact":{"name":"ModbusCloud","email":"info@modbuscloud.com","url":"https://modbuscloud.com"}},"servers":[{"url":"https://api.modbuscloud.com/v1","description":"Produktion"},{"url":"https://portal.modbuscloud.com/api/v1","description":"Produktion, alternative Adresse"}],"security":[{"bearerAuth":[]}],"tags":[{"name":"Key","x-displayName":"Schlüssel","description":"Prüfen Sie den Schlüssel, den Sie verwenden."},{"name":"Gateways","description":"Gateways und die Modbus-Geräte dahinter. In den Pfaden heißt ein Gateway `device`."},{"name":"Registers","x-displayName":"Register","description":"Register eines Gateways mit ihren aktuellen Werten."},{"name":"Readings","x-displayName":"Messwerte","description":"Messwertverlauf eines Gateways, seitenweise mit einem Cursor."},{"name":"Alerts","x-displayName":"Alarme","description":"Alarme Ihrer Organisation."},{"name":"Webhook events","x-displayName":"Webhook-Ereignisse","description":"Ereignisse, die an Ihren Endpoint gesendet werden. Signatur und Wiederholungen beschreibt der Abschnitt Webhooks in der Einführung."}],"paths":{"/introspect":{"get":{"tags":["Key"],"operationId":"introspect","summary":"API-Schlüssel prüfen","description":"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.","responses":{"200":{"description":"Der Schlüssel und seine Organisation.","headers":{"X-Request-Id":{"description":"ID dieser Anfrage, für den Support.","schema":{"type":"string"}},"X-RateLimit-Limit":{"description":"Erlaubte Anfragen pro Minute.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Verbleibende Anfragen in der aktuellen Minute.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Sekunden bis zum Neustart des Zeitfensters.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Introspection"}}}}}},"401":{"description":"Ungültiger API-Schlüssel","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"example":{"type":"https://docs.modbuscloud.com/errors#invalid_api_key","title":"Invalid API key","status":401,"detail":"This API key does not exist.","code":"invalid_api_key","request_id":"req_4f1c0d2e9a8b4c7d8e6f5a4b3c2d1e0f"}}}},"403":{"description":"Unzureichender Scope","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"example":{"type":"https://docs.modbuscloud.com/errors#insufficient_scope","title":"Insufficient scope","status":403,"detail":"This endpoint requires the 'registers:read' scope.","code":"insufficient_scope","request_id":"req_4f1c0d2e9a8b4c7d8e6f5a4b3c2d1e0f"}}}},"429":{"description":"Rate Limit überschritten","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"example":{"type":"https://docs.modbuscloud.com/errors#rate_limited","title":"Rate limit exceeded","status":429,"detail":"Max 100 requests per minute per key. Retry after 12 seconds.","code":"rate_limited","request_id":"req_4f1c0d2e9a8b4c7d8e6f5a4b3c2d1e0f"}}}},"500":{"description":"Interner Serverfehler","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"example":{"type":"https://docs.modbuscloud.com/errors#internal_error","title":"Internal server error","status":500,"detail":"Something went wrong on our side. Quote the request_id when contacting support.","code":"internal_error","request_id":"req_4f1c0d2e9a8b4c7d8e6f5a4b3c2d1e0f"}}}}}}},"/devices":{"get":{"tags":["Gateways"],"operationId":"listGateways","summary":"Gateways auflisten","description":"Alle Gateways Ihrer Organisation, zuletzt gesehene zuerst. Scope `devices:read`.","parameters":[{"name":"status","in":"query","description":"Nur Gateways mit diesem Status.","schema":{"type":"string","enum":["online","offline","pending","error"]}},{"name":"limit","in":"query","description":"Seitengröße, 1 bis 100.","schema":{"type":"integer","minimum":1,"maximum":100,"default":50}},{"name":"offset","in":"query","description":"Anzahl der zu überspringenden Zeilen.","schema":{"type":"integer","minimum":0,"default":0}}],"responses":{"200":{"description":"Eine Seite mit Gateways.","headers":{"X-Request-Id":{"description":"ID dieser Anfrage, für den Support.","schema":{"type":"string"}},"X-RateLimit-Limit":{"description":"Erlaubte Anfragen pro Minute.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Verbleibende Anfragen in der aktuellen Minute.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Sekunden bis zum Neustart des Zeitfensters.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Gateway"}},"meta":{"$ref":"#/components/schemas/OffsetMeta"}}}}}},"401":{"description":"Ungültiger API-Schlüssel","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"example":{"type":"https://docs.modbuscloud.com/errors#invalid_api_key","title":"Invalid API key","status":401,"detail":"This API key does not exist.","code":"invalid_api_key","request_id":"req_4f1c0d2e9a8b4c7d8e6f5a4b3c2d1e0f"}}}},"403":{"description":"Unzureichender Scope","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"example":{"type":"https://docs.modbuscloud.com/errors#insufficient_scope","title":"Insufficient scope","status":403,"detail":"This endpoint requires the 'registers:read' scope.","code":"insufficient_scope","request_id":"req_4f1c0d2e9a8b4c7d8e6f5a4b3c2d1e0f"}}}},"429":{"description":"Rate Limit überschritten","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"example":{"type":"https://docs.modbuscloud.com/errors#rate_limited","title":"Rate limit exceeded","status":429,"detail":"Max 100 requests per minute per key. Retry after 12 seconds.","code":"rate_limited","request_id":"req_4f1c0d2e9a8b4c7d8e6f5a4b3c2d1e0f"}}}},"500":{"description":"Interner Serverfehler","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"example":{"type":"https://docs.modbuscloud.com/errors#internal_error","title":"Internal server error","status":500,"detail":"Something went wrong on our side. Quote the request_id when contacting support.","code":"internal_error","request_id":"req_4f1c0d2e9a8b4c7d8e6f5a4b3c2d1e0f"}}}}}}},"/devices/{id}":{"get":{"tags":["Gateways"],"operationId":"getGateway","summary":"Gateway abrufen","description":"Ein Gateway mit seinem Kunden und den Modbus-Geräten, die es ausliest. Scope `devices:read`.","parameters":[{"name":"id","in":"path","required":true,"description":"ID des Gateways, aus `GET /devices`.","schema":{"type":"string","format":"uuid","examples":["ecc5e4e5-da58-4678-92af-d72b09c2b937"]},"example":"ecc5e4e5-da58-4678-92af-d72b09c2b937"}],"responses":{"200":{"description":"Das Gateway.","headers":{"X-Request-Id":{"description":"ID dieser Anfrage, für den Support.","schema":{"type":"string"}},"X-RateLimit-Limit":{"description":"Erlaubte Anfragen pro Minute.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Verbleibende Anfragen in der aktuellen Minute.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Sekunden bis zum Neustart des Zeitfensters.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/GatewayDetail"}}}}}},"401":{"description":"Ungültiger API-Schlüssel","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"example":{"type":"https://docs.modbuscloud.com/errors#invalid_api_key","title":"Invalid API key","status":401,"detail":"This API key does not exist.","code":"invalid_api_key","request_id":"req_4f1c0d2e9a8b4c7d8e6f5a4b3c2d1e0f"}}}},"403":{"description":"Unzureichender Scope","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"example":{"type":"https://docs.modbuscloud.com/errors#insufficient_scope","title":"Insufficient scope","status":403,"detail":"This endpoint requires the 'registers:read' scope.","code":"insufficient_scope","request_id":"req_4f1c0d2e9a8b4c7d8e6f5a4b3c2d1e0f"}}}},"404":{"description":"Nicht gefunden","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"example":{"type":"https://docs.modbuscloud.com/errors#not_found","title":"Not found","status":404,"detail":"Gateway not found.","code":"not_found","request_id":"req_4f1c0d2e9a8b4c7d8e6f5a4b3c2d1e0f"}}}},"429":{"description":"Rate Limit überschritten","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"example":{"type":"https://docs.modbuscloud.com/errors#rate_limited","title":"Rate limit exceeded","status":429,"detail":"Max 100 requests per minute per key. Retry after 12 seconds.","code":"rate_limited","request_id":"req_4f1c0d2e9a8b4c7d8e6f5a4b3c2d1e0f"}}}},"500":{"description":"Interner Serverfehler","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"example":{"type":"https://docs.modbuscloud.com/errors#internal_error","title":"Internal server error","status":500,"detail":"Something went wrong on our side. Quote the request_id when contacting support.","code":"internal_error","request_id":"req_4f1c0d2e9a8b4c7d8e6f5a4b3c2d1e0f"}}}}}}},"/devices/{id}/registers":{"get":{"tags":["Registers"],"operationId":"listRegisters","summary":"Register mit aktuellen Werten auflisten","description":"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`.","parameters":[{"name":"id","in":"path","required":true,"description":"ID des Gateways, aus `GET /devices`.","schema":{"type":"string","format":"uuid","examples":["ecc5e4e5-da58-4678-92af-d72b09c2b937"]},"example":"ecc5e4e5-da58-4678-92af-d72b09c2b937"},{"name":"modbus_device_id","in":"query","description":"Nur Register dieses Modbus- oder BACnet-Geräts.","schema":{"type":"string","format":"uuid"}},{"name":"limit","in":"query","description":"Seitengröße, 1 bis 1000.","schema":{"type":"integer","minimum":1,"maximum":1000,"default":1000}},{"name":"offset","in":"query","description":"Anzahl der zu überspringenden Zeilen.","schema":{"type":"integer","minimum":0,"default":0}}],"responses":{"200":{"description":"Eine Seite mit Registern des Gateways.","headers":{"X-Request-Id":{"description":"ID dieser Anfrage, für den Support.","schema":{"type":"string"}},"X-RateLimit-Limit":{"description":"Erlaubte Anfragen pro Minute.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Verbleibende Anfragen in der aktuellen Minute.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Sekunden bis zum Neustart des Zeitfensters.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Register"}},"meta":{"$ref":"#/components/schemas/OffsetMeta"}}}}}},"401":{"description":"Ungültiger API-Schlüssel","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"example":{"type":"https://docs.modbuscloud.com/errors#invalid_api_key","title":"Invalid API key","status":401,"detail":"This API key does not exist.","code":"invalid_api_key","request_id":"req_4f1c0d2e9a8b4c7d8e6f5a4b3c2d1e0f"}}}},"403":{"description":"Unzureichender Scope","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"example":{"type":"https://docs.modbuscloud.com/errors#insufficient_scope","title":"Insufficient scope","status":403,"detail":"This endpoint requires the 'registers:read' scope.","code":"insufficient_scope","request_id":"req_4f1c0d2e9a8b4c7d8e6f5a4b3c2d1e0f"}}}},"404":{"description":"Nicht gefunden","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"example":{"type":"https://docs.modbuscloud.com/errors#not_found","title":"Not found","status":404,"detail":"Gateway not found.","code":"not_found","request_id":"req_4f1c0d2e9a8b4c7d8e6f5a4b3c2d1e0f"}}}},"429":{"description":"Rate Limit überschritten","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"example":{"type":"https://docs.modbuscloud.com/errors#rate_limited","title":"Rate limit exceeded","status":429,"detail":"Max 100 requests per minute per key. Retry after 12 seconds.","code":"rate_limited","request_id":"req_4f1c0d2e9a8b4c7d8e6f5a4b3c2d1e0f"}}}},"500":{"description":"Interner Serverfehler","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"example":{"type":"https://docs.modbuscloud.com/errors#internal_error","title":"Internal server error","status":500,"detail":"Something went wrong on our side. Quote the request_id when contacting support.","code":"internal_error","request_id":"req_4f1c0d2e9a8b4c7d8e6f5a4b3c2d1e0f"}}}}}}},"/devices/{id}/readings":{"get":{"tags":["Readings"],"operationId":"listReadings","summary":"Messwerte auflisten","description":"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`.","parameters":[{"name":"id","in":"path","required":true,"description":"ID des Gateways, aus `GET /devices`.","schema":{"type":"string","format":"uuid","examples":["ecc5e4e5-da58-4678-92af-d72b09c2b937"]},"example":"ecc5e4e5-da58-4678-92af-d72b09c2b937"},{"name":"register_id","in":"query","description":"Eine Register-ID oder mehrere, durch Kommas getrennt.","schema":{"type":"string"}},{"name":"since","in":"query","description":"Beginn des Zeitfensters, inklusive. Standard `until` minus 24 Stunden.","schema":{"type":"string","format":"date-time"}},{"name":"until","in":"query","description":"Ende des Zeitfensters, exklusive. Standard jetzt.","schema":{"type":"string","format":"date-time"}},{"name":"order","in":"query","description":"Sortierung nach Zeit.","schema":{"type":"string","enum":["desc","asc"],"default":"desc"}},{"name":"limit","in":"query","description":"Seitengröße, 1 bis 1000.","schema":{"type":"integer","minimum":1,"maximum":1000,"default":100}},{"name":"cursor","in":"query","description":"`meta.next_cursor` der vorherigen Seite.","schema":{"type":"string"}}],"responses":{"200":{"description":"Eine Seite mit Messwerten.","headers":{"X-Request-Id":{"description":"ID dieser Anfrage, für den Support.","schema":{"type":"string"}},"X-RateLimit-Limit":{"description":"Erlaubte Anfragen pro Minute.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Verbleibende Anfragen in der aktuellen Minute.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Sekunden bis zum Neustart des Zeitfensters.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Reading"}},"meta":{"$ref":"#/components/schemas/CursorMeta"}}}}}},"400":{"description":"Ungültiger Parameter","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"example":{"type":"https://docs.modbuscloud.com/errors#invalid_parameter","title":"Invalid parameter","status":400,"detail":"The window between since and until can be at most 7 days. Pass a single register_id to request up to 366 days.","code":"invalid_parameter","request_id":"req_4f1c0d2e9a8b4c7d8e6f5a4b3c2d1e0f"}}}},"401":{"description":"Ungültiger API-Schlüssel","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"example":{"type":"https://docs.modbuscloud.com/errors#invalid_api_key","title":"Invalid API key","status":401,"detail":"This API key does not exist.","code":"invalid_api_key","request_id":"req_4f1c0d2e9a8b4c7d8e6f5a4b3c2d1e0f"}}}},"403":{"description":"Unzureichender Scope","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"example":{"type":"https://docs.modbuscloud.com/errors#insufficient_scope","title":"Insufficient scope","status":403,"detail":"This endpoint requires the 'registers:read' scope.","code":"insufficient_scope","request_id":"req_4f1c0d2e9a8b4c7d8e6f5a4b3c2d1e0f"}}}},"404":{"description":"Nicht gefunden","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"example":{"type":"https://docs.modbuscloud.com/errors#not_found","title":"Not found","status":404,"detail":"Gateway not found.","code":"not_found","request_id":"req_4f1c0d2e9a8b4c7d8e6f5a4b3c2d1e0f"}}}},"429":{"description":"Rate Limit überschritten","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"example":{"type":"https://docs.modbuscloud.com/errors#rate_limited","title":"Rate limit exceeded","status":429,"detail":"Max 100 requests per minute per key. Retry after 12 seconds.","code":"rate_limited","request_id":"req_4f1c0d2e9a8b4c7d8e6f5a4b3c2d1e0f"}}}},"500":{"description":"Interner Serverfehler","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"example":{"type":"https://docs.modbuscloud.com/errors#internal_error","title":"Internal server error","status":500,"detail":"Something went wrong on our side. Quote the request_id when contacting support.","code":"internal_error","request_id":"req_4f1c0d2e9a8b4c7d8e6f5a4b3c2d1e0f"}}}}}}},"/alerts":{"get":{"tags":["Alerts"],"operationId":"listAlerts","summary":"Alarme auflisten","description":"Alarme Ihrer Organisation, zuletzt ausgelöste zuerst. Scope `alerts:read`.","parameters":[{"name":"status","in":"query","schema":{"type":"string","enum":["active","returned","acknowledged","resolved"]},"description":"Nur Alarme mit diesem Status."},{"name":"severity","in":"query","schema":{"type":"string","enum":["critical","warning","info"]},"description":"Nur Alarme mit diesem Schweregrad."},{"name":"device_id","in":"query","schema":{"type":"string","format":"uuid"},"description":"Nur Alarme dieses Gateways."},{"name":"limit","in":"query","description":"Seitengröße, 1 bis 100.","schema":{"type":"integer","minimum":1,"maximum":100,"default":50}},{"name":"offset","in":"query","description":"Anzahl der zu überspringenden Zeilen.","schema":{"type":"integer","minimum":0,"default":0}}],"responses":{"200":{"description":"Eine Seite mit Alarmen.","headers":{"X-Request-Id":{"description":"ID dieser Anfrage, für den Support.","schema":{"type":"string"}},"X-RateLimit-Limit":{"description":"Erlaubte Anfragen pro Minute.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Verbleibende Anfragen in der aktuellen Minute.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Sekunden bis zum Neustart des Zeitfensters.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Alert"}},"meta":{"$ref":"#/components/schemas/OffsetMeta"}}}}}},"401":{"description":"Ungültiger API-Schlüssel","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"example":{"type":"https://docs.modbuscloud.com/errors#invalid_api_key","title":"Invalid API key","status":401,"detail":"This API key does not exist.","code":"invalid_api_key","request_id":"req_4f1c0d2e9a8b4c7d8e6f5a4b3c2d1e0f"}}}},"403":{"description":"Unzureichender Scope","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"example":{"type":"https://docs.modbuscloud.com/errors#insufficient_scope","title":"Insufficient scope","status":403,"detail":"This endpoint requires the 'registers:read' scope.","code":"insufficient_scope","request_id":"req_4f1c0d2e9a8b4c7d8e6f5a4b3c2d1e0f"}}}},"429":{"description":"Rate Limit überschritten","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"example":{"type":"https://docs.modbuscloud.com/errors#rate_limited","title":"Rate limit exceeded","status":429,"detail":"Max 100 requests per minute per key. Retry after 12 seconds.","code":"rate_limited","request_id":"req_4f1c0d2e9a8b4c7d8e6f5a4b3c2d1e0f"}}}},"500":{"description":"Interner Serverfehler","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"example":{"type":"https://docs.modbuscloud.com/errors#internal_error","title":"Internal server error","status":500,"detail":"Something went wrong on our side. Quote the request_id when contacting support.","code":"internal_error","request_id":"req_4f1c0d2e9a8b4c7d8e6f5a4b3c2d1e0f"}}}}}}}},"webhooks":{"device.online":{"post":{"operationId":"webhook_device_online","summary":"device.online","description":"Ein Gateway meldet sich wieder, auch wenn es zurückkommt, nachdem es als offline markiert war.","tags":["Webhook events"],"parameters":[{"name":"webhook-id","in":"header","required":true,"schema":{"type":"string"},"description":"Eindeutige ID der Nachricht, bei jedem erneuten Versuch gleich."},{"name":"webhook-timestamp","in":"header","required":true,"schema":{"type":"string"},"description":"Unix-Zeit in Sekunden dieses Versuchs."},{"name":"webhook-signature","in":"header","required":true,"schema":{"type":"string"},"description":"`v1,` gefolgt von der Base64-kodierten HMAC-SHA256-Signatur."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["id","type","timestamp","data"],"properties":{"id":{"type":"string","description":"ID der Nachricht, identisch mit dem Header `webhook-id`."},"type":{"type":"string","const":"device.online"},"timestamp":{"type":"string","format":"date-time","description":"Zeitpunkt des Ereignisses."},"data":{"$ref":"#/components/schemas/DeviceStatusEvent"}}},"example":{"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"}}}}},"responses":{"2XX":{"description":"Empfangen. Jeder 2xx-Status innerhalb von 10 Sekunden gilt als zugestellt."}}}},"device.offline":{"post":{"operationId":"webhook_device_offline","summary":"device.offline","description":"Ein Gateway meldet sich nicht mehr, weil die Verbindung getrennt wurde oder weil es länger still war als sein Heartbeat-Intervall.","tags":["Webhook events"],"parameters":[{"name":"webhook-id","in":"header","required":true,"schema":{"type":"string"},"description":"Eindeutige ID der Nachricht, bei jedem erneuten Versuch gleich."},{"name":"webhook-timestamp","in":"header","required":true,"schema":{"type":"string"},"description":"Unix-Zeit in Sekunden dieses Versuchs."},{"name":"webhook-signature","in":"header","required":true,"schema":{"type":"string"},"description":"`v1,` gefolgt von der Base64-kodierten HMAC-SHA256-Signatur."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["id","type","timestamp","data"],"properties":{"id":{"type":"string","description":"ID der Nachricht, identisch mit dem Header `webhook-id`."},"type":{"type":"string","const":"device.offline"},"timestamp":{"type":"string","format":"date-time","description":"Zeitpunkt des Ereignisses."},"data":{"$ref":"#/components/schemas/DeviceStatusEvent"}}},"example":{"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"}}}}},"responses":{"2XX":{"description":"Empfangen. Jeder 2xx-Status innerhalb von 10 Sekunden gilt als zugestellt."}}}},"alert.triggered":{"post":{"operationId":"webhook_alert_triggered","summary":"alert.triggered","description":"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.","tags":["Webhook events"],"parameters":[{"name":"webhook-id","in":"header","required":true,"schema":{"type":"string"},"description":"Eindeutige ID der Nachricht, bei jedem erneuten Versuch gleich."},{"name":"webhook-timestamp","in":"header","required":true,"schema":{"type":"string"},"description":"Unix-Zeit in Sekunden dieses Versuchs."},{"name":"webhook-signature","in":"header","required":true,"schema":{"type":"string"},"description":"`v1,` gefolgt von der Base64-kodierten HMAC-SHA256-Signatur."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["id","type","timestamp","data"],"properties":{"id":{"type":"string","description":"ID der Nachricht, identisch mit dem Header `webhook-id`."},"type":{"type":"string","const":"alert.triggered"},"timestamp":{"type":"string","format":"date-time","description":"Zeitpunkt des Ereignisses."},"data":{"$ref":"#/components/schemas/AlertTriggeredEvent"}}},"example":{"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"}}}}},"responses":{"2XX":{"description":"Empfangen. Jeder 2xx-Status innerhalb von 10 Sekunden gilt als zugestellt."}}}},"alert.returned":{"post":{"operationId":"webhook_alert_returned","summary":"alert.returned","description":"Der Wert liegt wieder innerhalb des Grenzwerts, oder das Gateway ist wieder online. Der Alarm bleibt offen, bis ihn jemand löst.","tags":["Webhook events"],"parameters":[{"name":"webhook-id","in":"header","required":true,"schema":{"type":"string"},"description":"Eindeutige ID der Nachricht, bei jedem erneuten Versuch gleich."},{"name":"webhook-timestamp","in":"header","required":true,"schema":{"type":"string"},"description":"Unix-Zeit in Sekunden dieses Versuchs."},{"name":"webhook-signature","in":"header","required":true,"schema":{"type":"string"},"description":"`v1,` gefolgt von der Base64-kodierten HMAC-SHA256-Signatur."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["id","type","timestamp","data"],"properties":{"id":{"type":"string","description":"ID der Nachricht, identisch mit dem Header `webhook-id`."},"type":{"type":"string","const":"alert.returned"},"timestamp":{"type":"string","format":"date-time","description":"Zeitpunkt des Ereignisses."},"data":{"$ref":"#/components/schemas/AlertReturnedEvent"}}},"example":{"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"}}}}},"responses":{"2XX":{"description":"Empfangen. Jeder 2xx-Status innerhalb von 10 Sekunden gilt als zugestellt."}}}},"alert.acknowledged":{"post":{"operationId":"webhook_alert_acknowledged","summary":"alert.acknowledged","description":"Jemand hat den Alarm im Portal bestätigt.","tags":["Webhook events"],"parameters":[{"name":"webhook-id","in":"header","required":true,"schema":{"type":"string"},"description":"Eindeutige ID der Nachricht, bei jedem erneuten Versuch gleich."},{"name":"webhook-timestamp","in":"header","required":true,"schema":{"type":"string"},"description":"Unix-Zeit in Sekunden dieses Versuchs."},{"name":"webhook-signature","in":"header","required":true,"schema":{"type":"string"},"description":"`v1,` gefolgt von der Base64-kodierten HMAC-SHA256-Signatur."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["id","type","timestamp","data"],"properties":{"id":{"type":"string","description":"ID der Nachricht, identisch mit dem Header `webhook-id`."},"type":{"type":"string","const":"alert.acknowledged"},"timestamp":{"type":"string","format":"date-time","description":"Zeitpunkt des Ereignisses."},"data":{"$ref":"#/components/schemas/AlertStatusEvent"}}},"example":{"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"}}}}},"responses":{"2XX":{"description":"Empfangen. Jeder 2xx-Status innerhalb von 10 Sekunden gilt als zugestellt."}}}},"alert.resolved":{"post":{"operationId":"webhook_alert_resolved","summary":"alert.resolved","description":"Der Alarm wurde geschlossen.","tags":["Webhook events"],"parameters":[{"name":"webhook-id","in":"header","required":true,"schema":{"type":"string"},"description":"Eindeutige ID der Nachricht, bei jedem erneuten Versuch gleich."},{"name":"webhook-timestamp","in":"header","required":true,"schema":{"type":"string"},"description":"Unix-Zeit in Sekunden dieses Versuchs."},{"name":"webhook-signature","in":"header","required":true,"schema":{"type":"string"},"description":"`v1,` gefolgt von der Base64-kodierten HMAC-SHA256-Signatur."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["id","type","timestamp","data"],"properties":{"id":{"type":"string","description":"ID der Nachricht, identisch mit dem Header `webhook-id`."},"type":{"type":"string","const":"alert.resolved"},"timestamp":{"type":"string","format":"date-time","description":"Zeitpunkt des Ereignisses."},"data":{"$ref":"#/components/schemas/AlertStatusEvent"}}},"example":{"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"}}}}},"responses":{"2XX":{"description":"Empfangen. Jeder 2xx-Status innerhalb von 10 Sekunden gilt als zugestellt."}}}},"automation.triggered":{"post":{"operationId":"webhook_automation_triggered","summary":"automation.triggered","description":"Eine Automatisierung mit einer Webhook-Aktion wurde ausgeführt.","tags":["Webhook events"],"parameters":[{"name":"webhook-id","in":"header","required":true,"schema":{"type":"string"},"description":"Eindeutige ID der Nachricht, bei jedem erneuten Versuch gleich."},{"name":"webhook-timestamp","in":"header","required":true,"schema":{"type":"string"},"description":"Unix-Zeit in Sekunden dieses Versuchs."},{"name":"webhook-signature","in":"header","required":true,"schema":{"type":"string"},"description":"`v1,` gefolgt von der Base64-kodierten HMAC-SHA256-Signatur."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["id","type","timestamp","data"],"properties":{"id":{"type":"string","description":"ID der Nachricht, identisch mit dem Header `webhook-id`."},"type":{"type":"string","const":"automation.triggered"},"timestamp":{"type":"string","format":"date-time","description":"Zeitpunkt des Ereignisses."},"data":{"$ref":"#/components/schemas/AutomationEvent"}}},"example":{"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"}]}}}}},"responses":{"2XX":{"description":"Empfangen. Jeder 2xx-Status innerhalb von 10 Sekunden gilt als zugestellt."}}}}},"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"mlk_...","description":"Ein API-Schlüssel aus Einstellungen, API-Schlüssel im Portal. Auf dieser Seite ist der Sandbox-Schlüssel bereits für Sie eingetragen."}},"schemas":{"Problem":{"type":"object","description":"Fehler im Problem-Details-Format nach RFC 9457.","required":["type","title","status","code","request_id"],"properties":{"type":{"type":"string","format":"uri"},"title":{"type":"string"},"status":{"type":"integer"},"detail":{"type":"string"},"code":{"type":"string","enum":["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":{"type":"string"}}},"OffsetMeta":{"type":"object","properties":{"total":{"type":"integer"},"limit":{"type":"integer"},"offset":{"type":"integer"}}},"CursorMeta":{"type":"object","properties":{"since":{"type":"string","format":"date-time"},"until":{"type":"string","format":"date-time"},"order":{"type":"string","enum":["asc","desc"]},"limit":{"type":"integer"},"has_more":{"type":"boolean"},"next_cursor":{"type":["string","null"],"description":"Als `cursor` für die nächste Seite übergeben. Null auf der letzten Seite."}}},"Introspection":{"type":"object","properties":{"key":{"type":"object","properties":{"name":{"type":"string"},"scopes":{"type":"array","items":{"type":"string"}},"created_at":{"type":"string","format":"date-time"},"expires_at":{"type":["string","null"],"format":"date-time"}}},"organization":{"type":"object","properties":{"name":{"type":"string"}}},"stats":{"type":"object","properties":{"gateways":{"type":"integer"},"devices":{"type":"integer","description":"Identisch mit gateways, bleibt für ältere Clients erhalten."},"open_alerts":{"type":"integer"}}}}},"Customer":{"type":"object","description":"Der Standort oder Kunde, dem ein Gateway zugeordnet ist.","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"address":{"type":["string","null"],"description":"Adresse des Standorts. Nur in `GET /devices/{id}`."},"city":{"type":["string","null"]}}},"Gateway":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"serial":{"type":"string","examples":["MCG-9V63A8M1"]},"name":{"type":"string"},"status":{"type":"string","enum":["online","offline","pending","error"]},"firmware_ver":{"type":["string","null"]},"ip_eth":{"type":["string","null"],"description":"Adresse im kabelgebundenen Netzwerk."},"ip_wifi":{"type":["string","null"]},"ip_4g":{"type":["string","null"],"description":"Adresse im 4G-Netz."},"signal_4g":{"type":["integer","null"],"description":"Signalstärke in dBm."},"last_seen":{"type":["string","null"],"format":"date-time"},"created_at":{"type":"string","format":"date-time"},"customer":{"type":["object","null"],"$ref":"#/components/schemas/Customer"}}},"ModbusDevice":{"type":"object","description":"Ein Modbus-Gerät (`rtu`, `tcp`) oder BACnet/IP-Gerät (`bacnet_ip`) hinter dem Gateway.","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":["string","null"]},"slave_id":{"type":"integer","description":"Modbus Unit ID. Bei bacnet_ip ein interner Slot 300..999."},"protocol":{"type":"string","enum":["rtu","tcp","bacnet_ip"]},"ip_address":{"type":["string","null"],"description":"Für Modbus TCP und BACnet/IP. Hinter einem BACnet-Router die Adresse des Routers."},"port":{"type":["integer","null"],"description":"Für Modbus TCP und BACnet/IP (Standard 47808)."},"poll_interval_ms":{"type":["integer","null"]},"bacnet_device_instance":{"type":["integer","null"],"description":"BACnet Device Instance, 0 bis 4194302. Nur bei bacnet_ip."},"bacnet_network":{"type":["integer","null"],"description":"BACnet-Netzwerknummer hinter einem BACnet-Router (1 bis 65534), sonst null."},"bacnet_mac":{"type":["string","null"],"description":"BACnet-MAC-Adresse hinter diesem Router, hexadezimal in Kleinbuchstaben (MS/TP-Adresse 10 ist `0a`), sonst null."},"template":{"type":["object","null"],"properties":{"id":{"type":"string","format":"uuid"},"brand":{"type":"string"},"model":{"type":"string"}}}}},"GatewayDetail":{"allOf":[{"$ref":"#/components/schemas/Gateway"},{"type":"object","properties":{"claimed_at":{"type":["string","null"],"format":"date-time"},"modbus_devices":{"type":"array","items":{"$ref":"#/components/schemas/ModbusDevice"}}}}]},"Register":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"modbus_device_id":{"type":"string","format":"uuid"},"modbus_device_name":{"type":["string","null"]},"name":{"type":"string","examples":["Supply temperature"]},"address":{"type":"integer","description":"Registeradresse. Bei einem BACnet-Datenpunkt eine interne Nummer, eindeutig auf dem Gateway."},"function_code":{"type":["integer","null"],"description":"3 Holding Register, 4 Input Register. Null bei einem BACnet-Datenpunkt."},"data_type":{"type":"string","examples":["int16","uint16","int32","float32"]},"unit":{"type":["string","null"],"examples":["°C"]},"scale_factor":{"type":["number","null"],"description":"value = raw_value × scale_factor"},"is_writable":{"type":"boolean"},"description":{"type":["string","null"]},"bacnet_object_type":{"type":["integer","null"],"description":"BACnet-Objekttyp, zum Beispiel 0 analog-input, 3 binary-input, 13 multi-state-input. Null bei Modbus."},"bacnet_object_instance":{"type":["integer","null"],"description":"BACnet-Objektinstanz. Null bei Modbus."},"bacnet_property_id":{"type":["integer","null"],"description":"Gelesene BACnet-Property, 85 ist Present_Value. Null bei Modbus."},"bacnet_array_index":{"type":["integer","null"],"description":"Array-Index dieser Property, oder null für den gesamten Wert."},"bacnet_write_priority":{"type":["integer","null"],"description":"BACnet-Schreibpriorität. Vorerst immer null, weil BACnet-Datenpunkte nur gelesen werden."},"latest_value":{"type":["number","null"],"description":"Aktueller Wert in physikalischen Einheiten."},"latest_raw_value":{"type":["number","null"],"description":"Aktueller Wert, wie er aus dem Register gelesen wurde."},"latest_ts":{"type":["string","null"],"format":"date-time"}}},"Reading":{"type":"object","properties":{"register_id":{"type":"string","format":"uuid"},"modbus_device_id":{"type":["string","null"],"format":"uuid"},"name":{"type":["string","null"]},"unit":{"type":["string","null"]},"value":{"type":["number","null"],"description":"In physikalischen Einheiten, mit angewendetem Skalierungsfaktor."},"raw_value":{"type":["number","null"],"description":"Wie aus dem Register gelesen."},"ts":{"type":"string","format":"date-time"}}},"Alert":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"device_id":{"type":["string","null"],"format":"uuid"},"rule_id":{"type":["string","null"],"format":"uuid"},"severity":{"type":"string","enum":["critical","warning","info"]},"message":{"type":["string","null"]},"status":{"type":"string","enum":["active","returned","acknowledged","resolved"]},"value":{"type":["number","null"]},"created_at":{"type":"string","format":"date-time"},"last_triggered_at":{"type":["string","null"],"format":"date-time"},"returned_at":{"type":["string","null"],"format":"date-time"},"ack_at":{"type":["string","null"],"format":"date-time"},"ack_by":{"type":["string","null"],"format":"uuid","description":"ID des Benutzers, der den Alarm bestätigt hat."},"ack_note":{"type":["string","null"]},"resolved_at":{"type":["string","null"],"format":"date-time"},"resolved_by":{"type":["string","null"],"format":"uuid","description":"ID des Benutzers, der den Alarm gelöst hat."},"resolve_note":{"type":["string","null"]},"entry_count":{"type":"integer","description":"Wie oft der Alarm ausgelöst wurde, während er offen war."},"reminder_at":{"type":["string","null"],"format":"date-time","description":"Zeitpunkt, zu dem eine im Portal gesetzte Erinnerung fällig ist. Null ohne Erinnerung."},"reminder_sent":{"type":["boolean","null"],"description":"Ob diese Erinnerung bereits gesendet wurde."}}},"DeviceStatusEvent":{"type":"object","properties":{"device_id":{"type":"string","format":"uuid"},"serial":{"type":"string"},"status":{"type":"string","enum":["online","offline"]},"previous_status":{"type":["string","null"]},"last_seen":{"type":["string","null"],"format":"date-time","description":"Letzte Meldung des Gateways."}}},"AlertTriggeredEvent":{"type":"object","properties":{"alert_id":{"type":"string","format":"uuid"},"rule_id":{"type":"string","format":"uuid"},"rule_name":{"type":"string"},"device_id":{"type":"string","format":"uuid"},"severity":{"type":"string","enum":["critical","warning","info"]},"value":{"type":"number"},"threshold":{"type":"number"},"condition":{"type":"string","description":"Vergleich der Regel, oder `offline`."},"message":{"type":"string"},"source":{"type":"string","enum":["rule","detector"]},"register_id":{"type":["string","null"],"format":"uuid"},"modbus_device_id":{"type":["string","null"],"format":"uuid"}}},"AlertReturnedEvent":{"type":"object","properties":{"alert_id":{"type":"string","format":"uuid"},"rule_id":{"type":"string","format":"uuid"},"rule_name":{"type":"string"},"device_id":{"type":"string","format":"uuid"},"severity":{"type":"string"},"value":{"type":"number"},"condition":{"type":"string","description":"`offline`, wenn das Gateway wieder online ist."},"source":{"type":"string","enum":["rule","detector"]}}},"AlertStatusEvent":{"type":"object","properties":{"alert_id":{"type":"string","format":"uuid"},"device_id":{"type":["string","null"],"format":"uuid"},"rule_id":{"type":["string","null"],"format":"uuid"},"severity":{"type":"string"},"message":{"type":"string"},"status":{"type":"string","enum":["acknowledged","resolved"]},"value":{"type":["number","null"]},"acknowledged_at":{"type":["string","null"],"format":"date-time"},"resolved_at":{"type":["string","null"],"format":"date-time"},"note":{"type":["string","null"]}}},"AutomationEvent":{"type":"object","properties":{"rule_id":{"type":"string","format":"uuid"},"rule_name":{"type":"string"},"actions":{"type":"array","items":{"type":"object"}}}}}}}