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-16 13:56:29 +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.
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`:
```shell
curl -X GET \
-H "Authorization: Bearer ABCDEFGH" \
curl \
-H "Authorization: Bearer TOKEN" \
-H "Content-Type: application/json" \
http://IP_ADDRESS:8123/ENDPOINT
```
@ -30,7 +30,7 @@ from requests import get
url = "http://localhost:8123/ENDPOINT"
headers = {
"Authorization": "Bearer ABCDEFGH",
"Authorization": "Bearer TOKEN",
"content-type": "application/json",
}
@ -45,7 +45,7 @@ turn_light_on:
url: http://localhost:8123/api/states/light.study_light
method: POST
headers:
authorization: 'Bearer ABCDEFGH'
authorization: 'Bearer TOKEN'
content-type: 'application/json'
payload: '{"state":"on"}'
```
@ -74,7 +74,8 @@ Returns a message if the API is up and running.
Sample `curl` command:
```shell
curl -X GET -H "Authorization: Bearer ABCDEFGH" \
curl \
-H "Authorization: Bearer TOKEN" \
-H "Content-Type: application/json" http://localhost:8123/api/
```
@ -128,7 +129,8 @@ Returns the current configuration as JSON.
Sample `curl` command:
```shell
curl -X GET -H "Authorization: Bearer ABCDEFGH" \
curl \
-H "Authorization: Bearer TOKEN" \
-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:
```shell
curl -X GET -H "Authorization: Bearer ABCDEFGH" \
curl \
-H "Authorization: Bearer TOKEN" \
-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:
```shell
curl -X GET -H "Authorization: Bearer ABCDEFGH" \
curl \
-H "Authorization: Bearer TOKEN" \
-H "Content-Type: application/json" http://localhost:8123/api/services
```
@ -274,27 +278,31 @@ Example with `minimal_response`
Sample `curl` commands:
```shell
curl -X GET -H "Authorization: Bearer ABCDEFGH" \
curl \
-H "Authorization: Bearer TOKEN" \
-H "Content-Type: application/json" \
http://localhost:8123/api/history/period/2016-12-29T00:00:00+02:00
```
```shell
curl -X GET -H "Authorization: Bearer ABCDEFGH" \
curl \
-H "Authorization: Bearer TOKEN" \
-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
curl -X GET -H "Authorization: Bearer ABCDEFGH" \
curl \
-H "Authorization: Bearer TOKEN" \
-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
curl -X GET -H "Authorization: Bearer ABCDEFGH" \
curl \
-H "Authorization: Bearer TOKEN" \
-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>
@ -343,21 +351,24 @@ Example
Sample `curl` commands:
```shell
curl -X GET -H "Authorization: Bearer ABCDEFGH" \
curl \
-H "Authorization: Bearer TOKEN" \
-H "Content-Type: application/json" \
http://localhost:8123/api/logbook/2016-12-29T00:00:00+02:00
```
```shell
curl -X GET -H "Authorization: Bearer ABCDEFGH" \
curl \
-H "Authorization: Bearer TOKEN" \
-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
curl -X GET -H "Authorization: Bearer ABCDEFGH" \
curl \
-H "Authorization: Bearer TOKEN" \
-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>
@ -386,7 +397,8 @@ Returns an array of state objects. Each state has the following attributes: `ent
Sample `curl` command:
```shell
curl -X GET -H "Authorization: Bearer ABCDEFGH" \
curl \
-H "Authorization: Bearer TOKEN" \
-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:
```shell
curl -X GET -H "Authorization: Bearer ABCDEFGH" \
curl \
-H "Authorization: Bearer TOKEN" \
-H "Content-Type: application/json" \
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:
```shell
curl -X GET -H "Authorization: Bearer ABCDEFGH" \
curl \
-H "Authorization: Bearer TOKEN" \
-H "Content-Type: application/json" \
http://localhost:8123/api/error_log
```
@ -449,9 +463,11 @@ Returns the data (image) from the specified camera `entity_id`.
Sample `curl` command:
```shell
curl -X GET -H "Authorization: Bearer ABCDEFGH" \
curl \
-H "Authorization: Bearer TOKEN" \
-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>
@ -477,7 +493,8 @@ Returns the list of calendar entities.
Sample `curl` command:
```shell
curl -X GET -H "Authorization: Bearer ABCDEFGH" \
curl \
-H "Authorization: Bearer TOKEN" \
-H "Content-Type: application/json" \
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:
```shell
curl -X GET -H "Authorization: Bearer ABCDEFGH" \
curl \
-H "Authorization: Bearer TOKEN" \
-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>
@ -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:
```shell
curl -X POST -H "Authorization: Bearer ABCDEFGH" \
curl \
-H "Authorization: Bearer TOKEN" \
-H "Content-Type: application/json" \
-d '{"state": "25", "attributes": {"unit_of_measurement": "°C"}}' \
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
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"}}
response = post(url, headers=headers, json=data)
@ -641,7 +660,8 @@ Sample `curl` commands:
Turn the light on:
```shell
curl -X POST -H "Authorization: Bearer ABCDEFGH" \
curl \
-H "Authorization: Bearer TOKEN" \
-H "Content-Type: application/json" \
-d '{"entity_id": "switch.christmas_lights"}' \
http://localhost:8123/api/services/switch/turn_on
@ -655,7 +675,7 @@ Turn the light on:
from requests import post
url = "http://localhost:8123/api/services/light/turn_on"
headers = {"Authorization": "Bearer ABCDEFGH"}
headers = {"Authorization": "Bearer TOKEN"}
data = {"entity_id": "light.study_light"}
response = post(url, headers=headers, json=data)
@ -665,9 +685,9 @@ print(response.text)
Send an MQTT message:
```shell
curl -X POST \
curl \
-H "Content-Type: application/json" \
-H "Authorization: Bearer ABCDEFGH" \
-H "Authorization: Bearer TOKEN" \
-d '{"payload": "OFF", "topic": "home/fridge", "retain": "True"}' \
http://localhost:8123/api/services/mqtt/publish
```
@ -697,7 +717,8 @@ Paulus is at work!
Sample `curl` command:
```shell
curl -X POST -H "Authorization: Bearer ABCDEFGH" \
curl \
-H "Authorization: Bearer TOKEN" \
-H "Content-Type: application/json" \
-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:
```shell
curl -X POST -H "Authorization: Bearer ${TOKEN}" \
curl \
-H "Authorization: Bearer TOKEN" \
-H 'Content-Type: application/json' \
-d '{ "name": "SetTimer", "data": { "seconds": "30" } }' \
http://localhost:8123/api/intent/handle