RESTful Switch

The rest switch platform allows you to control a given endpoint that supports a RESTful API. The switch can get the state via GET and set the state via POST on a given REST resource.

To enable this switch, add the following lines to your configuration.yaml file:

# Example configuration.yaml entry
  - platform: rest
    resource: http://IP_ADDRESS/ENDPOINT

Configuration variables:

  • resource (Required): The resource or endpoint that contains the value.
  • name (Optional): Name of the REST switch.
  • method (Optional): HTTP method to use (post or put). Defaults to post.
  • username (Optional): The username for accessing the REST endpoint.
  • password (Optional): The password for accessing the REST endpoint.
  • body_on (Optional): The body of the POST request that commands the switch to become enabled. Default is “ON”. This value can be a template.
  • body_off (Optional): The body of the POST request that commands the switch to become disabled. Default is “OFF”. This value can also be a template.
  • is_on_template (Optional): A template that determines the state of the switch from the value returned by the GET request on the resource URL. This template should compute to a boolean (True or False). If the value is valid JSON, it will be available in the template as the variable value_json. Default is equivalent to '{{ value_json == body_on }}'. This means that by default, the state of the switch is on if and only if the response to the GET request matches .

Make sure that the URL matches exactly your endpoint or resource.


Switch with templated value

This example shows a switch that uses a template to allow Home Assistant to determine its state. In this example the REST endpoint returns this JSON response with true indicating the switch is on.

{"is_active": "true"}
  - platform: rest
    resource: http://IP_ADDRESS/led_endpoint
    body_on: '{"active": "true"}'
    body_off: '{"active": "false"}'
    is_on_template: '{{value_json.is_active}}'

body_on and body_off can also depend on the state of the system. For example, to enable a remote temperature sensor tracking on a radio thermostat, one has to send the current value of the remote temperature sensor. This can be achieved by using the template '{"rem_temp":{{states.sensor.bedroom_temp.state}}}'.