API-overzicht

Met de apparaat-API stuur je metingen van je eigen hardware of software naar BoilerBuddy, waar je ze terugziet in grafieken en meldingen. De BoilerBuddy Alpo gebruikt dezelfde API.

De API werkt één kant op: metingen teruglezen of exporteren kan niet.

Basis-URL#

https://boilerbuddy.eu/api/v1

Gebruik altijd HTTPS.

De vier endpoints#

Endpoint	Waarvoor	Token nodig
POST /device/hello	Koppelen: een nieuw apparaat krijgt een koppelcode, en na het koppelen zijn token	Nee
GET /device/config	Welke sensoren het apparaat instuurt, met hun codes, en hoe vaak het meet	Ja
POST /device/readings	Een batch van 1 tot 1000 metingen insturen	Ja
POST /device/status	Een heartbeat: het apparaat laat weten dat het er is	Ja

Zo gebruikt een apparaat ze#

1. Token krijgen: een API-sleutel uit het portaal, of zelf koppelen met hello. Zie Koppelen via hello.
2. Configuratie ophalen: welke sensorcodes het apparaat instuurt. Zie Configuratie ophalen.
3. Meten en insturen: eerst lokaal bewaren, dan in batches versturen. Zie Metingen insturen en Bufferen en de klok.
4. Status sturen: om de paar minuten, ook als er niets te versturen is. Zie Limieten en foutcodes.

Het token#

Elk verzoek behalve hello draagt het token in een header:

Authorization: Bearer bb_live_42_Xk3…

• Een token is bb_live_<apparaat-id>_<geheim>, met een geheim van 40 letters en cijfers. Een gesimuleerd apparaat heeft bb_test_…. Dat bepaalt de server, en een token met het verkeerde voorvoegsel wordt geweigerd.
• Je ziet een token één keer; de server bewaart alleen een hash. Kwijt? Maak een nieuwe: de oude werkt dan direct niet meer.

JSON en tijden#

• Stuur Content-Type: application/json bij elk verzoek met een body. Antwoorden zijn altijd JSON, ook bij fouten. Alleen 204 en 304 hebben geen body.
• Tijden zijn ISO 8601 met seconden en een tijdzone, zoals 2026-10-08T11:59:00Z of 2026-10-08T13:59:00+02:00. Een tijd zonder tijdzone of een datum die niet bestaat (30 februari) wordt afgewezen. De server kapt af op hele seconden en slaat op in UTC.

Contract en referentie#

Het contract is openapi-v1.yaml, een OpenAPI 3.1-bestand dat ook op de pagina Ontwikkelaars staat. Wat erin staat, doet de server. Open het in bijvoorbeeld Swagger UI of Postman.

De API-referentie noemt elk veld, in het Engels. Werkende voorbeelden staan bij curl, Python en ESP32.