For Developers

The Hungry Machines optimizer is available over a documented HTTP API, so you don’t have to use the default Home Assistant app. You can build your own dashboard, a mobile app, a Home Assistant integration tuned to your home, or firmware on an embedded device — anything that can speak HTTPS.

This section is the public integration contract: everything you need to send the right data and apply the results, with worked examples in several languages.

Note

The API is a clean boundary. You send readings, preferences, appliance definitions, weather, and rates; you receive ready-to-apply schedules. How the optimizer turns your data into a schedule — the learning models and the optimization itself — is proprietary and lives entirely in the backend. You never need to reproduce it: send well-formed inputs, apply the commands the API returns, and display the results as-is. Building against that boundary keeps your integration stable across backend releases.

The three things a client does

Whatever you build, the shape is the same:

1. Register the account’s appliances and preferences (one-time).
2. Push readings so the optimizer can learn the home (ongoing, ~every 5 minutes).
3. Pull the schedule once a day and apply each 30-minute step to the device locally.

Your client owns all local device control — hysteresis, safety limits, hardware I/O. The API owns the optimization.

Pick your path

Custom Home Assistant integration You already run Home Assistant and want your own REST sensors, rest_command actions, and Lovelace cards instead of the default panel.

Build your own client No Home Assistant — you're integrating from a Python script, a mobile app, an ESP32, or any other platform. Talk to the API directly.

Authentication reference Token lifecycle: login, refresh, and how to handle 401s in an automated client. Start here before writing any request.

API Reference Per-endpoint request/response shapes, validation rules, and error codes — the canonical contract for everything the API accepts and returns.

Before you start

• Accounts are created on the website. Always have users sign up at hungrymachines.io — that flow sets up billing, subscription state, and onboarding, none of which the API does on its own. Your client authenticates an existing account; it doesn’t create real ones. See Authentication.
• Everything is one base URL. Both authentication and product endpoints live on https://api.hungrymachines.io. Users sign in with the same email and password they use everywhere else — no separate API credentials.
• The default app is open source. The Home Assistant panel and cards are MIT-licensed and a good reference (or fork target) if you want a head start. Patches and forks are welcome.

What you send vs. what you receive

Direction	Endpoint	Typical cadence	Purpose
Push	POST /api/v1/readings	Every ~5 min	HVAC sensor data — the input the optimizer learns from
Push	POST /api/v1/appliances/{id}/readings	Every ~5 min (per appliance)	EV / battery / water-heater state
Push	POST /api/v1/weather	Once a day	Your local weather forecast
Pull	GET /api/v1/schedules	Once a day	Ready-to-apply schedules for every appliance
Read/write	/api/v1/appliances · /api/v1/preferences · /api/v1/rates	As needed	Register devices, comfort settings, pricing

A note on treating outputs as opaque

A few fields the API returns are for display only — estimated_savings_pct, model_confidence, and the predicted-temperature trajectory line. Render them as-is; don’t build logic on how they’re computed, and don’t try to reverse-engineer the optimizer from them. The stable contract is: apply setpoint_temps (and on/off intervals) verbatim, honor the documented fallbacks, and show the rest. The API Reference spells out each field and its fallback.

Next steps

• Authentication — get a token and keep it fresh.
• Custom Home Assistant integration or Build your own client — pick your path.
• API Reference — the full endpoint-by-endpoint contract.