{ "openapi": "3.1.0", "info": { "title": "GridSense Application API", "version": "1.0.0", "description": "Read-only application API for installation metadata and last-known device telemetry. Authenticate with an application API key. Power is in W; energy is in Wh. Signs depend on device type: grid meter powerAc is positive for export and negative for import; battery powerDc is positive for charging and negative for discharging. Nullable telemetry is not zero. The JSON examples are fictional.", "x-gridsense-api-revision": "4f896f9a26d6403620ca5fcd8d29f5200bc371ad" }, "servers": [ { "url": "https://api.gridsense.nl/application/v1", "description": "GridSense Application API" } ], "security": [ { "ApiKey": [] }, { "BearerAuth": [] } ], "tags": [ { "name": "Application API", "description": "Read installation metadata and device telemetry." } ], "paths": { "/getInstallations": { "get": { "operationId": "getInstallations", "summary": "List installations", "description": "Returns every installation the application can currently read. Both an installation grant and continued owner access are required. Disabled applications or invalid keys receive 401. This is a live API request when executed in the playground.", "tags": [ "Application API" ], "responses": { "200": { "description": "Successful response. The example uses fictional data; the playground displays the actual API response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InstallationsResponse" }, "examples": { "Example": { "summary": "Example", "value": { "valid": true, "installations": [ { "id": 42, "name": "Example installation", "type": "commercial", "address": "Voorbeeldstraat 1", "postalCode": "3500 AA", "city": "Utrecht", "country": "NL", "timezone": "Europe/Amsterdam", "latitude": 52.0907, "longitude": 5.1214, "altitude": 5, "creationDate": "2026-09-01T09:00:00+02:00" } ] } } } } } }, "401": { "description": "Missing, malformed, unknown, revoked or expired key, or disabled application.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "UNAUTHORIZED": { "summary": "UNAUTHORIZED", "value": { "valid": false, "error": "UNAUTHORIZED" } } } } } }, "500": { "description": "Server-side failure.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "DATABASE_ERROR": { "summary": "DATABASE_ERROR", "value": { "valid": false, "error": "DATABASE_ERROR" } }, "INTERNAL_ERROR": { "summary": "INTERNAL_ERROR", "value": { "valid": false, "error": "INTERNAL_ERROR" } } } } } } } } }, "/getInstallationDevices": { "get": { "operationId": "getInstallationDevices", "summary": "List installation devices", "description": "Returns the last-known state of all six supported device categories for one accessible installation. First call getInstallations and copy a returned id into installationId. The example ID 42 is fictional. Offline devices are included: check lastSeenDate and treat null telemetry as unavailable. See the power direction guide for device-specific signs; grid meter powerAc is positive for export and battery powerDc is positive for charging.", "tags": [ "Application API" ], "responses": { "200": { "description": "Successful response. The example uses fictional data; the playground displays the actual API response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InstallationDevicesResponse" }, "examples": { "Example": { "summary": "Example", "value": { "valid": true, "installationId": 42, "inverters": [ { "id": 108, "installationId": 42, "gatewayId": 17, "manufacturer": "Example manufacturer", "model": "Example model", "version": null, "serialNumber": "EXAMPLE-108", "firstSeenDate": "2026-09-01T09:00:00+02:00", "lastSeenDate": "2026-09-08T12:00:00+02:00", "status": { "rawValue": 4, "name": "MPPT" }, "vendorStatusString": null, "isOffGrid": null, "maxChargePower": null, "maxDischargePower": null, "powerAc": 2000, "powerAcL1": null, "powerAcL2": null, "powerAcL3": null, "voltageAcL1": null, "voltageAcL2": null, "voltageAcL3": null, "currentAcL1": null, "currentAcL2": null, "currentAcL3": null, "frequency": null, "powerApparentAc": null, "powerReactiveAc": null, "powerFactor": null, "backupPowerAc": null, "powerDc": 2100, "powerDcPvTotal": 3600, "powerDcPv1": null, "powerDcPv2": null, "powerDcPv3": null, "powerDcPv4": null, "powerDcPv5": null, "powerDcPv6": null, "voltageDcPv1": null, "voltageDcPv2": null, "voltageDcPv3": null, "voltageDcPv4": null, "voltageDcPv5": null, "voltageDcPv6": null, "currentDcPv1": null, "currentDcPv2": null, "currentDcPv3": null, "currentDcPv4": null, "currentDcPv5": null, "currentDcPv6": null, "temperature": 38 } ], "batteries": [ { "id": 109, "installationId": 42, "gatewayId": 17, "inverterId": 108, "manufacturer": "Example manufacturer", "model": "Example model", "version": null, "serialNumber": "EXAMPLE-109", "firstSeenDate": "2026-09-01T09:00:00+02:00", "lastSeenDate": "2026-09-08T12:00:00+02:00", "status": null, "powerDc": 1500, "voltageDc": null, "currentDc": null, "soe": 65, "soh": 98, "temperature": null, "minCellTemperature": null, "avgCellTemperature": null, "maxCellTemperature": null, "minCellVoltage": null, "avgCellVoltage": null, "maxCellVoltage": null, "ratedEnergy": 10000, "maximumEnergy": null, "availableEnergy": null, "maxChargeContinuousPower": null, "maxDischargeContinuousPower": null, "minSoe": null, "maxSoe": null } ], "energyMeters": [ { "id": 110, "installationId": 42, "gatewayId": 17, "manufacturer": "Example manufacturer", "model": "Example model", "version": null, "serialNumber": "EXAMPLE-110", "firstSeenDate": "2026-09-01T09:00:00+02:00", "lastSeenDate": "2026-09-08T12:00:00+02:00", "powerAc": -500, "powerAcL1": null, "powerAcL2": null, "powerAcL3": null, "voltageAcL1": null, "voltageAcL2": null, "voltageAcL3": null, "currentAcL1": null, "currentAcL2": null, "currentAcL3": null, "frequency": null, "totalImportAc": null, "totalExportAc": null, "dailyImportAc": null, "dailyExportAc": null, "options": "Export+Import" } ], "evChargers": [ { "id": 111, "installationId": 42, "gatewayId": 17, "manufacturer": "Example manufacturer", "model": "Example model", "version": null, "serialNumber": "EXAMPLE-111", "firstSeenDate": "2026-09-01T09:00:00+02:00", "lastSeenDate": "2026-09-08T12:00:00+02:00", "mode": "ALWAYS_ON", "requireAuthorization": null, "supportsBiDirectionalCharging": false, "maxChargingCurrent": null, "currentMaxChargingCurrent": null, "status": null, "vendorStatusString": null, "powerOffered": null, "powerAc": 1000, "powerAcL1": null, "powerAcL2": null, "powerAcL3": null, "voltageAcL1": null, "voltageAcL2": null, "voltageAcL3": null, "currentAcL1": null, "currentAcL2": null, "currentAcL3": null, "frequencyAc": null, "powerDc": null, "voltageDc": null, "currentDc": null, "temperature": null } ], "relays": [ { "id": 112, "installationId": 42, "gatewayId": 17, "manufacturer": "Example manufacturer", "model": "Example model", "version": null, "serialNumber": "EXAMPLE-112", "firstSeenDate": "2026-09-01T09:00:00+02:00", "lastSeenDate": "2026-09-08T12:00:00+02:00", "relayCount": 2, "currentState": [ true, false ], "desiredState": [ null, false ] } ], "boilers": [ { "id": 113, "installationId": 42, "gatewayId": 17, "manufacturer": "Example manufacturer", "model": "Example model", "version": null, "serialNumber": "EXAMPLE-113", "firstSeenDate": "2026-09-01T09:00:00+02:00", "lastSeenDate": "2026-09-08T12:00:00+02:00", "status": null, "vendorStatusString": null, "boilerMode": "EXCESS_PV_BATTERY_PREFERRED", "powerAc": 500, "powerAcL1": null, "powerAcL2": null, "powerAcL3": null, "voltageAcL1": null, "voltageAcL2": null, "voltageAcL3": null, "currentAcL1": null, "currentAcL2": null, "currentAcL3": null, "frequency": null, "temperature": 52, "temperature2": null, "temperature3": null, "temperature4": null, "targetTemperature": null, "minimumTemperature": null, "availablePower": null, "effectiveMaxPower": null, "operationMode": null, "operationState": null, "deviceState": null, "relayState": null, "loadState": null, "pwmPercent": null } ] } } } } } }, "401": { "description": "Missing, malformed, unknown, revoked or expired key, or disabled application.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "UNAUTHORIZED": { "summary": "UNAUTHORIZED", "value": { "valid": false, "error": "UNAUTHORIZED" } } } } } }, "500": { "description": "Server-side serialization or device retrieval failure.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "INTERNAL_ERROR": { "summary": "INTERNAL_ERROR", "value": { "valid": false, "error": "INTERNAL_ERROR" } } } } } }, "400": { "description": "Required installationId is absent or not a valid integer.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "MISSING_PARAMETERS": { "summary": "MISSING_PARAMETERS", "value": { "valid": false, "error": "MISSING_PARAMETERS" } }, "INVALID_PARAMETERS": { "summary": "INVALID_PARAMETERS", "value": { "valid": false, "error": "INVALID_PARAMETERS" } } } } } }, "404": { "description": "Installation does not exist or this application cannot access it. Both cases intentionally return the same error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "DOESNT_EXIST": { "summary": "DOESNT_EXIST", "value": { "valid": false, "error": "DOESNT_EXIST" } } } } } } }, "parameters": [ { "name": "installationId", "in": "query", "required": true, "description": "Integer installation ID returned by getInstallations. Replace the fictional example with an ID your application can access. Fractions are rejected.", "schema": { "type": "integer" }, "example": 42 } ] } }, "/getInstallationCurrentEnergyFlow": { "get": { "operationId": "getInstallationCurrentEnergyFlow", "summary": "Get current installation energy flow", "description": "Returns aggregated energy flow for an accessible installation using the same calculation as the app API. First call getInstallations and enter a returned id as installationId. Only online devices contribute; data is null when none are online. All power fields are in W. gridPower is positive for import and negative for export, opposite to raw grid-meter powerAc. batteryPower is positive for charging and negative for discharging. housePower excludes EV charger and boiler consumption. See the power direction guide for calculation details and missing-reading caveats.", "tags": [ "Application API" ], "responses": { "200": { "description": "Current energy flow, or null data when no relevant devices are online.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InstallationCurrentEnergyFlowResponse" }, "examples": { "Example": { "summary": "Fictional installation exporting to the grid while charging a battery", "value": { "valid": true, "installationId": 42, "data": { "inverterPower": 4200, "solarPower": 5000, "batteryPower": 800, "batterySoe": 65, "gridPower": -1200, "housePower": 2000, "evChargerPower": 600, "boilerPower": 400, "lastUpdated": "2026-09-09T14:05:11+02:00" } } }, "NoOnlineDevices": { "summary": "No online devices", "value": { "valid": true, "installationId": 42, "data": null } } } } } }, "401": { "description": "Missing, malformed, unknown, revoked or expired key, or disabled application.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "UNAUTHORIZED": { "summary": "UNAUTHORIZED", "value": { "valid": false, "error": "UNAUTHORIZED" } } } } } }, "500": { "description": "Energy flow calculation or JSON encoding failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "INTERNAL_ERROR": { "summary": "INTERNAL_ERROR", "value": { "valid": false, "error": "INTERNAL_ERROR" } } } } } }, "400": { "description": "Required installationId is absent or not a valid integer.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "MISSING_PARAMETERS": { "summary": "MISSING_PARAMETERS", "value": { "valid": false, "error": "MISSING_PARAMETERS" } }, "INVALID_PARAMETERS": { "summary": "INVALID_PARAMETERS", "value": { "valid": false, "error": "INVALID_PARAMETERS" } } } } } }, "404": { "description": "Installation does not exist or this application cannot access it. Both cases intentionally return the same error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "DOESNT_EXIST": { "summary": "DOESNT_EXIST", "value": { "valid": false, "error": "DOESNT_EXIST" } } } } } } }, "parameters": [ { "name": "installationId", "in": "query", "required": true, "description": "Integer installation ID returned by getInstallations. Replace the fictional example with an ID your application can access. Fractions are rejected.", "schema": { "type": "integer" }, "example": 42 } ] } } }, "components": { "securitySchemes": { "ApiKey": { "type": "apiKey", "in": "header", "name": "Api-Key", "description": "Paste your full gsak_ application API key." }, "BearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "GridSense application API key", "description": "Use the same full gsak_ application API key as a bearer token. It is an opaque API key, not a JWT. Use either this or Api-Key; when both are sent a Bearer authorization header takes precedence." } }, "schemas": { "Installation": { "type": "object", "description": "Installation fields explicitly exposed by the application API. Nullable fields are unknown, unavailable or unsupported; null is not zero.", "properties": { "id": { "type": "integer", "description": "Unique identifier of this record." }, "name": { "type": "string", "description": "Installation display name." }, "type": { "type": "string", "description": "Installation category: private or commercial.", "enum": [ "private", "commercial" ] }, "address": { "type": "string", "description": "Street address of the installation." }, "postalCode": { "type": "string", "description": "Installation postal code." }, "city": { "type": "string", "description": "Installation city." }, "country": { "type": "string", "description": "Installation country code, for example NL." }, "timezone": { "type": "string", "description": "IANA timezone of the installation, for example Europe/Amsterdam." }, "latitude": { "type": [ "number", "null" ], "description": "Latitude in decimal degrees." }, "longitude": { "type": [ "number", "null" ], "description": "Longitude in decimal degrees." }, "altitude": { "type": [ "number", "null" ], "description": "Installation altitude in metres." }, "creationDate": { "type": [ "string", "null" ], "description": "Installation creation time, as an ISO 8601 timestamp with UTC offset.", "format": "date-time" } }, "required": [ "id", "name", "type", "address", "postalCode", "city", "country", "timezone", "latitude", "longitude", "altitude", "creationDate" ] }, "Inverter": { "type": "object", "description": "Inverter fields explicitly exposed by the application API. Nullable fields are unknown, unavailable or unsupported; null is not zero.", "properties": { "id": { "type": "integer", "description": "Unique identifier of this record." }, "installationId": { "type": [ "integer", "null" ], "description": "Identifier of the installation this device belongs to." }, "gatewayId": { "type": [ "integer", "null" ], "description": "Identifier of the associated gateway; null when no gateway is assigned." }, "manufacturer": { "type": [ "string", "null" ], "description": "Device manufacturer. Null bytes and surrounding whitespace are removed." }, "model": { "type": [ "string", "null" ], "description": "Device model. Null bytes and surrounding whitespace are removed." }, "version": { "type": [ "string", "null" ], "description": "Reported firmware/software version. Null bytes and surrounding whitespace are removed." }, "serialNumber": { "type": [ "string", "null" ], "description": "Device serial number. Null bytes and surrounding whitespace are removed." }, "firstSeenDate": { "type": [ "string", "null" ], "description": "First time this device was seen, as an ISO 8601 timestamp with UTC offset.", "format": "date-time" }, "lastSeenDate": { "type": [ "string", "null" ], "description": "Last time this device was seen, as an ISO 8601 timestamp with UTC offset. Check freshness before interpreting telemetry; this endpoint also includes offline devices.", "format": "date-time" }, "status": { "description": "Normalized SunSpec inverter status, or null when unavailable/unrecognized.", "anyOf": [ { "$ref": "#/components/schemas/InverterStatus" }, { "type": "null" } ] }, "vendorStatusString": { "type": [ "string", "null" ], "description": "Device/vendor-specific status text; no fixed set of values." }, "isOffGrid": { "type": [ "boolean", "null" ], "description": "Whether the inverter reports off-grid operation." }, "maxChargePower": { "type": [ "integer", "null" ], "description": "Maximum inverter charging power in W, expressed as a magnitude, not a signed measurement." }, "maxDischargePower": { "type": [ "integer", "null" ], "description": "Maximum inverter discharging power in W, expressed as a magnitude, not a signed measurement." }, "powerAc": { "type": [ "number", "null" ], "description": "Total AC active power in W. Positive = power supplied by the inverter to the installation AC bus (PV production and/or battery discharge). Negative = power absorbed from the AC bus (for example battery charging or standby consumption). It does not by itself indicate export/import at the grid connection." }, "powerAcL1": { "type": [ "number", "null" ], "description": "AC active power on phase L1 in W. Positive = power supplied by the inverter to the installation AC bus (PV production and/or battery discharge). Negative = power absorbed from the AC bus (for example battery charging or standby consumption). It does not by itself indicate export/import at the grid connection." }, "powerAcL2": { "type": [ "number", "null" ], "description": "AC active power on phase L2 in W. Positive = power supplied by the inverter to the installation AC bus (PV production and/or battery discharge). Negative = power absorbed from the AC bus (for example battery charging or standby consumption). It does not by itself indicate export/import at the grid connection." }, "powerAcL3": { "type": [ "number", "null" ], "description": "AC active power on phase L3 in W. Positive = power supplied by the inverter to the installation AC bus (PV production and/or battery discharge). Negative = power absorbed from the AC bus (for example battery charging or standby consumption). It does not by itself indicate export/import at the grid connection." }, "voltageAcL1": { "type": [ "number", "null" ], "description": "AC voltage on phase L1 in V." }, "voltageAcL2": { "type": [ "number", "null" ], "description": "AC voltage on phase L2 in V." }, "voltageAcL3": { "type": [ "number", "null" ], "description": "AC voltage on phase L3 in V." }, "currentAcL1": { "type": [ "number", "null" ], "description": "AC current on phase L1 in A. Use powerAcL1 for active power direction; current sign conventions depend on the device." }, "currentAcL2": { "type": [ "number", "null" ], "description": "AC current on phase L2 in A. Use powerAcL2 for active power direction; current sign conventions depend on the device." }, "currentAcL3": { "type": [ "number", "null" ], "description": "AC current on phase L3 in A. Use powerAcL3 for active power direction; current sign conventions depend on the device." }, "frequency": { "type": [ "number", "null" ], "description": "AC frequency in Hz." }, "powerApparentAc": { "type": [ "number", "null" ], "description": "Total AC apparent power in VA. Do not use its sign to determine active power import/export." }, "powerReactiveAc": { "type": [ "number", "null" ], "description": "Total AC reactive power in var. The API passes through the device convention; it does not guarantee a uniform inductive/capacitive sign mapping. Use powerAc for active power direction." }, "powerFactor": { "type": [ "number", "null" ], "description": "AC power factor, dimensionless. Device-specific sign convention; use powerAc for active power direction." }, "backupPowerAc": { "type": [ "number", "null" ], "description": "AC power at the backup/EPS output in W. Positive means supplying backup loads; negative means reverse flow into that output if the device reports it. This is not the grid connection measurement." }, "powerDc": { "type": [ "number", "null" ], "description": "Device-reported inverter DC power in W. On devices exposing net DC conversion (for example SolarEdge), positive = DC power into the inverter toward AC, negative = reverse conversion from AC to DC. Other integrations use this field for PV production. It is not a universal battery charge/discharge measurement: use batteries[].powerDc for that, and powerDcPvTotal for PV production." }, "powerDcPvTotal": { "type": [ "number", "null" ], "description": "Total PV DC production power in W. Positive means solar production into the inverter; zero means no measured production. Negative values are not a defined charging/import state. Prefer this field over powerDc for solar production; it can be null on unsupported devices." }, "powerDcPv1": { "type": [ "number", "null" ], "description": "PV DC power on input 1 in W. Positive = solar production into the inverter. Negative has no defined charge/import meaning." }, "powerDcPv2": { "type": [ "number", "null" ], "description": "PV DC power on input 2 in W. Positive = solar production into the inverter. Negative has no defined charge/import meaning." }, "powerDcPv3": { "type": [ "number", "null" ], "description": "PV DC power on input 3 in W. Positive = solar production into the inverter. Negative has no defined charge/import meaning." }, "powerDcPv4": { "type": [ "number", "null" ], "description": "PV DC power on input 4 in W. Positive = solar production into the inverter. Negative has no defined charge/import meaning." }, "powerDcPv5": { "type": [ "number", "null" ], "description": "PV DC power on input 5 in W. Positive = solar production into the inverter. Negative has no defined charge/import meaning." }, "powerDcPv6": { "type": [ "number", "null" ], "description": "PV DC power on input 6 in W. Positive = solar production into the inverter. Negative has no defined charge/import meaning." }, "voltageDcPv1": { "type": [ "number", "null" ], "description": "PV DC voltage on input 1 in V." }, "voltageDcPv2": { "type": [ "number", "null" ], "description": "PV DC voltage on input 2 in V." }, "voltageDcPv3": { "type": [ "number", "null" ], "description": "PV DC voltage on input 3 in V." }, "voltageDcPv4": { "type": [ "number", "null" ], "description": "PV DC voltage on input 4 in V." }, "voltageDcPv5": { "type": [ "number", "null" ], "description": "PV DC voltage on input 5 in V." }, "voltageDcPv6": { "type": [ "number", "null" ], "description": "PV DC voltage on input 6 in V." }, "currentDcPv1": { "type": [ "number", "null" ], "description": "PV DC current on input 1 in A; use the corresponding powerDcPv field for production." }, "currentDcPv2": { "type": [ "number", "null" ], "description": "PV DC current on input 2 in A; use the corresponding powerDcPv field for production." }, "currentDcPv3": { "type": [ "number", "null" ], "description": "PV DC current on input 3 in A; use the corresponding powerDcPv field for production." }, "currentDcPv4": { "type": [ "number", "null" ], "description": "PV DC current on input 4 in A; use the corresponding powerDcPv field for production." }, "currentDcPv5": { "type": [ "number", "null" ], "description": "PV DC current on input 5 in A; use the corresponding powerDcPv field for production." }, "currentDcPv6": { "type": [ "number", "null" ], "description": "PV DC current on input 6 in A; use the corresponding powerDcPv field for production." }, "temperature": { "type": [ "number", "null" ], "description": "Device temperature in °C." } }, "required": [ "id", "installationId", "gatewayId", "manufacturer", "model", "version", "serialNumber", "firstSeenDate", "lastSeenDate", "status", "vendorStatusString", "isOffGrid", "maxChargePower", "maxDischargePower", "powerAc", "powerAcL1", "powerAcL2", "powerAcL3", "voltageAcL1", "voltageAcL2", "voltageAcL3", "currentAcL1", "currentAcL2", "currentAcL3", "frequency", "powerApparentAc", "powerReactiveAc", "powerFactor", "backupPowerAc", "powerDc", "powerDcPvTotal", "powerDcPv1", "powerDcPv2", "powerDcPv3", "powerDcPv4", "powerDcPv5", "powerDcPv6", "voltageDcPv1", "voltageDcPv2", "voltageDcPv3", "voltageDcPv4", "voltageDcPv5", "voltageDcPv6", "currentDcPv1", "currentDcPv2", "currentDcPv3", "currentDcPv4", "currentDcPv5", "currentDcPv6", "temperature" ] }, "Battery": { "type": "object", "description": "Battery fields explicitly exposed by the application API. Nullable fields are unknown, unavailable or unsupported; null is not zero.", "properties": { "id": { "type": "integer", "description": "Unique identifier of this record." }, "installationId": { "type": [ "integer", "null" ], "description": "Identifier of the installation this device belongs to." }, "gatewayId": { "type": [ "integer", "null" ], "description": "Identifier of the associated gateway; null when no gateway is assigned." }, "inverterId": { "type": [ "integer", "null" ], "description": "Identifier of the associated inverter; null when no inverter is assigned." }, "manufacturer": { "type": [ "string", "null" ], "description": "Device manufacturer. Null bytes and surrounding whitespace are removed." }, "model": { "type": [ "string", "null" ], "description": "Device model. Null bytes and surrounding whitespace are removed." }, "version": { "type": [ "string", "null" ], "description": "Reported firmware/software version. Null bytes and surrounding whitespace are removed." }, "serialNumber": { "type": [ "string", "null" ], "description": "Device serial number. Null bytes and surrounding whitespace are removed." }, "firstSeenDate": { "type": [ "string", "null" ], "description": "First time this device was seen, as an ISO 8601 timestamp with UTC offset.", "format": "date-time" }, "lastSeenDate": { "type": [ "string", "null" ], "description": "Last time this device was seen, as an ISO 8601 timestamp with UTC offset. Check freshness before interpreting telemetry; this endpoint also includes offline devices.", "format": "date-time" }, "status": { "type": [ "integer", "null" ], "description": "Device-reported numeric battery status. The application API does not normalize a common status enum across manufacturers." }, "powerDc": { "type": [ "number", "null" ], "description": "Battery DC power in W. Positive = charging (energy into the battery); negative = discharging (energy out of the battery). Zero = no measured net power flow. This sign is the opposite of inverter AC output during battery-only operation." }, "voltageDc": { "type": [ "number", "null" ], "description": "DC voltage in V." }, "currentDc": { "type": [ "number", "null" ], "description": "Battery DC current in A. Where signed current is supported, positive = charging and negative = discharging. Use powerDc as the primary flow measurement." }, "soe": { "type": [ "number", "null" ], "description": "State of energy in percent (0–100), not a 0–1 fraction. For example 50 means 50%." }, "soh": { "type": [ "number", "null" ], "description": "State of health in percent (0–100), not a 0–1 fraction." }, "temperature": { "type": [ "number", "null" ], "description": "Device temperature in °C." }, "minCellTemperature": { "type": [ "number", "null" ], "description": "Minimum battery cell temperature in °C." }, "avgCellTemperature": { "type": [ "number", "null" ], "description": "Average battery cell temperature in °C." }, "maxCellTemperature": { "type": [ "number", "null" ], "description": "Maximum battery cell temperature in °C." }, "minCellVoltage": { "type": [ "number", "null" ], "description": "Minimum battery cell voltage in V." }, "avgCellVoltage": { "type": [ "number", "null" ], "description": "Average battery cell voltage in V." }, "maxCellVoltage": { "type": [ "number", "null" ], "description": "Maximum battery cell voltage in V." }, "ratedEnergy": { "type": [ "number", "null" ], "description": "Nominal battery capacity in Wh. Returns the configured capacity override when present, otherwise the device-reported rated energy." }, "maximumEnergy": { "type": [ "number", "null" ], "description": "Device-reported maximum energy capacity in Wh." }, "availableEnergy": { "type": [ "number", "null" ], "description": "Device-reported available stored energy in Wh." }, "maxChargeContinuousPower": { "type": [ "number", "null" ], "description": "Maximum continuous charging power in W, expressed as a magnitude." }, "maxDischargeContinuousPower": { "type": [ "number", "null" ], "description": "Maximum continuous discharging power in W, expressed as a magnitude." }, "minSoe": { "type": [ "integer", "null" ], "description": "Minimum state of energy limit in percent (0–100)." }, "maxSoe": { "type": [ "integer", "null" ], "description": "Maximum state of energy limit in percent (0–100)." } }, "required": [ "id", "installationId", "gatewayId", "inverterId", "manufacturer", "model", "version", "serialNumber", "firstSeenDate", "lastSeenDate", "status", "powerDc", "voltageDc", "currentDc", "soe", "soh", "temperature", "minCellTemperature", "avgCellTemperature", "maxCellTemperature", "minCellVoltage", "avgCellVoltage", "maxCellVoltage", "ratedEnergy", "maximumEnergy", "availableEnergy", "maxChargeContinuousPower", "maxDischargeContinuousPower", "minSoe", "maxSoe" ] }, "EnergyMeter": { "type": "object", "description": "EnergyMeter fields explicitly exposed by the application API. Nullable fields are unknown, unavailable or unsupported; null is not zero.", "properties": { "id": { "type": "integer", "description": "Unique identifier of this record." }, "installationId": { "type": [ "integer", "null" ], "description": "Identifier of the installation this device belongs to." }, "gatewayId": { "type": [ "integer", "null" ], "description": "Identifier of the associated gateway; null when no gateway is assigned." }, "manufacturer": { "type": [ "string", "null" ], "description": "Device manufacturer. Null bytes and surrounding whitespace are removed." }, "model": { "type": [ "string", "null" ], "description": "Device model. Null bytes and surrounding whitespace are removed." }, "version": { "type": [ "string", "null" ], "description": "Reported firmware/software version. Null bytes and surrounding whitespace are removed." }, "serialNumber": { "type": [ "string", "null" ], "description": "Device serial number. Null bytes and surrounding whitespace are removed." }, "options": { "type": [ "string", "null" ], "description": "Meter role/options reported by the integration, as a string or null. Null bytes and surrounding whitespace are removed; an empty string stays empty. Export+Import identifies the main grid import/export meter; Boiler consumption identifies a boiler consumption meter; strings containing Production ext indicate external production. This is an open string, not a fixed enum. For null, empty or unrecognized values, confirm the meter role and wiring before interpreting power." }, "firstSeenDate": { "type": [ "string", "null" ], "description": "First time this device was seen, as an ISO 8601 timestamp with UTC offset.", "format": "date-time" }, "lastSeenDate": { "type": [ "string", "null" ], "description": "Last time this device was seen, as an ISO 8601 timestamp with UTC offset. Check freshness before interpreting telemetry; this endpoint also includes offline devices.", "format": "date-time" }, "powerAc": { "type": [ "number", "null" ], "description": "Total AC active power in W. For a grid import/export meter: positive = export to the grid; negative = import from the grid. For a production meter: positive = production into the installation. Other meter roles depend on installation/wiring. Use options to identify the meter role; do not assume every meter measures the grid connection. Confirm the role and wiring when options is null, empty or unrecognized." }, "powerAcL1": { "type": [ "number", "null" ], "description": "AC active power on phase L1 in W. For a grid import/export meter: positive = export to the grid; negative = import from the grid. For a production meter: positive = production into the installation. Other meter roles depend on installation/wiring. Use options to identify the meter role; do not assume every meter measures the grid connection. Confirm the role and wiring when options is null, empty or unrecognized." }, "powerAcL2": { "type": [ "number", "null" ], "description": "AC active power on phase L2 in W. For a grid import/export meter: positive = export to the grid; negative = import from the grid. For a production meter: positive = production into the installation. Other meter roles depend on installation/wiring. Use options to identify the meter role; do not assume every meter measures the grid connection. Confirm the role and wiring when options is null, empty or unrecognized." }, "powerAcL3": { "type": [ "number", "null" ], "description": "AC active power on phase L3 in W. For a grid import/export meter: positive = export to the grid; negative = import from the grid. For a production meter: positive = production into the installation. Other meter roles depend on installation/wiring. Use options to identify the meter role; do not assume every meter measures the grid connection. Confirm the role and wiring when options is null, empty or unrecognized." }, "voltageAcL1": { "type": [ "number", "null" ], "description": "AC voltage on phase L1 in V." }, "voltageAcL2": { "type": [ "number", "null" ], "description": "AC voltage on phase L2 in V." }, "voltageAcL3": { "type": [ "number", "null" ], "description": "AC voltage on phase L3 in V." }, "currentAcL1": { "type": [ "number", "null" ], "description": "AC current on phase L1 in A. Use powerAcL1 for active power direction; current sign conventions depend on the device." }, "currentAcL2": { "type": [ "number", "null" ], "description": "AC current on phase L2 in A. Use powerAcL2 for active power direction; current sign conventions depend on the device." }, "currentAcL3": { "type": [ "number", "null" ], "description": "AC current on phase L3 in A. Use powerAcL3 for active power direction; current sign conventions depend on the device." }, "frequency": { "type": [ "number", "null" ], "description": "AC frequency in Hz." }, "totalImportAc": { "type": [ "number", "null" ], "description": "Cumulative AC energy imported in Wh, expressed as a magnitude. Direction is encoded in the field name, not the sign; the meter role/wiring determines the boundary." }, "totalExportAc": { "type": [ "number", "null" ], "description": "Cumulative AC energy exported in Wh, expressed as a magnitude. Direction is encoded in the field name, not the sign; the meter role/wiring determines the boundary." }, "dailyImportAc": { "type": [ "number", "null" ], "description": "Daily AC energy imported in Wh, expressed as a magnitude. Direction is encoded in the field name, not the sign; the meter role/wiring determines the boundary. Reset timing follows the device; the application API does not define a universal midnight/timezone." }, "dailyExportAc": { "type": [ "number", "null" ], "description": "Daily AC energy exported in Wh, expressed as a magnitude. Direction is encoded in the field name, not the sign; the meter role/wiring determines the boundary. Reset timing follows the device; the application API does not define a universal midnight/timezone." } }, "required": [ "id", "installationId", "gatewayId", "manufacturer", "model", "version", "serialNumber", "options", "firstSeenDate", "lastSeenDate", "powerAc", "powerAcL1", "powerAcL2", "powerAcL3", "voltageAcL1", "voltageAcL2", "voltageAcL3", "currentAcL1", "currentAcL2", "currentAcL3", "frequency", "totalImportAc", "totalExportAc", "dailyImportAc", "dailyExportAc" ] }, "EVCharger": { "type": "object", "description": "EVCharger fields explicitly exposed by the application API. Nullable fields are unknown, unavailable or unsupported; null is not zero.", "properties": { "id": { "type": "integer", "description": "Unique identifier of this record." }, "installationId": { "type": [ "integer", "null" ], "description": "Identifier of the installation this device belongs to." }, "gatewayId": { "type": [ "integer", "null" ], "description": "Identifier of the associated gateway; null when no gateway is assigned." }, "manufacturer": { "type": "string", "description": "Device manufacturer. Null bytes and surrounding whitespace are removed." }, "model": { "type": [ "string", "null" ], "description": "Device model. Null bytes and surrounding whitespace are removed." }, "version": { "type": [ "string", "null" ], "description": "Reported firmware/software version. Null bytes and surrounding whitespace are removed." }, "serialNumber": { "type": "string", "description": "Device serial number. Null bytes and surrounding whitespace are removed." }, "firstSeenDate": { "type": [ "string", "null" ], "description": "First time this device was seen, as an ISO 8601 timestamp with UTC offset.", "format": "date-time" }, "lastSeenDate": { "type": [ "string", "null" ], "description": "Last time this device was seen, as an ISO 8601 timestamp with UTC offset. Check freshness before interpreting telemetry; this endpoint also includes offline devices.", "format": "date-time" }, "mode": { "type": [ "string", "null" ], "description": "Selected EV charging mode. Read-only; this endpoint cannot change it.", "enum": [ "ALWAYS_ON", "CHARGE_EXCESS_PV_AND_LOWEST_PRICE", "CHARGE_LOWEST_PRICE", "CHARGE_EXCESS_PV", "ALWAYS_OFF", null ] }, "requireAuthorization": { "type": [ "boolean", "null" ], "description": "Whether authorization is required to start EV charging." }, "supportsBiDirectionalCharging": { "type": "boolean", "description": "Whether bidirectional charging is supported. Always false in the current application API implementation." }, "maxChargingCurrent": { "type": [ "number", "null" ], "description": "Configured maximum charging current in A." }, "currentMaxChargingCurrent": { "type": [ "number", "null" ], "description": "Current charging-current limit in A, computed from the selected mode and schedule; may differ from maxChargingCurrent. Zero means charging is not currently allowed." }, "status": { "type": [ "string", "null" ], "description": "Device-reported EV charger status string. The application API does not enforce a common enum across integrations." }, "vendorStatusString": { "type": [ "string", "null" ], "description": "Device/vendor-specific status text; no fixed set of values." }, "powerOffered": { "type": [ "number", "null" ], "description": "Charging power offered to the vehicle in W; a limit/offer, not actual consumption." }, "powerAc": { "type": [ "number", "null" ], "description": "Total AC active power in W. Positive = consumption for vehicle charging. Bidirectional charging is not supported in this version (supportsBiDirectionalCharging is false); a negative value has no supported vehicle-discharge/V2G meaning." }, "powerAcL1": { "type": [ "number", "null" ], "description": "AC active power on phase L1 in W. Positive = consumption for vehicle charging. Bidirectional charging is not supported in this version (supportsBiDirectionalCharging is false); a negative value has no supported vehicle-discharge/V2G meaning." }, "powerAcL2": { "type": [ "number", "null" ], "description": "AC active power on phase L2 in W. Positive = consumption for vehicle charging. Bidirectional charging is not supported in this version (supportsBiDirectionalCharging is false); a negative value has no supported vehicle-discharge/V2G meaning." }, "powerAcL3": { "type": [ "number", "null" ], "description": "AC active power on phase L3 in W. Positive = consumption for vehicle charging. Bidirectional charging is not supported in this version (supportsBiDirectionalCharging is false); a negative value has no supported vehicle-discharge/V2G meaning." }, "voltageAcL1": { "type": [ "number", "null" ], "description": "AC voltage on phase L1 in V." }, "voltageAcL2": { "type": [ "number", "null" ], "description": "AC voltage on phase L2 in V." }, "voltageAcL3": { "type": [ "number", "null" ], "description": "AC voltage on phase L3 in V." }, "currentAcL1": { "type": [ "number", "null" ], "description": "AC current on phase L1 in A. Use powerAcL1 for active power direction; current sign conventions depend on the device." }, "currentAcL2": { "type": [ "number", "null" ], "description": "AC current on phase L2 in A. Use powerAcL2 for active power direction; current sign conventions depend on the device." }, "currentAcL3": { "type": [ "number", "null" ], "description": "AC current on phase L3 in A. Use powerAcL3 for active power direction; current sign conventions depend on the device." }, "frequencyAc": { "type": [ "number", "null" ], "description": "AC frequency in Hz." }, "powerDc": { "type": [ "number", "null" ], "description": "DC charging power in W. Positive = power delivered to the vehicle for charging. Bidirectional charging is not supported in this version; a negative value has no supported vehicle-discharge/V2G meaning." }, "voltageDc": { "type": [ "number", "null" ], "description": "DC voltage in V." }, "currentDc": { "type": [ "number", "null" ], "description": "DC current in A. Use powerDc for power-flow direction; current sign conventions may depend on the device." }, "temperature": { "type": [ "number", "null" ], "description": "Device temperature in °C." } }, "required": [ "id", "installationId", "gatewayId", "manufacturer", "model", "version", "serialNumber", "firstSeenDate", "lastSeenDate", "mode", "requireAuthorization", "supportsBiDirectionalCharging", "maxChargingCurrent", "currentMaxChargingCurrent", "status", "vendorStatusString", "powerOffered", "powerAc", "powerAcL1", "powerAcL2", "powerAcL3", "voltageAcL1", "voltageAcL2", "voltageAcL3", "currentAcL1", "currentAcL2", "currentAcL3", "frequencyAc", "powerDc", "voltageDc", "currentDc", "temperature" ] }, "Relay": { "type": "object", "description": "Relay fields explicitly exposed by the application API. Nullable fields are unknown, unavailable or unsupported; null is not zero.", "properties": { "id": { "type": "integer", "description": "Unique identifier of this record." }, "installationId": { "type": [ "integer", "null" ], "description": "Identifier of the installation this device belongs to." }, "gatewayId": { "type": [ "integer", "null" ], "description": "Identifier of the associated gateway; null when no gateway is assigned." }, "manufacturer": { "type": [ "string", "null" ], "description": "Device manufacturer. Null bytes and surrounding whitespace are removed." }, "model": { "type": [ "string", "null" ], "description": "Device model. Null bytes and surrounding whitespace are removed." }, "version": { "type": [ "string", "null" ], "description": "Reported firmware/software version. Null bytes and surrounding whitespace are removed." }, "serialNumber": { "type": [ "string", "null" ], "description": "Device serial number. Null bytes and surrounding whitespace are removed." }, "firstSeenDate": { "type": [ "string", "null" ], "description": "First time this device was seen, as an ISO 8601 timestamp with UTC offset.", "format": "date-time" }, "lastSeenDate": { "type": [ "string", "null" ], "description": "Last time this device was seen, as an ISO 8601 timestamp with UTC offset. Check freshness before interpreting telemetry; this endpoint also includes offline devices.", "format": "date-time" }, "relayCount": { "type": [ "integer", "null" ], "description": "Number of relay channels." }, "currentState": { "type": [ "array", "null" ], "description": "Reported state of each relay, indexed from zero: true = on, false = off. Null means unavailable.", "items": { "type": "boolean" } }, "desiredState": { "type": [ "array", "null" ], "description": "Requested manual state of each relay, indexed from zero: true = on, false = off, null = automatic control/no manual override for that channel. The whole value may also be null. This is not necessarily the actual or automation-resolved state.", "items": { "type": [ "boolean", "null" ] } } }, "required": [ "id", "installationId", "gatewayId", "manufacturer", "model", "version", "serialNumber", "firstSeenDate", "lastSeenDate", "relayCount", "currentState", "desiredState" ] }, "Boiler": { "type": "object", "description": "Boiler fields explicitly exposed by the application API. Nullable fields are unknown, unavailable or unsupported; null is not zero.", "properties": { "id": { "type": "integer", "description": "Unique identifier of this record." }, "installationId": { "type": [ "integer", "null" ], "description": "Identifier of the installation this device belongs to." }, "gatewayId": { "type": [ "integer", "null" ], "description": "Identifier of the associated gateway; null when no gateway is assigned." }, "manufacturer": { "type": "string", "description": "Device manufacturer. Null bytes and surrounding whitespace are removed." }, "model": { "type": [ "string", "null" ], "description": "Device model. Null bytes and surrounding whitespace are removed." }, "version": { "type": [ "string", "null" ], "description": "Reported firmware/software version. Null bytes and surrounding whitespace are removed." }, "serialNumber": { "type": "string", "description": "Device serial number. Null bytes and surrounding whitespace are removed." }, "firstSeenDate": { "type": [ "string", "null" ], "description": "First time this device was seen, as an ISO 8601 timestamp with UTC offset.", "format": "date-time" }, "lastSeenDate": { "type": [ "string", "null" ], "description": "Last time this device was seen, as an ISO 8601 timestamp with UTC offset. Check freshness before interpreting telemetry; this endpoint also includes offline devices.", "format": "date-time" }, "status": { "type": [ "integer", "null" ], "description": "Device-reported numeric boiler status. The application API does not normalize a common status enum across manufacturers." }, "vendorStatusString": { "type": [ "string", "null" ], "description": "Device/vendor-specific status text; no fixed set of values." }, "boilerMode": { "type": [ "string", "null" ], "description": "Current boiler control mode. Read-only; this endpoint cannot change it.", "enum": [ "FORCE_ON", "FORCE_OFF", "EXCESS_PV_BATTERY_PREFERRED", "EXCESS_PV_BOILER_PREFERRED", null ] }, "powerAc": { "type": [ "number", "null" ], "description": "Total AC active power in W. Positive = electricity consumed for heating. Boilers do not generate/export electricity; a negative value has no defined export or discharge meaning." }, "powerAcL1": { "type": [ "number", "null" ], "description": "AC active power on phase L1 in W. Positive = electricity consumed for heating. Boilers do not generate/export electricity; a negative value has no defined export or discharge meaning." }, "powerAcL2": { "type": [ "number", "null" ], "description": "AC active power on phase L2 in W. Positive = electricity consumed for heating. Boilers do not generate/export electricity; a negative value has no defined export or discharge meaning." }, "powerAcL3": { "type": [ "number", "null" ], "description": "AC active power on phase L3 in W. Positive = electricity consumed for heating. Boilers do not generate/export electricity; a negative value has no defined export or discharge meaning." }, "voltageAcL1": { "type": [ "number", "null" ], "description": "AC voltage on phase L1 in V." }, "voltageAcL2": { "type": [ "number", "null" ], "description": "AC voltage on phase L2 in V." }, "voltageAcL3": { "type": [ "number", "null" ], "description": "AC voltage on phase L3 in V." }, "currentAcL1": { "type": [ "number", "null" ], "description": "AC current on phase L1 in A. Use powerAcL1 for active power direction; current sign conventions depend on the device." }, "currentAcL2": { "type": [ "number", "null" ], "description": "AC current on phase L2 in A. Use powerAcL2 for active power direction; current sign conventions depend on the device." }, "currentAcL3": { "type": [ "number", "null" ], "description": "AC current on phase L3 in A. Use powerAcL3 for active power direction; current sign conventions depend on the device." }, "frequency": { "type": [ "number", "null" ], "description": "AC frequency in Hz." }, "temperature": { "type": [ "number", "null" ], "description": "Device temperature in °C." }, "temperature2": { "type": [ "number", "null" ], "description": "Temperature sensor 2 in °C." }, "temperature3": { "type": [ "number", "null" ], "description": "Temperature sensor 3 in °C." }, "temperature4": { "type": [ "number", "null" ], "description": "Temperature sensor 4 in °C." }, "targetTemperature": { "type": [ "number", "null" ], "description": "Target water temperature in °C." }, "minimumTemperature": { "type": [ "number", "null" ], "description": "Minimum water temperature in °C." }, "availablePower": { "type": [ "number", "null" ], "description": "Available power reported by the boiler in W; a magnitude, not signed import/export." }, "effectiveMaxPower": { "type": [ "number", "null" ], "description": "Effective maximum boiler power in W; a magnitude, not measured consumption." }, "operationMode": { "type": [ "integer", "null" ], "description": "Vendor-specific numeric operation mode. No common enum is defined by the application API." }, "operationState": { "type": [ "integer", "null" ], "description": "Vendor-specific numeric operating state. No common enum is defined by the application API." }, "deviceState": { "type": [ "boolean", "null" ], "description": "Vendor-reported device on/enabled state." }, "relayState": { "type": [ "boolean", "null" ], "description": "Vendor-reported relay on/off state." }, "loadState": { "type": [ "integer", "null" ], "description": "Vendor-specific numeric load state. No common enum is defined by the application API." }, "pwmPercent": { "type": [ "number", "null" ], "description": "Pulse-width modulation duty cycle in percent (0–100)." } }, "required": [ "id", "installationId", "gatewayId", "manufacturer", "model", "version", "serialNumber", "firstSeenDate", "lastSeenDate", "status", "vendorStatusString", "boilerMode", "powerAc", "powerAcL1", "powerAcL2", "powerAcL3", "voltageAcL1", "voltageAcL2", "voltageAcL3", "currentAcL1", "currentAcL2", "currentAcL3", "frequency", "temperature", "temperature2", "temperature3", "temperature4", "targetTemperature", "minimumTemperature", "availablePower", "effectiveMaxPower", "operationMode", "operationState", "deviceState", "relayState", "loadState", "pwmPercent" ] }, "InverterStatus": { "type": "object", "description": "Normalized SunSpec inverter status.", "properties": { "rawValue": { "type": "integer", "description": "SunSpec status: 1 Off, 2 Sleeping, 3 Starting, 4 MPPT, 5 Throttled, 6 Shutting Down, 7 Fault, 8 Standby.", "enum": [ 1, 2, 3, 4, 5, 6, 7, 8 ] }, "name": { "type": "string", "description": "Human-readable label corresponding to rawValue.", "enum": [ "Off", "Sleeping", "Starting", "MPPT", "Throttled", "Shutting Down", "Fault", "Standby" ] } }, "required": [ "rawValue", "name" ] }, "InstallationsResponse": { "type": "object", "description": "Installations this application can currently read.", "properties": { "valid": { "type": "boolean", "description": "Request succeeded.", "const": true }, "installations": { "type": "array", "description": "Accessible installations. An empty array means the application currently has no accessible installations.", "items": { "$ref": "#/components/schemas/Installation" } } }, "required": [ "valid", "installations" ] }, "InstallationDevicesResponse": { "type": "object", "description": "Last-known device state. Read-only snapshot; measurements are not guaranteed simultaneous or fresh.", "properties": { "valid": { "type": "boolean", "description": "Request succeeded.", "const": true }, "installationId": { "type": "integer", "description": "Identifier of the requested accessible installation." }, "inverters": { "type": "array", "description": "All inverters of this installation, including offline devices with last-known state. Empty when none are returned.", "items": { "$ref": "#/components/schemas/Inverter" } }, "batteries": { "type": "array", "description": "All batteries of this installation, including offline devices with last-known state. Empty when none are returned.", "items": { "$ref": "#/components/schemas/Battery" } }, "energyMeters": { "type": "array", "description": "All energyMeters of this installation, including offline devices with last-known state. Empty when none are returned.", "items": { "$ref": "#/components/schemas/EnergyMeter" } }, "evChargers": { "type": "array", "description": "All evChargers of this installation, including offline devices with last-known state. Empty when none are returned.", "items": { "$ref": "#/components/schemas/EVCharger" } }, "relays": { "type": "array", "description": "All relays of this installation, including offline devices with last-known state. Empty when none are returned.", "items": { "$ref": "#/components/schemas/Relay" } }, "boilers": { "type": "array", "description": "All boilers of this installation, including offline devices with last-known state. Empty when none are returned.", "items": { "$ref": "#/components/schemas/Boiler" } } }, "required": [ "valid", "installationId", "inverters", "batteries", "energyMeters", "evChargers", "relays", "boilers" ] }, "Error": { "type": "object", "description": "Application API error. Inspect both the HTTP status and error code.", "properties": { "valid": { "type": "boolean", "description": "Request failed.", "const": false }, "error": { "type": "string", "description": "Machine-readable error code.", "enum": [ "UNAUTHORIZED", "MISSING_PARAMETERS", "INVALID_PARAMETERS", "DOESNT_EXIST", "DATABASE_ERROR", "INTERNAL_ERROR" ] } }, "required": [ "valid", "error" ] }, "InstallationCurrentEnergyFlow": { "type": "object", "description": "Aggregated flow from online devices only. Every field is present but can be null. Some sums start at zero and treat missing readings as zero, so numeric zero does not always mean a measured zero. Device readings are not synchronized.", "properties": { "inverterPower": { "type": [ "number", "null" ], "description": "Combined AC power of online inverters plus external production meters, in W. Positive = output into the installation; negative = absorption from the AC bus. Null when neither source contributes." }, "solarPower": { "type": [ "number", "null" ], "description": "Estimated solar power in W, derived from online inverter powerDc with integration-specific battery corrections. The inverter/battery subtotal is clamped to zero before adding external production meter powerAc. This is not simply the sum of powerDcPvTotal. Null when no source contributes." }, "batteryPower": { "type": [ "number", "null" ], "description": "Sum of online battery powerDc in W. Positive = charging; negative = discharging. Null when no batteries are online." }, "batterySoe": { "type": [ "number", "null" ], "description": "Arithmetic mean of soe across online batteries, in percent; not weighted by capacity. Null when no batteries are online. Missing individual soe values contribute zero while those batteries still count in the divisor." }, "gridPower": { "type": [ "number", "null" ], "description": "Grid power in W: positive = import; negative = export. This reverses raw grid-meter powerAc. Calculated as the negative mean powerAc of online meters with options Export+Import. Null when no energy meters are online; zero when online meters exist but none has that role. Zero alone does not prove a measured balanced grid connection." }, "housePower": { "type": [ "number", "null" ], "description": "Estimated consumption in W, excluding EV chargers and boilers: gridPower plus available inverterPower, minus available evChargerPower and boilerPower, clamped to a minimum of zero. Null when no energy meters are online. This is a derived estimate, not a separate house meter reading." }, "evChargerPower": { "type": [ "number", "null" ], "description": "Combined online EV charger power in W, using powerDc when available and otherwise powerAc per charger. Positive = charging consumption; no supported negative/V2G interpretation. Null when no chargers are online." }, "boilerPower": { "type": [ "number", "null" ], "description": "Boiler consumption in W. Uses the sum of non-null online boiler powerAc values; only when none is available does it use the sum of absolute powerAc from online Boiler consumption meters. The two sources are not added together. Positive = consumption; boiler device values are passed through without sign normalization. Null when neither source has a reading." }, "lastUpdated": { "type": [ "string", "null" ], "description": "Most recent lastSeenDate among the online inverters, batteries, energy meters, EV chargers and boilers included in the calculation, as an ISO 8601 timestamp with UTC offset. Null if no timestamp is available. Not the request time or proof that every reading is equally fresh.", "format": "date-time" } }, "required": [ "inverterPower", "solarPower", "batteryPower", "batterySoe", "gridPower", "housePower", "evChargerPower", "boilerPower", "lastUpdated" ] }, "InstallationCurrentEnergyFlowResponse": { "type": "object", "description": "Current aggregated installation energy flow. A successful response can have data: null.", "properties": { "valid": { "type": "boolean", "description": "Request succeeded.", "const": true }, "installationId": { "type": "integer", "description": "Identifier of the requested accessible installation." }, "data": { "description": "Energy flow object, or null when no inverters, batteries, energy meters, EV chargers or boilers are online. Relays do not contribute.", "anyOf": [ { "$ref": "#/components/schemas/InstallationCurrentEnergyFlow" }, { "type": "null" } ] } }, "required": [ "valid", "installationId", "data" ] } } } }