# ModbusCloud API

Read gateway, register, reading and alert data, and receive events as webhooks.

Base URL: `https://api.modbuscloud.com/v1`. The same documentation with Try it is at https://docs.modbuscloud.com, the OpenAPI document at https://docs.modbuscloud.com/openapi.json. The examples below use the public sandbox key, so you can run them as they are.

The ModbusCloud API gives your own systems the data our gateways read from Modbus equipment. You get the gateways, the Modbus devices behind them, registers with their latest values, the reading history and alerts. Webhooks push events to your endpoint the moment they happen.

## Quickstart

Every request needs an API key. To try the API right away, use the sandbox key below. It is read only and points at our demo organisation, where the gateways send new readings every minute. Everyone shares this key, so it allows 60 requests per minute per visitor.

```
mlk_72718174d83aa7fa5238c5eb8df5adc3e432c72cc80ea3242821f3aaabd9f630
```

Check that the key works:

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

List the gateways, then fetch the current values of one of them:

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

The **Try it** buttons on this page are filled in with the sandbox key as well.

## Concepts

| Term | Meaning |
|---|---|
| Gateway | The ModbusCloud Gateway on site. In the API paths a gateway is a `device`, for example `/devices/{id}`. |
| Modbus device | Equipment the gateway reads over Modbus RTU or Modbus TCP, such as a climate computer, a meter or a heat pump. One gateway can read many. |
| Register | One value of a Modbus device, with a name, a unit and a scale factor. |
| Reading | One stored value of a register at a point in time. |
| Alert | Raised when a rule is met, for example a value above a limit or a gateway going offline. |

**Values.** `value` and `latest_value` are in engineering units, so with the scale factor applied, exactly as the portal shows them. `raw_value` is the number as read from the register.

**History.** By default the history holds one value per register every five minutes, and at most one per minute. That depends on how often the gateway reads, which you set in the portal. Readings are kept for 12 months by default. Live values in the portal can be faster than that.

**Time.** All timestamps are ISO 8601 in UTC.

## Authentication

Send the key as a bearer token on every request.

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

Owners and admins create keys in the portal under **Settings, API keys**. A key is shown once, so store it right away. Each key belongs to one organisation and carries scopes.

| Scope | Gives access to |
|---|---|
| `devices:read` | Gateways and their Modbus devices |
| `registers:read` | Registers, latest values and reading history |
| `alerts:read` | Alerts |

Keys can expire and can be revoked in the portal at any time.

Writing to registers is off for every gateway until we switch it on. Request it per gateway on the Control tab in the portal. Until then a write to that gateway is answered with 403 `write_not_enabled`, whatever the key's scopes.

## Pagination

Gateways and alerts use `limit` (1 to 100, default 50) and `offset`, and return `meta.total`.

Registers use `limit` (1 to 1000, default 1000) and `offset`, and return `meta.total`. A gateway with a large BACnet device can have more than 1000 registers. Request the next page with `offset` until you have `meta.total` rows.

Readings use a cursor, because the history is large. Every page returns `meta.has_more` and `meta.next_cursor`. Pass `next_cursor` as `cursor` to get the next page, with the same other parameters. Rows are never skipped or repeated, also while new readings arrive.

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

To keep a copy of the history in your own database, request `order=asc` with `since` set to the last timestamp you stored, and follow `next_cursor` until `has_more` is false.

## Errors

