{ "openapi": "3.0.4", "info": { "title": "SMA Monitoring API", "description": "

This API provides master-data, measurements and logs from plant-groups, plants, sub-plants and devices. Plant owner consent (permission) to the API-consumer to retrieve his resource data is a prerequisite for the usage of this API.

The resource server on SMA production environment is named https://monitoring.smaapis.de.

Swagger and OAS3 are published under the Apache 2.0 license.

Release notes

", "termsOfService": "http://developer.sma.de/", "contact": { "name": "SMA API developers", "email": "api-developer-support@sma.de" }, "version": "Build 1.39 - build at: 2025-10-29T11:14:15" }, "servers": [ { "url": "https://sandbox.smaapis.de/monitoring", "description": "SMA sandbox server" } ], "paths": { "/v1/devices/{deviceId}": { "get": { "tags": [ "DeviceManagement" ], "summary": "Get device data. [Obsolete]", "description": "Returns data for a specific device. \r\n
Note: a new, leaner and more performant call “/{deviceId}/lean” has been implemented. The unnecessary plant info object and the time zone are omitted from the response. Both are likely to have been retrieved in advance (via the GET plant call). If possible, please switch accordingly.\",", "operationId": "GetDeviceDataByDeviceId", "parameters": [ { "name": "deviceId", "in": "path", "description": "The device Id. This is the property to be used in the path to retrieve data for a dedicated device.", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeviceDetailsResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "deprecated": true } }, "/v1/devices/{deviceId}/lean": { "get": { "tags": [ "DeviceManagement" ], "summary": "Get device data, without the plant model and timezone. Only supported for EnnexOS devices.", "description": "Returns data for a specific device.", "operationId": "GetDeviceDataByDeviceIdLean", "parameters": [ { "name": "deviceId", "in": "path", "description": "The device Id. This is the property to be used in the path to retrieve data for a dedicated device.", "required": true, "schema": { "type": "string" } }, { "name": "withNameplateData", "in": "query", "description": "Include device data describing the rated capabilities for reactive power of the device. Not supported for classic plants.", "schema": { "type": "boolean", "default": false } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeviceDetailsLeanResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/v1/devices/{deviceId}/relation": { "get": { "tags": [ "DeviceManagement" ], "summary": "Get device relation data. Only supported for EnnexOS devices.", "description": "Returns device relation data for a specific device.", "operationId": "GetDeviceRelationDataByDeviceId", "parameters": [ { "name": "deviceId", "in": "path", "description": "The device Id. This is the property to be used in the path to retrieve data for a dedicated device.", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PlantDeviceRelationResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/v1/devices/{deviceId}/status": { "get": { "tags": [ "DeviceManagement" ], "summary": "Get device data and status.", "description": "Returns the status for the requested device.", "operationId": "GetDeviceStatusById", "parameters": [ { "name": "deviceId", "in": "path", "description": "The device Id. This is the property to be used in the path to retrieve data for a dedicated device.", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeviceInfosStatusResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/v1/devices/{deviceId}/measurements/sets": { "get": { "tags": [ "DeviceMonitoring" ], "summary": "Get supported measurement sets of a given device.", "description": "Returns the supported measurement sets of a given device. A measurement set is supported by a device if at least for one property of the measurement set at least one measurement value was supplied by the device in the past.", "operationId": "GetDeviceMeasurementSets", "parameters": [ { "name": "deviceId", "in": "path", "description": "

The device Id. This is the property to be used in the path to retrieve data for a dedicated device.

", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeviceSupportedMeasurementSetsResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/v1/devices/{deviceId}/measurements/sets/{setType}/{period}": { "get": { "tags": [ "DeviceMonitoring" ], "summary": "Get measurements-set for device.", "description": "Returns the measurement set as specified in query for a given device and period.\r\n The values and the unit of the values depend on the requested period and the parameter \"ReturnEnergyValues\".\r\n ", "operationId": "GetDeviceMeasurementsSetsData", "parameters": [ { "name": "deviceId", "in": "path", "description": "The device Id. This is the property to be used in the path to retrieve data for a dedicated device.", "required": true, "schema": { "type": "string" } }, { "name": "setType", "in": "path", "description": "The type of the measurement set.\r\n ", "required": true, "schema": { "enum": [ "EnergyAndPowerBattery", "EnergyAndPowerConsumption", "EnergyAndPowerInOut", "EnergyAndPowerPv", "EnergyMix", "PowerAc", "EnergyDc", "PowerDc", "Sensor" ], "type": "string", "description": "The device set type." } }, { "name": "period", "in": "path", "description": "The period of a measurement set.\r\n ", "required": true, "schema": { "enum": [ "Recent", "Day", "Week", "Month", "Year", "Total" ], "type": "string", "description": "The period type." } }, { "name": "Date", "in": "query", "description": "The date used for getting measurements and logs of a plant-group/plant/sub-plant or device.\r\n The format of the date-parameter given in the path depends on the used period.\r\n ", "schema": { "type": "string" } }, { "name": "WithTotal", "in": "query", "description": "Has only effect for measurement set EnergyMix.", "schema": { "type": "boolean" } }, { "name": "ReturnEnergyValues", "in": "query", "description": "Request energy values. Only applicable for measurement sets \"EnergyAndPowerBattery\", \"EnergyAndPowerConsumption\", \"EnergyAndPowerInOut\" and \"EnergyAndPowerPv\".", "schema": { "type": "boolean" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeviceMeasurementSetsResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/v1/devices/{deviceId}/logs": { "get": { "tags": [ "DeviceMonitoring" ], "summary": "Get device event logs.", "description": "Returns the log messages of a given device. The logs are currently available only for the last 6 months in ennexOs systems and only for the last 3 months in classic systems.", "operationId": "GetDeviceLogs", "parameters": [ { "name": "deviceId", "in": "path", "description": "

The device Id. This is the property to be used in the path to retrieve data for a dedicated device.

", "required": true, "schema": { "type": "string" } }, { "name": "From", "in": "query", "description": "This field represents the start date interval for the log messages to be returned.\r\n\r\nThe specified date value should be in the format: yyyy-MM-dd (see ISO_8601).\r\n\r\nNote: The logs are currently available only for the last 6 months in ennexOs systems and only for the last 3 months in classic systems.", "required": true, "schema": { "type": "string" } }, { "name": "To", "in": "query", "description": "This field represents the end date interval for the log messages to be returned.\r\n\r\nIf no value is specified, then the log messages are returned up to the current date.\r\n\r\nThe specified date value should be in the format: yyyy-MM-dd (see ISO_8601).", "schema": { "type": "string" } }, { "name": "Level", "in": "query", "description": "The criticality level of the log messages:\r\n", "schema": { "enum": [ "Disturbance", "Error", "Info", "Warning" ], "type": "string" } }, { "name": "Language", "in": "query", "description": "The language of the requested log messages.\r\nThe logs (messages) are returned in the specified language. If not specified, then the default is english (en).\r\n
\r\nThe language should be specified in two-letter-code (e.g. 'en', see ISO 639-1).", "schema": { "type": "string" } }, { "name": "PendingOnly", "in": "query", "description": "Get only pending messages.", "schema": { "type": "boolean" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeviceLogsResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/v1/plantGroups": { "get": { "tags": [ "PlantGroupManagement" ], "summary": "Get plant-group list.", "description": "Returns a list of all available and accessible plant-groups for a given user.", "operationId": "GetPlantGroups", "parameters": [ { "name": "WithStatus", "in": "query", "description": "Include status of plant groups.", "schema": { "type": "boolean" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PlantGroupStatusList" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/v1/plantGroups/{plantGroupId}/plants": { "get": { "tags": [ "PlantGroupManagement" ], "summary": "Get plants of plant-group.", "description": "Returns a list of all available plants of a specific plant-group.", "operationId": "GetPlantsForPlantGroupId", "parameters": [ { "name": "plantGroupId", "in": "path", "description": "The plant-group id. This is the property to be used in the path to retrieve data for a dedicated plant-\r\n group.", "required": true, "schema": { "type": "string" } }, { "name": "Filter", "in": "query", "description": "Filter query for id, name or description of components (can be plant, sub-plant or device).", "schema": { "type": "string" } }, { "name": "WithStatus", "in": "query", "description": "Include status of plants.", "schema": { "type": "boolean" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PlantGroupPlants" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/v1/plantGroups/{plantGroupId}": { "get": { "tags": [ "PlantGroupManagement" ], "summary": "Get plant-group data.", "description": "Returns information to a specific plant-group.", "operationId": "GetPlantGroupData", "parameters": [ { "name": "plantGroupId", "in": "path", "description": "The plant-group id. This is the property to be used in the path to retrieve data for a dedicated plant-\r\n group.", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PlantGroup" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/v1/plantGroups/{plantGroupId}/status": { "get": { "tags": [ "PlantGroupManagement" ], "summary": "Get plant-group status.", "description": "Returns the status of plant-group.", "operationId": "GetPlantGroupStatus", "parameters": [ { "name": "plantGroupId", "in": "path", "description": "The plantGroupId. This is the property to be used in the path to retrieve data for a dedicated plant group.", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PlantGroupStatus" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/v1/plantGroups/{plantGroupId}/logs": { "get": { "tags": [ "PlantGroupMonitoring" ], "summary": "Get plant-group logs.", "description": "Returns the logs of a given plant-group. The logs are currently available only for the last 6 months in ennexOs systems and only for the last 3 months in classic systems.", "operationId": "GetPlantGroupLogs", "parameters": [ { "name": "plantGroupId", "in": "path", "description": "

The plant group id. This is the property to be used in the path to retrieve data for a dedicated\r\n plant.

", "required": true, "schema": { "type": "string" } }, { "name": "From", "in": "query", "description": "This field represents the start date interval for the log messages to be returned.\r\n\r\nThe specified date value should be in the format: yyyy-MM-dd (see ISO_8601).\r\n\r\nNote: The logs are currently available only for the last 6 months in ennexOs systems and only for the last 3 months in classic systems.", "required": true, "schema": { "type": "string" } }, { "name": "To", "in": "query", "description": "This field represents the end date interval for the log messages to be returned.\r\n\r\nIf no value is specified, then the log messages are returned up to the current date.\r\n\r\nThe specified date value should be in the format: yyyy-MM-dd (see ISO_8601).", "schema": { "type": "string" } }, { "name": "Level", "in": "query", "description": "The criticality level of the log messages:\r\n", "schema": { "enum": [ "Disturbance", "Error", "Info", "Warning" ], "type": "string" } }, { "name": "Language", "in": "query", "description": "The language of the requested log messages.\r\nThe logs (messages) are returned in the specified language. If not specified, then the default is english (en).\r\n
\r\nThe language should be specified in two-letter-code (e.g. 'en', see ISO 639-1).", "schema": { "type": "string" } }, { "name": "PendingOnly", "in": "query", "description": "Get only pending messages.", "schema": { "type": "boolean" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PlantGroupLogsResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/v1/plants": { "get": { "tags": [ "PlantManagement" ], "summary": "Get plants.", "description": "Returns a list of all available and accessible plants for a given user. If the optional parameter \"withStatus\" is set, plant status will also be returned.", "operationId": "GetPlants", "parameters": [ { "name": "Filter", "in": "query", "description": "Query filter for the name of a plant. For classic plants, the query includes also the description of the plants.", "schema": { "type": "string" } }, { "name": "WithStatus", "in": "query", "description": "Include status of plants.", "schema": { "type": "boolean" } }, { "name": "WithInstallation", "in": "query", "description": "Include installation details of plants.", "schema": { "type": "boolean" } }, { "name": "WithLocation", "in": "query", "description": "Include location details of plants.", "schema": { "type": "boolean" } }, { "name": "WithDirectSellingInfo", "in": "query", "description": "Include direct selling info of plants.", "schema": { "type": "boolean" } }, { "name": "WithMeterIds", "in": "query", "description": "Include metering identifiers of plants. Currently, only NMI (national metering identifier in Australia) is supported.", "schema": { "type": "boolean" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PlantStatusList" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/v1/plants/{plantId}/subPlants": { "get": { "tags": [ "PlantManagement" ], "summary": "Get the sub-plants for the requested plant.", "description": "Returns a list of all available sub-plants of a plant assigned to a user.", "operationId": "GetSubPlantsForPlantId", "parameters": [ { "name": "plantId", "in": "path", "description": "The plant id. This is the property to be used in the path to retrieve data for a dedicated plant.", "required": true, "schema": { "type": "string" } }, { "name": "WithStatus", "in": "query", "description": "Include status of sub-plants.", "schema": { "type": "boolean" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PlantManagementSubPlantResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/v1/plants/{plantId}": { "get": { "tags": [ "PlantManagement" ], "summary": "Get plant data.", "description": "Returns base information to a specific plant.", "operationId": "GetPlantData", "parameters": [ { "name": "plantId", "in": "path", "description": "The plant id. This is the property to be used in the path to retrieve data for a dedicated plant.", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Plant" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/v1/plants/{plantId}/devices": { "get": { "tags": [ "PlantManagement" ], "summary": "Get plant devices. [Obsolete]", "description": "Returns devices of a given plant for the given filters. \r\n
Note: a new, leaner and more performant call “/{plantId}/devices/lean” has been implemented. The unnecessary plant info object and the time zone are omitted from the response. Both are likely to have been retrieved in advance (via the GET plant call). If possible, please switch accordingly.\",", "operationId": "GetDevicesForPlant", "parameters": [ { "name": "plantId", "in": "path", "description": "The plant id. This is the property to be used in the path to retrieve data for a dedicated plant.", "required": true, "schema": { "type": "string" } }, { "name": "Filter", "in": "query", "description": "Query filter for the name of a device.", "schema": { "type": "string" } }, { "name": "WithDeactivatedDevices", "in": "query", "description": "Include deactivated devices. By default, deactivated devices are not contained in the device plant list.", "schema": { "type": "boolean" } }, { "name": "DeviceCategory", "in": "query", "description": "Filter for device category (device subproperty 'characteristic.category'). By default, no device category filtering is applied.", "schema": { "enum": [ "Consumer" ], "type": "string" } }, { "name": "WithSmartConnectedInfo", "in": "query", "description": "Only provided for ennexOS devices and if smartConnected query parameter is set.\r\nTrue, if ennexOS device supports smartConnected, false, if device is not feasible.\r\nFor SunnyPortal (classic) the property is not contained in the response.", "schema": { "type": "boolean" } }, { "name": "WithSubPlantDevices", "in": "query", "description": "Include devices from sub-plants. By default, devices from sub-plants are contained in the device plant list.", "schema": { "type": "boolean" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PlantManagementPlantDevicesResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "deprecated": true } }, "/v1/plants/{plantId}/devices/lean": { "get": { "tags": [ "PlantManagement" ], "summary": "Get plant devices, without the plant model and timezone. Only supported for EnnexOS devices.", "description": "Returns devices of a given plant for the given filters.", "operationId": "GetDevicesForPlantLean", "parameters": [ { "name": "plantId", "in": "path", "description": "The plant id. This is the property to be used in the path to retrieve data for a dedicated plant.", "required": true, "schema": { "type": "string" } }, { "name": "Filter", "in": "query", "description": "Query filter for the name of a device.", "schema": { "type": "string" } }, { "name": "WithDeactivatedDevices", "in": "query", "description": "Include deactivated devices. By default, deactivated devices are not contained in the device plant list.", "schema": { "type": "boolean" } }, { "name": "DeviceCategory", "in": "query", "description": "Filter for device category (device subproperty 'characteristic.category'). By default, no device category filtering is applied.", "schema": { "enum": [ "Consumer" ], "type": "string" } }, { "name": "WithSmartConnectedInfo", "in": "query", "description": "Only provided for ennexOS devices and if smartConnected query parameter is set.\r\nTrue, if ennexOS device supports smartConnected, false, if device is not feasible.\r\nFor SunnyPortal (classic) the property is not contained in the response.", "schema": { "type": "boolean" } }, { "name": "WithSubPlantDevices", "in": "query", "description": "Include devices from sub-plants. By default, devices from sub-plants are contained in the device plant list.", "schema": { "type": "boolean" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PlantManagementPlantDevicesLeanResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/v1/plants/{plantId}/status": { "get": { "tags": [ "PlantManagement" ], "summary": "Get plant status.", "description": "Returns the status for the requested plant.", "operationId": "GetPlantStatus", "parameters": [ { "name": "plantId", "in": "path", "description": "The plant id. This is the property to be used in the path to retrieve data for a dedicated plant.", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PlantStatus" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/v1/plants/{plantId}/installation": { "get": { "tags": [ "PlantMasterData" ], "summary": "Get plant installation.", "description": "Returns the installation setup data of a given plant.", "operationId": "GetPlantInstallation", "parameters": [ { "name": "plantId", "in": "path", "description": "The plant id. This is the property to be used in the path to retrieve data for a dedicated plant.", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PlantInstallationResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/v1/plants/{plantId}/location": { "get": { "tags": [ "PlantMasterData" ], "summary": "Get plant location.", "description": "Returns the location of a given plant.", "operationId": "GetPlantLocation", "parameters": [ { "name": "plantId", "in": "path", "description": "The plant id. This is the property to be used in the path to retrieve data for a dedicated plant.", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PlantLocationResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/v1/plants/{plantId}/stakeholders": { "get": { "tags": [ "PlantMasterData" ], "summary": "Get plant stakeholders.", "description": "Returns stakeholder data of a given plant.", "operationId": "GetPlantStakeholders", "parameters": [ { "name": "plantId", "in": "path", "description": "The plant id. This is the property to be used in the path to retrieve data for a dedicated plant.", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PlantStakeholdersResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/v1/plants/{plantId}/stakeholders/derived/{userId}": { "get": { "tags": [ "PlantMasterData" ], "summary": "Get plant stakeholders.", "description": "Returns stakeholder data of a given plant.", "operationId": "GetPlantDerivedStakeholders", "parameters": [ { "name": "plantId", "in": "path", "description": "The plant id. This is the property to be used in the path to retrieve data for a dedicated plant.", "required": true, "schema": { "type": "string" } }, { "name": "userId", "in": "path", "required": true, "schema": { "type": "integer", "format": "int64" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PlantDerivedStakeholderResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/v1/plants/{plantId}/configuration": { "get": { "tags": [ "PlantMasterData" ], "summary": "Get plant configuration.", "description": "Returns configuration details for the specified plant identifier.", "operationId": "GetPlantConfiguration", "parameters": [ { "name": "plantId", "in": "path", "description": "The plant id. This is the property to be used in the path to retrieve data for a dedicated plant.", "required": true, "schema": { "type": "string" } }, { "name": "withSmartConnectedConfiguration", "in": "query", "description": "If set to true, the service will try to load smart connected configuration", "schema": { "type": "boolean", "default": false } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PlantConfigurationResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/v1/plants/{plantId}/images": { "get": { "tags": [ "PlantMasterData" ], "summary": "Get plant images.", "description": "Returns images for the specified plant identifier.", "operationId": "GetPlantImages", "parameters": [ { "name": "plantId", "in": "path", "description": "The plant id. This is the property to be used in the path to retrieve data for a dedicated plant.", "required": true, "schema": { "type": "string" } }, { "name": "imageType", "in": "query", "description": "Filter for image type.", "schema": { "enum": [ "PortalProfileSmall", "PortalProfileLarge" ], "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PlantImagesResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/v1/plants/{plantId}/images/{imageId}": { "get": { "tags": [ "PlantMasterData" ], "summary": "Get plant image.", "description": "Returns image for the specified plant and image identifier.", "operationId": "GetPlantImage", "parameters": [ { "name": "plantId", "in": "path", "description": "The plant id. This is the property to be used in the path to retrieve data for a dedicated plant.", "required": true, "schema": { "type": "string" } }, { "name": "imageId", "in": "path", "description": "The plant image Id.", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "image/png": { "schema": { "type": "string", "format": "binary" } }, "image/jpeg": { "schema": { "type": "string", "format": "binary" } }, "image/gif": { "schema": { "type": "string", "format": "binary" } }, "application/json": { "schema": { "type": "string", "format": "binary" } } } }, "400": { "description": "Bad Request", "content": { "image/png": { "schema": { "$ref": "#/components/schemas/ApiError" } }, "image/jpeg": { "schema": { "$ref": "#/components/schemas/ApiError" } }, "image/gif": { "schema": { "$ref": "#/components/schemas/ApiError" } }, "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Unauthorized", "content": { "image/png": { "schema": { "$ref": "#/components/schemas/ApiError" } }, "image/jpeg": { "schema": { "$ref": "#/components/schemas/ApiError" } }, "image/gif": { "schema": { "$ref": "#/components/schemas/ApiError" } }, "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Forbidden", "content": { "image/png": { "schema": { "$ref": "#/components/schemas/ApiError" } }, "image/jpeg": { "schema": { "$ref": "#/components/schemas/ApiError" } }, "image/gif": { "schema": { "$ref": "#/components/schemas/ApiError" } }, "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Not Found", "content": { "image/png": { "schema": { "$ref": "#/components/schemas/ApiError" } }, "image/jpeg": { "schema": { "$ref": "#/components/schemas/ApiError" } }, "image/gif": { "schema": { "$ref": "#/components/schemas/ApiError" } }, "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Internal Server Error", "content": { "image/png": { "schema": { "$ref": "#/components/schemas/ApiError" } }, "image/jpeg": { "schema": { "$ref": "#/components/schemas/ApiError" } }, "image/gif": { "schema": { "$ref": "#/components/schemas/ApiError" } }, "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/v1/plants/{plantId}/capabilities": { "get": { "tags": [ "PlantMasterData" ], "summary": "Get plant capabilities.", "description": "Provides information about the capabilities of a plant system and its devices. Not supported for classic plants.", "operationId": "GetPlantCapabilities", "parameters": [ { "name": "plantId", "in": "path", "description": "This value represents the unique identifier of a plant system.", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PlantCapabilitiesResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/v1/plants/gridControlCheck": { "post": { "tags": [ "PlantMasterData" ], "summary": "Get the eligible commands for a given plant based on meter, plant or device identifier and chosen commands with additional error information.", "description": "Lists for all requested commands whether they are supported by a specific plant based on meter, plant or device identifier at the time of the query.\r\nFor each command requested, error information or possible reasons are given if it is not supported.", "operationId": "GetGridControlCheck", "requestBody": { "description": "The request parameter", "content": { "application/json-patch+json": { "schema": { "$ref": "#/components/schemas/EligibilityRequest" } }, "application/json": { "schema": { "$ref": "#/components/schemas/EligibilityRequest" } }, "text/json": { "schema": { "$ref": "#/components/schemas/EligibilityRequest" } }, "application/*+json": { "schema": { "$ref": "#/components/schemas/EligibilityRequest" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EligibilityResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/v1/plants/{plantId}/measurements/sets/{setType}/{period}": { "get": { "tags": [ "PlantMonitoring" ], "summary": "Get measurements-set for plant.", "description": "Returns the measurement set as specified in query for a given plant and period.\r\n The values and the unit of the values depend on the requested period. For the period \"Recent\", \"Day\" and \"Week\", power values are supplied in unit \"W\".\r\n For the period \"Month\", \"Year\" and \"Total\" energy values, in the unit \"Wh\".", "operationId": "GetMeasurementsSetsForPlant", "parameters": [ { "name": "plantId", "in": "path", "description": "The plant id. This is the property to be used in the path to retrieve data for a dedicated plant.", "required": true, "schema": { "type": "string" } }, { "name": "setType", "in": "path", "description": "The type of the measurement set.\r\n ", "required": true, "schema": { "enum": [ "EnergyBalance", "GridSettings", "Sensor", "EnergyAndPowerPv" ], "type": "string", "description": "The set type." } }, { "name": "period", "in": "path", "description": "The period of a measurement set\r\n ", "required": true, "schema": { "enum": [ "Recent", "Day", "Week", "Month", "Year", "Total" ], "type": "string", "description": "The period type." } }, { "name": "Date", "in": "query", "description": "The date used for getting measurements and logs of a plant-group/plant/sub-plant or device.\r\n The format of the date-parameter given in the path depends on the used period.\r\n ", "schema": { "type": "string" } }, { "name": "WithTotal", "in": "query", "description": "Include the total values for the requested period which are equal to the values of the requested period in the next-higher resolution. Note: in rare cases, total values may be higher than the aggregation of all single values (e.g. unrecorded changes, etc.).", "schema": { "type": "boolean" } }, { "name": "BatteryHybrid", "in": "query", "description": "If plant contains only dc batteries, battery dis-/ charging values will be loaded starting from period set type month.", "schema": { "type": "boolean" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PlantMeasurementSetsResponse" }, "example": { "plant": { "plantId": "25057", "name": "Test plant", "description": "My test plant", "timezone": "Europe/Berlin" }, "setType": "string", "resolution": "FiveMinutes", "set": [ { "time": "2026-11-06T17:38:59.2682962", "pvGeneration": 3445.543, "directConsumption": 143.53, "totalConsumption": 3445.543, "batteryCharging": 234.54, "batteryDischarging": 456.125, "batteryStateOfCharge": 64.65, "dieselGeneration": 463.34, "combinedHeatAndPowerGeneration": 3445.543, "hydroGeneration": 345.543, "gridFeedIn": 245.783, "gridConsumption": 75.33, "totalGeneration": 764.5, "selfConsumption": 56.8, "autarkyRate": 0.8, "selfConsumptionRate": 0.3, "selfSupply": 75.42, "batteryChargingDc": 43.2, "batteryDischargingDc": 55.6 }, { "time": "2026-11-06T17:38:59.2683014", "setPointFeedInPower": 42.0, "setPointReactivePower": 66.0 } ], "total": { "pvGeneration": 4445.543, "directConsumption": 243.53, "totalConsumption": 4445.543, "batteryCharging": 334.54, "batteryDischarging": 556.125, "batteryStateOfCharge": 74.65, "dieselGeneration": 563.34, "combinedHeatAndPowerGeneration": 4445.543, "hydroGeneration": 445.543, "gridFeedIn": 345.783, "gridConsumption": 85.33, "totalGeneration": 864.5, "selfConsumption": 66.8, "autarkyRate": 0.7, "selfConsumptionRate": 0.3, "selfSupply": 85.42 } } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/v1/plants/{plantId}/logs": { "get": { "tags": [ "PlantMonitoring" ], "summary": "Get plant logs.", "description": "Returns the log messages of a given plant. The logs are currently available only for the last 6 months in ennexOs systems and only for the last 3 months in classic systems.", "operationId": "GetPlantLogs", "parameters": [ { "name": "plantId", "in": "path", "description": "

The plant id. This is the property to be used in the path to retrieve data for a dedicated plant.

", "required": true, "schema": { "type": "string" } }, { "name": "From", "in": "query", "description": "This field represents the start date interval for the log messages to be returned.\r\n\r\nThe specified date value should be in the format: yyyy-MM-dd (see ISO_8601).\r\n\r\nNote: The logs are currently available only for the last 6 months in ennexOs systems and only for the last 3 months in classic systems.", "required": true, "schema": { "type": "string" } }, { "name": "To", "in": "query", "description": "This field represents the end date interval for the log messages to be returned.\r\n\r\nIf no value is specified, then the log messages are returned up to the current date.\r\n\r\nThe specified date value should be in the format: yyyy-MM-dd (see ISO_8601).", "schema": { "type": "string" } }, { "name": "Level", "in": "query", "description": "The criticality level of the log messages:\r\n", "schema": { "enum": [ "Disturbance", "Error", "Info", "Warning" ], "type": "string" } }, { "name": "Language", "in": "query", "description": "The language of the requested log messages.\r\nThe logs (messages) are returned in the specified language. If not specified, then the default is english (en).\r\n
\r\nThe language should be specified in two-letter-code (e.g. 'en', see ISO 639-1).", "schema": { "type": "string" } }, { "name": "PendingOnly", "in": "query", "description": "Get only pending messages.", "schema": { "type": "boolean" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PlantLogsResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/v1/plants/{plantId}/communication": { "get": { "tags": [ "PlantMonitoring" ], "summary": "Get plant communication times.", "description": "Returns a list of communication times for all devices of the given plant.", "operationId": "GetPlantCommunication", "parameters": [ { "name": "plantId", "in": "path", "description": "The plant id. This is the property to be used in the path to retrieve data for a dedicated plant", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PlantCommunicationResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/v1/plants/{plantId}/batteryOperationState": { "get": { "tags": [ "PlantMonitoring" ], "summary": "Get plant battery operation state. Currently only of EnnexOs.", "description": "Returns the plant identifier and the aggregated battery operation state.", "operationId": "GetBatteryOperationState", "parameters": [ { "name": "plantId", "in": "path", "description": "The plant id. This is the property to be used in the path to retrieve data for a dedicated plant", "required": true, "schema": { "type": "integer", "format": "int64" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BatteryOperationStateResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/v1/plants/{plantId}/notifications": { "get": { "tags": [ "PlantNotifications" ], "operationId": "GetNotificationConfiguration", "parameters": [ { "name": "plantId", "in": "path", "required": true, "schema": { "type": "integer", "format": "int64" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PlantNotificationsResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/v1/subPlants/{subPlantId}": { "get": { "tags": [ "SubPlantManagement" ], "summary": "Get sub-plant data.", "description": "Returns information to a specific sub-plant.", "operationId": "GetSubPlantData", "parameters": [ { "name": "subPlantId", "in": "path", "description": "The sub-plant id. This is the property to be used in the path to retrieve data for a dedicated sub-plant.", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubPlantResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/v1/subPlants/{subPlantId}/devices": { "get": { "tags": [ "SubPlantManagement" ], "summary": "Get sub-plant devices.", "description": "Returns only the active devices of a given sub-plant.", "operationId": "GetSubPlantDevices", "parameters": [ { "name": "subPlantId", "in": "path", "description": "The sub-plant id. This is the property to be used in the path to retrieve data for a dedicated sub-plant.", "required": true, "schema": { "type": "string" } }, { "name": "withDeactivatedDevices", "in": "query", "description": "Include deactivated devices. By default, deactivated devices are not contained in the device sub-plant list.", "schema": { "type": "boolean", "default": false } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubPlantDevicesResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/v1/subPlants/{subPlantId}/status": { "get": { "tags": [ "SubPlantManagement" ], "summary": "(Restricted to ) gets sub plant status.", "description": "Returns the status of sub-plant.", "operationId": "GetSubPlantStatus", "parameters": [ { "name": "subPlantId", "in": "path", "description": "The sub-plant id. This is the property to be used in the path to retrieve data for a dedicated sub-plant.", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubPlantStatusResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/v1/subPlants/{subPlantId}/logs": { "get": { "tags": [ "SubPlantMonitoring" ], "summary": "Get sub-plant logs.", "description": "Returns the log messages of a given sub-plant. The logs are currently available only for the last 6 months in ennexOs systems and only for the last 3 months in classic systems.", "operationId": "GetSubPlantLogs", "parameters": [ { "name": "subPlantId", "in": "path", "description": "

The sub-plant id. This is the property to be used in the path to retrieve data for a dedicated sub-plant.

", "required": true, "schema": { "type": "string" } }, { "name": "From", "in": "query", "description": "This field represents the start date interval for the log messages to be returned.\r\n\r\nThe specified date value should be in the format: yyyy-MM-dd (see ISO_8601).\r\n\r\nNote: The logs are currently available only for the last 6 months in ennexOs systems and only for the last 3 months in classic systems.", "required": true, "schema": { "type": "string" } }, { "name": "To", "in": "query", "description": "This field represents the end date interval for the log messages to be returned.\r\n\r\nIf no value is specified, then the log messages are returned up to the current date.\r\n\r\nThe specified date value should be in the format: yyyy-MM-dd (see ISO_8601).", "schema": { "type": "string" } }, { "name": "Level", "in": "query", "description": "The criticality level of the log messages:\r\n", "schema": { "enum": [ "Disturbance", "Error", "Info", "Warning" ], "type": "string" } }, { "name": "Language", "in": "query", "description": "The language of the requested log messages.\r\nThe logs (messages) are returned in the specified language. If not specified, then the default is english (en).\r\n
\r\nThe language should be specified in two-letter-code (e.g. 'en', see ISO 639-1).", "schema": { "type": "string" } }, { "name": "PendingOnly", "in": "query", "description": "Get only pending messages.", "schema": { "type": "boolean" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubPlantLogsResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } } }, "components": { "schemas": { "AllPlantLogsResponse": { "type": "object", "properties": { "marker": { "type": "string", "description": "A marker to paginate results", "nullable": true }, "logs": { "type": "array", "items": { "$ref": "#/components/schemas/SimpleLog" }, "description": "Gets the logs.", "nullable": true } }, "additionalProperties": false, "description": "A response containing all accessible plant logs." }, "ApiError": { "type": "object", "properties": { "message": { "type": "string", "nullable": true }, "code": { "type": "string", "nullable": true } }, "additionalProperties": false }, "BasicDevice": { "type": "object", "properties": { "deviceId": { "type": "integer", "description": "Gets or sets the DeviceId.", "format": "int64" }, "plantId": { "type": "integer", "description": "Gets or sets the PlantId.", "format": "int64" }, "gateWayDeviceId": { "type": "integer", "description": "Gets or sets the GateWayDeviceId.", "format": "int64", "nullable": true }, "disabledAt": { "type": "string", "description": "Gets or sets the DisabledAt attribute.", "format": "date-time", "nullable": true } }, "additionalProperties": false, "description": "A small device relation model." }, "BatteryLimits": { "type": "object", "properties": { "upperChargeLimit": { "type": "number", "description": "Upper battery charging limit (percentage 0-100%).", "format": "double", "nullable": true, "example": 90 }, "dischargeLimit": { "type": "number", "description": "Minimum width of deep discharge protection area (percentage 0-100%).", "format": "double", "nullable": true, "example": 10 }, "dischargeOffLimit": { "type": "number", "description": "Lower limit deep discharge protect area prior shutdown (percentage 0-100%).", "format": "double", "nullable": true, "example": 2 } }, "additionalProperties": false, "description": "The BatteryLimits value model (will only be returned if the device has battery capabilities)." }, "BatteryOperationStateResponse": { "type": "object", "properties": { "plantId": { "type": "integer", "description": "The plant identifier.", "format": "int64" }, "batteryOperationState": { "enum": [ "Backup", "Normal", "Unknown" ], "type": "string", "description": "The battery operation state." } }, "additionalProperties": false, "description": "" }, "Capabilities": { "type": "object", "properties": { "measurementData": { "type": "array", "items": { "enum": [ "PvGeneration", "Consumption", "Battery", "BatteryHybrid", "Grid", "Live", "EvCharging" ], "type": "string", "description": "Capability" }, "nullable": true } }, "additionalProperties": false, "description": "The capabilities of a plant." }, "Characteristic": { "type": "object", "properties": { "category": { "enum": [ "Consumer" ], "type": "string", "description": "Device category. Currently only Consumer category is supported.", "example": "Consumer" }, "subCategory": { "enum": [ "Unknown", "WashingMachine", "Dishwasher", "UserDefined", "MeteringOnly", "HeatPump", "HeatingRod", "DirectCommunication" ], "type": "string", "description": "Device subcategory. If the device is a Consumer, one of the subcategories (see available values below) is delivered.", "example": "Dishwasher" } }, "additionalProperties": false, "description": "Device property based on the device category and subcategory.\r\nCurrently available only for Consumer devices." }, "Device": { "type": "object", "properties": { "deviceId": { "type": "string", "description": "The device Id. This is the property to be used in the path to retrieve data for a dedicated device.", "nullable": true, "example": "302453" }, "name": { "type": "string", "description": "Name of the device.", "nullable": true, "example": "SB 3000TL-30" }, "timezone": { "type": "string", "description": "Timezone in IANA format.", "nullable": true, "example": "Europe/Berlin" } }, "additionalProperties": false, "description": "The device resource acts as a digital representation of a device-owners physical device. It provides a view of most essential device data items such as device type, device name, device description and links to further detailed device data. Devices are associated to a plant, subPlant or plantGroup." }, "DeviceCommunication": { "type": "object", "properties": { "device": { "$ref": "#/components/schemas/Device" }, "lastContact": { "type": "string", "description": "The last contact of the device in local plant time (YYYY-MM-DDThh:mm:ss.s, see ISO_8601).", "format": "date-time" }, "expectedContact": { "type": "string", "description": "The expected contact of the device in local plant time (YYYY-MM-DDThh:mm:ss.s, see ISO_8601).", "format": "date-time" } }, "additionalProperties": false, "description": "The device communication monitoring response." }, "DeviceDetails": { "type": "object", "properties": { "deviceId": { "type": "string", "description": "The device Id. This is the property to be used in the path to retrieve data for a dedicated device.", "nullable": true, "example": "302453" }, "name": { "type": "string", "description": "Name of the device.", "nullable": true, "example": "SB 3000TL-30" }, "timezone": { "type": "string", "description": "Timezone in IANA format.", "nullable": true, "example": "Europe/Berlin" }, "type": { "type": "string", "description": "Device type.", "nullable": true, "example": "Solar Inverters" }, "product": { "type": "string", "description": "Device product name.", "nullable": true, "example": "SB4.0-1AV-41" }, "productId": { "type": "integer", "description": "The product id. Identifies the product of a device uniquely. Delivered only if the data is dedicated to a device.", "format": "int32", "nullable": true, "example": 9403 }, "serial": { "type": "string", "description": "Serial number of the device.", "nullable": true, "example": "2005890720" }, "vendor": { "type": "string", "description": "Device vendor.", "nullable": true, "example": "SMA Solar Technology AG" }, "generatorPower": { "type": "number", "description": "Nominal AC power of the device in [W].", "format": "double", "nullable": true, "example": 4000 }, "generatorPowerDc": { "type": "number", "description": "Max. DC generator power in [Wp].", "format": "double", "nullable": true, "example": 4000 }, "isActive": { "type": "boolean", "description": "True, if device is active, false, if device is deactivated. Always true for classic consumers without direct communication.", "example": false }, "deactivatedAt": { "type": "string", "description": "Date time in UTC when the ennexOS device has been deactivated. Not available for classic devices.", "format": "date-time", "nullable": true, "example": "2019-04-07T12:30:02" }, "batteryCapacity": { "type": "number", "description": "Gets the battery capacity.", "format": "double", "nullable": true, "example": 3500 }, "ipAddress": { "type": "string", "description": "Gets IP address.", "nullable": true, "example": "192.168.178.21" }, "firmwareVersion": { "type": "string", "description": "Gets the firmware version.", "nullable": true, "example": "03.00.07.R" }, "communicationProtocol": { "type": "string", "description": "Gets the communication protocol, f.e. SpeedWire or Modbus", "nullable": true, "example": "Speedwire" }, "startUpUtc": { "type": "string", "description": "Start up date UTC.", "format": "date-time", "example": "2019-07-01T00:00:00" }, "isResetted": { "type": "boolean", "description": "True, if device has been reset, but not yet reassigned to plant.\r\n Null, if information isn't available (e.g. user may not administrate device)\r\n (typically this property will only be set by portal)", "example": false }, "termOfGuarantee": { "type": "string", "description": "Gets the terms of guarantee.", "format": "date-time", "nullable": true, "example": "2044-07-01T00:00:00" }, "isSmartConnectedReady": { "type": "boolean", "description": "Smart Connected readiness of the device", "nullable": true }, "batteryLimits": { "$ref": "#/components/schemas/BatteryLimits" }, "nameplateData": { "$ref": "#/components/schemas/DeviceNameplateData" } }, "additionalProperties": false, "description": "Detailed information about a device" }, "DeviceDetailsLeanResponse": { "type": "object", "properties": { "details": { "$ref": "#/components/schemas/DeviceDetails" } }, "additionalProperties": false, "description": "A get device by device ID response." }, "DeviceDetailsResponse": { "type": "object", "properties": { "plant": { "$ref": "#/components/schemas/Plant" }, "details": { "$ref": "#/components/schemas/DeviceDetails" } }, "additionalProperties": false, "description": "A get device by device ID response." }, "DeviceInfos": { "type": "object", "properties": { "deviceId": { "type": "string", "description": "The device Id. This is the property to be used in the path to retrieve data for a dedicated device.", "nullable": true, "example": "302453" }, "name": { "type": "string", "description": "Name of the device.", "nullable": true, "example": "SB 3000TL-30" }, "timezone": { "type": "string", "description": "Timezone in IANA format.", "nullable": true, "example": "Europe/Berlin" }, "characteristic": { "$ref": "#/components/schemas/Characteristic" }, "type": { "type": "string", "description": "Device type.", "nullable": true, "example": "Solar Inverters" }, "product": { "type": "string", "description": "Device product name.", "nullable": true, "example": "SB4.0-1AV-41" }, "productId": { "type": "integer", "description": "The product id. Identifies the product of a device uniquely. Delivered only if the data is dedicated to a device.", "format": "int32", "nullable": true, "example": 9403 }, "serial": { "type": "string", "description": "Serial number of the device.", "nullable": true, "example": "2005890720" }, "vendor": { "type": "string", "description": "Device vendor.", "nullable": true, "example": "SMA Solar Technology AG" }, "generatorPower": { "type": "number", "description": "Nominal AC power of the device in [W].", "format": "double", "nullable": true, "example": 4000 }, "generatorPowerDc": { "type": "number", "description": "Max. DC generator power in [Wp].", "format": "double", "nullable": true, "example": 4000 }, "isActive": { "type": "boolean", "description": "True, if device is active, false, if device is deactivated. Always true for classic consumers without direct communication.", "example": false }, "deactivatedAt": { "type": "string", "description": "Date time in UTC when the ennexOS device has been deactivated. Not available for classic devices.", "format": "date-time", "nullable": true, "example": "2019-04-07T12:30:02" }, "isSmartConnectedReady": { "type": "boolean", "description": "Smart Connected readiness of the device", "nullable": true } }, "additionalProperties": false, "description": "The device resource acts as a digital representation of a device-owners physical device. It provides a view of most essential device\r\ndata items such as device type, device name, device description and links to further detailed device data. Devices are associated to a\r\nplant, subPlant or plantGroup." }, "DeviceInfosStatus": { "type": "object", "properties": { "deviceId": { "type": "string", "description": "The device Id. This is the property to be used in the path to retrieve data for a dedicated device.", "nullable": true, "example": "302453" }, "name": { "type": "string", "description": "Name of the device.", "nullable": true, "example": "SB 3000TL-30" }, "timezone": { "type": "string", "description": "Timezone in IANA format.", "nullable": true, "example": "Europe/Berlin" }, "type": { "type": "string", "description": "Device type.", "nullable": true, "example": "Solar Inverters" }, "product": { "type": "string", "description": "Device product name.", "nullable": true, "example": "SB4.0-1AV-41" }, "productId": { "type": "integer", "description": "The product id. Identifies the product of a device uniquely. Delivered only if the data is dedicated to a device.", "format": "int32", "nullable": true, "example": 9403 }, "serial": { "type": "string", "description": "Serial number of the device.", "nullable": true, "example": "2005890720" }, "vendor": { "type": "string", "description": "Device vendor.", "nullable": true, "example": "SMA Solar Technology AG" }, "generatorPower": { "type": "number", "description": "Nominal AC power of the device in [W].", "format": "double", "nullable": true, "example": 4000 }, "generatorPowerDc": { "type": "number", "description": "Max. DC generator power in [Wp].", "format": "double", "nullable": true, "example": 4000 }, "isActive": { "type": "boolean", "description": "True, if device is active, false, if device is deactivated. Always true for classic consumers without direct communication.", "example": false }, "deactivatedAt": { "type": "string", "description": "Date time in UTC when the ennexOS device has been deactivated. Not available for classic devices.", "format": "date-time", "nullable": true, "example": "2019-04-07T12:30:02" }, "status": { "type": "string", "description": "The status of a device from uncritical to critical:\r\n\r\nThe status is returned as \"Unknown\" if no status is available.", "nullable": true, "example": "Ok" }, "operationStatus": { "type": "string", "description": "The operation status of a device:\r\n\r\nOnly available for ennexOS devices.", "nullable": true, "example": "Auto" }, "isSmartConnectedReady": { "type": "boolean", "description": "Smart Connected readiness of the device", "nullable": true } }, "additionalProperties": false, "description": "Information about the device base status." }, "DeviceInfosStatusResponse": { "type": "object", "properties": { "plant": { "$ref": "#/components/schemas/Plant" }, "device": { "$ref": "#/components/schemas/DeviceInfosStatus" } }, "additionalProperties": false, "description": "The device resource acts as a digital representation of a device-owners physical device. It provides a view of most essential device data items such as device type, device name, device description and links to further detailed device data.Devices are associated to a plant, subPlant or plantGroup." }, "DeviceLogsResponse": { "type": "object", "properties": { "device": { "$ref": "#/components/schemas/Device" }, "logs": { "type": "array", "items": { "$ref": "#/components/schemas/Log" }, "description": "Gets the logs.", "nullable": true } }, "additionalProperties": false, "description": "A device logs response." }, "DeviceMeasurementSet": { "type": "object", "additionalProperties": false, "description": "Device measurement set." }, "DeviceMeasurementSetsResponse": { "type": "object", "properties": { "plant": { "$ref": "#/components/schemas/Plant" }, "device": { "$ref": "#/components/schemas/Device" }, "setType": { "type": "string", "description": "The type of the measurement set\r\n", "nullable": true }, "resolution": { "enum": [ "OneMinute", "FiveMinutes", "FifteenMinutes", "OneHour", "OneDay", "OneMonth", "OneYear" ], "type": "string", "description": "Resolution of provided measurement data which is only provided for ennexOS devices except for period Recent.", "nullable": true }, "set": { "type": "array", "items": { "oneOf": [ { "$ref": "#/components/schemas/EnergyAndPowerBatteryMeasurementSet" }, { "$ref": "#/components/schemas/EnergyAndPowerConsumptionMeasurementSet" }, { "$ref": "#/components/schemas/EnergyAndPowerInOutMeasurementSet" }, { "$ref": "#/components/schemas/EnergyAndPowerPvMeasurementSet" }, { "$ref": "#/components/schemas/EnergyDcMeasurementSet" }, { "$ref": "#/components/schemas/EnergyMixMeasurementSet" }, { "$ref": "#/components/schemas/PowerAcMeasurementSet" }, { "$ref": "#/components/schemas/PowerDcMeasurementSet" }, { "$ref": "#/components/schemas/SensorMeasurementSet" } ], "description": "Device measurement set." }, "description": "The measurement set values.", "nullable": true }, "total": { "oneOf": [ { "$ref": "#/components/schemas/EnergyAndPowerBatteryMeasurementSet" }, { "$ref": "#/components/schemas/EnergyAndPowerConsumptionMeasurementSet" }, { "$ref": "#/components/schemas/EnergyAndPowerInOutMeasurementSet" }, { "$ref": "#/components/schemas/EnergyAndPowerPvMeasurementSet" }, { "$ref": "#/components/schemas/EnergyDcMeasurementSet" }, { "$ref": "#/components/schemas/EnergyMixMeasurementSet" }, { "$ref": "#/components/schemas/PowerAcMeasurementSet" }, { "$ref": "#/components/schemas/PowerDcMeasurementSet" }, { "$ref": "#/components/schemas/SensorMeasurementSet" } ], "description": "The total values available for EnergyMix measurement set. The total values for the requested period are equal to the values of the requested period in the next-higher resolution. Note: in rare cases, total values may be higher than the aggregation of all single values (e.g. unrecorded changes, etc.).", "nullable": true } }, "additionalProperties": false, "description": "A device monitoring measurement set response." }, "DeviceNameplateData": { "type": "object", "properties": { "rtgVAMaxOut": { "type": "number", "description": "Limit value for the apparent power [VA] at the active power output", "format": "double", "nullable": true }, "rtgVAMaxIn": { "type": "number", "description": "Limit value for the apparent power [VA] at the active power draw", "format": "double", "nullable": true }, "rtgVarMax": { "type": "array", "items": { "$ref": "#/components/schemas/QuadrantIndexValue" }, "description": "Rating values for reactive power (Parameter VArMaxQxRtg) [var].\r\nLimits the reactive power in each quadrant from Q1 to Q4.", "nullable": true }, "rtgPfMin": { "type": "array", "items": { "$ref": "#/components/schemas/QuadrantIndexValue" }, "description": "Rating values for cos phi (Parameter PFMinQxRtg).\r\nLimits the reactive power mode with cos phi setpoints or cos phi characteristic curves.", "nullable": true } }, "additionalProperties": false, "description": "Nameplate data describing the rated capabilities of the device. Not supported for classic plants." }, "DeviceSupportedMeasurementSetsResponse": { "type": "object", "properties": { "plant": { "$ref": "#/components/schemas/Plant" }, "device": { "$ref": "#/components/schemas/Device" }, "sets": { "type": "array", "items": { "enum": [ "EnergyAndPowerBattery", "EnergyAndPowerConsumption", "EnergyAndPowerInOut", "EnergyAndPowerPv", "EnergyMix", "PowerAc", "EnergyDc", "PowerDc", "Sensor" ], "type": "string", "description": "The device set type." }, "description": "Supported measurement sets.", "nullable": true } }, "additionalProperties": false, "description": "Supported measurement sets of a device." }, "DirectSellingInfo": { "type": "object", "properties": { "directSellingContractNumber": { "type": "string", "description": "The direct selling contract number.", "nullable": true } }, "additionalProperties": false, "description": "The direct selling contract info." }, "EligibilityRequest": { "required": [ "plantIdentifier" ], "type": "object", "properties": { "plantIdentifier": { "$ref": "#/components/schemas/PlantIdentifier" }, "checkCommands": { "type": "array", "items": { "enum": [ "FeedInLimit", "OpModFixedPfAbsorbW", "OpModFixedPFInjectW", "OpModEnergize", "OpModFixedPFW", "ExportLimit", "GenerationLimit" ], "type": "string", "description": "Command type." }, "description": "Optional parameter for listing the commands to be checked. If empty or not available, then all commands are checked by default.", "nullable": true }, "checkSettings": { "type": "array", "items": { "enum": [ "ActivePowerRampSettings", "ActivePowerFixedLimitSettings", "ActivePowerDefaultDynamicTargetSettings", "ActivePowerVoltWattCurveSettings", "ActivePowerFreqWattSettings", "ReactivePowerModeSettings", "ReactivePowerVoltVarCurveSettings", "ReactivePowerFixedPfInjectingAndAbsorbingSettings", "EnergizeSettings", "VoltageFaultRideThroughSettings", "FrequencyFaultRideThroughSettings" ], "type": "string", "description": "To get settings and get eligibility" }, "description": "Optional parameter for listing the commands to be checked. If empty or not available, then all commands are checked by default.", "nullable": true } }, "additionalProperties": false, "description": "Request for eligibility check." }, "EligibilityResponse": { "type": "object", "properties": { "feedInLimit": { "$ref": "#/components/schemas/EligibleInfo" }, "opModFixedPFAbsorbW": { "$ref": "#/components/schemas/EligibleInfo" }, "opModFixedPFInjectW": { "$ref": "#/components/schemas/EligibleInfo" }, "opModEnergize": { "$ref": "#/components/schemas/EligibleInfo" }, "opModFixedPFW": { "$ref": "#/components/schemas/EligibleInfo" }, "activePowerRampSettings": { "$ref": "#/components/schemas/EligibleInfo" }, "activePowerFixedLimitSettings": { "$ref": "#/components/schemas/EligibleInfo" }, "activePowerDefaultDynamicTargetSettings": { "$ref": "#/components/schemas/EligibleInfo" }, "activePowerVoltWattCurveSettings": { "$ref": "#/components/schemas/EligibleInfo" }, "activePowerFreqWattSettings": { "$ref": "#/components/schemas/EligibleInfo" }, "reactivePowerModeSettings": { "$ref": "#/components/schemas/EligibleInfo" }, "reactivePowerVoltVarCurveSettings": { "$ref": "#/components/schemas/EligibleInfo" }, "energizeSettings": { "$ref": "#/components/schemas/EligibleInfo" }, "voltageFaultRideThroughSettings": { "$ref": "#/components/schemas/EligibleInfo" }, "frequencyFaultRideThroughSettings": { "$ref": "#/components/schemas/EligibleInfo" }, "generationLimit": { "$ref": "#/components/schemas/EligibleInfo" }, "exportLimit": { "$ref": "#/components/schemas/EligibleInfo" } }, "additionalProperties": false, "description": "Response for plant commands eligibility." }, "EligibleError": { "type": "object", "properties": { "errorType": { "enum": [ "ServiceCommunication", "DeviceOffline", "DeviceTimeout", "DeviceCommunication", "DeviceUnauthorized", "DevicePassword", "DirectSellingInterface", "DeprecatedCommand", "NotSupported", "NoControlDeviceFound" ], "type": "string", "description": "Current error message\r\n" }, "devices": { "type": "array", "items": { "$ref": "#/components/schemas/EligibleErrorDevice" }, "description": "List of affected devices", "nullable": true } }, "additionalProperties": false, "description": "Error information for failed eligibility check" }, "EligibleErrorDevice": { "type": "object", "properties": { "deviceId": { "type": "string", "description": "", "nullable": true }, "serialNumber": { "type": "string", "description": "", "nullable": true } }, "additionalProperties": false, "description": "" }, "EligibleInfo": { "type": "object", "properties": { "isEligible": { "type": "boolean", "description": "" }, "eligibleErrors": { "type": "array", "items": { "$ref": "#/components/schemas/EligibleError" }, "description": "Eligibility errors per device.", "nullable": true } }, "additionalProperties": false, "description": "Eligibility information, with optional error information." }, "EnergyAndPowerBatteryMeasurementSet": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/DeviceMeasurementSet" } ], "properties": { "time": { "type": "string", "description": "Timestamp in local plant time (YYYY-MM-DDThh:mm:ss.s, see ISO_8601).", "format": "date-time", "nullable": true, "example": "2020-03-23T12:40:00" }, "batteryCharging": { "type": "number", "description": "Power/energy that the system stored in the battery.", "format": "double", "nullable": true, "example": 4166.666 }, "batteryDischarging": { "type": "number", "description": "Power/energy that the consumers in the system consumed from the battery.", "format": "double", "nullable": true, "example": 4589.154 }, "batteryStateOfCharge": { "type": "number", "description": "State of charge of the battery in percent, in relation to the battery capacity. Filled only for the periods: Recent, Day, Week.", "format": "double", "nullable": true, "example": 34.465 }, "batteryStateOfHealth": { "type": "number", "description": "State of health of the battery in percent, in relation to the battery state. Filled only for the periods: Month, Year, Total. Not available for classic devices.", "format": "double", "nullable": true, "example": 81.654 }, "batteryStateOfChargeArray": { "type": "array", "items": { "$ref": "#/components/schemas/IndexValue" }, "description": "State of charge of the battery in percent in relation to the battery capacity as array. Filled only for the periods: Recent, Day, Week. Not available for classic devices.", "nullable": true }, "batteryStateOfHealthArray": { "type": "array", "items": { "$ref": "#/components/schemas/IndexValue" }, "description": "State of health of the battery in percent in relation to the battery state as array. Filled only for the periods: Month, Year, Total. Not available for classic devices.", "nullable": true }, "batteryVoltage": { "type": "array", "items": { "$ref": "#/components/schemas/IndexValue" }, "description": "Battery voltage (DC) of each battery stack in V as array. Filled only for the periods: Recent, Day, Week. Not available for classic devices.", "nullable": true }, "batteryCurrent": { "type": "array", "items": { "$ref": "#/components/schemas/IndexValue" }, "description": "Battery current (DC) of each battery stack in A as array. Filled only for the periods: Recent, Day, Week. Not available for classic devices.", "nullable": true }, "batteryTemperature": { "type": "array", "items": { "$ref": "#/components/schemas/IndexValue" }, "description": "Battery temperature of each battery stack in °C as array. Filled only for the periods: Recent, Day, Week. Not available for classic devices.", "nullable": true }, "currentBatteryChargingSetVoltage": { "type": "array", "items": { "$ref": "#/components/schemas/IndexValue" }, "description": "Current battery setpoint charging voltage (DC) of each battery stack in V as array. Filled only for the periods: Recent, Day, Week. Not available for classic devices.", "nullable": true } }, "additionalProperties": false, "description": "Battery-charging and discharging (energy and power), state of charge (power) and state of health (energy) values." }, "EnergyAndPowerConsumptionMeasurementSet": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/DeviceMeasurementSet" } ], "properties": { "time": { "type": "string", "description": "Timestamp in local plant time (YYYY-MM-DDThh:mm:ss.s, see ISO_8601).", "format": "date-time", "nullable": true, "example": "2020-03-23T12:40:00" }, "consumption": { "type": "number", "description": "Returns the consumption.", "format": "double", "nullable": true, "example": 7522.907 } }, "additionalProperties": false, "description": "Consumption (energy and power) values." }, "EnergyAndPowerInOutMeasurementSet": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/DeviceMeasurementSet" } ], "properties": { "time": { "type": "string", "description": "Timestamp in local plant time (YYYY-MM-DDThh:mm:ss.s, see ISO_8601).", "format": "date-time", "nullable": true, "example": "2020-03-23T12:40:00" }, "gridFeedIn": { "type": "number", "description": "Power/energy fed into the grid.", "format": "double", "nullable": true, "example": 349595.84 }, "gridConsumption": { "type": "number", "description": "Power/energy consumed from the grid.", "format": "double", "nullable": true, "example": 310161.4 } }, "additionalProperties": false, "description": "Feed-In and external consumption (energy and power) values." }, "EnergyAndPowerPvMeasurementSet": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/DeviceMeasurementSet" } ], "properties": { "time": { "type": "string", "description": "Timestamp in local plant time (YYYY-MM-DDThh:mm:ss.s, see ISO_8601).", "format": "date-time", "nullable": true, "example": "2020-03-23T12:40:00" }, "pvGeneration": { "type": "number", "description": "Power/energy generated by pv inverters in the system.", "format": "double", "nullable": true, "example": 7732.648 } }, "additionalProperties": false, "description": "PV-generation (energy and power) values." }, "EnergyBalanceMeasurementSet": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/PlantMeasurementSet" } ], "properties": { "time": { "type": "string", "description": "Timestamp in local plant time (YYYY-MM-DDThh:mm:ss.s, see ISO_8601).", "format": "date-time", "nullable": true, "example": "2020-03-23T12:40:00" }, "pvGeneration": { "type": "number", "description": "Power/energy generated by pv inverters in the system.", "format": "double", "nullable": true, "example": 3445.543 }, "directConsumption": { "type": "number", "description": "Power/energy that the consumers in the system consumed directly from the system, without intermediate storage.", "format": "double", "nullable": true, "example": 143.53 }, "totalConsumption": { "type": "number", "description": "Total amount of power/energy that the consumers in the system consumed (independent whether it is generated from the system or generated from the utility grid).", "format": "double", "nullable": true, "example": 3445.543 }, "batteryCharging": { "type": "number", "description": "Power/energy that the system stored in the battery.", "format": "double", "nullable": true, "example": 234.54 }, "batteryDischarging": { "type": "number", "description": "Power/energy that the consumers in the system consumed from the battery.", "format": "double", "nullable": true, "example": 456.125 }, "batteryStateOfCharge": { "type": "number", "description": "State of charge of the battery in percent, in relation to the battery capacity. Filled only for the periods: Recent, Day, Week.", "format": "double", "nullable": true, "example": 64.65 }, "dieselGeneration": { "type": "number", "description": "Power/energy generated by diesel generators in the system.", "format": "double", "nullable": true, "example": 463.34 }, "combinedHeatAndPowerGeneration": { "type": "number", "description": "Power/energy generated by block and power stations in the system.", "format": "double", "nullable": true, "example": 3445.543 }, "hydroGeneration": { "type": "number", "description": "Power/energy generated by hydroelectric power stations in the system.", "format": "double", "nullable": true, "example": 345.543 }, "gridFeedIn": { "type": "number", "description": "Power/energy fed into the grid.", "format": "double", "nullable": true, "example": 245.783 }, "gridConsumption": { "type": "number", "description": "Power/energy consumed from the grid.", "format": "double", "nullable": true, "example": 75.33 }, "totalGeneration": { "type": "number", "description": "Power/energy generated by all the different generator devices in the system.", "format": "double", "nullable": true, "example": 764.5 }, "selfConsumption": { "type": "number", "description": "Power/energy from the PV-system that is being stored into the battery and power/energy the consumers in the system consumed from the system.", "format": "double", "nullable": true, "example": 56.8 }, "autarkyRate": { "type": "number", "description": "Autarky rate which is returned as a value between 0 and 1.", "format": "double", "nullable": true, "example": 0.8 }, "selfConsumptionRate": { "type": "number", "description": "Ratio of self-consumption to power/energy which is returned as a value between 0 and 1.", "format": "double", "nullable": true, "example": 0.3 }, "selfSupply": { "type": "number", "description": "Power/energy the consumers in the system consumed from the System and by discharging the battery.", "format": "double", "nullable": true, "example": 75.42 }, "usableStorageCapacityWithHealth": { "type": "number", "description": "Maximum of potential usable plant energy storage. Capacity of all existing batteries combined. Taking into account the degradation of battery cells. Filled only for the period: Recent.", "format": "double", "nullable": true, "example": 4972.34 }, "batteryChargingDc": { "type": "number", "description": "Power/energy that the system stored in the battery in dc. Only available for month, year, total.", "format": "double", "nullable": true, "example": 234.54 }, "batteryDischargingDc": { "type": "number", "description": "Power/energy that the consumers in the system consumed from the battery in dc. Only available for month, year, total.", "format": "double", "nullable": true, "example": 456.125 } }, "additionalProperties": false, "description": "Energy balance values.\r\n \r\nNote: Only the energy balance properties available is SP / SP powered by ennexOS can be provided via the Monitoring API." }, "EnergyDcMeasurementSet": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/DeviceMeasurementSet" } ], "properties": { "time": { "type": "string", "description": "Timestamp in local plant time (YYYY-MM-DDThh:mm:ss.s, see ISO_8601).", "format": "date-time", "nullable": true, "example": "2020-03-23T12:40:00" }, "dcEnergyInput": { "type": "array", "items": { "$ref": "#/components/schemas/IndexValue" }, "description": "Array of DC energy input values of tuples ([index A-Z], [value in Wh]).", "nullable": true } }, "additionalProperties": false, "description": "Direct energy input." }, "EnergyMixMeasurementSet": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/DeviceMeasurementSet" } ], "properties": { "time": { "type": "string", "description": "The timestamp in local plant time (YYYY-MM-DDThh:mm:ss.s, see ISO_8601).", "format": "date-time", "nullable": true, "example": "2020-03-23T12:40:00" }, "pvConsumptionRate": { "type": "number", "description": "Rate of power consumed by the given device from pv inverters in the device's plant which is returned as a value between 0 and 1.", "format": "double", "nullable": true, "example": 0.52 }, "batteryConsumptionRate": { "type": "number", "description": "Rate of power consumed by the given device from the batteries in the device's plant which is returned as a value between 0 and 1.", "format": "double", "nullable": true, "example": 0.28 }, "gridConsumptionRate": { "type": "number", "description": "Rate of power consumed by the given device from the grid which is returned as a value between 0 and 1.", "format": "double", "nullable": true, "example": 0.25 }, "totalConsumption": { "type": "number", "description": "Total amount of power/energy consumed by the given device.", "format": "double", "nullable": true, "example": 40.5 } }, "additionalProperties": false, "description": "Measurement set with energy mix values of a consumer for periods Month, Year and Total." }, "GridSettingsMeasurementSet": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/PlantMeasurementSet" } ], "properties": { "time": { "type": "string", "description": "Timestamp in local plant time (YYYY-MM-DDThh:mm:ss.s, see ISO_8601).", "format": "date-time", "nullable": true, "example": "2020-03-23T12:40:00" }, "setPointFeedInPower": { "type": "number", "description": "Maximum active power set-point specification in %.", "format": "double", "nullable": true, "example": 42 }, "setPointReactivePower": { "type": "number", "description": "Maximum reactive power set-point specification in %.", "format": "double", "nullable": true, "example": 66 }, "setValueLimitationFeedInPower": { "type": "number", "description": "Set value limitation active power in %.", "format": "double", "nullable": true, "example": 53 }, "setValueLimitationReactivePower": { "type": "number", "description": "Set value limitation of reactive power in %.", "format": "double", "nullable": true, "example": 77 } }, "additionalProperties": false, "description": "Grid Settings status values on plant level. Available for periods Recent and Day. Not available for classic plants." }, "Image": { "type": "object", "properties": { "imageId": { "type": "string", "description": "The id of the image.", "nullable": true, "example": "28102020_162210{32x32}" }, "imageType": { "enum": [ "PortalProfileSmall", "PortalProfileLarge" ], "type": "string", "description": "The type of the image.", "example": "PortalProfileSmall" }, "title": { "type": "string", "description": "The title of the image.", "nullable": true, "example": "Anlagenfoto" }, "subtitle": { "type": "string", "description": "The subtitle of the image.", "nullable": true, "example": "Anlage-Südseite 2020" } }, "additionalProperties": false, "description": "The image of a plant." }, "IndexValue": { "type": "object", "properties": { "index": { "type": "string", "description": "Array index [A-Z] of the channel.", "nullable": true, "example": "A" }, "value": { "type": "number", "description": "Array value.", "format": "double", "nullable": true, "example": 35.44 } }, "additionalProperties": false, "description": "" }, "Log": { "type": "object", "properties": { "logId": { "type": "string", "description": "The log id represents the event id. For ennexOS devices and plants, the log id is always available, for classic devices and plants, the log id is only available in case the messageTagId can be unambiguously mapped to the event id.", "nullable": true, "example": "15251" }, "timestamp": { "type": "string", "description": "The timestamp in local plant time (YYYY-MM-DDThh:mm:ss.s, see ISO_8601).", "format": "date-time", "example": "2020-03-11T02:58:03" }, "messageTagId": { "type": "string", "description": "A unique identifier for the message contained in the log entry.", "nullable": true, "example": "1849" }, "message": { "type": "string", "description": "Description of the error in the current requested language.", "nullable": true, "example": "SMACOM A: communication status goes to Ok" }, "level": { "type": "string", "description": "The level of the specific log-entry.", "nullable": true, "example": "Info" }, "occurrence": { "type": "string", "description": "The type of the event: Appeared or Solved.", "nullable": true, "example": "Solved" }, "counter": { "type": "string", "description": "Count how many times a specific log occurred, null if no multiple events within the time span.", "nullable": true, "example": "0" }, "deviceId": { "type": "string", "description": "The device id. Delivered only if the data is dedicated to a device.", "nullable": true, "example": "302453" }, "subPlantId": { "type": "string", "description": "The sub-plant id. Delivered only if the data is dedicated to a sub-plant.", "nullable": true, "example": "250561" }, "plantId": { "type": "string", "description": "The plant id. Delivered only if the data is dedicated to a plant.", "nullable": true, "example": "25056" } }, "additionalProperties": false, "description": "A plant log." }, "MeterId": { "type": "object", "properties": { "nmi": { "type": "string", "description": "A national metering identifier.", "nullable": true } }, "additionalProperties": false, "description": "A metering identifier." }, "MigrationInfo": { "type": "object", "properties": { "oldPlantId": { "type": "string", "description": "The previous plant identifier from the old (classic) Sunny Portal.", "nullable": true, "example": "c9cce24f-b646-48bd-929b-addcb4cd2810" }, "migrationTime": { "type": "string", "description": "Migration timestamp in UTC format (yyyy-MM-ddTHH:mm:ssZ).", "format": "date-time" } }, "additionalProperties": false, "description": "Contains details about the plant migration process. Only available if the system was migrated (automatically, in the background) from the old (classic) Sunny Portal to the new one (Sunny Portal powered by ennexOS)." }, "Plant": { "type": "object", "properties": { "plantId": { "type": "string", "description": "The plant id. This is the property to be used in the path to retrieve data for a dedicated plant.", "nullable": true, "example": "25056" }, "name": { "type": "string", "description": "Name of the plant. It is a user assigned label.", "nullable": true, "example": "Niestetal Plant" }, "description": { "type": "string", "description": "Additional description of the plant. It is a user assigned description.", "nullable": true, "example": "One of the biggest solar plants." }, "timezone": { "type": "string", "description": "Timezone in IANA format.", "nullable": true, "example": "Europe/Berlin" } }, "additionalProperties": false, "description": "The plant resource acts as a digital representation of a plant-owners physical plant. It provides a view of most essential plant data items such as plant name, plant description and links to further detailed plant data." }, "PlantAddress": { "type": "object", "properties": { "country": { "type": "string", "description": "Country code where the plant is located in format ISO 3166 ALPHA-2.", "nullable": true, "example": "DE" }, "federalState": { "type": "string", "description": "Federal state where the plant is located.", "nullable": true, "example": "Hessen" }, "city": { "type": "string", "description": "City where the plant is located.", "nullable": true, "example": "Niestetal" }, "zipCode": { "type": "string", "description": "Zip code of the city.", "nullable": true, "example": "34266" }, "street": { "type": "string", "description": "Street where the plant is located.", "nullable": true, "example": "Sonnenallee" }, "streetNo": { "type": "string", "description": "Street number.", "nullable": true, "example": "1" }, "longitude": { "type": "number", "description": "Longitude.", "format": "double", "nullable": true, "example": 9.53829 }, "latitude": { "type": "number", "description": "Latitude.", "format": "double", "nullable": true, "example": 51.31555 }, "elevation": { "type": "number", "description": "Elevation.", "format": "double", "nullable": true, "example": 136 } }, "additionalProperties": false, "description": "The address data of a plant." }, "PlantCapabilitiesResponse": { "type": "object", "properties": { "plant": { "$ref": "#/components/schemas/Plant" }, "capabilities": { "$ref": "#/components/schemas/Capabilities" } }, "additionalProperties": false, "description": "The capabilities of a plant." }, "PlantCommunicationResponse": { "type": "object", "properties": { "plant": { "$ref": "#/components/schemas/Plant" }, "deviceCommunications": { "type": "array", "items": { "$ref": "#/components/schemas/DeviceCommunication" }, "description": "The devices with the time of the last and expected contact.", "nullable": true } }, "additionalProperties": false, "description": "The plant communication monitoring response." }, "PlantConfigurationResponse": { "type": "object", "properties": { "plantId": { "type": "string", "description": "The plant id. This is the property to be used in the path to retrieve data for a dedicated plant.", "nullable": true, "example": "25056" }, "name": { "type": "string", "description": "Name of the plant. It is a user assigned label.", "nullable": true, "example": "Niestetal Plant" }, "description": { "type": "string", "description": "Additional description of the plant. It is a user assigned description.", "nullable": true, "example": "One of the biggest solar plants." }, "timezone": { "type": "string", "description": "Timezone in IANA format.", "nullable": true, "example": "Europe/Berlin" }, "plantWithPV": { "type": "boolean", "description": "EnnexOs: true, if the plant has PV-generation values in the last 24h.\r\nClassic: true, if the plant has PV-generation values." }, "plantWithBattery": { "type": "boolean", "description": "EnnexOs: true, if the plant has at least one active battery device with measurement values in the last 24h.\r\nClassic: true, if the plant has at least one active battery device." }, "plantWithEnergyMeter": { "type": "boolean", "description": "EnnexOs: true, if the plant has energy meter values in the last 24h.\r\nClassic: true, if the plant has energy meter values." }, "plantWithLiveData": { "type": "boolean", "description": "True, if the plant supports live data, false otherwise. Currently only classic WebConnect and Home-Manager systems support live data." }, "smartConnectedConfiguration": { "$ref": "#/components/schemas/SmartConnectedConfiguration" } }, "additionalProperties": false, "description": "The configuration details of a plant." }, "PlantDerivedStakeholderResponse": { "type": "object", "properties": { "plant": { "$ref": "#/components/schemas/Plant" }, "userId": { "type": "integer", "description": "Gets the user.", "format": "int64" }, "role": { "enum": [ "Undefined", "Owner", "Installer", "Operator" ], "type": "string", "description": "Gets the derived stakeholder role." } }, "additionalProperties": false, "description": "A plant derived stakeholder response." }, "PlantDeviceRelationResponse": { "type": "object", "properties": { "basicDevice": { "$ref": "#/components/schemas/BasicDevice" } }, "additionalProperties": false, "description": "Basic device response." }, "PlantEnergyAndPowerPvMeasurementSet": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/PlantMeasurementSet" } ], "properties": { "time": { "type": "string", "description": "Timestamp in local plant time (YYYY-MM-DDThh:mm:ss.s, see ISO_8601).", "format": "date-time", "nullable": true, "example": "2020-03-23T12:40:00" }, "pvGeneration": { "type": "number", "description": "Power/energy generated by pv inverters in the system.", "format": "double", "nullable": true, "example": 7732.648 } }, "additionalProperties": false, "description": "PV-generation (energy and power) values." }, "PlantGroup": { "type": "object", "properties": { "plantGroupId": { "type": "string", "description": "The plant group id. Delivered only if the data is dedicated to a plant-group.", "nullable": true, "example": "2505" }, "name": { "type": "string", "description": "Gets the group name. It is a user assigned label.", "nullable": true, "example": "The plant group name" }, "description": { "type": "string", "description": "Additional description. It is a user assigned description.", "nullable": true, "example": "The plant group description" } }, "additionalProperties": false, "description": "The plant group resource acts as organizational layer to improve plant management. It enables measurement and balance views for a collection of plants with a single request." }, "PlantGroupLogsResponse": { "type": "object", "properties": { "plant": { "$ref": "#/components/schemas/PlantGroup" }, "logs": { "type": "array", "items": { "$ref": "#/components/schemas/Log" }, "description": "Gets the logs.", "nullable": true } }, "additionalProperties": false, "description": "A plant logs response." }, "PlantGroupPlants": { "type": "object", "properties": { "plantGroup": { "$ref": "#/components/schemas/PlantGroup" }, "plants": { "type": "array", "items": { "$ref": "#/components/schemas/PlantStatus" }, "description": "Gets the plants.", "nullable": true } }, "additionalProperties": false, "description": "The plants for plant group response." }, "PlantGroupStatus": { "type": "object", "properties": { "plantGroupId": { "type": "string", "description": "The plant group id. Delivered only if the data is dedicated to a plant-group.", "nullable": true, "example": "2505" }, "name": { "type": "string", "description": "Gets the group name. It is a user assigned label.", "nullable": true, "example": "The plant group name" }, "description": { "type": "string", "description": "Additional description. It is a user assigned description.", "nullable": true, "example": "The plant group description" }, "status": { "type": "string", "description": "The status of a plant-group from uncritical to critical:\r\n\r\nThe status is returned as \"Unknown\" if no status is available.", "nullable": true, "example": "Ok" } }, "additionalProperties": false, "description": "The plant group resource acts as organizational layer to improve plant management. It enables measurement and balance views for a collection of plants with a single request." }, "PlantGroupStatusList": { "type": "object", "properties": { "plantGroups": { "type": "array", "items": { "$ref": "#/components/schemas/PlantGroupStatus" }, "description": "Gets or sets the groups the plant belongs to.", "nullable": true } }, "additionalProperties": false, "description": "A plant group management response." }, "PlantIdentifier": { "type": "object", "properties": { "meterId": { "$ref": "#/components/schemas/MeterId" }, "plantId": { "type": "string", "description": "Plant identifier.", "nullable": true, "example": "25056" }, "serialNumber": { "type": "string", "description": "Serial number of any SMA device in the system to be identified. Either readable directly from the device type label or in the Sunny Portal(s) in the Configuration section, in the device overview or configuration.", "nullable": true, "example": "4636494" } }, "additionalProperties": false, "description": "Plant Identifier." }, "PlantImagesResponse": { "type": "object", "properties": { "plant": { "$ref": "#/components/schemas/Plant" }, "images": { "type": "array", "items": { "$ref": "#/components/schemas/Image" }, "description": "The plant images", "nullable": true } }, "additionalProperties": false, "description": "A plant management images response." }, "PlantInstallation": { "type": "object", "properties": { "peakPower": { "type": "number", "description": "This property with the misleading name will be removed in the future. Use dcPowerInputMax for DC power in [Wp] or acNominalPower (custom) or calcAcNominalPower (sum over all active PV inverters) both in [W] for AC power instead.", "format": "double", "example": 4000, "deprecated": true }, "acNominalPower": { "type": "number", "description": "Nominal AC power of the plant in [W], (user-defined or calculated from PV Modules configuration) in Sunny Portal powered by ennexOS, not available in Sunny Portal (classic).", "format": "double", "example": 4100 }, "calcAcNominalPower": { "type": "number", "description": "Nominal AC power of the plant in [W], calculated as the sum of the individual AC powers of all active PV inverters.", "format": "double", "nullable": true, "example": 4150 }, "dcPowerInputMax": { "type": "number", "description": "Maximum power (PV array power) of the plant’s generators in Wp.", "format": "double", "example": 4420 }, "feedInTariff": { "type": "number", "description": "Gets or sets the feed in tariff.", "format": "double", "nullable": true, "example": 0.108 }, "co2SavingsFactor": { "type": "integer", "description": "The CO2 savings factor [g/kWh] indicates how much CO2 is produced when generating one kilowatt hour of electricity, or how much CO2 was not produced by the environmentally friendly electricity generation of your PV system.", "format": "int32", "nullable": true, "example": 640 }, "startUpUtc": { "type": "string", "description": "Start up date in UTC.", "format": "date-time", "example": "2019-07-01T00:00:00" }, "orientation": { "$ref": "#/components/schemas/PlantOrientation" } }, "additionalProperties": false, "description": "Installation details of plant." }, "PlantInstallationResponse": { "type": "object", "properties": { "plantId": { "type": "string", "description": "The plant id. This is the property to be used in the path to retrieve data for a dedicated plant.", "nullable": true, "example": "25056" }, "name": { "type": "string", "description": "Name of the plant. It is a user assigned label.", "nullable": true, "example": "Niestetal Plant" }, "description": { "type": "string", "description": "Additional description of the plant. It is a user assigned description.", "nullable": true, "example": "One of the biggest solar plants." }, "timezone": { "type": "string", "description": "Timezone in IANA format.", "nullable": true, "example": "Europe/Berlin" }, "peakPower": { "type": "number", "description": "This property with the misleading name will be removed in the future. Use dcPowerInputMax for DC power in [Wp] or acNominalPower (custom) or calcAcNominalPower (sum over all active PV inverters) both in [W] for AC power instead.", "format": "double", "example": 4200, "deprecated": true }, "acNominalPower": { "type": "number", "description": "Nominal AC power of the plant in [W], (user-defined or calculated from PV Modules configuration) in Sunny Portal powered by ennexOS, not available in Sunny Portal (classic).", "format": "double", "example": 4100 }, "dcPowerInputMax": { "type": "number", "description": "Maximum power (PV array power) of the plant’s generators in Wp.", "format": "double", "example": 4420 }, "feedInTariff": { "type": "number", "description": "Gets or sets the feed in tariff.", "format": "double", "nullable": true, "example": 0.108 }, "co2SavingsFactor": { "type": "integer", "description": "The CO2 savings factor [g/kWh] indicates how much CO2 is produced when generating one kilowatt hour of electricity, or how much CO2 was not produced by the environmentally friendly electricity generation of your PV system.", "format": "int32", "nullable": true, "example": 640 }, "startUpUtc": { "type": "string", "description": "Start up date in UTC.", "format": "date-time", "example": "2019-07-01T00:00:00" }, "orientation": { "$ref": "#/components/schemas/PlantOrientation" }, "pvModuleAreas": { "type": "array", "items": { "$ref": "#/components/schemas/PvModuleArea" }, "nullable": true }, "storageData": { "$ref": "#/components/schemas/StorageData" }, "calcAcNominalPower": { "type": "number", "description": "Nominal AC power of the plant in [W], calculated as the sum of the individual AC powers of all active PV inverters.", "format": "double", "nullable": true, "example": 4150 } }, "additionalProperties": false, "description": "Installation details of plant." }, "PlantLocation": { "type": "object", "properties": { "currencyCode3": { "type": "string", "description": "The ISO currency code according to ISO 4217..", "nullable": true, "example": "EUR" }, "address": { "$ref": "#/components/schemas/PlantAddress" } }, "additionalProperties": false, "description": "Location of plant" }, "PlantLocationResponse": { "type": "object", "properties": { "plantId": { "type": "string", "description": "The plant id. This is the property to be used in the path to retrieve data for a dedicated plant.", "nullable": true, "example": "25056" }, "name": { "type": "string", "description": "Name of the plant. It is a user assigned label.", "nullable": true, "example": "Niestetal Plant" }, "description": { "type": "string", "description": "Additional description of the plant. It is a user assigned description.", "nullable": true, "example": "One of the biggest solar plants." }, "timezone": { "type": "string", "description": "Timezone in IANA format.", "nullable": true, "example": "Europe/Berlin" }, "currencyCode3": { "type": "string", "description": "The ISO currency code according to ISO 4217..", "nullable": true, "example": "EUR" }, "address": { "$ref": "#/components/schemas/PlantAddress" } }, "additionalProperties": false, "description": "Location of plant" }, "PlantLogsResponse": { "type": "object", "properties": { "plant": { "$ref": "#/components/schemas/Plant" }, "logs": { "type": "array", "items": { "$ref": "#/components/schemas/Log" }, "description": "Gets the logs.", "nullable": true } }, "additionalProperties": false, "description": "A plant logs response." }, "PlantManagementPlantDevicesLeanResponse": { "type": "object", "properties": { "devices": { "type": "array", "items": { "$ref": "#/components/schemas/DeviceInfos" }, "description": "Gets the devices.", "nullable": true } }, "additionalProperties": false }, "PlantManagementPlantDevicesResponse": { "type": "object", "properties": { "plant": { "$ref": "#/components/schemas/Plant" }, "devices": { "type": "array", "items": { "$ref": "#/components/schemas/DeviceInfos" }, "description": "Gets the devices.", "nullable": true } }, "additionalProperties": false, "description": "A plant management plant devices response." }, "PlantManagementSubPlantResponse": { "type": "object", "properties": { "plant": { "$ref": "#/components/schemas/Plant" }, "subPlants": { "type": "array", "items": { "$ref": "#/components/schemas/SubPlantStatus" }, "description": "The sub-plant resource acts as organizational layer to improve plant management. It enables measurement and balance views for a\r\nsubset of plant devices with a single request.", "nullable": true } }, "additionalProperties": false, "description": "A plant management sub plant response." }, "PlantMeasurementSet": { "type": "object", "additionalProperties": false, "description": "Plant measurement set." }, "PlantMeasurementSetsResponse": { "type": "object", "properties": { "plant": { "$ref": "#/components/schemas/Plant" }, "setType": { "type": "string", "description": "The measurement set type.\r\n", "nullable": true }, "resolution": { "enum": [ "OneMinute", "FiveMinutes", "FifteenMinutes", "OneHour", "OneDay", "OneMonth", "OneYear" ], "type": "string", "description": "Resolution of provided measurement data which is only provided for ennexOS plants except for period Recent and GridSettings status values.", "nullable": true }, "set": { "type": "array", "items": { "oneOf": [ { "$ref": "#/components/schemas/EnergyBalanceMeasurementSet" }, { "$ref": "#/components/schemas/GridSettingsMeasurementSet" }, { "$ref": "#/components/schemas/PlantEnergyAndPowerPvMeasurementSet" }, { "$ref": "#/components/schemas/PlantSensorMeasurementSet" } ], "description": "Plant measurement set." }, "description": "The measurement set values.", "nullable": true }, "total": { "oneOf": [ { "$ref": "#/components/schemas/EnergyBalanceMeasurementSet" }, { "$ref": "#/components/schemas/GridSettingsMeasurementSet" }, { "$ref": "#/components/schemas/PlantEnergyAndPowerPvMeasurementSet" }, { "$ref": "#/components/schemas/PlantSensorMeasurementSet" } ], "description": "The total values available for EnergyBalance measurement set. The total values for the requested period are equal to the values of the requested period in the next-higher resolution. Note: in rare cases, total values may be higher than the aggregation of all single values (e.g. unrecorded changes, etc.).", "nullable": true } }, "additionalProperties": false, "description": "A measurement sets response." }, "PlantNotification": { "type": "object", "properties": { "reportTypes": { "enum": [ "Report", "Alarm" ], "type": "string", "description": "Type of the notification." }, "designation": { "type": "string", "description": "Naming of the notification.", "nullable": true }, "cycle": { "enum": [ "Immediate", "Hourly", "Daily", "Weekly", "Monthly", "Annually" ], "type": "string", "description": "Notification cycle." }, "emails": { "type": "array", "items": { "type": "string" }, "description": "Recipient emails of a notification.", "nullable": true }, "active": { "type": "boolean", "description": "Notification status." } }, "additionalProperties": false, "description": "Notification configuration." }, "PlantNotificationsResponse": { "type": "object", "properties": { "plant": { "$ref": "#/components/schemas/Plant" }, "notifications": { "type": "array", "items": { "$ref": "#/components/schemas/PlantNotification" }, "description": "", "nullable": true } }, "additionalProperties": false, "description": "Provides an overview of the configured notifications at the plant level." }, "PlantOrientation": { "type": "object", "properties": { "trackingH": { "type": "boolean", "description": "Tracking h.", "nullable": true, "example": true }, "trackingV": { "type": "boolean", "description": "Tracking v.", "nullable": true, "example": false }, "azimuth": { "type": "integer", "description": "Azimuth.", "format": "int32", "nullable": true, "example": -30 }, "collectorSlope": { "type": "integer", "description": "Grade.", "format": "int32", "nullable": true, "example": 45 } }, "additionalProperties": false, "description": "The orientation details for classic plants." }, "PlantSensorMeasurementSet": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/PlantMeasurementSet" } ], "properties": { "time": { "type": "string", "description": "Timestamp in local plant time (YYYY-MM-DDThh:mm:ss.s, see ISO_8601).", "format": "date-time", "nullable": true, "example": "2020-03-23T12:40:00" }, "externalInsolation": { "type": "number", "description": "System insolation for the sensor in W/m².", "format": "double", "nullable": true, "example": 4.43 }, "ambientTemperature": { "type": "number", "description": "System ambient temperature for the sensor in °C.", "format": "double", "nullable": true, "example": 8.2 }, "moduleTemperature": { "type": "number", "description": "System module temperature for the sensor in °C.", "format": "double", "nullable": true, "example": 15.6 }, "windSpeed": { "type": "number", "description": "System wind speed for the sensor in m/s.", "format": "double", "nullable": true, "example": 3.6 } }, "additionalProperties": false, "description": "Sensor: Sensor values on plant level which can be requested for Recent and Day period." }, "PlantStakeholdersResponse": { "type": "object", "properties": { "plant": { "$ref": "#/components/schemas/Plant" }, "stakeholders": { "type": "array", "items": { "$ref": "#/components/schemas/Stakeholder" }, "description": "Gets the stakeholders.", "nullable": true } }, "additionalProperties": false, "description": "A plant stakeholders response." }, "PlantStatus": { "type": "object", "properties": { "plantId": { "type": "string", "description": "The plant id. This is the property to be used in the path to retrieve data for a dedicated plant.", "nullable": true, "example": "25056" }, "name": { "type": "string", "description": "Name of the plant. It is a user assigned label.", "nullable": true, "example": "Niestetal Plant" }, "description": { "type": "string", "description": "Additional description of the plant. It is a user assigned description.", "nullable": true, "example": "One of the biggest solar plants." }, "timezone": { "type": "string", "description": "Timezone in IANA format.", "nullable": true, "example": "Europe/Berlin" }, "status": { "type": "string", "description": "The status of the plant which considers the status of all active devices (belonging directly to the plant as well as belonging to the plant's sub-plants) from uncritical to critical:\r\n\r\nThe status is returned as \"Unknown\" if no status is available.\r\nFor classic plants, the status is only available if the Pro package is activated.", "nullable": true, "example": "Ok" } }, "additionalProperties": false, "description": "The plant resource acts as a digital representation of a plant-owners physical plant. It provides a view of most essential plant data items such as plant name, plant description and links to further detailed plant data." }, "PlantStatusInstallationLocation": { "type": "object", "properties": { "plantId": { "type": "string", "description": "The plant id. This is the property to be used in the path to retrieve data for a dedicated plant.", "nullable": true, "example": "25056" }, "name": { "type": "string", "description": "Name of the plant. It is a user assigned label.", "nullable": true, "example": "Niestetal Plant" }, "description": { "type": "string", "description": "Additional description of the plant. It is a user assigned description.", "nullable": true, "example": "One of the biggest solar plants." }, "timezone": { "type": "string", "description": "Timezone in IANA format.", "nullable": true, "example": "Europe/Berlin" }, "meterIds": { "type": "array", "items": { "$ref": "#/components/schemas/MeterId" }, "description": "The plants metering identifiers.", "nullable": true }, "status": { "type": "string", "description": "The status of the plant which considers the status of all active devices (belonging directly to the plant as well as belonging to the plant's sub-plants) from uncritical to critical:\r\n\r\nThe status is returned as \"Unknown\" if no status is available.\r\nFor classic plants, the status is only available if the Pro package is activated.", "nullable": true, "example": "Ok" }, "migrationInfo": { "$ref": "#/components/schemas/MigrationInfo" }, "installation": { "$ref": "#/components/schemas/PlantInstallation" }, "location": { "$ref": "#/components/schemas/PlantLocation" }, "directSellingInfo": { "$ref": "#/components/schemas/DirectSellingInfo" } }, "additionalProperties": false, "description": "The plant resource acts as a digital representation of a plant-owners physical plant. It provides a view of most essential plant data items such as plant name, plant description and links to further detailed plant data." }, "PlantStatusList": { "type": "object", "properties": { "plants": { "type": "array", "items": { "$ref": "#/components/schemas/PlantStatusInstallationLocation" }, "description": "Gets the plants.", "nullable": true } }, "additionalProperties": false, "description": "A plant management response." }, "PowerAcMeasurementSet": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/DeviceMeasurementSet" } ], "properties": { "time": { "type": "string", "description": "Timestamp in local plant time (YYYY-MM-DDThh:mm:ss.s, see ISO_8601).", "format": "date-time", "nullable": true, "example": "2020-03-23T12:40:00" }, "voltagePhaseA2B": { "type": "number", "description": "Grid voltage phase A against B in V.", "format": "double", "nullable": true, "example": 230.88 }, "voltagePhaseB2C": { "type": "number", "description": "Grid voltage phase B against C in V.", "format": "double", "nullable": true, "example": 23.5 }, "voltagePhaseC2A": { "type": "number", "description": "Grid voltage phase C against A in V.", "format": "double", "nullable": true, "example": 3.5 }, "voltagePhaseA": { "type": "number", "description": "Grid voltage phase A in V.", "format": "double", "nullable": true, "example": 230.88 }, "voltagePhaseB": { "type": "number", "description": "Grid voltage phase B in V.", "format": "double", "nullable": true, "example": 228.08 }, "voltagePhaseC": { "type": "number", "description": "Grid voltage phase C in V.", "format": "double", "nullable": true, "example": 227.96 }, "currentPhaseA": { "type": "number", "description": "Grid current phase A in A.", "format": "double", "nullable": true, "example": 7.416 }, "currentPhaseB": { "type": "number", "description": "Grid current phase B in A.", "format": "double", "nullable": true, "example": 1.783 }, "currentPhaseC": { "type": "number", "description": "Grid current phase C in A.", "format": "double", "nullable": true, "example": 2.365 }, "activePowerPhaseA": { "type": "number", "description": "(Active) power A in W.", "format": "double", "nullable": true, "example": 89.453 }, "activePowerPhaseB": { "type": "number", "description": "(Active) power B in W.", "format": "double", "nullable": true, "example": 245.569 }, "activePowerPhaseC": { "type": "number", "description": "(Active) power C in W.", "format": "double", "nullable": true, "example": 100.854 }, "activePower": { "type": "number", "description": "(Active) PV power in W.", "format": "double", "nullable": true, "example": 435.876 }, "reactivePowerPhaseA": { "type": "number", "description": "Reactive power A in VAr. Not available for classic devices.", "format": "double", "nullable": true, "example": 318 }, "reactivePowerPhaseB": { "type": "number", "description": "Reactive power B in VAr. Not available for classic devices.", "format": "double", "nullable": true, "example": 1.681 }, "reactivePowerPhaseC": { "type": "number", "description": "Reactive power C in VAr. Not available for classic devices.", "format": "double", "nullable": true, "example": 1.745 }, "reactivePower": { "type": "number", "description": "Reactive power in VAr.", "format": "double", "nullable": true, "example": 307 }, "apparentPowerPhaseA": { "type": "number", "description": "Apparent power A in VA. Not available for classic devices.", "format": "double", "nullable": true, "example": 2.185 }, "apparentPowerPhaseB": { "type": "number", "description": "Apparent power B in VA. Not available for classic devices.", "format": "double", "nullable": true, "example": 2.023 }, "apparentPowerPhaseC": { "type": "number", "description": "Apparent power C in VA. Not available for classic devices.", "format": "double", "nullable": true, "example": 2.489 }, "apparentPower": { "type": "number", "description": "Apparent power in VA.", "format": "double", "nullable": true, "example": 406 }, "gridFrequency": { "type": "number", "description": "Grid frequency in Hz.", "format": "double", "nullable": true, "example": 49.97 }, "displacementPowerFactor": { "type": "number", "description": "The displacement power factor is the ratio of true power to apparent power due to the phase displacement between the current and voltage and is calculated as cos(Phi) where Phi is the difference between the phase of the voltage and the phase of the current (phase displacement) in degrees. The range of values ​​is therefore between -1 and 1. Not available for classic devices.", "format": "double", "nullable": true, "example": 2.5 } }, "additionalProperties": false, "description": "Current, active, reactive and apparent power values as well as grid voltage values for phases A, B, C and in total on device level. Available for periods Recent and Day." }, "PowerDcMeasurementSet": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/DeviceMeasurementSet" } ], "properties": { "time": { "type": "string", "description": "Timestamp in local plant time (YYYY-MM-DDThh:mm:ss.s, see ISO_8601).", "format": "date-time", "nullable": true, "example": "2020-07-09T11:46:00" }, "dcPowerInput": { "type": "array", "items": { "$ref": "#/components/schemas/IndexValue" }, "description": "Array of DC power input values of tuples ([index A-Z], [value in W]).", "nullable": true }, "dcVoltageInput": { "type": "array", "items": { "$ref": "#/components/schemas/IndexValue" }, "description": "Array of DC voltage input values of tuples ([index A-Z], [value in V]).", "nullable": true }, "dcCurrentInput": { "type": "array", "items": { "$ref": "#/components/schemas/IndexValue" }, "description": "Array of DC current input values of tuples ([index A-Z], [value in A])", "nullable": true }, "isolationResistance": { "type": "number", "description": "Isolation resistance in Ohm.", "format": "double", "nullable": true, "example": 2985073 } }, "additionalProperties": false, "description": "Direct power input, voltage and current values as well as insulation resistance on device level. Available for the periods Recent and Day." }, "PvModuleArea": { "type": "object", "properties": { "id": { "type": "integer", "description": "Id of PV module area", "format": "int64" }, "description": { "type": "string", "description": "Description of PV module area", "nullable": true }, "trackingH": { "type": "boolean", "description": "Tracking of horizontal axis (azimuth)" }, "trackingV": { "type": "boolean", "description": "Tracking of vertical axis (slope)" }, "azimuth": { "type": "integer", "description": "Angle of horizontal orientation with valid range of values between -180 and 180", "format": "int32" }, "collectorSlope": { "type": "integer", "description": "Angle of vertical orientation (inclination) with valid range of values between 0 and 90", "format": "int32" }, "dcPeakPower": { "type": "number", "description": "Max dc power input", "format": "double", "nullable": true } }, "additionalProperties": false, "description": "The PV module information including orientation details for ennexOS plants." }, "QuadrantIndexValue": { "type": "object", "properties": { "index": { "type": "string", "description": "Array index [Q1-Q4] for each quadrant", "nullable": true }, "value": { "type": "number", "description": "Array value", "format": "double", "nullable": true } }, "additionalProperties": false, "description": "Quadrant values\r\n" }, "SensorMeasurementSet": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/DeviceMeasurementSet" } ], "properties": { "time": { "type": "string", "description": "Timestamp in local plant time (YYYY-MM-DDThh:mm:ss.s, see ISO_8601).", "format": "date-time", "nullable": true, "example": "2020-03-23T12:40:00" }, "externalInsolation": { "type": "number", "description": "External insolation for the sensor in W/m².", "format": "double", "nullable": true, "example": 4.43 }, "ambientTemperature": { "type": "number", "description": "Ambient temperature for the sensor in °C.", "format": "double", "nullable": true, "example": 8.2 }, "moduleTemperature": { "type": "number", "description": "Module temperature for the sensor in °C.", "format": "double", "nullable": true, "example": 15.6 }, "windSpeed": { "type": "number", "description": "Wind speed for the sensor in m/s.", "format": "double", "nullable": true, "example": 3.6 } }, "additionalProperties": false, "description": "External sensor insolation, ambient temperature, module temperature and wind speed values. Available for the periods Recent and Day." }, "SimpleLog": { "type": "object", "properties": { "logId": { "type": "string", "description": "The log id represents the event id. For ennexOS devices and plants, the log id is always available, for classic devices and plants, the log id is only available in case the messageTagId can be unambiguously mapped to the event id.", "nullable": true, "example": "15251" }, "timestamp": { "type": "string", "description": "The timestamp in local plant time (YYYY-MM-DDThh:mm:ss.s, see ISO_8601).", "format": "date-time", "example": "2020-03-11T02:58:03" }, "messageTagId": { "type": "string", "description": "A unique identifier for the message contained in the log entry.", "nullable": true, "example": "1849" }, "message": { "type": "string", "description": "Description of the error in the current requested language.", "nullable": true, "example": "SMACOM A: communication status goes to Ok" }, "level": { "type": "string", "description": "The level of the specific log-entry.", "nullable": true, "example": "Info" }, "occurrence": { "type": "string", "description": "The type of the event: Appeared or Solved.", "nullable": true, "example": "Solved" }, "counter": { "type": "string", "description": "Count how many times a specific log occurred, null if no multiple events within the time span.", "nullable": true, "example": "0" }, "deviceId": { "type": "string", "description": "The device id. Delivered only if the data is dedicated to a device.", "nullable": true, "example": "302453" }, "subPlantId": { "type": "string", "description": "The sub-plant id. Delivered only if the data is dedicated to a sub-plant.", "nullable": true, "example": "250561" }, "plantId": { "type": "string", "description": "The plant id. Delivered only if the data is dedicated to a plant.", "nullable": true, "example": "25056" } }, "additionalProperties": false }, "SmartConnectedConfiguration": { "type": "object", "properties": { "isActive": { "type": "boolean" }, "deliveryAddress": { "enum": [ "Plant", "Installer", "Operator" ], "type": "string" }, "emailRecipient": { "enum": [ "Installer", "Operator", "Both" ], "type": "string" } }, "additionalProperties": false, "description": "" }, "Stakeholder": { "type": "object", "properties": { "stakeholderId": { "type": "string", "description": "Id for plantOperator. eventually provide UserId?", "nullable": true, "example": "47149" }, "type": { "enum": [ "Operator", "Installer", "Owner" ], "type": "string", "description": "Type of stakeholder. Available types are operator, installer, owner", "example": "Owner" }, "userId": { "type": "string", "description": "If available the UserId of the stakeholder", "nullable": true, "example": "12345" }, "companyName": { "type": "string", "description": "Name of the company.", "nullable": true, "example": "SMA Solar Technology AG" }, "title": { "type": "string", "description": "The title of the user/stakeholder.", "nullable": true, "example": "Miss" }, "firstName": { "type": "string", "description": "Stakeholder's first name.", "nullable": true, "example": "Jenny" }, "lastName": { "type": "string", "description": "Stakeholder's last name.", "nullable": true, "example": "Miller" }, "country": { "type": "string", "description": "Country where the stakeholder lives in format ISO 3166 ALPHA-2.", "nullable": true, "example": "DE" }, "state": { "type": "string", "description": "State where the stakeholder lives.", "nullable": true, "example": "Hessen" }, "zipCode": { "type": "string", "description": "Zip code where the stakeholder lives.", "nullable": true, "example": "34266" }, "city": { "type": "string", "description": "City where the stakeholder lives.", "nullable": true, "example": "Niestetal" }, "street": { "type": "string", "description": "Street where the stakeholder lives.", "nullable": true, "example": "Sonnenallee" }, "phoneNumber": { "type": "string", "description": "Phone number of the stakeholder.", "nullable": true, "example": "+49 561 9522-0" }, "email": { "type": "string", "description": "eMail of the stakeholder.", "nullable": true, "example": "info@SMA.de" }, "taxId": { "type": "string", "description": "Tax identifier of the stakeholder.", "nullable": true, "example": "MST MXA 90L01 F205 F" }, "contactForService": { "type": "array", "items": { "enum": [ "SmartConnectedInstaller", "SmartConnectedOperator" ], "type": "string", "description": "Smart Connected stakeholder types" }, "description": "Contact role for SMA Smart Connected.", "nullable": true } }, "additionalProperties": false, "description": "Stakeholder of a plant. Stakeholder-types may include the plantOwner, the plantOperator or plantInstaller." }, "StorageData": { "type": "object", "properties": { "usableStorageCapacity": { "type": "number", "description": "Maximum usable energy storage capacity of all existing batteries in Wh.\r\nThe usable storage capacity is influenced by the discharge stop setting and the charge stop setting.\r\nBattery capacity loss due to aging is not taken into account.", "format": "double" }, "maxCapacity": { "type": "number", "description": "Max energy storage capacity (Nameplate Ratings) in Wh. If there is more than one storage device in the system, this is the sum of all device capacities.", "format": "double" }, "maxChargeRate": { "type": "number", "description": "Maximum energy transfer rate received from the storage in W. If the battery inverter energy transfer rate is lower, then limited to this.", "format": "double" }, "maxDischargeRate": { "type": "number", "description": "Maximum energy transfer rate delivered from the storage in W. If the battery inverter energy transfer rate is lower, then limited to this.", "format": "double" } }, "additionalProperties": false, "description": "Battery master data at plant level. If there is more than one battery in the system, these are total values, possibly limited by the limitations of the connected battery inverter, e.g. energy transfer rates. Not supported for classic plants." }, "SubPlant": { "type": "object", "properties": { "subPlantId": { "type": "string", "description": "The sub-plant id. This is the property to be used in the path to retrieve data for a dedicated sub-plant.", "nullable": true, "example": "250561" }, "name": { "type": "string", "description": "Name of the sub-plant. It is a user assigned label.", "nullable": true, "example": "The sub-plant name" }, "description": { "type": "string", "description": "Additional description of a sub-plant. It is a user assigned description.", "nullable": true, "example": "The sub-plant description" }, "timezone": { "type": "string", "description": "Timezone in IANA format.", "nullable": true, "example": "Europe/Berlin" } }, "additionalProperties": false, "description": "The sub-plant resource acts as organizational layer to improve plant management. It enables measurement and balance views for a subset\r\nof plant devices with a single request." }, "SubPlantDevicesResponse": { "type": "object", "properties": { "subPlant": { "$ref": "#/components/schemas/SubPlant" }, "devices": { "type": "array", "items": { "$ref": "#/components/schemas/DeviceInfos" }, "description": "The devices.", "nullable": true } }, "additionalProperties": false, "description": "A sub plant devices response." }, "SubPlantLogsResponse": { "type": "object", "properties": { "subPlant": { "$ref": "#/components/schemas/SubPlant" }, "logs": { "type": "array", "items": { "$ref": "#/components/schemas/Log" }, "description": "Gets the logs.", "nullable": true } }, "additionalProperties": false, "description": "A sub plant logs response." }, "SubPlantResponse": { "type": "object", "properties": { "plant": { "$ref": "#/components/schemas/Plant" }, "subPlant": { "$ref": "#/components/schemas/SubPlant" } }, "additionalProperties": false, "description": "A sub plants response." }, "SubPlantStatus": { "type": "object", "properties": { "subPlantId": { "type": "string", "description": "The sub-plant id. This is the property to be used in the path to retrieve data for a dedicated sub-plant.", "nullable": true, "example": "250561" }, "name": { "type": "string", "description": "Name of the sub-plant. It is a user assigned label.", "nullable": true, "example": "The sub-plant name" }, "description": { "type": "string", "description": "Additional description of a sub-plant. It is a user assigned description.", "nullable": true, "example": "The sub-plant description" }, "timezone": { "type": "string", "description": "Timezone in IANA format.", "nullable": true, "example": "Europe/Berlin" }, "status": { "type": "string", "description": "The status of a sub-plant from uncritical to critical:\r\n\r\nThe status is returned as \"Unknown\" if no status is available.", "nullable": true, "example": "Ok" } }, "additionalProperties": false, "description": "The sub-plant resource acts as organizational layer to improve plant management. It enables measurement and balance views for a subset\r\nof plant devices with a single request." }, "SubPlantStatusResponse": { "type": "object", "properties": { "plant": { "$ref": "#/components/schemas/Plant" }, "subPlant": { "$ref": "#/components/schemas/SubPlantStatus" } }, "additionalProperties": false, "description": "A get sub plant status response." } }, "securitySchemes": { "Bearer": { "type": "apiKey", "description": "The authentication bearer(according to OAuth2) to authenticate itself to the API.", "name": "Authorization", "in": "header" } } }, "security": [ { "Bearer": [ ] } ], "tags": [ { "name": "DeviceManagement", "description": "Provides device setup data and device status." }, { "name": "DeviceMonitoring", "description": "Provides device measurements data and event logs." }, { "name": "PlantGroupManagement", "description": "Provides list of plants assigned to plant-group, plant-group setup data and status." }, { "name": "PlantGroupMonitoring", "description": "Provides event logs of plant-groups." }, { "name": "PlantManagement", "description": "Provides overall plant list, devices assigned to plants, plant setup data and status." }, { "name": "PlantMasterData", "description": "Provides installation, location, stakeholder and configuration data of plants." }, { "name": "PlantMonitoring", "description": "Provides plants measurements data and event logs." }, { "name": "PlantNotifications", "description": "Provides the configured notifications at the plant level." }, { "name": "SubPlantManagement", "description": "Provides sub-plant devices list, sub-plant setup data and status." }, { "name": "SubPlantMonitoring", "description": "Provides sub-plant event logs." } ], "externalDocs": { "description": "Find out more about SMA APIs", "url": "http://developer.sma.de" } }