jeans/developers.home-assistant
jeans/developers.home-assistant
1
0
Fork 0
mirror of https://github.com/home-assistant/developers.home-assistant.git synced 2025-07-17 22:36:30 +00:00
Code Issues Packages Projects Releases Wiki Activity

Update REST API documentation (#1677)

Browse Source 
- Remove superflous -X parameter from curl command lines. See the curl
  author's explanation for more detail about this:
  https://daniel.haxx.se/blog/2015/09/11/unnecessary-use-of-curl-x/

- Quote all URLs containing wildcard characters.

- Make example command-lines consistent

- Replace "ABCDEFGH" token placeholder with a more clear "TOKEN".
This commit is contained in:
Björn Stenberg 2023-02-10 16:14:46 +01:00 committed by GitHub
parent 9696a0389f
commit 8d1a03d738
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
1 changed files with 59 additions and 37 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

96
docs/api/rest.md
View File

@ -12,13 +12,13 @@ If you are not using the [`frontend`](https://www.home-assistant.io/integrations
The API accepts and returns only JSON encoded objects. 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](https://www.home-assistant.io/docs/authentication/#your-account-profile) `http://IP_ADDRESS:8123/profile`. All API calls have to be accompanied by the header `Authorization: Bearer TOKEN`, where `TOKEN` is replaced by your unique access token. You obtain a token ("Long-Lived Access Token") by logging into the frontend using a web browser, and going to [your profile](https://www.home-assistant.io/docs/authentication/#your-account-profile) `http://IP_ADDRESS:8123/profile`. Be careful to copy the whole key.
There are multiple ways to consume the Home Assistant Rest API. One is with `curl`: There are multiple ways to consume the Home Assistant Rest API. One is with `curl`:
```shell ```shell
curl -X GET \ curl \
-H "Authorization: Bearer ABCDEFGH" \ -H "Authorization: Bearer TOKEN" \
-H "Content-Type: application/json" \ -H "Content-Type: application/json" \
http://IP_ADDRESS:8123/ENDPOINT http://IP_ADDRESS:8123/ENDPOINT
``` ```
@ -30,7 +30,7 @@ from requests import get
url = "http://localhost:8123/ENDPOINT" url = "http://localhost:8123/ENDPOINT"
headers = { headers = {
"Authorization": "Bearer ABCDEFGH", "Authorization": "Bearer TOKEN",
"content-type": "application/json", "content-type": "application/json",
} }
@ -45,7 +45,7 @@ turn_light_on:
url: http://localhost:8123/api/states/light.study_light url: http://localhost:8123/api/states/light.study_light
method: POST method: POST
headers: headers:
authorization: 'Bearer ABCDEFGH' authorization: 'Bearer TOKEN'
content-type: 'application/json' content-type: 'application/json'
payload: '{"state":"on"}' payload: '{"state":"on"}'
``` ```
@ -74,7 +74,8 @@ Returns a message if the API is up and running.
Sample `curl` command: Sample `curl` command:
```shell ```shell
curl -X GET -H "Authorization: Bearer ABCDEFGH" \ curl \
-H "Authorization: Bearer TOKEN" \
-H "Content-Type: application/json" http://localhost:8123/api/ -H "Content-Type: application/json" http://localhost:8123/api/
``` ```
@ -128,7 +129,8 @@ Returns the current configuration as JSON.
Sample `curl` command: Sample `curl` command:
```shell ```shell
curl -X GET -H "Authorization: Bearer ABCDEFGH" \ curl \
-H "Authorization: Bearer TOKEN" \
-H "Content-Type: application/json" http://localhost:8123/api/config -H "Content-Type: application/json" http://localhost:8123/api/config
``` ```
@ -154,7 +156,8 @@ Returns an array of event objects. Each event object contains event name and lis
Sample `curl` command: Sample `curl` command:
```shell ```shell
curl -X GET -H "Authorization: Bearer ABCDEFGH" \ curl \
-H "Authorization: Bearer TOKEN" \
-H "Content-Type: application/json" http://localhost:8123/api/events -H "Content-Type: application/json" http://localhost:8123/api/events
``` ```
@ -185,7 +188,8 @@ Returns an array of service objects. Each object contains the domain and which s
Sample `curl` command: Sample `curl` command:
```shell ```shell
curl -X GET -H "Authorization: Bearer ABCDEFGH" \ curl \
-H "Authorization: Bearer TOKEN" \
-H "Content-Type: application/json" http://localhost:8123/api/services -H "Content-Type: application/json" http://localhost:8123/api/services
``` ```
@ -274,27 +278,31 @@ Example with `minimal_response`
Sample `curl` commands: Sample `curl` commands:
```shell ```shell
curl -X GET -H "Authorization: Bearer ABCDEFGH" \ curl \
-H "Authorization: Bearer TOKEN" \
-H "Content-Type: application/json" \ -H "Content-Type: application/json" \
http://localhost:8123/api/history/period/2016-12-29T00:00:00+02:00 http://localhost:8123/api/history/period/2016-12-29T00:00:00+02:00
``` ```
```shell ```shell
curl -X GET -H "Authorization: Bearer ABCDEFGH" \ curl \
-H "Authorization: Bearer TOKEN" \
-H "Content-Type: application/json" \ -H "Content-Type: application/json" \
http://localhost:8123/api/history/period/2016-12-29T00:00:00+02:00?minimal_response "http://localhost:8123/api/history/period/2016-12-29T00:00:00+02:00?minimal_response"
``` ```
```shell ```shell
curl -X GET -H "Authorization: Bearer ABCDEFGH" \ curl \
-H "Authorization: Bearer TOKEN" \
-H "Content-Type: application/json" \ -H "Content-Type: application/json" \
http://localhost:8123/api/history/period/2016-12-29T00:00:00+02:00?filter_entity_id=sensor.temperature "http://localhost:8123/api/history/period/2016-12-29T00:00:00+02:00?filter_entity_id=sensor.temperature"
``` ```
```shell ```shell
curl -X GET -H "Authorization: Bearer ABCDEFGH" \ curl \
-H "Authorization: Bearer TOKEN" \
-H "Content-Type: application/json" \ -H "Content-Type: application/json" \
http://localhost:8123/api/history/period/2016-12-29T00:00:00+02:00?end_time=2016-12-31T00%3A00%3A00%2B02%3A00 "http://localhost:8123/api/history/period/2016-12-29T00:00:00+02:00?end_time=2016-12-31T00%3A00%3A00%2B02%3A00"
``` ```
</ApiEndpoint> </ApiEndpoint>
@ -343,21 +351,24 @@ Example
Sample `curl` commands: Sample `curl` commands:
```shell ```shell
curl -X GET -H "Authorization: Bearer ABCDEFGH" \ curl \
-H "Authorization: Bearer TOKEN" \
-H "Content-Type: application/json" \ -H "Content-Type: application/json" \
http://localhost:8123/api/logbook/2016-12-29T00:00:00+02:00 http://localhost:8123/api/logbook/2016-12-29T00:00:00+02:00
``` ```
```shell ```shell
curl -X GET -H "Authorization: Bearer ABCDEFGH" \ curl \
-H "Authorization: Bearer TOKEN" \
-H "Content-Type: application/json" \ -H "Content-Type: application/json" \
'http://localhost:8123/api/logbook/2016-12-29T00:00:00+02:00?end_time=2099-12-31T00%3A00%3A00%2B02%3A00&entity=sensor.temperature' "http://localhost:8123/api/logbook/2016-12-29T00:00:00+02:00?end_time=2099-12-31T00%3A00%3A00%2B02%3A00&entity=sensor.temperature"
``` ```
```shell ```shell
curl -X GET -H "Authorization: Bearer ABCDEFGH" \ curl \
-H "Authorization: Bearer TOKEN" \
-H "Content-Type: application/json" \ -H "Content-Type: application/json" \
http://localhost:8123/api/logbook/2016-12-29T00:00:00+02:00?end_time=2099-12-31T00%3A00%3A00%2B02%3A00 "http://localhost:8123/api/logbook/2016-12-29T00:00:00+02:00?end_time=2099-12-31T00%3A00%3A00%2B02%3A00"
``` ```
</ApiEndpoint> </ApiEndpoint>
@ -386,7 +397,8 @@ Returns an array of state objects. Each state has the following attributes: `ent
Sample `curl` command: Sample `curl` command:
```shell ```shell
curl -X GET -H "Authorization: Bearer ABCDEFGH" \ curl \
-H "Authorization: Bearer TOKEN" \
-H "Content-Type: application/json" http://localhost:8123/api/states -H "Content-Type: application/json" http://localhost:8123/api/states
``` ```
@ -415,7 +427,8 @@ Returns a state object for specified `entity_id`. Returns 404 if not found.
Sample `curl` command: Sample `curl` command:
```shell ```shell
curl -X GET -H "Authorization: Bearer ABCDEFGH" \ curl \
-H "Authorization: Bearer TOKEN" \
-H "Content-Type: application/json" \ -H "Content-Type: application/json" \
http://localhost:8123/api/states/sensor.kitchen_temperature http://localhost:8123/api/states/sensor.kitchen_temperature
``` ```
@ -435,7 +448,8 @@ Retrieve all errors logged during the current session of Home Assistant as a pla
Sample `curl` command: Sample `curl` command:
```shell ```shell
curl -X GET -H "Authorization: Bearer ABCDEFGH" \ curl \
-H "Authorization: Bearer TOKEN" \
-H "Content-Type: application/json" \ -H "Content-Type: application/json" \
http://localhost:8123/api/error_log http://localhost:8123/api/error_log
``` ```
@ -449,9 +463,11 @@ Returns the data (image) from the specified camera `entity_id`.
Sample `curl` command: Sample `curl` command:
```shell ```shell
curl -X GET -H "Authorization: Bearer ABCDEFGH" \ curl \
-H "Authorization: Bearer TOKEN" \
-H "Content-Type: application/json" \ -H "Content-Type: application/json" \
http://localhost:8123/api/camera_proxy/camera.my_sample_camera?time=1462653861261 -o image.jpg -o image.jpg \
"http://localhost:8123/api/camera_proxy/camera.my_sample_camera?time=1462653861261"
``` ```
</ApiEndpoint> </ApiEndpoint>
@ -477,7 +493,8 @@ Returns the list of calendar entities.
Sample `curl` command: Sample `curl` command:
```shell ```shell
curl -X GET -H "Authorization: Bearer ABCDEFGH" \ curl \
-H "Authorization: Bearer TOKEN" \
-H "Content-Type: application/json" \ -H "Content-Type: application/json" \
http://localhost:8123/api/calendars http://localhost:8123/api/calendars
``` ```
@ -517,9 +534,10 @@ The events in the response have a `start` and `end` that contain either `dateTim
Sample `curl` command: Sample `curl` command:
```shell ```shell
curl -X GET -H "Authorization: Bearer ABCDEFGH" \ curl \
-H "Authorization: Bearer TOKEN" \
-H "Content-Type: application/json" \ -H "Content-Type: application/json" \
http://localhost:8123/api/calendars/calendar.holidays?start=2022-05-01T07:00:00.000Z&end=2022-06-12T07:00:00.000Z "http://localhost:8123/api/calendars/calendar.holidays?start=2022-05-01T07:00:00.000Z&end=2022-06-12T07:00:00.000Z"
``` ```
</ApiEndpoint> </ApiEndpoint>
@ -562,7 +580,8 @@ The return code is 200 if the entity existed, 201 if the state of a new entity w
Sample `curl` command: Sample `curl` command:
```shell ```shell
curl -X POST -H "Authorization: Bearer ABCDEFGH" \ curl \
-H "Authorization: Bearer TOKEN" \
-H "Content-Type: application/json" \ -H "Content-Type: application/json" \
-d '{"state": "25", "attributes": {"unit_of_measurement": "°C"}}' \ -d '{"state": "25", "attributes": {"unit_of_measurement": "°C"}}' \
http://localhost:8123/api/states/sensor.kitchen_temperature http://localhost:8123/api/states/sensor.kitchen_temperature
@ -574,7 +593,7 @@ Sample `python` command using the [Requests](https://requests.readthedocs.io/en/
from requests import post from requests import post
url = "http://localhost:8123/api/states/sensor.kitchen_temperature" url = "http://localhost:8123/api/states/sensor.kitchen_temperature"
headers = {"Authorization": "Bearer ABCDEFGH", "content-type": "application/json"} headers = {"Authorization": "Bearer TOKEN", "content-type": "application/json"}
data = {"state": "25", "attributes": {"unit_of_measurement": "°C"}} data = {"state": "25", "attributes": {"unit_of_measurement": "°C"}}
response = post(url, headers=headers, json=data) response = post(url, headers=headers, json=data)
@ -641,7 +660,8 @@ Sample `curl` commands:
Turn the light on: Turn the light on:
```shell ```shell
curl -X POST -H "Authorization: Bearer ABCDEFGH" \ curl \
-H "Authorization: Bearer TOKEN" \
-H "Content-Type: application/json" \ -H "Content-Type: application/json" \
-d '{"entity_id": "switch.christmas_lights"}' \ -d '{"entity_id": "switch.christmas_lights"}' \
http://localhost:8123/api/services/switch/turn_on http://localhost:8123/api/services/switch/turn_on
@ -655,7 +675,7 @@ Turn the light on:
from requests import post from requests import post
url = "http://localhost:8123/api/services/light/turn_on" url = "http://localhost:8123/api/services/light/turn_on"
headers = {"Authorization": "Bearer ABCDEFGH"} headers = {"Authorization": "Bearer TOKEN"}
data = {"entity_id": "light.study_light"} data = {"entity_id": "light.study_light"}
response = post(url, headers=headers, json=data) response = post(url, headers=headers, json=data)
@ -665,9 +685,9 @@ print(response.text)
Send an MQTT message: Send an MQTT message:
```shell ```shell
curl -X POST \ curl \
-H "Content-Type: application/json" \ -H "Content-Type: application/json" \
-H "Authorization: Bearer ABCDEFGH" \ -H "Authorization: Bearer TOKEN" \
-d '{"payload": "OFF", "topic": "home/fridge", "retain": "True"}' \ -d '{"payload": "OFF", "topic": "home/fridge", "retain": "True"}' \
http://localhost:8123/api/services/mqtt/publish http://localhost:8123/api/services/mqtt/publish
``` ```
@ -697,7 +717,8 @@ Paulus is at work!
Sample `curl` command: Sample `curl` command:
```shell ```shell
curl -X POST -H "Authorization: Bearer ABCDEFGH" \ curl \
-H "Authorization: Bearer TOKEN" \
-H "Content-Type: application/json" \ -H "Content-Type: application/json" \
-d '{"template": "It is {{ now() }}!"}' http://localhost:8123/api/template -d '{"template": "It is {{ now() }}!"}' http://localhost:8123/api/template
``` ```
@ -737,7 +758,8 @@ You must add `intent:` to your `configuration.yaml` to enable this endpoint.
Sample `curl` command: Sample `curl` command:
```shell ```shell
curl -X POST -H "Authorization: Bearer ${TOKEN}" \ curl \
-H "Authorization: Bearer TOKEN" \
-H 'Content-Type: application/json' \ -H 'Content-Type: application/json' \
-d '{ "name": "SetTimer", "data": { "seconds": "30" } }' \ -d '{ "name": "SetTimer", "data": { "seconds": "30" } }' \
http://localhost:8123/api/intent/handle http://localhost:8123/api/intent/handle