# ModbusCloud API

Lees data van gateways, registers, meetwaarden en alarmen, en ontvang events als webhooks.

Base URL: `https://api.modbuscloud.com/v1`. Dezelfde documentatie met de knop Uitproberen staat op https://docs.modbuscloud.com/nl, het OpenAPI-document op https://docs.modbuscloud.com/nl/openapi.json. De voorbeelden hieronder gebruiken de openbare sandboxsleutel, dus je kunt ze zo uitvoeren.

Met 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.

## Snel aan de slag

Voor 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.

```
mlk_72718174d83aa7fa5238c5eb8df5adc3e432c72cc80ea3242821f3aaabd9f630
```

Controleer of de sleutel werkt:

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

Vraag de gateways op en haal daarna de actuele waarden van een ervan op:

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

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

Ook de knoppen **Uitproberen** op deze pagina zijn al ingevuld met de sandboxsleutel.

## Begrippen

| Begrip | Betekenis |
|---|---|
| Gateway | De ModbusCloud Gateway op locatie. In de API-paden heet een gateway `device`, bijvoorbeeld `/devices/{id}`. |
| 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. |
| Register | Eén waarde van een Modbus apparaat, met een naam, een eenheid en een schaalfactor. |
| Meetwaarde | Eén opgeslagen waarde van een register op een bepaald moment. |
| Alarm | Ontstaat als aan een regel wordt voldaan, bijvoorbeeld een waarde boven een grens of een gateway die offline gaat. |

**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.

**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.

**Tijd.** Alle tijdstempels zijn ISO 8601 in UTC.

## Authenticatie

Stuur de sleutel bij elk verzoek mee als bearer token.

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

Eigenaren 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.

| Scope | Geeft toegang tot |
|---|---|
| `devices:read` | Gateways en hun Modbus apparaten |
| `registers:read` | Registers, laatste waarden en meetgeschiedenis |
| `alerts:read` | Alarmen |

Sleutels kunnen verlopen en je kunt ze op elk moment intrekken in het portaal.

Schrijven 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.

## Paginering

Gateways en alarmen gebruiken `limit` (1 tot 100, standaard 50) en `offset`, en geven `meta.total` terug.

Registers 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.

Meetwaarden 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.

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

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

Wil 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.

## Fouten

Fouten gebruiken het problem details-formaat van RFC 9457, met content type `application/problem+json`.

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

Gebruik `code` in je logica, want die blijft gelijk. `detail` is bedoeld voor mensen en kan veranderen.

| Status | code | Wanneer |
|---|---|---|
| 400 | `invalid_parameter` | Een queryparameter ontbreekt, is ongeldig of valt buiten het bereik |
| 400 | `bad_request` | De request body is geen geldige JSON, of een veld erin ontbreekt of is ongeldig |
| 401 | `missing_api_key` | Geen header `Authorization: Bearer` |
| 401 | `invalid_api_key` | De sleutel bestaat niet |
| 401 | `api_key_revoked` | De sleutel is ingetrokken in het portaal |
| 401 | `api_key_expired` | De sleutel is verlopen |
| 403 | `insufficient_scope` | De sleutel mist de scope die dit endpoint nodig heeft |
| 403 | `write_not_enabled` | Schrijven staat voor deze gateway niet aan |
| 404 | `not_found` | De gateway, het register of het alarm hoort niet bij je organisatie |
| 422 | `bacnet_write_unsupported` | Het register is een BACnet-punt, en schrijven naar BACnet-punten kan nog niet |
| 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 |
| 500 | `internal_error` | Er ging iets mis aan onze kant |
| 502 | `publish_failed` | De schrijfopdracht kon niet naar de gateway worden gestuurd |
| 503 | `gateway_offline` | De gateway is offline, de schrijfopdracht is niet verstuurd |

Elk antwoord bevat een header `X-Request-Id`. Noem die als je contact met ons opneemt over een verzoek.

## Taal

Foutmeldingen en tekstvelden volgen `Accept-Language` (`en`, `nl`, `de`), met Engels als standaard. Het antwoord bevat `Content-Language`.

## Limieten

Elke 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.

| Header | Betekenis |
|---|---|
| `X-RateLimit-Limit` | Toegestane verzoeken per minuut |
| `X-RateLimit-Remaining` | Resterende verzoeken in de huidige minuut |
| `X-RateLimit-Reset` | Seconden tot het venster opnieuw begint |
| `Retry-After` | Alleen bij een 429, het aantal seconden dat je moet wachten |

