Decision Windows API

GET /v1/decision/windows — N cheapest hours / Flex segments. Loxone wallbox: Flex Windows. Open API; Community 120 requests/day.

Decision Windows answers: “Which N hours in this date range are cheapest (or most expensive)?”

Everyday example

Your wallbox needs 6 charging hours in the next 3 days. You call the API with count=6, mode=cheapest, and role=consume. It returns six one-hour slots like “Tue 02:00–03:00 at 2,1 ct/kWh.” Your EMS turns charging on only in those hours.

When to use / when not

Use when:

• You already know how many hours you need (or kWh ÷ kW power)
• You want spacing rules (min_gap_hours, max_consecutive, allowed_hours)

Do not use when:

• You want the API to compute hours from battery SOC → Hours Demand
• A simple hourly traffic light is enough → Decision API

What you need

• Community tier or higher
• Header: X-API-Key: sf_live_YOUR_KEY
• Start and end times for your search window (ISO 8601)

Step by step

1. Choose a time window: start (included) and end (excluded), e.g. midnight to midnight in three days. 2. Set mode=cheapest for charging/consuming, or mode=expensive for export/discharge. 3. Set role=consume or role=export (labels for your docs/UI). 4. Set count (number of hours) or energy_kwh + max_power_kw (API computes count). 5. Add optional filters: min_gap_hours, max_per_day, allowed_hours=8-22, etc. 6. Read slots[] for relay times; read day_plan for hours per calendar day.

Minimal request and response

curl "https://api.spotpriceapi.com/v1/decision/windows?count=10&start=2026-08-02T00:00:00&end=2026-08-05T00:00:00&mode=cheapest&role=consume&timezone=Europe/Vienna&min_gap_hours=2" \
  -H "X-API-Key: sf_live_YOUR_KEY"

{
  "decision_status": "ok",
  "decision_engine": "windows_v1",
  "allocation": "global",
  "window": { "hours_available": 72, "hours_requested": 10, "hours_returned": 10 },
  "slots": [
    { "rank": 1, "start": "2026-08-03T02:00:00+02:00", "end": "2026-08-03T03:00:00+02:00", "price_ct_kwh": 2.1, "action": "favor" }
  ],
  "day_plan": { "2026-08-02": 2, "2026-08-04": 8 }
}

In plain words: You asked for 10 hours; you got 10. rank: 1 is the best (cheapest) pick. day_plan shows how those hours spread across days.

Endpoint

GET https://api.spotpriceapi.com/v1/decision/windows

Parameters

Need a window and a count (or Flex merge). mode / role default to cheapest / consume if omitted.

Optional parameters (common)

Important response fields

Common mistakes

• start after end → HTTP 400 invalid_range
• Forgetting count and energy_kwh/segments → HTTP 400 incomplete_request
• Omitting mode / role → defaults cheapest / consume (not 400)
• Missing ISO start/end and no window_start_hour+window_end_hour and no flex_pack and no slot_id (Sparvo merge) → HTTP 400 incomplete_request
• count larger than tier horizon (168 full / 48 basic) → HTTP 400
• Expecting HTTP error when tier is too low — you get decision_status: not_available with HTTP 200

Next steps

• Hours Demand — auto hour count from SOC
• Decision API — hourly traffic light
• Webhooks — plant.plan_updated push
• Loxone Flex Windows — loads on/off, Sparvo schedules
• Loxone windows (legacy) — two-block GET/Parse
• Errors — full 400 error list

Flex v1.1 (loads on/off) — optional

count picks N cheap hours in a window — not the wallbox. The wallbox (and relays/pool) is a Flex slot: Sparvo device + schedule (API field recipes), PicoC slot in Portal EMS connection, PicoC on/off. Without flex parameters the response stays windows_v1.

With flex params: decision_engine: windows_v1.1, ems block directly after decision_status. ems.current_segment_hours / hours_needed_today = remaining need (0 when segment done). window.hours_requested is the same remaining need. ems.next_slot_start = next hour from the current full hour. deadline_reached is true whenever now ≥ end (even without deadline_strict).

GET (curl/scripts) — query params as before. POST (Loxone VO) — like Hours one analog: {"slot_id":"3","flex_pack":<v.0>}. Type slot_id. flex_pack=0 means omitted (Sparvo merge); a progress/plug-only pack (segments=0) still merges. mode/role default cheapest/consume. No named <v.Vi…> tags, no five <v.n> as five wires.

curl -X POST "https://api.spotpriceapi.com/v1/decision/windows" \
  -H "X-API-Key: sf_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d "{\"window_start_hour\":18,\"window_end_hour\":6,\"segments\":7,\"segment_consecutive\":\"soft\",\"mode\":\"cheapest\",\"role\":\"consume\",\"timezone\":\"Europe/Vienna\",\"hours_completed\":2,\"slot_id\":\"wallbox_1\"}"

curl "https://api.spotpriceapi.com/v1/decision/windows?window_start_hour=18&window_end_hour=6&segments=7&segment_consecutive=soft&mode=cheapest&role=consume&timezone=Europe/Vienna&hours_completed=2" \
  -H "X-API-Key: sf_live_YOUR_KEY"

Loxone walkthrough: Flex Windows.

Device schedules (Sparvo → EMS)

GET https://api.spotpriceapi.com/v1/plant/device-schedules

Returns EMS-linked devices (api_linked): schedules from Sparvo, PicoC slot via Portal EMS connection (/settings/ems). Fields include slot_id, recipes[] (UI: Schedule), matching recipe, segments, window_*. Community key.