buildings_actions_create

POST /public-api/buildings/:uuid/actions/

Send an action to a building.

Set inverter power (percentage)

You can also perform curtailment actions based on power; see "Set inverter power (power)" below for more information.

Warning:

A building's behaviour may vary depending on whether consumption_compensated_curtailment is active for this building. For more information, see the documentation for GET /buildings/

This action may be used to curtail the power output of solar inverters. The use of this action affects all inverters belonging to the specified building..

Basic usage

The minimum required property of a curtailment action is "inverters_set_power_percentage". This property can be used to set the desired power output percentage of an inverter and is effective as soon as possible. The following example will set the targeted inverter's power output to 50%. If no timeout is specified, the power output will stay 50% until a new power output percentage has been set:

{
    "inverters_set_power_percentage": 50
}

Custom timeout

In order to set a timeout, the "inverters_set_power_timeout" property can be added to the curtailment action.

The following example will set the targeted inverter's power output to 50% for a duration of 120 seconds. This duration will be used until you specify a new amount. In this example, the power_timeout will be set to 120 seconds. The timeout will stay 120 seconds for all future requests, until a new amount has been specified again. After the timeout has expired, the power_percentage will default to 100% unless specified differently:

Note: The given timeout must be at least 60 seconds.

{
    "inverters_set_power_percentage": 50
    "inverters_set_power_timeout": 120
}

Custom fallback percentage

When the previous example expires after the specified 120 seconds, the inverters will revert back to outputting 100% power. Sometimes this may not be desirable and users may want their inverters to fall back to a different value after the action has expired.

To achieve this, "inverters_set_power_timeout_percentage" can be added to the curtailment action to provide an alternative fallback value. The following example will set the targeted inverter's power output to 20% for a duration of 75 seconds. After these 75 seconds expire, the inverter will fall back to the specified timeout percentange and output 42% power:

Note: To set the "inverters_set_power_timeout_percentage", "inverters_set_power_timeout" must also be set.

{
    "inverters_set_power_percentage": 20
    "inverters_set_power_timeout": 75
    "inverters_set_power_timeout_percentage": 42
}

Set inverter power (power) (Rollout starting September 2025)

You can also perform curtailment actions based on percentage; see "Set inverter power (percentage)" above for more information.

Warning:

A building's behaviour may vary depending on whether consumption_compensated_curtailment is active for this building. For more information, see the documentation for GET /buildings/

This action may be used to curtail the power output of solar inverters. The use of this action affects all inverters belonging to the specified building..

Basic usage

The minimum required property of a curtailment action is "inverters_set_power_watts". This property can be used to set the desired total power output of all inverters and is effective as soon as possible. The following example will set the target power output to 0 watt. If no timeout is specified, the power output will stay 0 until a new power output has been set:

{
    "inverters_set_power_watts": 0
}

Custom timeout

In order to set a timeout, the "inverters_set_power_timeout" property can be added to the curtailment action.

The following example will set the desired total power output of all inverters to 0 watt for a duration of 120 seconds. This duration will be used until you specify a new amount. In this example, the power timeout will be set to 120 seconds. The timeout will stay 120 seconds for all future requests, until a new amount has been specified again. After the timeout has expired, the power will default to unlimited value unless specified differently:

Note: The given timeout must be at least 60 seconds.

{
    "inverters_set_power_watts": 0
    "inverters_set_power_timeout": 120
}

Custom fallback power

When the previous example expires after the specified 120 seconds, the inverters will revert back to outputting unlimited. Sometimes this may not be desirable and users may want their inverters to fall back to a different value after the action has expired.

To achieve this, "inverters_set_power_timeout_watts" can be added to the curtailment action to provide an alternative fallback value. The following example will set the desired total power output of all inverters to 10.000 watt for a duration of 75 seconds. After these 75 seconds expire, the inverter will fall back to the specified timeout power and output max. 20.000 watt:

Note: To set the "inverters_set_power_timeout_watts", "inverters_set_power_timeout" must also be set.

{
    "inverters_set_power_watts": 10000
    "inverters_set_power_timeout": 75
    "inverters_set_power_timeout_watts": 20000
}

Set battery power

This action may be used to control the power charge and discharge of a battery connected to the specified building.

Charging

In order to specify the amount of power the battery should charge, specify "battery_set_power_charge_watts". A timeout must always be provided for the specified charge amount. This can be done by providing "battery_set_power_timeout" in seconds. This timeout must be at least 60 seconds.

The following example will set the targeted battery's charging power to 10kW for 300 seconds:

{
    "battery_set_power_charge_watts": 10000,
    "battery_set_power_timeout": 300
}

Discharging

In order to specify the amount of power the battery should discharge, specify "battery_set_power_discharge_watts". A timeout must always be provided for the specified charge amount. This can be done by providing "battery_set_power_timeout" in seconds. This timeout must be at least 60 seconds.

