5.4.3 api switch ctrl

The /api/switch/ctrl is used for control of switches. 

Service and Privileges Groups

  • Service group is Switch.

  • Privileges group is Switch Access Control.


  • GET

  • POST


The request contains parameters in the URL (or in the application/x-www-form-urlencoded format when POST is used).

Table 1. Request Parameters
Parameter NameMandatoryExpected ValuesDefault ValueDescription



Integer defining a switch (typically 1 to 4)

Defines which switch will be controlled. api/switch/caps can be used for obtaining the number of switches of a particular device.



String defining the command

Defines which command will be applied to the switch. The available commands are:

  • on - activate switch

  • off - deactivate switch

  • trigger - activate monostable switch, toggle the state of bistable switch

  • lock - lock switch (locked switch is deactivated and cannot be operated)

  • unlock - unlock switch (allow normal operation)

  • hold - hold switch activated (held switch is activated and cannot be operated), if the switch is locked and held together it is deactivated

  • release - release the switch from being held (allow normal operation)



String defining a text that is to be returned instead of standard JSON response

The device will return the text specified in this parameter instead of a standard JSON response.



(used when action=hold)

Range of 1–86 400 seconds

Defines the timeout in seconds after which the switch releases again automatically after receiving the hold command.

Example of a Request



The success response is in the application/json format (unless a custom text response is defined in the response parameter).

Table 2. Response JSON Keys
KeyTypical Returned ValuesDescription


true or false

When a command was performed successfully, the success value is true, and it is false when the requested switch state could not be reached (e.g. the switch is locked and the requested state is activated switch).

Example of a Response

{ "success": true }

Additional error information is contained in the response when the success is false. Error code 14 "action failed" is returned when the requested result could not be achieved (e.g. when the switch is locked and action=on is requested). A command to change the operation type (i.e. held, locked) will always succeed since the operation can be changed all the time except when the switch is disabled (a device will return error 14 to all commands when the switch is disabled).