Rates

The rates endpoints expose the time-of-use (TOU) electricity rate curve the optimizer consumes. Use them to color the schedule timeline by peak / off-peak pricing or to override the zone-based curve with your own rates.

All values are in cents per kWh. Clients displaying dollars must divide by 100; clients submitting dollars must multiply by 100 first.

The rate curve has the same 48 × 30-minute shape as schedules — each interval is a half-hour slot of local-day, indexed 0 (00:00–00:30) through 47 (23:30–00:00). Each hour repeats twice.

By default the curve is resolved from the user’s pricing_location (zone 1–8 — see Preferences). A user can replace it with their own 24-hour override via PUT /api/v1/rates; that override is expanded to 48 half-hour slots (each hour repeats twice) and returned with source: "custom".

GET /api/v1/rates

Auth: Required (Bearer JWT)

Example

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

Response (200) — zone fallback

{
  "pricing_location": 1,
  "intervals": [0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19, 20, 21, 22, 23, 24, 25, 26, 27, 28, 29, 30, 31, 32, 33, 34, 35, 36, 37, 38, 39, 40, 41, 42, 43, 44, 45, 46, 47],
  "rates_cents_per_kwh": [24.7, 24.7, 24.7, 24.7, 24.7, 24.7, 24.7, 24.7, 24.7, 24.7, 24.7, 24.7, 36.8, 36.8, 36.8, 36.8, 36.8, 36.8, 36.8, 36.8, 36.8, 36.8, 36.8, 36.8, 36.8, 36.8, 36.8, 36.8, 36.8, 36.8, 36.8, 36.8, 59.7, 59.7, 59.7, 59.7, 59.7, 59.7, 59.7, 59.7, 59.7, 59.7, 36.8, 36.8, 36.8, 36.8, 36.8, 36.8],
  "source": "zone",
  "hourly_rates_cents_per_kwh": null,
  "unit": "cents/kWh"
}

Response (200) — custom override

{
  "pricing_location": 1,
  "intervals": [0, 1, "...", 47],
  "rates_cents_per_kwh": [40.0, 40.0, "... 48 values total ..."],
  "source": "custom",
  "hourly_rates_cents_per_kwh": [40.0, 40.0, "... 24 values total ..."],
  "unit": "cents/kWh"
}

Response fields

Field	Type	Description
`pricing_location`	integer	Zone 1–8 — resolved from the user’s profile, defaults to `1` when unset
`intervals`	array[int]	Indices `0`–`47` (each represents a 30-minute slot of local-day)
`rates_cents_per_kwh`	array[float]	Exactly 48 floats — cents per kWh for each interval (zone curve OR the 48-expansion of the user’s hourly override)
`source`	string	`"custom"` if the user has a stored override, otherwise `"zone"`
`hourly_rates_cents_per_kwh`	array[float] \| null	The user’s raw 24-element override when `source` is `"custom"`; `null` when `source` is `"zone"`
`unit`	string	Always `"cents/kWh"`

Errors

Status	Detail	Cause
401	`"Not authenticated"`	Missing or invalid token
503	`"Database not configured"`	DB not configured on the server

PUT /api/v1/rates

Auth: Required (Bearer JWT)

Set or clear the authenticated user’s custom 24-hour electricity rate curve. Submit null to clear the override and revert to the zone-based curve.

Example

curl -X PUT https://api.hungrymachines.io/api/v1/rates \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "hourly_rates_cents_per_kwh": [40.0, 40.0, 40.0, 40.0, 40.0, 40.0, 40.0, 40.0, 40.0, 40.0, 40.0, 40.0, 40.0, 40.0, 40.0, 40.0, 40.0, 40.0, 40.0, 40.0, 40.0, 40.0, 40.0, 40.0]
  }'

To clear the override:

curl -X PUT https://api.hungrymachines.io/api/v1/rates \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"hourly_rates_cents_per_kwh": null}'

Request body

{
  "hourly_rates_cents_per_kwh": [40.0, 40.0, "... 24 values total ..."]
}

Validation

Field	Constraints
`hourly_rates_cents_per_kwh`	Exactly 24 floats — one per hour (`00:00` → `23:00`). Each value must be finite and in `[0, 200]`. Submit `null` to clear.

Response (200)

Same shape as GET /api/v1/rates. After a successful set, source is "custom" and hourly_rates_cents_per_kwh echoes the input array; after a clear, source is "zone" and hourly_rates_cents_per_kwh is null.

Errors

Status	Detail	Cause
400	`"hourly_rates_cents_per_kwh must have exactly 24 values"`	Array length is not 24
400	`"rate at hour <i> must be between 0 and 200 cents/kWh"`	Value is non-finite or outside `[0, 200]`
401	`"Not authenticated"`	Missing or invalid token
503	`"Database not configured"`	DB not configured or write failed