REST API

Home Assistant provides a RESTful API on the same port as the web frontend. (default port is port 8123).

If you are not using the frontend in your setup then you need to add the api component to your configuration.yaml file.

http://IP_ADDRESS:8123/ is an interface to control Home Assistant.
http://IP_ADDRESS:8123/api/ is a RESTful API.

The API accepts and returns only JSON encoded objects.

All API calls have to be accompanied by the header Authorization: Bearer ABCDEFGH, where ABCDEFGH is replaced by your token. You can obtain a token ("Long-Lived Access Token") by logging into the frontend using a web browser, and going to your profile http://IP_ADDRESS:8123/profile.

There are multiple ways to consume the Home Assistant Rest API. One is with curl:

curl -X GET \
 -H "Authorization: Bearer ABCDEFGH" \
 -H "Content-Type: application/json" \
 http://IP_ADDRESS:8123/ENDPOINT

Another option is to use Python and the Requests module.

from requests import get

url = "http://localhost:8123/ENDPOINT"
headers = {
 "Authorization": "Bearer ABCDEFGH",
 "content-type": "application/json",
}

response = get(url, headers=headers)
print(response.text)

Another option is to use the Restful Command integration in a Home Assistant automation or script.

turn_light_on:
 url: http://localhost:8123/api/states/light.study_light
 method: POST
 headers:
 authorization: 'Bearer ABCDEFGH'
 content-type: 'application/json'
 payload: '{"state":"on"}'

Successful calls will return status code 200 or 201. Other status codes that can return are:

400 (Bad Request)
401 (Unauthorized)
404 (Not Found)
405 (Method not allowed)

Actions#

The API supports the following actions:

get

/api/

🔒

get

/api/config

🔒

get

/api/discovery_info

🔓

get

/api/events

🔒

get

/api/services

🔒

get

/api/history/period/<timestamp>

🔒

get

/api/logbook/<timestamp>

🔒

get

/api/states

🔒

get

/api/states/<entity_id>

🔒

get

/api/error_log

🔒

get

/api/camera_proxy/<camera entity_id>

🔒

post

/api/states/<entity_id>

🔒

post

/api/events/<event_type>

🔒

post

/api/services/<domain>/<service>

🔒

post

/api/template

🔒

post

/api/config/core/check_config

🔒