Reduxi API guides
Connect your own systems to Reduxi: the External API delivers cloud data over HTTPS, the MQTT API gives you direct access to a Reduxi Controller through your MQTT broker.
1 Which API guide do you need?
Reduxi offers two API guides. Use the External API to retrieve data about your controllers, devices, forecasts and prices from the Reduxi cloud. Use the MQTT API to read values from a Reduxi Controller and send it setpoints and commands through your own MQTT broker.
| External API | MQTT API | |
|---|---|---|
| Type | REST API over HTTPS (OpenAPI 3.0) | MQTT messages (version 3.x) on your MQTT broker |
| Data comes from | Reduxi cloud | Reduxi Controller |
| Access | Bearer token | MQTT broker host, port, user name and password, set in the Reduxi Configurator |
| Direction | Retrieves data | Reads data, sends setpoints and commands |
| Use it for | Dashboards, reporting and integrations with controller, device, forecast and price data | Monitoring and controlling a controller in real time |
2 External API (REST)
The External API gives you access to the data of your controllers in the Reduxi cloud. All power and energy values come in base units: W and Wh. Requests are authorized with a Bearer token.
- Controllers: list of controllers, controller details and the latest known status of a controller's devices
- Alarms: active alarms of a controller
- Device data: measurements per device, aggregated measurements per device category and queries across several devices
- Data types: the data types available for a device
- Predictions: forecast data per location or per controller
- Pricing: day-ahead spot market prices, spot market regions and location price lists
3 MQTT API
The MQTT API connects a Reduxi Controller to your MQTT broker. The controller publishes its readouts, device and strategy information to topics, and you send setpoints, commands and settings back through other topics. The current specification is version 1.5 and requires controller software version 20260421084600.
- Controller: identifier, keep-alive, readout and keep-alive intervals, grid settings
- Devices: device list, device information, readouts and setpoints
- Strategies: strategy list, information, readouts, parameters, active status and external EMS settings
- Commands: refresh metadata and reboot
MQTT documentation is generated from the viewpoint of Reduxi Controller.
When you read from Reduxi MQTT, you will see the "PUB" term. Why PUB? Because we publish the data from Reduxi Controller to the topic.
When you set values to Reduxi Controller over MQTT, you will see the "SUB" term. Why SUB? Because we subscribe to the topic and read data from it, setting the values you have sent to the Reduxi Controller.
Sections 4 to 8 show how to set up the Reduxi Configurator so that the controller sends data to your MQTT broker. They end with an example of reading one device and setting its setpoints.
4 MQTT version support
We support the 3. x version. However, we do not support 5. x.
5 MQTT interface configuration
Please login to the Reduxi Controller device and go to the System settings. Under System settings, select MQTT v3 and define MQTT broker data:
- Host (just domain/IP, without mqtts://)
- Port
- Username
- Password
Text description of this image
Screenshot of the Reduxi Configurator page MQTT v3 connection. Left menu under the reduxi CONFIGURATOR logo: Users; Devices; Strategies; System (expanded, minus sign); Identifier; Network; Open VPN; Connector (expanded); Cloud; MQTT v3 (selected, bold); iFlex; Configuration (collapsed, plus sign); Distribution System Operators; Time. Page header: MQTT v3 connection, green link icon at right. Status table: Client: empty; Host: empty; Connected: green tick. Form section Mqtt connection: Host: mqtt.example.com (grey, placeholder style); Port: 1883 (grey); Username: empty; Password: empty; Server CA chain (PEM format): Choose File, No file chosen; Client public certificate (PEM format): Choose File, No file chosen; Client private key (PEM format): Choose File, No file chosen; Readout interval: 5 sec. Buttons: Clear, Save.
6 Windows client (MQTT Explorer)
You could try to collect data by using MQTT Explorer and connecting to the MQTT broker with the following:
You can connect to the MQTT broker when you start an MQTT explorer application.
Text description of this image
Screenshot of MQTT Explorer (top bar: DISCONNECT, search box) with the MQTT Connection dialog open over the dimmed main window. Left list: yellow plus button with label Connections; one saved entry mqtt.example.com with small text mqtt://mqtt.example.com:1883/ (selected). Dialog title: MQTT Connection, with mqtt://mqtt.example.com:1883/ next to it. Fields: Name: mqtt.example.com; Validate certificate: toggle off; Encryption (tls): toggle off; Protocol: mqtt:// (dropdown); Host: mqtt.example.com; Port: 1883; Username: empty; Password: masked with dots, with a show/hide eye icon. Buttons: DELETE, ADVANCED, SAVE (yellow), CONNECT (dark). In the dimmed background, part of the Topic panel and a JSON value with the entries type POWER_ACTIVE, target FIXED, phaseType null is visible.
7 Commands
7.1. Refresh metadata
Request Reduxi to republish all metadata about the system, devices and strategies to MQTT. Otherwise, only readouts and setpoints are published periodically.
Topic: controllers/controller_unit_id/commands/refresh
Text description of this image
Screenshot of MQTT Explorer (status DISCONNECT, search box at top) used to send the refresh command. Left topic tree: e8c1fe29.ala.eu-central-1.emqxsl.com; controllers; ZGFE with keepAlive = 1734965285703; commands with entry refresh; identifier = {"unitId":"ZGFE","unitIdFormatted":"ZGE","boardModel":"REDUXI_1","CPUSerial":"16516642034211ad","EMMCSerial":"4.(cut off); settings; interval: readout = 15000, keepAlive = 60000; devices: 2 with info = {"id":2,"name":"Tesla Wall Connector Gen 3","typeId":59,"type":{"id":59,"categoryId":3,"category":{"id":3,"name":"EV charger","enumeration":"EV_CHARGER"; 4 (1 topic, 2 messages); 12 with info = {"id":12,"name":"Iskraemeco AM550","typeId":16,"type":{"id":16,"categoryId":1,"category":{"id":1,"name":"Energy meter","enumeration":"ENERGY_METER"; 17 (1 topic, 2 messages); 18 (1 topic, 2 messages); strategies: 8 with info = {"id":8,"typeId":7,"type":{"id":7,"name":"1-phase current based ON/OFF regulation","enumeration":"DISCRETE_CURRENT_PHASE_1"}; parameters (3 topics, 12 messages); 20 (2 topics, 8 messages); 27 (selected) with info = {"id":27,"typeId":8,"type":{"id":8,"name":"Energy manager coordinator for PV, EVSE, battery and heat pump","enumeration":"UMBRELLA"}; parameters (1 topic, 4 messages); list = [{"id":8,"typeId":7. Right side: Topic panel (badge 2) with path controllers / ZGFE / strategies / 27; Value panel with History; Publish panel with Topic: controllers/ZGFE/commands/refresh; format raw, xml, json with json selected; empty message body; button PUBLISH with a red arrow pointing at it.
7.2. Reboot
Reboots the Reduxi Controller.
Topic: controllers/controller_unit_id/commands/reboot
Text description of this image
Screenshot of the MQTT Explorer application (status DISCONNECT, search box at top) used to send the reboot command. Left topic tree: $SYS (48 topics, 406 messages); controllers; devices (29 topics, 865 messages); strategies (38 topics, 884 messages); commands (0 topics, 1 message); identifier = {"unitId","unitIdFormatted","CPUSerial":.} (selected row); settings (2 topics, 2 messages); keepAlive = 1675762462861. Right side: a JSON message preview at the top with softwareVersion "20230207091611", hwVersion "0", hasWifiModule false, dso {.}; History: 1. Publish panel with Topic: /controllers/ … /commands/reboot, with a red bracket at the end of the topic field. Format options raw, xml, json: json is selected. The message body is empty. Button PUBLISH is circled in red. QoS: 0; retain: checkbox not ticked.
8 Setpoints
Setpoints control the power or current of a device. The Reduxi Controller publishes the active setpoints of each device, and you set new ones through the matching /set topic.
8.1. View all active setpoints for the device
Topic: controllers/controller_unit_id/devices/device_id/setpoint
Text description of this image
Screenshot of MQTT Explorer (status DISCONNECT, search box at top) showing the setpoint of device 15. Left topic tree: $SYS (48 topics, 862 messages); controllers; devices; 13 (3 topics, 235 messages); 14 (3 topics, 235 messages); 15 expanded with entries readout = {"time":1675762671666,"values":[{"deviceId":15,"dataTypeId":174,"dataTypeEnum":"VOLTAGE_L1"; setpoint = {"deviceId":15,"values":[{"action":"NONE","type":"POWER_ACTIVE","target":"FIXED","phaseType":"L1".} (selected row, marked with a red bracket); info = {"id":15,"name":"Baterija","typeId":14,"type":{"id":14,"name":"Victron Energy MultiPlus II","enumeration":"BATTE; then 18, 8, 9, 10, 11, 12 (3 topics, 233 messages each); list = [{"id":8,"name":"Sončna elektrarna","typeId":7,"type":{"id":7,"name":"SolarEdge","enumeration":"SOLAR_SOLARE; types = [{"id":40,"name":"ABB","enumeration":"CHARGER_ABB"; strategies (38 topics, 2104 messages); commands (0 topics, 1 message); identifier = {"unitId","unitIdFormatted","CPUSerial"; settings (2 topics, 2 messages); keepAlive = 1675762644772. Right side, Topic / controllers / / devices / 15 / setpoint. Value panel, QoS: 0, 02/07/2023 10:37:53 AM, with the formatted-view button circled in red and the JSON value boxed with a red bracket: { "deviceId": 15, "values": [ { "action": "NONE", "type": "POWER_ACTIVE", "target": "FIXED", "phaseType": "L1", "value": 0, "priority": 100, "validForTime": 28571 }, {. (continues). History: 20.
8.2. Set setpoints for the device
Topic: controllers/controller_unit_id/devices/device_id/setpoint/set
Text description of this image
Screenshot of MQTT Explorer (status DISCONNECT, search box at top) used to publish a setpoint for device 15. Left topic tree: $SYS (48 topics, 1192 messages); controllers; devices (highlighted); 13 (3 topics, 341 messages); 14 (3 topics, 341 messages); 15 expanded with readout = {"time":1675762794195,"values":[{"deviceId":15,"dataTypeId":174,"dataTypeEnum":"VOLTAGE_L1"; setpoint = {"deviceId":15,"values":[{"action":"NONE","type":"POWER_ACTIVE","target":"FIXED","phaseType":"L1".} (selected row); info = {"id":15,"name":"Baterija","typeId":14,"type":{"id":14,"name":"Victron Energy MultiPlus II","enumeration":"BATTE; 18 (3 topics, 339 messages); 8 (3 topics, 340 messages, highlighted); 9, 10, 11, 12 (3 topics, 339 messages each); list = [{"id":8,"name":"Sončna elektrarna","typeId":7,"type":{"id":7,"name":"SolarEdge"; types = [{"id":40,"name":"ABB","enumeration":"CHARGER_ABB"; strategies (38 topics, 3062 messages); commands (0 topics, 1 message); identifier = {"unitId","unitIdFormatted","CPUSerial":; settings (2 topics, 2 messages); keepAlive = 1675762764833. Right side: History badge 20, then Publish panel. Topic: /controllers/ … /devices/15/setpoint/set; the topic field is marked with red brackets and the word set is underlined in red. Format raw, xml, json: json selected. Message body, boxed with a red bracket: { "values": [ { "action": "SET", "type": "POWER_ACTIVE", "target": "FIXED", "phaseType": null, "value": 1000, "priority": 10000, "validForTime": 60000 } ] }. Button PUBLISH circled in red. QoS: 0; retain not ticked. A History section is below.
8.2.1. Example 1
Set power active to -1 kW (export) on all phases for 15 seconds.
{
"values": [
{
"action": "SET",
"type": "POWER_ACTIVE",
"target": "FIXED",
"phaseType": null,
"value": 1000,
"priority": 10000,
"validForTime": 15000
}
]
}
8.2.2. Example 2
Limit maximum current to 10A on phase L2 for 30 seconds.
{
"values": [
{
"action": "SET",
"type": "CURRENT",
"target": "MAX",
"phaseType": "L2",
"value": 10,
"priority": 10000,
"validForTime": 30000
}
]
}