The following example will set the targeted battery's discharging power to 10kW for 300 seconds:

{
    "battery_set_power_discharge_watts": 10000,
    "battery_set_power_timeout": 300
}

Note: If the specified amount of battery charge/discharge is higher than what the battery can do at that moment, it will do as much as it can do. For example: If the battery can charge 10000 watts for 300 seconds, but you send the action for 20000 watts in 300 seconds, it will just do 10000 watts.

Disclaimer: If the request gives a 200 OK, it means the action has been received successfully. It does NOT necessarily mean that the action will be executed. The given action is a wish, but depending on the situation it might only be executed partly or not at all.

Update EV Sockets

This action allows users to control the charging power of electric vehicle (EV) sockets connected to the specified building. Users can set the desired charging power and define a timeout for how long this setting will remain active for each individual socket.

Charging

In order to specify the amount of power the EV Socket should charge, specify "ev_socket_set_power_charge_watts". A timeout must always be provided for the specified charge amount. This can be done by providing "ev_socket_set_power_timeout" in seconds. This timeout must be at least 60 seconds.

The following example sets the charging power to 7.2kW (7200 watts) for 300 seconds for the first socket, and 1.5 kw (1500 watts) for 300 seconds for the second socket.

{
    ev_sockets_update": [
       {
           "sensor_uuid": "4aaf2b4f-90f0-438d-81a7-30fa79107e86",
           "ev_socket_set_power_charge_watts": 7200,
           "ev_socket_set_power_timeout": 300
       },
       {
           "sensor_uuid": "99b985e1-7327-4804-8e9b-5f4216403d7d1",
           "ev_socket_set_power_charge_watts": 1500,
           "ev_socket_set_power_timeout": 300
       }
   ]
}

Disclaimer: For optimal use of this endpoint, all EV sockets should be managed. If only one socket is restricted, the available capacity will be utilized by another asset.

Note: If the specified amount of EV Socket charge is higher than what the EV Socket can do at that moment, it will do as much as it can do.

For example: If the EV Socket can charge 10000 watts for 300 seconds, but you send the action for 20000 watts in 300 seconds, it will just do 10000 watts. After the timeout expires, the EV Socket will adjust to the maximum charging power possible based on the conditions at the location.

Update setpoints

This action is only applicable to GBS setpoints and cannot be used for other types of setpoints, such as those for batteries.

A set of setpoints could be provided. A setpoint is a value for a sensor (by uuid), you can get a list of sensors with GET /buildings/{uuid}/sensors/.

fallback_timeout_minutes serves as a kill switch. Once specified, a command must follow within the timeout. If not, the setpoints are set as previously sent.

A minimum command for the kill switch is:

{
    "setpoints_update": {
        "fallback_timeout_minutes": 1440
    }
}

The following command disables the kill switch and does not switch back to a fallback:

{
    "setpoints_update": {
        "fallback_timeout_minutes": 0
    }
}

New fallback values within the fallback_setpoints always overwrite the previous setpoints. The data inside fallback_setpoints is atomic and is overwritten in its entirety. Setpoints that do not need to be changed must still be given, so the list must always be sent in complete.

After the timeout expires, all setpoints defined in the latest fallback_setpoints are set.

Create FCR Planning

This action is used to create an FCR planning for a block of 4 hours. The use of this action affects all batteries belonging to this specific building.

Basic usage

All properties shown below are required to be filled:

{
    "fcr_planning": {
       "power": 500000,
       "start_timestamp": 1710932400
       "stop_timestamp": 1710946800
       "enabled": True
    }
}

power is the awarded FCR power in watts to be delivered during the scheduled period.

start_timestamp is a timestamp in epoch. This is the starting time of the FCR contracted FCR block, for 4 hours. stop_timestamp is a timestamp in epoch. This is the ending time of the FCR contracted FCR block, for 4 hours. The given timestamp must lie in the future, and must be either 00:00, 04:00, 08:00, 12:00, 16:00 or 20:00 in local (Amsterdam) time

enabled is a boolean that indicates if this block is enabled or not. If you have planned a particular FCR block before that should be canceled, you sent the same action again but with enabled on False.

To overwrite actions with new values, sent a new action with the same start_timestamp.

Request

Responses

No Content

buildings_actions_create

/public-api/buildings/:uuid/actions/

Set inverter power (percentage)

Warning:

Basic usage

Custom timeout

Custom fallback percentage

Set inverter power (power) (Rollout starting September 2025)

Warning:

Basic usage

Custom timeout

Custom fallback power

Set battery power

Charging

Discharging

Update EV Sockets

Charging

Update setpoints

Create FCR Planning

Basic usage

Request​

Responses​

Request

Responses