REST API and webhooks

The API returns data when your software asks for it. A webhook sends a message to your server as soon as something happens. The API needs a system that sends HTTPS requests, and a webhook needs a system that receives them.

What you need

• The role Owner or Admin to create an API key or webhook. Other roles do not see API keys and Webhooks under Settings.
• An API key. How to create one is described in Create an API key.

What you retrieve with the API

The table shows which data you retrieve and which permission the key needs for it.

Every request goes to https://api.modbuscloud.com/v1, with the key as a bearer token in the Authorization header. In the paths, a gateway is called device.

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

Receive events with a webhook

A webhook sends a POST request with JSON to your own address as soon as something happens. For each webhook you choose which events it forwards:

• An alert fires, returns, is acknowledged or is resolved (alert.triggered, alert.returned, alert.acknowledged, alert.resolved).
• A gateway goes offline or comes back online (device.offline, device.online).
• An automation runs a webhook action (automation.triggered).

Every message is signed according to Standard Webhooks, with a secret that starts with whsec_. If a message does not arrive, the portal tries again, up to six attempts in just over seven hours. How to add and test a webhook is described in Set up a webhook.

The API reference

The API reference describes the endpoints, the fields, the error codes and the webhook messages in English. You can try every endpoint there directly in the browser.

To generate a client, use the OpenAPI 3.1 file at https://docs.modbuscloud.com/openapi.json.

Try it with the sandbox key

Without a key of your own, you try the API with the public sandbox key from the quickstart of the API reference. This key is read-only and belongs to the demo account, the portal of a fictitious installation company. The reference already has it filled in. Everyone shares the same key, so each visitor may make 60 requests per minute.

Limits and error messages

A key may make 100 requests per minute. The counter starts again at the beginning of every minute. If you go over the limit, the API answers with status 429 and Retry-After gives the number of seconds until you can continue.

If you request the registers of 50 gateways every minute, you already use half of that limit. Receive alerts through a webhook instead of requesting them again and again.

An error comes as Problem Details according to RFC 9457. Let your software react to the code field, because the text in detail can change. All codes are in the list of error codes. Every response has an X-Request-Id header. Quote it when you get help.

How the API returns values

A value comes converted with the scale factor of the register, as in the portal. The raw value from the register is included. If a register reads 2314 with scale factor 0.1, the API returns "latest_value": 231.4 and "latest_raw_value": 2314.

If the portal shows a status text or the text of an error code for a register, the API returns only the number. Times are in UTC, in ISO 8601 format.

Retrieve history in pages

The history comes in pages of at most 1000 readings. Every page returns meta.next_cursor. Send it as cursor in the next request, until meta.has_more is false. This way you miss no reading and get none twice, even when new readings arrive in between.

One request covers at most 7 days, or 366 days if you specify a single register. Without a period you get the last 24 hours.

The history stores at most one reading per minute for each register. By default the gateway reads every 300 seconds (5 minutes). How to change that is described in Choose the polling interval. If you need a file for Excel once, use Download readings.

Keys and webhooks belong to the organisation

An API key and a webhook apply to the whole organisation, not to a single customer or site. A key therefore reads the gateways of all your customers.

The API and webhooks are part of the portal licence, with no cost per request. Where the API runs and where your data is stored is described in Where your data is stored and who can access it.