API-Überblick

Mit der Geräte-API sendest du Messwerte von deiner eigenen Hardware oder Software an BoilerBuddy. Dort erscheinen sie in Diagrammen und Meldungen. Die BoilerBuddy Alpo nutzt dieselbe API.

Die API funktioniert in eine Richtung: Messwerte lassen sich nicht zurücklesen oder exportieren.

Basis-URL#

https://boilerbuddy.eu/api/v1

Nutze immer HTTPS.

Die vier Endpunkte#

Endpunkt	Zweck	Token nötig
POST /device/hello	Koppeln: Ein neues Gerät bekommt einen Kopplungscode und nach dem Koppeln seinen Token	Nein
GET /device/config	Welche Sensoren das Gerät meldet, mit ihren Codes, und wie oft es misst	Ja
POST /device/readings	Einen Stapel von 1 bis 1000 Messwerten hochladen	Ja
POST /device/status	Ein Heartbeat: Das Gerät sagt, dass es noch da ist	Ja

Wie ein Gerät sie nutzt#

1. Einen Token besorgen: einen API-Schlüssel aus dem Portal, oder das Gerät koppelt sich selbst mit hello. Siehe Koppeln mit hello.
2. Die Konfiguration abrufen: welche Sensorcodes das Gerät meldet. Siehe Die Konfiguration abrufen.
3. Messen und hochladen: Messwerte zuerst lokal speichern und dann in Stapeln senden. Siehe Messwerte senden und Puffern und die Uhr.
4. Einen Status senden: alle paar Minuten, auch wenn es nichts hochzuladen gibt. Siehe Limits und Fehlercodes.

Der Token#

Jede Anfrage außer hello trägt den Token in einem Header:

Authorization: Bearer bb_live_42_Xk3…

• Ein Token hat die Form bb_live_<device id>_<secret>, mit einem Geheimnis aus 40 Buchstaben und Ziffern. Ein simuliertes Gerät hat bb_test_…. Welches es ist, entscheidet der Server, und ein Token mit dem falschen Präfix wird abgelehnt.
• Du siehst einen Token nur einmal; der Server speichert nur einen Hash. Verloren? Erstelle einen neuen: Der alte funktioniert dann sofort nicht mehr.

JSON und Zeitstempel#

• Sende Content-Type: application/json bei jeder Anfrage mit Body. Antworten sind immer JSON, auch Fehler. Nur 204 und 304 haben keinen Body.
• Zeitstempel sind ISO 8601 mit Sekunden und Zeitzone, etwa 2026-10-08T11:59:00Z oder 2026-10-08T13:59:00+02:00. Ein Zeitstempel ohne Zeitzone oder ein Datum, das es nicht gibt (30. Februar), wird abgelehnt. Der Server kürzt auf ganze Sekunden und speichert alles in UTC.

Vertrag und Referenz#

Der Vertrag ist openapi-v1.yaml, eine OpenAPI-3.1-Datei, die auch auf der Seite Entwickler verlinkt ist. Was darin steht, macht der Server. Öffne sie zum Beispiel in Swagger UI oder Postman.

Die API-Referenz listet jedes Feld auf. Funktionierende Beispiele findest du für curl, Python und ESP32.