Errors use the problem details format of RFC 9457, with 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"
}
```

Branch on `code`, which is stable. `detail` is meant for people and can change.

| Status | code | When |
|---|---|---|
| 400 | `invalid_parameter` | A query parameter is missing, malformed or out of range |
| 400 | `bad_request` | The request body is not valid JSON, or a field in it is missing or invalid |
| 401 | `missing_api_key` | No `Authorization: Bearer` header |
| 401 | `invalid_api_key` | The key does not exist |
| 401 | `api_key_revoked` | The key was revoked in the portal |
| 401 | `api_key_expired` | The key passed its expiry date |
| 403 | `insufficient_scope` | The key lacks the scope this endpoint needs |
| 403 | `write_not_enabled` | Writing is not switched on for this gateway |
| 404 | `not_found` | The gateway, register or alert is not in your organisation |
| 422 | `bacnet_write_unsupported` | The register is a BACnet point, and writing to BACnet points is not supported yet |
| 429 | `rate_limited` | More than 100 requests in the current minute, or the write limit of the gateway or organisation. `Retry-After` says how many seconds to wait |
| 500 | `internal_error` | Something failed on our side |
| 502 | `publish_failed` | The write command could not be sent to the gateway |
| 503 | `gateway_offline` | The gateway is offline, so the write command was not sent |

Every response carries an `X-Request-Id` header. Mention it when you contact us about a request.

## Language

Errors and text fields follow `Accept-Language` (`en`, `nl`, `de`), with English as the default. The response carries `Content-Language`.

## Rate limits

Each key may make 100 requests per minute. The window resets at the start of every minute. The shared sandbox key is counted per visitor, 60 requests per minute each. Every response tells you where you stand.

| Header | Meaning |
|---|---|
| `X-RateLimit-Limit` | Requests allowed per minute |
| `X-RateLimit-Remaining` | Requests left in the current minute |
| `X-RateLimit-Reset` | Seconds until the window resets |
| `Retry-After` | On a 429 only, seconds to wait |

Polling the registers of 50 gateways once a minute uses half of the budget. Use webhooks for events instead of polling alerts.

## Webhooks

Webhooks send an HTTP POST to your endpoint when something happens. Owners and admins add endpoints in the portal under **Settings, Webhooks**, pick the events and copy the signing secret. The events and their payloads are listed under **Webhooks** in the menu on this page.

Every delivery has the same envelope.

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

### Verifying the signature

Deliveries are signed according to the [Standard Webhooks](https://www.standardwebhooks.com) specification, so you can use their libraries directly.

| Header | Content |
|---|---|
| `webhook-id` | Unique id of the message. The same on every retry. |
| `webhook-timestamp` | Unix time in seconds of this attempt |
| `webhook-signature` | `v1,` followed by the base64 HMAC-SHA256 signature |
| `X-ModbusCloud-Event` | The event type, the same as `type` in the body |

Node.js with `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 with `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 any other language, compute HMAC-SHA256 over `{webhook-id}.{webhook-timestamp}.{raw body}` with the secret as key, where the key is the part after `whsec_` decoded from base64. Base64-encode the result and compare it with the value after `v1,` in a constant-time comparison. Reject messages with a timestamp more than five minutes from your clock.

Always verify against the raw body as received. Parsing and serialising the JSON first changes the bytes and breaks the signature.

### Delivery and retries

- Respond with any 2xx status within 10 seconds. Do the processing after you have answered.
- A delivery fails on a non-2xx status, a timeout or a redirect. Redirects are not followed.
- Failed deliveries are retried after 30 seconds, 2 minutes, 10 minutes, 1 hour and 6 hours, so six attempts over a little more than seven hours.
- Retries carry the same `webhook-id`. Store the ids you processed and skip duplicates.
- The order of deliveries is not guaranteed. Use `timestamp` and the alert `status` to decide what is current.
- After ten deliveries in a row that failed every attempt, the endpoint is paused. Switch it back on in the portal.
- Endpoints must be reachable on the public internet over http or https. Use https.

## Versioning

This is version 1. We add endpoints, fields and events without notice, so ignore fields you do not know. Changes that could break an integration come as a new version, announced in advance.

## Support

Questions or something not working? Mail [info@modbuscloud.com](mailto:info@modbuscloud.com) and include the `X-Request-Id`.

## Endpoints

### Key

Check the key you are using.

#### Check your API key

`GET /introspect`

Returns the key name, its scopes and the organisation it belongs to. Any valid key may call this.

| Status | Meaning |
|---|---|
| 200 | The key and its organisation. |
| 401 | Invalid API key |
| 403 | Insufficient scope |
| 429 | Rate limit exceeded |
| 500 | Internal server error |

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

### Gateways

Gateways and the Modbus devices behind them. A gateway is a `device` in the paths.

#### List gateways

`GET /devices`

All gateways of your organisation, most recently seen first. Scope `devices:read`.

| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
| `status` | query | string: `online`, `offline`, `pending`, `error` | no | Only gateways with this status. |
| `limit` | query | integer, default `50` | no | Page size, 1 to 100. |
| `offset` | query | integer, default `0` | no | Rows to skip. |

| Status | Meaning |
|---|---|
| 200 | A page of gateways. |
| 401 | Invalid API key |
| 403 | Insufficient scope |
| 429 | Rate limit exceeded |
| 500 | Internal server error |

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

#### Get a gateway

`GET /devices/{id}`

One gateway with its customer and the Modbus devices it reads. Scope `devices:read`.

| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
| `id` | path | string (uuid) | yes | Gateway id, from `GET /devices`. |

| Status | Meaning |
|---|---|
| 200 | The gateway. |
| 401 | Invalid API key |
| 403 | Insufficient scope |
| 404 | Not found |
| 429 | Rate limit exceeded |
| 500 | Internal server error |

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

### Registers

Registers of a gateway with their latest values.

#### List registers with latest values

`GET /devices/{id}/registers`

The registers of the gateway with their latest value, in pages ordered by display order and address. Poll this for the current state. BACnet points are registers too, with the `bacnet_*` fields filled in. Scope `registers:read`.

| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
| `id` | path | string (uuid) | yes | Gateway id, from `GET /devices`. |
| `modbus_device_id` | query | string (uuid) | no | Only registers of this field device (Modbus or BACnet). |
| `limit` | query | integer, default `1000` | no | Page size, 1 to 1000. |
| `offset` | query | integer, default `0` | no | Rows to skip. |

| Status | Meaning |
|---|---|
| 200 | A page of registers of the gateway. |
| 401 | Invalid API key |
| 403 | Insufficient scope |
| 404 | Not found |
| 429 | Rate limit exceeded |
| 500 | Internal server error |

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

### Readings

Reading history of a gateway, paged with a cursor.

#### List readings

`GET /devices/{id}/readings`

Reading history of the gateway inside a time window, newest first unless `order=asc`. The window is `since` (inclusive) to `until` (exclusive) and defaults to the last 24 hours. It can be at most 7 days, or 366 days when you pass exactly one `register_id`. Follow `meta.next_cursor` for the next page. Scope `registers:read`.

| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
| `id` | path | string (uuid) | yes | Gateway id, from `GET /devices`. |
| `register_id` | query | string | no | One register id, or several separated by commas. |
| `since` | query | string (date-time) | no | Start of the window, inclusive. Default `until` minus 24 hours. |
| `until` | query | string (date-time) | no | End of the window, exclusive. Default now. |
| `order` | query | string: `desc`, `asc`, default `desc` | no | Sort by time. |
| `limit` | query | integer, default `100` | no | Page size, 1 to 1000. |
| `cursor` | query | string | no | `meta.next_cursor` of the previous page. |

| Status | Meaning |
|---|---|
| 200 | A page of readings. |
| 400 | Invalid parameter |
| 401 | Invalid API key |
| 403 | Insufficient scope |
| 404 | Not found |
| 429 | Rate limit exceeded |
| 500 | Internal server error |

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

### Alerts

Alerts of your organisation.

#### List alerts

`GET /alerts`

Alerts of your organisation, most recently triggered first. Scope `alerts:read`.

| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
| `status` | query | string: `active`, `returned`, `acknowledged`, `resolved` | no | Only alerts with this status. |
| `severity` | query | string: `critical`, `warning`, `info` | no | Only alerts with this severity. |
| `device_id` | query | string (uuid) | no | Only alerts of this gateway. |
| `limit` | query | integer, default `50` | no | Page size, 1 to 100. |
| `offset` | query | integer, default `0` | no | Rows to skip. |

| Status | Meaning |
|---|---|
| 200 | A page of alerts. |
| 401 | Invalid API key |
| 403 | Insufficient scope |
| 429 | Rate limit exceeded |
| 500 | Internal server error |

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

## Webhook events

Every event is a POST to your endpoint with the envelope and signature described under Webhooks above.

### device.online

A gateway is reporting again, also when it comes back after it was marked offline.

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

A gateway stopped reporting, because it disconnected or because it was silent for longer than its 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

A rule was met and an alert opened, or an open alert fired again. For offline alerts `condition` is `offline` and value fields are absent.

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

The value is back within the limit, or the gateway is back online. The alert stays open until someone resolves it.

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

Someone acknowledged the alert in the portal.

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

The alert was closed.

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

An automation with a webhook action ran.

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

## Schemas

### Problem

Error in the RFC 9457 problem details format.

| Field | Type | Description |
|---|---|---|
| `type` (required) | string (uri) |  |
| `title` (required) | string |  |
| `status` (required) | integer |  |
| `detail` | string |  |
| `code` (required) | 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` (required) | string |  |

