Preferences

The preferences endpoints let you configure your comfort settings and optimization mode. These values control how aggressively the optimizer shifts energy usage.

See also Rates for the TOU pricing curve the optimizer consumes.

GET /api/v1/preferences

Auth: Required (Bearer JWT)

Example

curl https://api.hungrymachines.io/api/v1/preferences \
  -H "Authorization: Bearer YOUR_TOKEN"

Response (200)

{
  "base_temperature": 72.0,
  "savings_level": 1,
  "time_away": "08:00",
  "time_home": "17:00",
  "optimization_mode": "cool",
  "hourly_high_temps_f": null,
  "hourly_low_temps_f": null
}

If the user hasn’t set preferences yet, defaults are returned.

Fields

Field	Type	Default	Description
base_temperature	float	72.0	Desired temperature (°F)
savings_level	integer	1	How far the optimizer can deviate from base temp
time_away	string	"08:00"	When you typically leave home (HH:MM)
time_home	string	"17:00"	When you typically return home (HH:MM)
optimization_mode	string	"cool"	"cool", "heat", "auto", or "off"
hourly_high_temps_f	array[float] | null	null	Optional 24-element per-hour upper comfort bound (°F). When set, takes precedence over base_temperature + savings_level + time_away/time_home.
hourly_low_temps_f	array[float] | null	null	Optional 24-element per-hour lower comfort bound (°F). When set, takes precedence over base_temperature + savings_level + time_away/time_home.

Savings levels

Level	Band	Behavior
1 (tight)	±2 °F	Conservative — minimal deviation from base temperature
2 (moderate)	±6 °F	Balanced — noticeable pre-cooling/pre-heating during away hours
3 (aggressive)	±12 °F	Maximum savings — wider temperature swings, especially when away

Hourly comfort bands (advanced)

The default comfort band is symmetric around base_temperature, widened by savings_level during the time_away window. If you want explicit per-hour bounds — for example, a tighter band during occupied hours and a wider band overnight — submit hourly_high_temps_f and hourly_low_temps_f together.

• Both arrays must be set together, or both must be null to clear the override.
• Each array is exactly 24 values, indexed 0 (midnight) through 23 (11 PM local time).
• Each value must be in [50, 90] °F.
• For every hour i, hourly_low_temps_f[i] < hourly_high_temps_f[i].
• When the override is set, time_away, time_home, and savings_level are ignored — the optimizer respects the explicit bounds at every hour.

Example: tighter [68, 74] band from 8 AM through 9 PM, wider [64, 78] band overnight.

{
  "hourly_high_temps_f": [78, 78, 78, 78, 78, 78, 78, 78, 74, 74, 74, 74, 74, 74, 74, 74, 74, 74, 74, 74, 74, 74, 78, 78],
  "hourly_low_temps_f":  [64, 64, 64, 64, 64, 64, 64, 64, 68, 68, 68, 68, 68, 68, 68, 68, 68, 68, 68, 68, 68, 68, 64, 64]
}

---

PUT /api/v1/preferences

Auth: Required (Bearer JWT)

Update one or more preference fields. Only the fields you include are changed; others keep their current values.

Example

curl -X PUT https://api.hungrymachines.io/api/v1/preferences \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "base_temperature": 73.0,
    "savings_level": 2,
    "optimization_mode": "auto"
  }'

Request body

All fields are optional — include only what you want to change.

{
  "base_temperature": 73.0,
  "savings_level": 2,
  "time_away": "07:30",
  "time_home": "18:00",
  "optimization_mode": "auto"
}

Validation

Field	Constraints
base_temperature	60.0–85.0 °F
savings_level	1, 2, or 3
time_away	HH:MM format
time_home	HH:MM format
optimization_mode	"cool", "heat", "auto", "off"
hourly_high_temps_f	Exactly 24 finite floats, each in [50, 90] °F
hourly_low_temps_f	Exactly 24 finite floats, each in [50, 90] °F
hourly_low_temps_f[i] < hourly_high_temps_f[i]	Per-hour lower bound must be strictly less than upper bound
hourly_high_temps_f + hourly_low_temps_f	Both fields must be set together (or both null to clear)

Response (200)

Returns the full preferences object after the update (same shape as GET):

{
  "base_temperature": 73.0,
  "savings_level": 2,
  "time_away": "07:30",
  "time_home": "18:00",
  "optimization_mode": "auto"
}

Errors

Status	Detail	Cause
400	"base_temperature must be between 60 and 85"	Validation failure
400	"hourly_high_temps_f and hourly_low_temps_f must be set together or both cleared"	Only one of the two arrays was provided as a non-null value
400	"hourly_high_temps_f and hourly_low_temps_f must each have exactly 24 values"	Wrong array length
400	"hourly bands at hour <i> must be between 50 and 90 F"	Value out of range at hour <i>
400	"hourly low must be less than high at hour <i>"	hourly_low_temps_f[i] >= hourly_high_temps_f[i]
401	"Not authenticated"	Missing or invalid token