Vraag 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.

## Webhooks

Webhooks 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.

Elke aflevering heeft dezelfde envelop.

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

### De handtekening controleren

Afleveringen zijn ondertekend volgens de specificatie van [Standard Webhooks](https://www.standardwebhooks.com), dus je kunt hun bibliotheken direct gebruiken.

| Header | Inhoud |
|---|---|
| `webhook-id` | Unieke id van het bericht. Bij elke nieuwe poging hetzelfde. |
| `webhook-timestamp` | Unix-tijd in seconden van deze poging |
| `webhook-signature` | `v1,` gevolgd door de HMAC-SHA256-handtekening in base64 |
| `X-ModbusCloud-Event` | Het type event, hetzelfde als `type` in de body |

Node.js met `npm install standardwebhooks`:

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

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

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

Python met `pip install standardwebhooks`:

```python
from standardwebhooks.webhooks import Webhook

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

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

In 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.

Controleer 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.

### Aflevering en nieuwe pogingen

- Antwoord binnen 10 seconden met een willekeurige 2xx-status. Verwerk het event pas nadat je hebt geantwoord.
- Een aflevering mislukt bij een status buiten 2xx, een time-out of een redirect. Redirects worden niet gevolgd.
- 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.
- Nieuwe pogingen hebben dezelfde `webhook-id`. Bewaar de ids die je hebt verwerkt en sla dubbele over.
- De volgorde van afleveringen is niet gegarandeerd. Gebruik `timestamp` en de `status` van het alarm om te bepalen wat actueel is.
- Na tien afleveringen op rij waarvan elke poging mislukte, wordt het endpoint gepauzeerd. Zet het in het portaal weer aan.
- Endpoints moeten via het openbare internet bereikbaar zijn over http of https. Gebruik https.

## Versies

Dit 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.

## Support

Vragen, of werkt er iets niet? Mail naar [info@modbuscloud.com](mailto:info@modbuscloud.com) en vermeld de `X-Request-Id`.

## Endpoints

### Sleutel

Controleer de sleutel die je gebruikt.

#### Je API-sleutel controleren

`GET /introspect`

Geeft de naam van de sleutel, de scopes en de organisatie waar hij bij hoort. Elke geldige sleutel mag dit aanroepen.

| Status | Betekenis |
|---|---|
| 200 | De sleutel en zijn organisatie. |
| 401 | Ongeldige API-sleutel |
| 403 | Onvoldoende scope |
| 429 | Limiet overschreden |
| 500 | Interne serverfout |

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

### Gateways

Gateways en de Modbus apparaten erachter. In de paden heet een gateway `device`.

#### Gateways opvragen

`GET /devices`

Alle gateways van je organisatie, de laatst geziene eerst. Scope `devices:read`.

| Parameter | In | Type | Verplicht | Beschrijving |
|---|---|---|---|---|
| `status` | query | string: `online`, `offline`, `pending`, `error` | nee | Alleen gateways met deze status. |
| `limit` | query | integer, standaard `50` | nee | Paginagrootte, 1 tot 100. |
| `offset` | query | integer, standaard `0` | nee | Aantal rijen om over te slaan. |

| Status | Betekenis |
|---|---|
| 200 | Een pagina met gateways. |
| 401 | Ongeldige API-sleutel |
| 403 | Onvoldoende scope |
| 429 | Limiet overschreden |
| 500 | Interne serverfout |

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

#### Een gateway opvragen

`GET /devices/{id}`

Eén gateway met de klant en de Modbus apparaten die hij uitleest. Scope `devices:read`.

| Parameter | In | Type | Verplicht | Beschrijving |
|---|---|---|---|---|
| `id` | path | string (uuid) | ja | Id van de gateway, uit `GET /devices`. |

| Status | Betekenis |
|---|---|
| 200 | De gateway. |
| 401 | Ongeldige API-sleutel |
| 403 | Onvoldoende scope |
| 404 | Niet gevonden |
| 429 | Limiet overschreden |
| 500 | Interne serverfout |

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

### Registers

Registers van een gateway met hun laatste waarden.

#### Registers met laatste waarden opvragen

`GET /devices/{id}/registers`

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`.

| Parameter | In | Type | Verplicht | Beschrijving |
|---|---|---|---|---|
| `id` | path | string (uuid) | ja | Id van de gateway, uit `GET /devices`. |
| `modbus_device_id` | query | string (uuid) | nee | Alleen registers van dit Modbus- of BACnet-apparaat. |
| `limit` | query | integer, standaard `1000` | nee | Paginagrootte, 1 tot 1000. |
| `offset` | query | integer, standaard `0` | nee | Aantal rijen om over te slaan. |

| Status | Betekenis |
|---|---|
| 200 | Een pagina met registers van de gateway. |
| 401 | Ongeldige API-sleutel |
| 403 | Onvoldoende scope |
| 404 | Niet gevonden |
| 429 | Limiet overschreden |
| 500 | Interne serverfout |

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

### Meetwaarden

Meetgeschiedenis van een gateway, in pagina's met een cursor.

#### Meetwaarden opvragen

`GET /devices/{id}/readings`

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`.

| Parameter | In | Type | Verplicht | Beschrijving |
|---|---|---|---|---|
| `id` | path | string (uuid) | ja | Id van de gateway, uit `GET /devices`. |
| `register_id` | query | string | nee | Eén register-id, of meerdere gescheiden door komma's. |
| `since` | query | string (date-time) | nee | Begin van het venster, inclusief. Standaard `until` min 24 uur. |
| `until` | query | string (date-time) | nee | Einde van het venster, exclusief. Standaard nu. |
| `order` | query | string: `desc`, `asc`, standaard `desc` | nee | Sorteren op tijd. |
| `limit` | query | integer, standaard `100` | nee | Paginagrootte, 1 tot 1000. |
| `cursor` | query | string | nee | `meta.next_cursor` van de vorige pagina. |

| Status | Betekenis |
|---|---|
| 200 | Een pagina met meetwaarden. |
| 400 | Ongeldige parameter |
| 401 | Ongeldige API-sleutel |
| 403 | Onvoldoende scope |
| 404 | Niet gevonden |
| 429 | Limiet overschreden |
| 500 | Interne serverfout |

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

### Alarmen

Alarmen van je organisatie.

#### Alarmen opvragen

`GET /alerts`

Alarmen van je organisatie, het laatst afgegane alarm eerst. Scope `alerts:read`.

| Parameter | In | Type | Verplicht | Beschrijving |
|---|---|---|---|---|
| `status` | query | string: `active`, `returned`, `acknowledged`, `resolved` | nee | Alleen alarmen met deze status. |
| `severity` | query | string: `critical`, `warning`, `info` | nee | Alleen alarmen met deze ernst. |
| `device_id` | query | string (uuid) | nee | Alleen alarmen van deze gateway. |
| `limit` | query | integer, standaard `50` | nee | Paginagrootte, 1 tot 100. |
| `offset` | query | integer, standaard `0` | nee | Aantal rijen om over te slaan. |

| Status | Betekenis |
|---|---|
| 200 | Een pagina met alarmen. |
| 401 | Ongeldige API-sleutel |
| 403 | Onvoldoende scope |
| 429 | Limiet overschreden |
| 500 | Interne serverfout |

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

## Webhook-events

Elk event is een POST naar je endpoint, met de envelop en handtekening die hierboven onder Webhooks staan beschreven.

### device.online

Een gateway meldt zich weer, ook als hij terugkomt nadat hij als offline was gemarkeerd.

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

### device.offline

Een gateway meldt zich niet meer, omdat de verbinding is verbroken of omdat hij langer stil was dan zijn heartbeat-interval.

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

### alert.triggered

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.

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

### alert.returned

De waarde is weer binnen de grens, of de gateway is weer online. Het alarm blijft open tot iemand het oplost.

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

### alert.acknowledged

Iemand heeft het alarm in het portaal bevestigd.

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

### alert.resolved

Het alarm is gesloten.

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

### automation.triggered

Een automatisering met een webhookactie is uitgevoerd.

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

## Schema's

### Problem

Fout in het problem details-formaat van RFC 9457.

| Veld | Type | Beschrijving |
|---|---|---|
| `type` (verplicht) | string (uri) |  |
| `title` (verplicht) | string |  |
| `status` (verplicht) | integer |  |
| `detail` | string |  |
| `code` (verplicht) | string: `invalid_parameter`, `bad_request`, `missing_api_key`, `invalid_api_key`, `api_key_revoked`, `api_key_expired`, `insufficient_scope`, `write_not_enabled`, `bacnet_write_unsupported`, `not_found`, `conflict`, `rate_limited`, `internal_error`, `publish_failed`, `gateway_offline` |  |
| `request_id` (verplicht) | string |  |

### OffsetMeta

| Veld | Type | Beschrijving |
|---|---|---|
| `total` | integer |  |
| `limit` | integer |  |
| `offset` | integer |  |

### CursorMeta

| Veld | Type | Beschrijving |
|---|---|---|
| `since` | string (date-time) |  |
| `until` | string (date-time) |  |
| `order` | string: `asc`, `desc` |  |
| `limit` | integer |  |
| `has_more` | boolean |  |
| `next_cursor` | string, of null | Geef mee als `cursor` voor de volgende pagina. Null op de laatste pagina. |

### Introspection

| Veld | Type | Beschrijving |
|---|---|---|
| `key` | object |  |
| `organization` | object |  |
| `stats` | object |  |

### Customer

De locatie of klant waaraan een gateway is toegewezen.

| Veld | Type | Beschrijving |
|---|---|---|
| `id` | string (uuid) |  |
| `name` | string |  |
| `address` | string, of null | Adres van de locatie. Alleen in `GET /devices/{id}`. |
| `city` | string, of null |  |

### Gateway

| Veld | Type | Beschrijving |
|---|---|---|
| `id` | string (uuid) |  |
| `serial` | string |  |
| `name` | string |  |
| `status` | string: `online`, `offline`, `pending`, `error` |  |
| `firmware_ver` | string, of null |  |
| `ip_eth` | string, of null | Adres op het bekabelde netwerk. |
| `ip_wifi` | string, of null |  |
| `ip_4g` | string, of null | Adres op het 4G-netwerk. |
| `signal_4g` | integer, of null | Signaalsterkte in dBm. |
| `last_seen` | string (date-time), of null |  |
| `created_at` | string (date-time) |  |
| `customer` | Customer |  |

### ModbusDevice

Een Modbus apparaat (`rtu`, `tcp`) of BACnet/IP-apparaat (`bacnet_ip`) achter de gateway.

| Veld | Type | Beschrijving |
|---|---|---|
| `id` | string (uuid) |  |
| `name` | string, of null |  |
| `slave_id` | integer | Modbus unit id. Voor bacnet_ip een intern slot 300..999. |
| `protocol` | string: `rtu`, `tcp`, `bacnet_ip` |  |
| `ip_address` | string, of null | Voor Modbus TCP en BACnet/IP. Achter een BACnet-router het adres van de router. |
| `port` | integer, of null | Voor Modbus TCP en BACnet/IP (standaard 47808). |
| `poll_interval_ms` | integer, of null |  |
| `bacnet_device_instance` | integer, of null | BACnet device instance, 0 tot 4194302. Alleen voor bacnet_ip. |
| `bacnet_network` | integer, of null | BACnet-netwerknummer achter een BACnet-router (1 tot 65534), anders null. |
| `bacnet_mac` | string, of null | BACnet-MAC-adres achter die router, in hex met kleine letters (MS/TP-adres 10 is `0a`), anders null. |
| `template` | object, of null |  |

### GatewayDetail

Alle velden van Gateway, aangevuld met:

| Veld | Type | Beschrijving |
|---|---|---|
| `claimed_at` | string (date-time), of null |  |
| `modbus_devices` | array van ModbusDevice |  |

### Register

| Veld | Type | Beschrijving |
|---|---|---|
| `id` | string (uuid) |  |
| `modbus_device_id` | string (uuid) |  |
| `modbus_device_name` | string, of null |  |
| `name` | string |  |
| `address` | integer | Registeradres. Voor een BACnet-punt een intern nummer, uniek op de gateway. |
| `function_code` | integer, of null | 3 holding register, 4 input register. Null voor een BACnet-punt. |
| `data_type` | string |  |
| `unit` | string, of null |  |
| `scale_factor` | number, of null | value = raw_value × scale_factor |
| `is_writable` | boolean |  |
| `description` | string, of null |  |
| `bacnet_object_type` | integer, of null | BACnet-objecttype, bijvoorbeeld 0 analog-input, 3 binary-input, 13 multi-state-input. Null voor Modbus. |
| `bacnet_object_instance` | integer, of null | BACnet-objectinstantie. Null voor Modbus. |
| `bacnet_property_id` | integer, of null | BACnet-property die wordt gelezen, 85 is Present_Value. Null voor Modbus. |
| `bacnet_array_index` | integer, of null | Array-index van die property, of null voor de hele waarde. |
| `bacnet_write_priority` | integer, of null | BACnet-schrijfprioriteit. Voorlopig altijd null, omdat BACnet-punten alleen gelezen worden. |
| `latest_value` | number, of null | Laatste waarde, omgerekend met de schaalfactor. |
| `latest_raw_value` | number, of null | Laatste waarde zoals gelezen uit het register. |
| `latest_ts` | string (date-time), of null |  |

### Reading

| Veld | Type | Beschrijving |
|---|---|---|
| `register_id` | string (uuid) |  |
| `modbus_device_id` | string (uuid), of null |  |
| `name` | string, of null |  |
| `unit` | string, of null |  |
| `value` | number, of null | Omgerekend met de schaalfactor, in de eenheid van het register. |
| `raw_value` | number, of null | Zoals gelezen uit het register. |
| `ts` | string (date-time) |  |

### Alert

| Veld | Type | Beschrijving |
|---|---|---|
| `id` | string (uuid) |  |
| `device_id` | string (uuid), of null |  |
| `rule_id` | string (uuid), of null |  |
| `severity` | string: `critical`, `warning`, `info` |  |
| `message` | string, of null |  |
| `status` | string: `active`, `returned`, `acknowledged`, `resolved` |  |
| `value` | number, of null |  |
| `created_at` | string (date-time) |  |
| `last_triggered_at` | string (date-time), of null |  |
| `returned_at` | string (date-time), of null |  |
| `ack_at` | string (date-time), of null |  |
| `ack_by` | string (uuid), of null | Id van de gebruiker die het alarm heeft bevestigd. |
| `ack_note` | string, of null |  |
| `resolved_at` | string (date-time), of null |  |
| `resolved_by` | string (uuid), of null | Id van de gebruiker die het alarm heeft opgelost. |
| `resolve_note` | string, of null |  |
| `entry_count` | integer | Hoe vaak het alarm afging terwijl het open stond. |
| `reminder_at` | string (date-time), of null | Moment waarop een herinnering uit het portaal afgaat. Null zonder herinnering. |
| `reminder_sent` | boolean, of null | Of die herinnering al is verstuurd. |

### DeviceStatusEvent

| Veld | Type | Beschrijving |
|---|---|---|
| `device_id` | string (uuid) |  |
| `serial` | string |  |
| `status` | string: `online`, `offline` |  |
| `previous_status` | string, of null |  |
| `last_seen` | string (date-time), of null | Laatste keer dat de gateway zich meldde. |

### AlertTriggeredEvent

| Veld | Type | Beschrijving |
|---|---|---|
| `alert_id` | string (uuid) |  |
| `rule_id` | string (uuid) |  |
| `rule_name` | string |  |
| `device_id` | string (uuid) |  |
| `severity` | string: `critical`, `warning`, `info` |  |
| `value` | number |  |
| `threshold` | number |  |
| `condition` | string | Vergelijking van de regel, of `offline`. |
| `message` | string |  |
| `source` | string: `rule`, `detector` |  |
| `register_id` | string (uuid), of null |  |
| `modbus_device_id` | string (uuid), of null |  |

### AlertReturnedEvent

| Veld | Type | Beschrijving |
|---|---|---|
| `alert_id` | string (uuid) |  |
| `rule_id` | string (uuid) |  |
| `rule_name` | string |  |
| `device_id` | string (uuid) |  |
| `severity` | string |  |
| `value` | number |  |
| `condition` | string | `offline` als de gateway weer online is. |
| `source` | string: `rule`, `detector` |  |

### AlertStatusEvent

| Veld | Type | Beschrijving |
|---|---|---|
| `alert_id` | string (uuid) |  |
| `device_id` | string (uuid), of null |  |
| `rule_id` | string (uuid), of null |  |
| `severity` | string |  |
| `message` | string |  |
| `status` | string: `acknowledged`, `resolved` |  |
| `value` | number, of null |  |
| `acknowledged_at` | string (date-time), of null |  |
| `resolved_at` | string (date-time), of null |  |
| `note` | string, of null |  |

### AutomationEvent

| Veld | Type | Beschrijving |
|---|---|---|
| `rule_id` | string (uuid) |  |
| `rule_name` | string |  |
| `actions` | array van object |  |