### OffsetMeta

| Field | Type | Description |
|---|---|---|
| `total` | integer |  |
| `limit` | integer |  |
| `offset` | integer |  |

### CursorMeta

| Field | Type | Description |
|---|---|---|
| `since` | string (date-time) |  |
| `until` | string (date-time) |  |
| `order` | string: `asc`, `desc` |  |
| `limit` | integer |  |
| `has_more` | boolean |  |
| `next_cursor` | string, or null | Pass as `cursor` for the next page. Null on the last page. |

### Introspection

| Field | Type | Description |
|---|---|---|
| `key` | object |  |
| `organization` | object |  |
| `stats` | object |  |

### Customer

The site or customer a gateway is assigned to.

| Field | Type | Description |
|---|---|---|
| `id` | string (uuid) |  |
| `name` | string |  |
| `address` | string, or null | Address of the site. Only in `GET /devices/{id}`. |
| `city` | string, or null |  |

### Gateway

| Field | Type | Description |
|---|---|---|
| `id` | string (uuid) |  |
| `serial` | string |  |
| `name` | string |  |
| `status` | string: `online`, `offline`, `pending`, `error` |  |
| `firmware_ver` | string, or null |  |
| `ip_eth` | string, or null | Address on the wired network. |
| `ip_wifi` | string, or null |  |
| `ip_4g` | string, or null | Address on the 4G network. |
| `signal_4g` | integer, or null | Signal strength in dBm. |
| `last_seen` | string (date-time), or null |  |
| `created_at` | string (date-time) |  |
| `customer` | Customer |  |

