2024.11.0
Home ▸ Integrations ▸

RESTful Command

This integrationIntegrations connect and integrate Home Assistant with your devices, services, and more. [Learn more] can expose regular REST commands as actions. Actions can be called from a script or in automation.

To use this integrationIntegrations connect and integrate Home Assistant with your devices, services, and more. [Learn more], add the following lines to your configuration.yamlThe configuration.yaml file is the main configuration file for Home Assistant. It lists the integrations to be loaded and their specific configurations. In some cases, the configuration needs to be edited manually directly in the configuration.yaml file. Most integrations can be configured in the UI. [Learn more] file. After changing the configuration.yamlThe configuration.yaml file is the main configuration file for Home Assistant. It lists the integrations to be loaded and their specific configurations. In some cases, the configuration needs to be edited manually directly in the configuration.yaml file. Most integrations can be configured in the UI. [Learn more] file, restart Home Assistant to apply the changes.

# Example configuration.yaml entry
rest_command:
  example_request:
    url: "http://example.com/"

Configuration Variables

Looking for your configuration file?
service_name map Required

The name used to expose the action. E.g., in the above example, it would be ‘rest_command.example_request’.

url template Required

The URL (supports template) for sending request.

method string (Optional, default: get)

HTTP method to use (get, patch, post, put, or delete).

headers map (Optional)

The headers for the requests.

payload template (Optional)

A string/template to send with request.

username string (Optional)

The username for basic HTTP authentication (digest is not supported).

password string (Optional)

The password for basic HTTP authentication (digest is not supported).

timeout string (Optional, default: 10)

Timeout for requests in seconds.

content_type string (Optional)

Content type for the request.

verify_ssl boolean (Optional, default: true)

Verify the SSL certificate of the endpoint.

Examples

Basic example which uses PUT method and payload encoded as form data

This example implements 2 REST commands to add actions for the missing shuffle functionality of the iTunes integration.

rest_command:
  shuffle_on: 
    url: "http://YOUR_ITUNES-API_SERVER_IP:8181/shuffle"
    method: put
    content_type: "application/x-www-form-urlencoded"
    payload: "mode=songs"
  shuffle_off: 
    url: "http://YOUR_ITUNES-API_SERVER_IP:8181/shuffle"
    method: put
    content_type: "application/x-www-form-urlencoded"
    payload: "mode=off"

Using REST command Response in automations

REST commands provide an action response in a dictionary containing status (containing the HTTP response code) and content containing the response body as text or JSON. This response can be accessed in automations using response_variable.

The following example shows how the REST command response may be used in automations. In this case, checking the Traefik API for errors.

# Create a ToDo notification based on file contents
automation:
  - alias: "Check API response"
    triggers:
      - ...
    actions:
      - action: rest_command.traefik_get_rawdata
        response_variable: traefik_response
      - if: "{{ traefik_response['status'] == 200 }}"
        then:
          - alias: "Parse data"
            variables:
              routers: "{{ traefik_response['content']['routers'] }}"
              router_errors: >
                {%- for router in routers -%}
                  {%- if 'error' in routers[router] -%}
                    {{router}}: {{ routers[router]['error'] }}
                  {% endif -%}
                {%- endfor -%}
              got_errors: "{{ router_errors|length > 0 }}"
          - if: "{{ got_errors }}"
            then:
              - action: notify.mobile_app_iphone
                data:
                  title: "Traefik errors"
                  message: "{{ router_errors }}"
        else:
          - action: notify.mobile_app_iphone
            data:
              title: "Could not reach Traefik"
              message: "HTTP code: {{ traefik_response['returncode'] }}"

rest_command:
  traefik_get_rawdata:
    url: http://127.0.0.1:8080/api/rawdata
    method: GET

Using templates to change the payload based on entities

The commands can be dynamic, using templates to insert values of other entities. Actions support variables for doing things with templates.

In this example, uses templates for dynamic parameters.

# Example configuration.yaml entry
rest_command:
  my_request:
    url: https://slack.com/api/users.profile.set
    method: POST
    headers:
      authorization: !secret rest_headers_secret
      accept: "application/json, text/html"
      user-agent: 'Mozilla/5.0 {{ useragent }}'
    payload: '{"profile":{"status_text": "{{ status }}","status_emoji": "{{ emoji }}"}}'
    content_type:  'application/json; charset=utf-8'
    verify_ssl: true

How to test your new REST command

Call the new action from developer tools in the sidebar with some data like:

{
  "status":"My Status Goes Here",
  "emoji":":plex:"
}

Using a REST command as an action in an automation 

automation:
- alias: "Arrive at Work"
  triggers:
    - trigger: zone
      entity_id: device_tracker.my_device
      zone: zone.work
      event: enter
  actions:
    - action: rest_command.my_request
      data:
        status: "At Work"
        emoji: ":calendar:"