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.

Building with an agent?

Start at Build With an AI Agent — the call sequence, the rules, and a copy-ready prompt naming the OpenAPI spec and llms-full.txt.

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 after each overnight run, and again whenever it changes during the 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 Assistant integration is built on: the routes documented here are the ones it calls.

Pick your path

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

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

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

API ReferencePer-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	After the overnight run, and again when it changes	Ready-to-apply schedules for every appliance
Pull	GET /api/v1/schedules/updated-at	Every few minutes	One timestamp that changes whenever today’s schedules are replaced
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; Errors, Limits & Stability covers the full list plus what you may do with each.

Stay in the loop

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

Website

NameEmail addressNotify 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.
• Errors, Limits & Stability — error codes, rate limits, and what’s stable within a major version.