### ModbusDevice

A field device behind the gateway, either a Modbus device (`rtu`, `tcp`) or a BACnet/IP device (`bacnet_ip`).

| Field | Type | Description |
|---|---|---|
| `id` | string (uuid) |  |
| `name` | string, or null |  |
| `slave_id` | integer | Modbus unit id. For bacnet_ip an internal slot 300..999. |
| `protocol` | string: `rtu`, `tcp`, `bacnet_ip` |  |
| `ip_address` | string, or null | For Modbus TCP and BACnet/IP. Behind a BACnet router, the address of the router. |
| `port` | integer, or null | For Modbus TCP and BACnet/IP (default 47808). |
| `poll_interval_ms` | integer, or null |  |
| `bacnet_device_instance` | integer, or null | BACnet device instance, 0 to 4194302. Only for bacnet_ip. |
| `bacnet_network` | integer, or null | BACnet network number behind a BACnet router (1 to 65534), otherwise null. |
| `bacnet_mac` | string, or null | BACnet MAC address behind that router, lowercase hex (MS/TP address 10 is `0a`), otherwise null. |
| `template` | object, or null |  |

### GatewayDetail

All fields of Gateway, plus:

| Field | Type | Description |
|---|---|---|
| `claimed_at` | string (date-time), or null |  |
| `modbus_devices` | array of ModbusDevice |  |

### Register

