Readings

The readings endpoint accepts sensor data from your thermostat or Home Assistant integration. Push readings every 5 minutes for the optimizer to build an accurate thermal model of your home.

POST /api/v1/readings

Auth: Required (Bearer JWT)

Request body

{
  "readings": [
    {
      "timestamp": "2025-11-18T14:30:00+00:00",
      "indoor_temp": 72.5,
      "hvac_state": "COOL",
      "indoor_humidity": 45.0,
      "outdoor_temp": 85.0,
      "target_temp": 72.0,
      "fan_mode": "auto",
      "power_watts": 298.0
    }
  ]
}

Fields

Field	Type	Required	Constraints
timestamp	string (ISO 8601)	Yes	UTC recommended
indoor_temp	float	Yes	30.0–120.0 °F
hvac_state	string	Yes	"HEAT", "COOL", "ECO", "DRY", "OFF", or "FAN". Aliases like "cooling", "eco_cool", "dehumidify", "fan_only", "heat_cool", "auto", "idle" are normalized server-side — pass whatever your thermostat reports. "ECO" and "DRY" count separately from "COOL" so the thermal model can learn per-sub-mode cooling rates.
indoor_humidity	float	No	Percent (0–100)
outdoor_temp	float	No	Fahrenheit
target_temp	float	No	Current thermostat setpoint
fan_mode	string	No	e.g. "auto", "low", "high"
power_watts	float	No	Current power draw

Example

curl -X POST https://api.hungrymachines.io/api/v1/readings \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "readings": [
      {
        "timestamp": "2025-11-18T14:30:00+00:00",
        "indoor_temp": 72.5,
        "hvac_state": "COOL",
        "outdoor_temp": 85.0,
        "target_temp": 72.0
      }
    ]
  }'

Response (201)

{
  "accepted": 1
}

The accepted count reflects how many readings were stored.

Errors

Status	Detail	Cause
400	"indoor_temp must be between 30 and 120"	Validation failure
401	"Not authenticated"	Missing or invalid token
429	"Rate limit exceeded: max 300 readings per user per day"	Over daily limit

Rate limit

Each user may submit up to 300 readings per day. At one reading every 5 minutes, that’s 288 readings — well within the limit. Batching multiple readings in a single request counts each reading individually toward the daily total.

Tip

You can batch up to 100 readings in a single POST. This is useful when catching up after a network outage — buffer readings locally and send them when connectivity returns.

How readings are used

The optimizer uses your readings to:

1. Build a thermal model of your home (how quickly it heats and cools based on outdoor conditions, HVAC state, and time of day)
2. Generate optimized schedules that shift energy consumption to cheaper rate periods while maintaining comfort

The thermal model needs at least 72 hourly buckets of data — roughly 3 days of continuous 5-minute readings — before the fitter will produce a model. A daily 06:30 UTC initial-fit job picks up users who have just crossed that threshold, so a brand-new account typically gets its first per-user model 3–4 days after starting to push readings. Until then, the schedule endpoint returns defaults based on your preferences. The weekly refit on Sunday 02:00 UTC then keeps every user’s model current.