API
API overview
What you can do with the device API, its four endpoints, the order in which a device uses them, and the conventions for tokens, JSON and timestamps.
With the device API you send readings from your own hardware or software to BoilerBuddy, where they show up in charts and alerts. The BoilerBuddy Alpo uses the same API.
The API works in one direction: there is no way to read readings back or export them.
Base URL
https://boilerbuddy.eu/api/v1
Always use HTTPS.
The four endpoints
| Endpoint | Purpose | Token needed |
|---|---|---|
POST /device/hello |
Pairing: a new device gets a pairing code, and after pairing its token | No |
GET /device/config |
Which sensors the device reports, with their codes, and how often it measures | Yes |
POST /device/readings |
Upload a batch of 1 to 1000 readings | Yes |
POST /device/status |
A heartbeat: the device says it is still there | Yes |
How a device uses them
- Get a token: an API key from the portal, or pair the device itself with
hello. See Pairing with hello. - Fetch the configuration: which sensor codes the device reports. See Fetching the configuration.
- Measure and upload: store readings locally first, then send them in batches. See Sending readings and Buffering and the clock.
- Send a status: every few minutes, also when there is nothing to upload. See Limits and error codes.
The token
Every request except hello carries the token in a header:
Authorization: Bearer bb_live_42_Xk3…
- A token is
bb_live_<device id>_<secret>, with a secret of 40 letters and digits. A simulated device hasbb_test_…. The server decides which, and a token with the wrong prefix is refused. - You see a token once; the server only keeps a hash. Lost it? Create a new one: the old one stops working immediately.
JSON and timestamps
- Send
Content-Type: application/jsonwith every request that has a body. Answers are always JSON, errors included. Only204and304have no body. - Timestamps are ISO 8601 with seconds and a time zone, such as
2026-10-08T11:59:00Zor2026-10-08T13:59:00+02:00. A timestamp without a time zone, or a date that does not exist (30 February), is rejected. The server truncates to whole seconds and stores everything in UTC.
Contract and reference
The contract is openapi-v1.yaml, an OpenAPI 3.1 file that is also linked from the Developers page. What it says is what the server does. Open it in, for example, Swagger UI or Postman.
The API reference lists every field. For working examples, see curl, Python and ESP32.