| Field | Type | Description |
|---|---|---|
| `id` | string (uuid) |  |
| `modbus_device_id` | string (uuid) |  |
| `modbus_device_name` | string, or null |  |
| `name` | string |  |
| `address` | integer | Register address. For a BACnet point an internal number, unique on the gateway. |
| `function_code` | integer, or null | 3 holding register, 4 input register. Null for a BACnet point. |
| `data_type` | string |  |
| `unit` | string, or null |  |
| `scale_factor` | number, or null | value = raw_value × scale_factor |
| `is_writable` | boolean |  |
| `description` | string, or null |  |
| `bacnet_object_type` | integer, or null | BACnet object type, for example 0 analog-input, 3 binary-input, 13 multi-state-input. Null for Modbus. |
| `bacnet_object_instance` | integer, or null | BACnet object instance. Null for Modbus. |
| `bacnet_property_id` | integer, or null | BACnet property that is read, 85 is Present_Value. Null for Modbus. |
| `bacnet_array_index` | integer, or null | Array index of that property, or null for the whole value. |
| `bacnet_write_priority` | integer, or null | BACnet write priority. Always null for now, because BACnet points are read only. |
| `latest_value` | number, or null | Latest value in engineering units. |
| `latest_raw_value` | number, or null | Latest value as read from the register. |
| `latest_ts` | string (date-time), or null |  |

### Reading

| Field | Type | Description |
|---|---|---|
| `register_id` | string (uuid) |  |
| `modbus_device_id` | string (uuid), or null |  |
| `name` | string, or null |  |
| `unit` | string, or null |  |
| `value` | number, or null | In engineering units, scale factor applied. |
| `raw_value` | number, or null | As read from the register. |
| `ts` | string (date-time) |  |

### Alert

| Field | Type | Description |
|---|---|---|
| `id` | string (uuid) |  |
| `device_id` | string (uuid), or null |  |
| `rule_id` | string (uuid), or null |  |
| `severity` | string: `critical`, `warning`, `info` |  |
| `message` | string, or null |  |
| `status` | string: `active`, `returned`, `acknowledged`, `resolved` |  |
| `value` | number, or null |  |
| `created_at` | string (date-time) |  |
| `last_triggered_at` | string (date-time), or null |  |
| `returned_at` | string (date-time), or null |  |
| `ack_at` | string (date-time), or null |  |
| `ack_by` | string (uuid), or null | Id of the user who acknowledged the alert. |
| `ack_note` | string, or null |  |
| `resolved_at` | string (date-time), or null |  |
| `resolved_by` | string (uuid), or null | Id of the user who resolved the alert. |
| `resolve_note` | string, or null |  |
| `entry_count` | integer | How often the alert fired while open. |
| `reminder_at` | string (date-time), or null | When a reminder set in the portal is due. Null without a reminder. |
| `reminder_sent` | boolean, or null | Whether that reminder has been sent. |

### DeviceStatusEvent

| Field | Type | Description |
|---|---|---|
| `device_id` | string (uuid) |  |
| `serial` | string |  |
| `status` | string: `online`, `offline` |  |
| `previous_status` | string, or null |  |
| `last_seen` | string (date-time), or null | Last time the gateway reported. |

### AlertTriggeredEvent

| Field | Type | Description |
|---|---|---|
| `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 | Comparison of the rule, or `offline`. |
| `message` | string |  |
| `source` | string: `rule`, `detector` |  |
| `register_id` | string (uuid), or null |  |
| `modbus_device_id` | string (uuid), or null |  |

### AlertReturnedEvent

| Field | Type | Description |
|---|---|---|
| `alert_id` | string (uuid) |  |
| `rule_id` | string (uuid) |  |
| `rule_name` | string |  |
| `device_id` | string (uuid) |  |
| `severity` | string |  |
| `value` | number |  |
| `condition` | string | `offline` when the gateway is back online. |
| `source` | string: `rule`, `detector` |  |

### AlertStatusEvent

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

### AutomationEvent

| Field | Type | Description |
|---|---|---|
| `rule_id` | string (uuid) |  |
| `rule_name` | string |  |
| `actions` | array of object |  |
