{"openapi":"3.1.0","info":{"title":"ModbusCloud API","version":"1.0.0","summary":"Lees data van gateways, registers, meetwaarden en alarmen, en ontvang events als webhooks.","description":"\nMet de ModbusCloud API krijgen je eigen systemen de data die onze gateways uit Modbus apparatuur lezen. Je krijgt de gateways, de Modbus apparaten erachter, registers met hun laatste waarden, de meetgeschiedenis en alarmen. Webhooks sturen events naar je endpoint zodra ze plaatsvinden.\n\n## Snel aan de slag\n\nVoor elk verzoek heb je een API-sleutel nodig. Wil je de API meteen uitproberen, gebruik dan de sandboxsleutel hieronder. Die kan alleen lezen en hoort bij onze demo-organisatie, waar de gateways elke minuut nieuwe meetwaarden sturen. Iedereen gebruikt deze sleutel, dus per bezoeker zijn er 60 verzoeken per minuut mogelijk.\n\n```\nmlk_72718174d83aa7fa5238c5eb8df5adc3e432c72cc80ea3242821f3aaabd9f630\n```\n\nControleer of de sleutel werkt:\n\n```bash\ncurl https://api.modbuscloud.com/v1/introspect \\\n  -H \"Authorization: Bearer mlk_72718174d83aa7fa5238c5eb8df5adc3e432c72cc80ea3242821f3aaabd9f630\"\n```\n\nVraag de gateways op en haal daarna de actuele waarden van een ervan op:\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\nOok de knoppen **Uitproberen** op deze pagina zijn al ingevuld met de sandboxsleutel.\n\n## Begrippen\n\n| Begrip | Betekenis |\n|---|---|\n| Gateway | De ModbusCloud Gateway op locatie. In de API-paden heet een gateway `device`, bijvoorbeeld `/devices/{id}`. |\n| Modbus apparaat | Apparatuur die de gateway via Modbus RTU of Modbus TCP uitleest, zoals een klimaatcomputer, een kWh-meter of een warmtepomp. Eén gateway kan er veel uitlezen. |\n| Register | Eén waarde van een Modbus apparaat, met een naam, een eenheid en een schaalfactor. |\n| Meetwaarde | Eén opgeslagen waarde van een register op een bepaald moment. |\n| Alarm | Ontstaat als aan een regel wordt voldaan, bijvoorbeeld een waarde boven een grens of een gateway die offline gaat. |\n\n**Waarden.** `value` en `latest_value` zijn omgerekend met de schaalfactor en staan in de eenheid van het register, precies zoals het portaal ze toont. `raw_value` is het getal zoals het uit het register is gelezen.\n\n**Geschiedenis.** Standaard bevat de geschiedenis één waarde per register per vijf minuten, en maximaal één per minuut. Dat hangt af van hoe vaak de gateway uitleest, en dat stel je in het portaal in. Meetwaarden blijven standaard 12 maanden bewaard. Live waarden in het portaal kunnen vaker binnenkomen.\n\n**Tijd.** Alle tijdstempels zijn ISO 8601 in UTC.\n\n## Authenticatie\n\nStuur de sleutel bij elk verzoek mee als bearer token.\n\n```\nAuthorization: Bearer mlk_...\n```\n\nEigenaren en beheerders maken sleutels aan in het portaal onder **Instellingen, API-sleutels**. Een sleutel wordt één keer getoond, dus sla hem meteen op. Elke sleutel hoort bij één organisatie en heeft scopes.\n\n| Scope | Geeft toegang tot |\n|---|---|\n| `devices:read` | Gateways en hun Modbus apparaten |\n| `registers:read` | Registers, laatste waarden en meetgeschiedenis |\n| `alerts:read` | Alarmen |\n\nSleutels kunnen verlopen en je kunt ze op elk moment intrekken in het portaal.\n\nSchrijven naar registers staat voor elke gateway uit tot wij het aanzetten. Vraag het per gateway aan op het tabblad Aansturen in het portaal. Tot die tijd krijgt een schrijfopdracht naar die gateway 403 `write_not_enabled` terug, ongeacht de scopes van de sleutel.\n\n## Paginering\n\nGateways en alarmen gebruiken `limit` (1 tot 100, standaard 50) en `offset`, en geven `meta.total` terug.\n\nRegisters gebruiken `limit` (1 tot 1000, standaard 1000) en `offset`, en geven `meta.total` terug. Een gateway met een groot BACnet-apparaat kan meer dan 1000 registers hebben. Vraag dan met `offset` de volgende pagina op tot je `meta.total` rijen hebt.\n\nMeetwaarden gebruiken een cursor, omdat de geschiedenis groot is. Elke pagina geeft `meta.has_more` en `meta.next_cursor` terug. Geef `next_cursor` mee als `cursor` om de volgende pagina op te halen, met verder dezelfde parameters. Er worden nooit rijen overgeslagen of dubbel geleverd, ook niet terwijl er nieuwe meetwaarden binnenkomen.\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\nWil je een kopie van de geschiedenis in je eigen database bijhouden, vraag dan op met `order=asc` en `since` op het laatste tijdstip dat je hebt opgeslagen, en volg `next_cursor` tot `has_more` false is.\n\n## Fouten\n\nFouten gebruiken het problem details-formaat van RFC 9457, met 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\nGebruik `code` in je logica, want die blijft gelijk. `detail` is bedoeld voor mensen en kan veranderen.\n\n| Status | code | Wanneer |\n|---|---|---|\n| 400 | `invalid_parameter` | Een queryparameter ontbreekt, is ongeldig of valt buiten het bereik |\n| 400 | `bad_request` | De request body is geen geldige JSON, of een veld erin ontbreekt of is ongeldig |\n| 401 | `missing_api_key` | Geen header `Authorization: Bearer` |\n| 401 | `invalid_api_key` | De sleutel bestaat niet |\n| 401 | `api_key_revoked` | De sleutel is ingetrokken in het portaal |\n| 401 | `api_key_expired` | De sleutel is verlopen |\n| 403 | `insufficient_scope` | De sleutel mist de scope die dit endpoint nodig heeft |\n| 403 | `write_not_enabled` | Schrijven staat voor deze gateway niet aan |\n| 404 | `not_found` | De gateway, het register of het alarm hoort niet bij je organisatie |\n| 422 | `bacnet_write_unsupported` | Het register is een BACnet-punt, en schrijven naar BACnet-punten kan nog niet |\n| 429 | `rate_limited` | Meer dan 100 verzoeken in de huidige minuut, of de schrijflimiet van de gateway of organisatie. `Retry-After` zegt hoeveel seconden je moet wachten |\n| 500 | `internal_error` | Er ging iets mis aan onze kant |\n| 502 | `publish_failed` | De schrijfopdracht kon niet naar de gateway worden gestuurd |\n| 503 | `gateway_offline` | De gateway is offline, de schrijfopdracht is niet verstuurd |\n\nElk antwoord bevat een header `X-Request-Id`. Noem die als je contact met ons opneemt over een verzoek.\n\n## Taal\n\nFoutmeldingen en tekstvelden volgen `Accept-Language` (`en`, `nl`, `de`), met Engels als standaard. Het antwoord bevat `Content-Language`.\n\n## Limieten\n\nElke sleutel mag 100 verzoeken per minuut doen. Het venster begint aan het begin van elke minuut opnieuw. De gedeelde sandboxsleutel telt per bezoeker, met 60 verzoeken per minuut voor elk. Elk antwoord laat zien hoe je ervoor staat.\n\n| Header | Betekenis |\n|---|---|\n| `X-RateLimit-Limit` | Toegestane verzoeken per minuut |\n| `X-RateLimit-Remaining` | Resterende verzoeken in de huidige minuut |\n| `X-RateLimit-Reset` | Seconden tot het venster opnieuw begint |\n| `Retry-After` | Alleen bij een 429, het aantal seconden dat je moet wachten |\n\nVraag je de registers van 50 gateways eens per minuut op, dan gebruik je de helft van het budget. Gebruik webhooks voor events in plaats van alarmen te pollen.\n\n## Webhooks\n\nWebhooks sturen een HTTP POST naar je endpoint als er iets gebeurt. Eigenaren en beheerders voegen endpoints toe in het portaal onder **Instellingen, Webhooks**, kiezen de events en kopiëren het ondertekeningsgeheim. De events en hun payloads staan onder **Webhooks** in het menu op deze pagina.\n\nElke aflevering heeft dezelfde envelop.\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### De handtekening controleren\n\nAfleveringen zijn ondertekend volgens de specificatie van [Standard Webhooks](https://www.standardwebhooks.com), dus je kunt hun bibliotheken direct gebruiken.\n\n| Header | Inhoud |\n|---|---|\n| `webhook-id` | Unieke id van het bericht. Bij elke nieuwe poging hetzelfde. |\n| `webhook-timestamp` | Unix-tijd in seconden van deze poging |\n| `webhook-signature` | `v1,` gevolgd door de HMAC-SHA256-handtekening in base64 |\n| `X-ModbusCloud-Event` | Het type event, hetzelfde als `type` in de body |\n\nNode.js met `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 met `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 elke andere taal bereken je HMAC-SHA256 over `{webhook-id}.{webhook-timestamp}.{raw body}` met het geheim als sleutel. Die sleutel is het deel na `whsec_`, gedecodeerd uit base64. Codeer het resultaat in base64 en vergelijk het in constante tijd met de waarde na `v1,`. Weiger berichten met een tijdstempel die meer dan vijf minuten van je eigen klok afwijkt.\n\nControleer altijd tegen de ruwe body zoals je die hebt ontvangen. Als je de JSON eerst parseert en opnieuw serialiseert, veranderen de bytes en klopt de handtekening niet meer.\n\n### Aflevering en nieuwe pogingen\n\n- Antwoord binnen 10 seconden met een willekeurige 2xx-status. Verwerk het event pas nadat je hebt geantwoord.\n- Een aflevering mislukt bij een status buiten 2xx, een time-out of een redirect. Redirects worden niet gevolgd.\n- Mislukte afleveringen worden opnieuw geprobeerd na 30 seconden, 2 minuten, 10 minuten, 1 uur en 6 uur. Dat zijn zes pogingen in iets meer dan zeven uur.\n- Nieuwe pogingen hebben dezelfde `webhook-id`. Bewaar de ids die je hebt verwerkt en sla dubbele over.\n- De volgorde van afleveringen is niet gegarandeerd. Gebruik `timestamp` en de `status` van het alarm om te bepalen wat actueel is.\n- Na tien afleveringen op rij waarvan elke poging mislukte, wordt het endpoint gepauzeerd. Zet het in het portaal weer aan.\n- Endpoints moeten via het openbare internet bereikbaar zijn over http of https. Gebruik https.\n\n## Versies\n\nDit is versie 1. We voegen endpoints, velden en events toe zonder aankondiging, dus negeer velden die je niet kent. Wijzigingen die een koppeling kunnen breken komen als nieuwe versie, en die kondigen we vooraf aan.\n\n## Support\n\nVragen, of werkt er iets niet? Mail naar [info@modbuscloud.com](mailto:info@modbuscloud.com) en vermeld de `X-Request-Id`.\n","contact":{"name":"ModbusCloud","email":"info@modbuscloud.com","url":"https://modbuscloud.com"}},"servers":[{"url":"https://api.modbuscloud.com/v1","description":"Productie"},{"url":"https://portal.modbuscloud.com/api/v1","description":"Productie, alternatief adres"}],"security":[{"bearerAuth":[]}],"tags":[{"name":"Key","x-displayName":"Sleutel","description":"Controleer de sleutel die je gebruikt."},{"name":"Gateways","description":"Gateways en de Modbus apparaten erachter. In de paden heet een gateway `device`."},{"name":"Registers","description":"Registers van een gateway met hun laatste waarden."},{"name":"Readings","x-displayName":"Meetwaarden","description":"Meetgeschiedenis van een gateway, in pagina's met een cursor."},{"name":"Alerts","x-displayName":"Alarmen","description":"Alarmen van je organisatie."},{"name":"Webhook events","x-displayName":"Webhook-events","description":"Events die naar je endpoint worden gestuurd. Ondertekening en nieuwe pogingen staan onder Webhooks in de inleiding."}],"paths":{"/introspect":{"get":{"tags":["Key"],"operationId":"introspect","summary":"Je API-sleutel controleren","description":"Geeft de naam van de sleutel, de scopes en de organisatie waar hij bij hoort. Elke geldige sleutel mag dit aanroepen.","responses":{"200":{"description":"De sleutel en zijn organisatie.","headers":{"X-Request-Id":{"description":"Id van dit verzoek, voor support.","schema":{"type":"string"}},"X-RateLimit-Limit":{"description":"Toegestane verzoeken per minuut.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Resterende verzoeken in de huidige minuut.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Seconden tot het venster opnieuw begint.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Introspection"}}}}}},"401":{"description":"Ongeldige API-sleutel","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":"Onvoldoende 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":"Limiet overschreden","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":"Interne serverfout","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 opvragen","description":"Alle gateways van je organisatie, de laatst geziene eerst. Scope `devices:read`.","parameters":[{"name":"status","in":"query","description":"Alleen gateways met deze status.","schema":{"type":"string","enum":["online","offline","pending","error"]}},{"name":"limit","in":"query","description":"Paginagrootte, 1 tot 100.","schema":{"type":"integer","minimum":1,"maximum":100,"default":50}},{"name":"offset","in":"query","description":"Aantal rijen om over te slaan.","schema":{"type":"integer","minimum":0,"default":0}}],"responses":{"200":{"description":"Een pagina met gateways.","headers":{"X-Request-Id":{"description":"Id van dit verzoek, voor support.","schema":{"type":"string"}},"X-RateLimit-Limit":{"description":"Toegestane verzoeken per minuut.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Resterende verzoeken in de huidige minuut.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Seconden tot het venster opnieuw begint.","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":"Ongeldige API-sleutel","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":"Onvoldoende 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":"Limiet overschreden","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":"Interne serverfout","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":"Een gateway opvragen","description":"Eén gateway met de klant en de Modbus apparaten die hij uitleest. Scope `devices:read`.","parameters":[{"name":"id","in":"path","required":true,"description":"Id van de gateway, uit `GET /devices`.","schema":{"type":"string","format":"uuid","examples":["ecc5e4e5-da58-4678-92af-d72b09c2b937"]},"example":"ecc5e4e5-da58-4678-92af-d72b09c2b937"}],"responses":{"200":{"description":"De gateway.","headers":{"X-Request-Id":{"description":"Id van dit verzoek, voor support.","schema":{"type":"string"}},"X-RateLimit-Limit":{"description":"Toegestane verzoeken per minuut.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Resterende verzoeken in de huidige minuut.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Seconden tot het venster opnieuw begint.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/GatewayDetail"}}}}}},"401":{"description":"Ongeldige API-sleutel","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":"Onvoldoende 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":"Niet gevonden","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":"Limiet overschreden","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":"Interne serverfout","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":"Registers met laatste waarden opvragen","description":"De registers van de gateway met hun laatste waarde, in pagina's gesorteerd op weergavevolgorde en adres. Vraag dit periodiek op voor de actuele stand. BACnet-punten zijn ook registers, met de velden `bacnet_*` ingevuld. Scope `registers:read`.","parameters":[{"name":"id","in":"path","required":true,"description":"Id van de gateway, uit `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":"Alleen registers van dit Modbus- of BACnet-apparaat.","schema":{"type":"string","format":"uuid"}},{"name":"limit","in":"query","description":"Paginagrootte, 1 tot 1000.","schema":{"type":"integer","minimum":1,"maximum":1000,"default":1000}},{"name":"offset","in":"query","description":"Aantal rijen om over te slaan.","schema":{"type":"integer","minimum":0,"default":0}}],"responses":{"200":{"description":"Een pagina met registers van de gateway.","headers":{"X-Request-Id":{"description":"Id van dit verzoek, voor support.","schema":{"type":"string"}},"X-RateLimit-Limit":{"description":"Toegestane verzoeken per minuut.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Resterende verzoeken in de huidige minuut.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Seconden tot het venster opnieuw begint.","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":"Ongeldige API-sleutel","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":"Onvoldoende 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":"Niet gevonden","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":"Limiet overschreden","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":"Interne serverfout","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":"Meetwaarden opvragen","description":"Meetgeschiedenis van de gateway binnen een tijdvenster, de nieuwste eerst tenzij `order=asc`. Het venster loopt van `since` (inclusief) tot `until` (exclusief) en is standaard de laatste 24 uur. Het mag maximaal 7 dagen beslaan, of 366 dagen als je precies één `register_id` meegeeft. Volg `meta.next_cursor` voor de volgende pagina. Scope `registers:read`.","parameters":[{"name":"id","in":"path","required":true,"description":"Id van de gateway, uit `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":"Eén register-id, of meerdere gescheiden door komma's.","schema":{"type":"string"}},{"name":"since","in":"query","description":"Begin van het venster, inclusief. Standaard `until` min 24 uur.","schema":{"type":"string","format":"date-time"}},{"name":"until","in":"query","description":"Einde van het venster, exclusief. Standaard nu.","schema":{"type":"string","format":"date-time"}},{"name":"order","in":"query","description":"Sorteren op tijd.","schema":{"type":"string","enum":["desc","asc"],"default":"desc"}},{"name":"limit","in":"query","description":"Paginagrootte, 1 tot 1000.","schema":{"type":"integer","minimum":1,"maximum":1000,"default":100}},{"name":"cursor","in":"query","description":"`meta.next_cursor` van de vorige pagina.","schema":{"type":"string"}}],"responses":{"200":{"description":"Een pagina met meetwaarden.","headers":{"X-Request-Id":{"description":"Id van dit verzoek, voor support.","schema":{"type":"string"}},"X-RateLimit-Limit":{"description":"Toegestane verzoeken per minuut.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Resterende verzoeken in de huidige minuut.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Seconden tot het venster opnieuw begint.","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":"Ongeldige 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":"Ongeldige API-sleutel","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":"Onvoldoende 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":"Niet gevonden","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":"Limiet overschreden","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":"Interne serverfout","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":"Alarmen opvragen","description":"Alarmen van je organisatie, het laatst afgegane alarm eerst. Scope `alerts:read`.","parameters":[{"name":"status","in":"query","schema":{"type":"string","enum":["active","returned","acknowledged","resolved"]},"description":"Alleen alarmen met deze status."},{"name":"severity","in":"query","schema":{"type":"string","enum":["critical","warning","info"]},"description":"Alleen alarmen met deze ernst."},{"name":"device_id","in":"query","schema":{"type":"string","format":"uuid"},"description":"Alleen alarmen van deze gateway."},{"name":"limit","in":"query","description":"Paginagrootte, 1 tot 100.","schema":{"type":"integer","minimum":1,"maximum":100,"default":50}},{"name":"offset","in":"query","description":"Aantal rijen om over te slaan.","schema":{"type":"integer","minimum":0,"default":0}}],"responses":{"200":{"description":"Een pagina met alarmen.","headers":{"X-Request-Id":{"description":"Id van dit verzoek, voor support.","schema":{"type":"string"}},"X-RateLimit-Limit":{"description":"Toegestane verzoeken per minuut.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Resterende verzoeken in de huidige minuut.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Seconden tot het venster opnieuw begint.","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":"Ongeldige API-sleutel","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":"Onvoldoende 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":"Limiet overschreden","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":"Interne serverfout","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":"Een gateway meldt zich weer, ook als hij terugkomt nadat hij als offline was gemarkeerd.","tags":["Webhook events"],"parameters":[{"name":"webhook-id","in":"header","required":true,"schema":{"type":"string"},"description":"Unieke id van het bericht, bij elke nieuwe poging hetzelfde."},{"name":"webhook-timestamp","in":"header","required":true,"schema":{"type":"string"},"description":"Unix-tijd in seconden van deze poging."},{"name":"webhook-signature","in":"header","required":true,"schema":{"type":"string"},"description":"`v1,` gevolgd door de HMAC-SHA256-handtekening in base64."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["id","type","timestamp","data"],"properties":{"id":{"type":"string","description":"Id van het bericht, gelijk aan de header `webhook-id`."},"type":{"type":"string","const":"device.online"},"timestamp":{"type":"string","format":"date-time","description":"Moment waarop het event plaatsvond."},"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":"Ontvangen. Elke 2xx-status binnen 10 seconden telt als afgeleverd."}}}},"device.offline":{"post":{"operationId":"webhook_device_offline","summary":"device.offline","description":"Een gateway meldt zich niet meer, omdat de verbinding is verbroken of omdat hij langer stil was dan zijn heartbeat-interval.","tags":["Webhook events"],"parameters":[{"name":"webhook-id","in":"header","required":true,"schema":{"type":"string"},"description":"Unieke id van het bericht, bij elke nieuwe poging hetzelfde."},{"name":"webhook-timestamp","in":"header","required":true,"schema":{"type":"string"},"description":"Unix-tijd in seconden van deze poging."},{"name":"webhook-signature","in":"header","required":true,"schema":{"type":"string"},"description":"`v1,` gevolgd door de HMAC-SHA256-handtekening in base64."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["id","type","timestamp","data"],"properties":{"id":{"type":"string","description":"Id van het bericht, gelijk aan de header `webhook-id`."},"type":{"type":"string","const":"device.offline"},"timestamp":{"type":"string","format":"date-time","description":"Moment waarop het event plaatsvond."},"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":"Ontvangen. Elke 2xx-status binnen 10 seconden telt als afgeleverd."}}}},"alert.triggered":{"post":{"operationId":"webhook_alert_triggered","summary":"alert.triggered","description":"Aan een regel is voldaan en er is een alarm geopend, of een open alarm ging opnieuw af. Bij offline-alarmen is `condition` gelijk aan `offline` en ontbreken de waardevelden.","tags":["Webhook events"],"parameters":[{"name":"webhook-id","in":"header","required":true,"schema":{"type":"string"},"description":"Unieke id van het bericht, bij elke nieuwe poging hetzelfde."},{"name":"webhook-timestamp","in":"header","required":true,"schema":{"type":"string"},"description":"Unix-tijd in seconden van deze poging."},{"name":"webhook-signature","in":"header","required":true,"schema":{"type":"string"},"description":"`v1,` gevolgd door de HMAC-SHA256-handtekening in base64."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["id","type","timestamp","data"],"properties":{"id":{"type":"string","description":"Id van het bericht, gelijk aan de header `webhook-id`."},"type":{"type":"string","const":"alert.triggered"},"timestamp":{"type":"string","format":"date-time","description":"Moment waarop het event plaatsvond."},"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":"Ontvangen. Elke 2xx-status binnen 10 seconden telt als afgeleverd."}}}},"alert.returned":{"post":{"operationId":"webhook_alert_returned","summary":"alert.returned","description":"De waarde is weer binnen de grens, of de gateway is weer online. Het alarm blijft open tot iemand het oplost.","tags":["Webhook events"],"parameters":[{"name":"webhook-id","in":"header","required":true,"schema":{"type":"string"},"description":"Unieke id van het bericht, bij elke nieuwe poging hetzelfde."},{"name":"webhook-timestamp","in":"header","required":true,"schema":{"type":"string"},"description":"Unix-tijd in seconden van deze poging."},{"name":"webhook-signature","in":"header","required":true,"schema":{"type":"string"},"description":"`v1,` gevolgd door de HMAC-SHA256-handtekening in base64."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["id","type","timestamp","data"],"properties":{"id":{"type":"string","description":"Id van het bericht, gelijk aan de header `webhook-id`."},"type":{"type":"string","const":"alert.returned"},"timestamp":{"type":"string","format":"date-time","description":"Moment waarop het event plaatsvond."},"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":"Ontvangen. Elke 2xx-status binnen 10 seconden telt als afgeleverd."}}}},"alert.acknowledged":{"post":{"operationId":"webhook_alert_acknowledged","summary":"alert.acknowledged","description":"Iemand heeft het alarm in het portaal bevestigd.","tags":["Webhook events"],"parameters":[{"name":"webhook-id","in":"header","required":true,"schema":{"type":"string"},"description":"Unieke id van het bericht, bij elke nieuwe poging hetzelfde."},{"name":"webhook-timestamp","in":"header","required":true,"schema":{"type":"string"},"description":"Unix-tijd in seconden van deze poging."},{"name":"webhook-signature","in":"header","required":true,"schema":{"type":"string"},"description":"`v1,` gevolgd door de HMAC-SHA256-handtekening in base64."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["id","type","timestamp","data"],"properties":{"id":{"type":"string","description":"Id van het bericht, gelijk aan de header `webhook-id`."},"type":{"type":"string","const":"alert.acknowledged"},"timestamp":{"type":"string","format":"date-time","description":"Moment waarop het event plaatsvond."},"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":"Ontvangen. Elke 2xx-status binnen 10 seconden telt als afgeleverd."}}}},"alert.resolved":{"post":{"operationId":"webhook_alert_resolved","summary":"alert.resolved","description":"Het alarm is gesloten.","tags":["Webhook events"],"parameters":[{"name":"webhook-id","in":"header","required":true,"schema":{"type":"string"},"description":"Unieke id van het bericht, bij elke nieuwe poging hetzelfde."},{"name":"webhook-timestamp","in":"header","required":true,"schema":{"type":"string"},"description":"Unix-tijd in seconden van deze poging."},{"name":"webhook-signature","in":"header","required":true,"schema":{"type":"string"},"description":"`v1,` gevolgd door de HMAC-SHA256-handtekening in base64."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["id","type","timestamp","data"],"properties":{"id":{"type":"string","description":"Id van het bericht, gelijk aan de header `webhook-id`."},"type":{"type":"string","const":"alert.resolved"},"timestamp":{"type":"string","format":"date-time","description":"Moment waarop het event plaatsvond."},"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":"Ontvangen. Elke 2xx-status binnen 10 seconden telt als afgeleverd."}}}},"automation.triggered":{"post":{"operationId":"webhook_automation_triggered","summary":"automation.triggered","description":"Een automatisering met een webhookactie is uitgevoerd.","tags":["Webhook events"],"parameters":[{"name":"webhook-id","in":"header","required":true,"schema":{"type":"string"},"description":"Unieke id van het bericht, bij elke nieuwe poging hetzelfde."},{"name":"webhook-timestamp","in":"header","required":true,"schema":{"type":"string"},"description":"Unix-tijd in seconden van deze poging."},{"name":"webhook-signature","in":"header","required":true,"schema":{"type":"string"},"description":"`v1,` gevolgd door de HMAC-SHA256-handtekening in base64."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["id","type","timestamp","data"],"properties":{"id":{"type":"string","description":"Id van het bericht, gelijk aan de header `webhook-id`."},"type":{"type":"string","const":"automation.triggered"},"timestamp":{"type":"string","format":"date-time","description":"Moment waarop het event plaatsvond."},"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":"Ontvangen. Elke 2xx-status binnen 10 seconden telt als afgeleverd."}}}}},"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"mlk_...","description":"Een API-sleutel uit Instellingen, API-sleutels in het portaal. Op deze pagina is de sandboxsleutel al voor je ingevuld."}},"schemas":{"Problem":{"type":"object","description":"Fout in het problem details-formaat van 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":"Geef mee als `cursor` voor de volgende pagina. Null op de laatste pagina."}}},"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":"Gelijk aan gateways, blijft bestaan voor oudere clients."},"open_alerts":{"type":"integer"}}}}},"Customer":{"type":"object","description":"De locatie of klant waaraan een gateway is toegewezen.","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"address":{"type":["string","null"],"description":"Adres van de locatie. Alleen 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":"Adres op het bekabelde netwerk."},"ip_wifi":{"type":["string","null"]},"ip_4g":{"type":["string","null"],"description":"Adres op het 4G-netwerk."},"signal_4g":{"type":["integer","null"],"description":"Signaalsterkte 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":"Een Modbus apparaat (`rtu`, `tcp`) of BACnet/IP-apparaat (`bacnet_ip`) achter de gateway.","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":["string","null"]},"slave_id":{"type":"integer","description":"Modbus unit id. Voor bacnet_ip een intern slot 300..999."},"protocol":{"type":"string","enum":["rtu","tcp","bacnet_ip"]},"ip_address":{"type":["string","null"],"description":"Voor Modbus TCP en BACnet/IP. Achter een BACnet-router het adres van de router."},"port":{"type":["integer","null"],"description":"Voor Modbus TCP en BACnet/IP (standaard 47808)."},"poll_interval_ms":{"type":["integer","null"]},"bacnet_device_instance":{"type":["integer","null"],"description":"BACnet device instance, 0 tot 4194302. Alleen voor bacnet_ip."},"bacnet_network":{"type":["integer","null"],"description":"BACnet-netwerknummer achter een BACnet-router (1 tot 65534), anders null."},"bacnet_mac":{"type":["string","null"],"description":"BACnet-MAC-adres achter die router, in hex met kleine letters (MS/TP-adres 10 is `0a`), anders 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":"Registeradres. Voor een BACnet-punt een intern nummer, uniek op de gateway."},"function_code":{"type":["integer","null"],"description":"3 holding register, 4 input register. Null voor een BACnet-punt."},"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-objecttype, bijvoorbeeld 0 analog-input, 3 binary-input, 13 multi-state-input. Null voor Modbus."},"bacnet_object_instance":{"type":["integer","null"],"description":"BACnet-objectinstantie. Null voor Modbus."},"bacnet_property_id":{"type":["integer","null"],"description":"BACnet-property die wordt gelezen, 85 is Present_Value. Null voor Modbus."},"bacnet_array_index":{"type":["integer","null"],"description":"Array-index van die property, of null voor de hele waarde."},"bacnet_write_priority":{"type":["integer","null"],"description":"BACnet-schrijfprioriteit. Voorlopig altijd null, omdat BACnet-punten alleen gelezen worden."},"latest_value":{"type":["number","null"],"description":"Laatste waarde, omgerekend met de schaalfactor."},"latest_raw_value":{"type":["number","null"],"description":"Laatste waarde zoals gelezen uit het register."},"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":"Omgerekend met de schaalfactor, in de eenheid van het register."},"raw_value":{"type":["number","null"],"description":"Zoals gelezen uit het register."},"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 van de gebruiker die het alarm heeft bevestigd."},"ack_note":{"type":["string","null"]},"resolved_at":{"type":["string","null"],"format":"date-time"},"resolved_by":{"type":["string","null"],"format":"uuid","description":"Id van de gebruiker die het alarm heeft opgelost."},"resolve_note":{"type":["string","null"]},"entry_count":{"type":"integer","description":"Hoe vaak het alarm afging terwijl het open stond."},"reminder_at":{"type":["string","null"],"format":"date-time","description":"Moment waarop een herinnering uit het portaal afgaat. Null zonder herinnering."},"reminder_sent":{"type":["boolean","null"],"description":"Of die herinnering al is verstuurd."}}},"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":"Laatste keer dat de gateway zich meldde."}}},"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":"Vergelijking van de regel, of `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` als de gateway weer online is."},"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"}}}}}}}