{"openapi":"3.0.3","info":{"title":"SpotpriceAPI v1","version":"1.0.0","description":"Austrian EPEX AT electricity-price forecasts and decision APIs. Human docs: https://spotpriceapi.com/docs"},"servers":[{"url":"https://api.spotpriceapi.com"}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"X-API-Key"}}},"paths":{"/v1/forecast":{"get":{"summary":"Hourly electricity-price forecast (EPEX AT)","parameters":[{"name":"timezone","in":"query","schema":{"type":"string"},"description":"IANA timezone for response timestamps"}],"responses":{"200":{"description":"Successful response"}},"security":[{"ApiKeyAuth":[]}]}},"/v1/decision":{"get":{"summary":"Per-hour decision / quartile signals","parameters":[{"name":"timezone","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"Successful response"}},"security":[{"ApiKeyAuth":[]}]}},"/v1/decision/windows":{"get":{"summary":"Ranked cheapest or expensive hour windows (windows_v1; flex → windows_v1.1)","parameters":[{"name":"start","in":"query","required":false,"schema":{"type":"string"},"description":"ISO window start; omit when using window_* hours or flex_pack"},{"name":"end","in":"query","required":false,"schema":{"type":"string"},"description":"ISO window end; omit when using window_* hours or flex_pack"},{"name":"window_start_hour","in":"query","schema":{"type":"integer","minimum":0,"maximum":23},"description":"Flex rolling start hour (0–23); with window_end_hour"},{"name":"window_end_hour","in":"query","schema":{"type":"integer","minimum":0,"maximum":23},"description":"Flex rolling end hour (0–23); overnight wrap ok"},{"name":"flex_pack","in":"query","schema":{"type":"integer","minimum":0},"description":"Loxone pack: start|(end<<5)|(seg<<10)|(done<<16)|(plugged<<22); 0 = omit"},{"name":"mode","in":"query","required":false,"schema":{"type":"string","enum":["cheapest","expensive"]},"description":"Default cheapest"},{"name":"role","in":"query","required":false,"schema":{"type":"string","enum":["consume","export"]},"description":"Default consume"},{"name":"count","in":"query","schema":{"type":"integer"}},{"name":"energy_kwh","in":"query","schema":{"type":"number"}},{"name":"max_power_kw","in":"query","schema":{"type":"number"}},{"name":"timezone","in":"query","schema":{"type":"string"}},{"name":"segments","in":"query","description":"Flex v1.1: e.g. 7 or 3,5","schema":{"type":"string"}},{"name":"segment_consecutive","in":"query","description":"Flex: off | soft | required","schema":{"type":"string"}},{"name":"hours_completed","in":"query","schema":{"type":"number","minimum":0},"description":"Float, 15-min grid"},{"name":"deadline_strict","in":"query","schema":{"type":"boolean"},"description":"Echoed; after window end Demand/slots are 0"},{"name":"repeat_daily","in":"query","schema":{"type":"boolean"},"description":"Echoed; not applied in Wallbox v0.4"},{"name":"deadline_hour","in":"query","schema":{"type":"integer","minimum":0,"maximum":23},"description":"Sparvo latest start (inclusive). Infers clock hours from ISO start/end when window_* is omitted"},{"name":"slot_id","in":"query","schema":{"type":"string"},"description":"Flex slot (`1` / `wallbox_1` / `O3`). One PicoC output 1–8 per plant; Portal EMS connection assigns the slot"}],"responses":{"200":{"description":"Successful response"}},"security":[{"ApiKeyAuth":[]}]},"post":{"summary":"Same as GET — JSON body for Loxone VO (Hours-style one <v.0> on Input)","requestBody":{"required":true,"content":{"application/json":{"example":{"slot_id":"3","flex_pack":0},"schema":{"type":"object","required":[],"properties":{"start":{"type":"string"},"end":{"type":"string"},"window_start_hour":{"type":"integer","minimum":0,"maximum":23},"window_end_hour":{"type":"integer","minimum":0,"maximum":23},"flex_pack":{"type":"number","minimum":0,"description":"0 = omit (Sparvo merge). Pack includes plugged<<22"},"mode":{"type":"string","enum":["cheapest","expensive"]},"role":{"type":"string","enum":["consume","export"]},"segments":{"oneOf":[{"type":"integer"},{"type":"string"}]},"segment_consecutive":{"type":"string"},"hours_completed":{"type":"number"},"energy_kwh":{"type":"number"},"energy_delivered_kwh":{"type":"number"},"battery_to_ev_pct":{"type":"number","minimum":0,"maximum":100},"plugged":{"type":"number","minimum":0,"maximum":1},"max_power_kw":{"type":"number"},"timezone":{"type":"string"},"slot_id":{"type":"string","description":"Flex slot (`1` / `wallbox_1` / `O3`). One PicoC output 1–8 per plant; assigned in Portal EMS connection"},"deadline_strict":{"type":"boolean"},"repeat_daily":{"type":"boolean"},"deadline_hour":{"type":"integer","minimum":0,"maximum":23,"description":"Sparvo latest start; ISO windows infer clock hours from start/end"},"allocation":{"type":"string"}}}}}},"responses":{"200":{"description":"Successful response"}},"security":[{"ApiKeyAuth":[]}]}},"/v1/plant/device-schedules":{"get":{"summary":"EMS-linked device schedules (Sparvo Zeitplan/Schedule as recipes[]; PicoC slot via Portal /settings/ems)","responses":{"200":{"description":"Successful response"}},"security":[{"ApiKeyAuth":[]}]}},"/v1/decision/hours-demand":{"post":{"summary":"Hours needed + charge_hours from SOC, load, PV (hours_demand_v1.11, prep after cover)","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"mode":{"type":"string","enum":["decide","telemetry"]},"battery":{"type":"object"},"meter":{"type":"object"},"load":{"type":"object"},"pv":{"type":"object"}}}}}},"responses":{"200":{"description":"Successful response"}},"security":[{"ApiKeyAuth":[]}]}},"/v1/plant/telemetry":{"post":{"summary":"Plant SOC and cumulative import meter ingest","responses":{"200":{"description":"Successful response"}},"security":[{"ApiKeyAuth":[]}]}},"/v1/plant/pv-forecast":{"get":{"summary":"7-day site PV yield (daily/hourly kWh)","parameters":[{"name":"granularity","in":"query","schema":{"type":"string","enum":["daily","hourly","both"],"default":"daily"}},{"name":"days","in":"query","schema":{"type":"integer","minimum":1,"maximum":7,"default":7}},{"name":"timezone","in":"query","schema":{"type":"string"}},{"name":"locale","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"Successful response"}},"security":[{"ApiKeyAuth":[]}]}},"/v1/plant/weather":{"get":{"summary":"Site weather current + multi-day outlook","parameters":[{"name":"days","in":"query","schema":{"type":"integer","minimum":1,"maximum":7,"default":3}},{"name":"timezone","in":"query","schema":{"type":"string"}},{"name":"locale","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"Successful response"}},"security":[{"ApiKeyAuth":[]}]}},"/v1/status":{"get":{"summary":"API readiness and endpoint map","responses":{"200":{"description":"Successful response"}},"security":[{"ApiKeyAuth":[]}]}}}}