Developers
Build your own BoilerBuddy
Read your solar water heater with your own hardware and send the readings to BoilerBuddy. You get the whole portal with it: charts, alerts and sharing. The BoilerBuddy Alpo uses the same API.
Base URL, API v1
https://boilerbuddy.eu/api/v1
OpenAPI 3.1, as YAML. Open it in Swagger UI, Postman or your own code generator. This file is the contract: what it says is what the server does.
API
Four endpoints
That's all you need to pair a device and send readings.
POST/device/helloPairing. Your device gets a pairing code to show, and once paired, its token, exactly once.
GET/device/configWhich sensors your device sends and how often. With an ETag, so polling is cheap.
POST/device/readingsReadings in batches of up to 1000, each with its own timestamp. Sending something twice does no harm.
POST/device/statusA heartbeat, so the portal can tell whether your device is offline or just quiet.
Authentication
Every request except hello carries a token in the Authorization header. You get the token by pairing with a code, or you create one in the portal on your device's page. It's shown once, so keep it safe.
Authorization: Bearer bb_live_…Good to know
- Times in ISO 8601 with a time zone. The server stores UTC.
- A well-formed batch always gets a 200, even if individual readings are rejected. The response says why, per reading.
- Per device 60 requests a minute, of which at most 10 with readings. On a 429, wait as long as Retry-After says.
- Buffer locally and catch up later: readings up to a year old are accepted.
Your first reading
This is how to send a collector temperature with curl. The sensor code (T1 here) is in your device's configuration.
curl -X POST \
https://boilerbuddy.eu/api/v1/device/readings \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{
"batch_uuid": "0d4f6c1e-8a51-4c43-9b6b-3c1f0f7a2e11",
"readings": [{
"sensor": "T1",
"value": 61.4,
"measured_at": "2026-10-08T11:59:00Z"
}]
}'{
"accepted": 1,
"duplicates": 0,
"unmapped": [],
"rejected": []
}Guides and examples
Pairing a device, sending readings reliably and dealing with a clock that isn't in sync yet. With complete examples.
Stuck on something?
Questions about the API, or about a controller you'd like to connect? Let us know.