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. It’s the same API our own Home Hub and Satellite devices run on — no separate internal contract, just the one documented here.

Pick your path

Custom Home Assistant integration You 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 / solar 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.

Stay in the loop

Get an email when the API contract changes — new endpoints, field additions, deprecations.

Website

Name Email address Notify me

This list is separate from the newsletter — you'll only hear from us about API and integration changes, starting with a confirmation email to opt in.

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.