{"openapi":"3.1.0","info":{"title":"Aotea Energy Halswell Flex Retailer API","description":"DRAFT integration contract. Telemetry requires verified units and registry data. Production control returns 501 until commissioned. Dashboard registration is planned.","license":{"name":""},"version":"1.0.1"},"paths":{"/api/v1.0.1/retailers/batteries/{battery_id}/control":{"put":{"tags":["Retailers"],"summary":"Draft control contract. Production returns 501 until the dispatch adapter is commissioned.","operationId":"battery_control","parameters":[{"name":"battery_id","in":"path","description":"Battery from the authorised installation list","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ControlRequest"}}},"required":true},"responses":{"202":{"description":"Future adapter: queued, not hardware-applied","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ControlReceipt"}}}},"400":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RetailerErrorBody"}}}},"401":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RetailerErrorBody"}}}},"403":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RetailerErrorBody"}}}},"404":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RetailerErrorBody"}}}},"409":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RetailerErrorBody"}}}},"429":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RetailerErrorBody"}}}},"501":{"description":"Dispatch not commissioned; no command sent","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RetailerErrorBody"}}}},"503":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RetailerErrorBody"}}}}},"security":[{"retailer-key":[]}]}},"/api/v1.0.1/retailers/batteries/{battery_id}/telemetry":{"get":{"tags":["Retailers"],"operationId":"battery_telemetry","parameters":[{"name":"battery_id","in":"path","description":"Battery from the authorised installation list","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Telemetry"}}}},"400":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RetailerErrorBody"}}}},"401":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RetailerErrorBody"}}}},"403":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RetailerErrorBody"}}}},"404":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RetailerErrorBody"}}}},"429":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RetailerErrorBody"}}}},"503":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RetailerErrorBody"}}}}},"security":[{"retailer-key":[]}]}},"/api/v1.0.1/retailers/installations":{"get":{"tags":["Retailers"],"operationId":"installations","responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/Installation"}}}}},"401":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RetailerErrorBody"}}}},"403":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RetailerErrorBody"}}}},"429":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RetailerErrorBody"}}}},"503":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RetailerErrorBody"}}}}},"security":[{"retailer-key":[]}]}},"/api/v1.0.1/retailers/me":{"get":{"tags":["Retailers"],"operationId":"identity","responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RetailerIdentity"}}}},"401":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RetailerErrorBody"}}}},"429":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RetailerErrorBody"}}}},"503":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RetailerErrorBody"}}}}},"security":[{"retailer-key":[]}]}}},"components":{"schemas":{"ControlReceipt":{"type":"object","required":["command_id","status","requested"],"properties":{"command_id":{"type":"string","format":"uuid"},"requested":{"$ref":"#/components/schemas/ControlRequest"},"status":{"type":"string","description":"A queued request is not evidence that hardware applied it."}}},"ControlRequest":{"type":"object","description":"Complete replacement of the retailer's requested operating parameters.","required":["charge_power_limit_kw","discharge_power_limit_kw","operating_mode"],"properties":{"charge_power_limit_kw":{"type":"number","format":"double","minimum":0},"discharge_power_limit_kw":{"type":"number","format":"double","minimum":0},"operating_mode":{"$ref":"#/components/schemas/OperatingMode"}},"additionalProperties":false},"Installation":{"type":"object","required":["installation_id","icp","batteries","control_authorised"],"properties":{"batteries":{"type":"array","items":{"type":"string","format":"uuid"}},"control_authorised":{"type":"boolean","description":"Consent permits control; this does not claim the dispatch adapter is commissioned."},"icp":{"type":"string"},"installation_id":{"type":"string","format":"uuid"}}},"OperatingMode":{"type":"string","enum":["charge","discharge","idle","self_consumption"]},"OperatingState":{"type":"string","enum":["charging","discharging","idle","unavailable"]},"RetailerErrorBody":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"}}},"RetailerIdentity":{"type":"object","required":["trader_participant_id","key_id","telemetry_read","control_write"],"properties":{"control_write":{"type":"boolean"},"key_id":{"type":"string","format":"uuid"},"telemetry_read":{"type":"boolean"},"trader_participant_id":{"type":"string"}}},"Telemetry":{"type":"object","required":["battery_id","operating_state"],"properties":{"battery_available_capacity_kwh":{"type":["number","null"],"format":"double","description":"Estimated DC energy above the effective reserve, adjusted by state of health.\nNull when capacity, effective reserve, SOC or SOH is unknown."},"battery_id":{"type":"string","format":"uuid"},"observed_at":{"type":["string","null"],"format":"date-time","description":"Timestamp of the latest received sample, even when it has become stale."},"operating_state":{"$ref":"#/components/schemas/OperatingState"},"real_power_import_export_kw":{"type":["number","null"],"format":"double","description":"Real power at the grid connection: positive import, negative export, in kW."},"state_of_charge_percent":{"type":["number","null"],"format":"double"}}}},"securitySchemes":{"retailer-key":{"type":"http","scheme":"bearer","bearerFormat":"Retailer API key (aer_...)","description":"Separate retailer credential issued after trader identity approval. Customer JWTs and user API keys are not accepted. Keys are never sent in query strings."}}},"tags":[{"name":"Retailers","description":"Halswell Flex telemetry and customer-authorised control"}]}