# For Developers

Build your own frontend, Home Assistant integration, or device client on top of the Hungry Machines API.

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: Building with an agent?**
>
> Start at [Build With an AI Agent](/guides/build-with-an-agent/) — the call sequence, the rules, and a copy-ready prompt naming the [OpenAPI spec](/api-reference/openapi/) and [llms-full.txt](/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 integration](/guides/custom-home-assistant/): 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](/guides/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](/getting-started/authentication/): Token lifecycle: login, refresh, and how to handle 401s in an automated client. Start here before writing any request.
- [API Reference](/api-reference/readings/): 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](https://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](/getting-started/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`](/api-reference/readings/) | Every ~5 min | HVAC sensor data — the input the optimizer learns from |
| Push | [`POST /api/v1/appliances/{id}/readings`](/api-reference/appliances/) | Every ~5 min (per appliance) | EV / battery / water-heater / solar state |
| Push | [`POST /api/v1/weather`](/api-reference/weather/) | Once a day | Your local weather forecast |
| Pull | [`GET /api/v1/schedules`](/api-reference/appliances/#get-apiv1schedules) | After the overnight run, and again when it changes | Ready-to-apply schedules for every appliance |
| Pull | [`GET /api/v1/schedules/updated-at`](/api-reference/appliances/#get-apiv1schedulesupdated-at) | Every few minutes | One timestamp that changes whenever today's schedules are replaced |
| Read/write | [`/api/v1/appliances`](/api-reference/appliances/) · [`/api/v1/preferences`](/api-reference/preferences/) · [`/api/v1/rates`](/api-reference/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](/api-reference/schedule/) spells out each field and its fallback; [Errors, Limits & Stability](/api-reference/errors-and-limits/) 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.

Sign up for a developer account: https://hungrymachines.io/signup

## Next steps

- [Authentication](/getting-started/authentication/) — get a token and keep it fresh.
- [Custom Home Assistant integration](/guides/custom-home-assistant/) or [Build your own client](/guides/build-your-own-client/) — pick your path.
- [API Reference](/api-reference/readings/) — the full endpoint-by-endpoint contract.
- [Errors, Limits & Stability](/api-reference/errors-and-limits/) — error codes, rate limits, and what's stable within a major version.

Canonical page: https://docs.hungrymachines.io/for-developers/