Home Assistant – control/read entities via Restful API

1. JQ and Curl are needed for this tutorial !
Note for windows users: Make sure Curl is installed ! It should be installed on newer windows versions,
in case you don’t have it, head over to https://curl.se/windows (On linux / MacOS, it is installed by default)
Also, you will need jq (for Windows / MacOS / Linux) , you can find it on https://stedolan.github.io/jq/download/

2. Read entities and attributes
In this example, we are going to read the state of an entity:

curl -s -X GET -H "Authorization: Bearer XXX" -H "Content-type:application/json" http://HA_IP:8123/api/states/switch.switch_14 > result.txt

this is a command-line that returns the state of switch_14 in JSON and put it in a file called result.txt
* XXX needs to be replaced by a long-live token (this can be generated from within HA: http://HA_IP:8123/profile
on the bottom click “generate token” and copy the result over the XXX)
* HA_IP needs to be replaced by the IP-address (or DNS name) of your HA instance.
* switch.switch_14 can be replaced by your own enitity that you want to read.
* result.txt can be replaced by a name of your likings.

You will find something like underneath in the result file.
This is pure JSON, so you can parse/filter it with any regular Json library.

{"entity_id":"switch.switch_14","state":"on","attributes":{"friendly_name":"desk switch","assumed_state":false},"last_changed":"2023-01-02T13:19:25.286369+00:00","last_updated":"2023-01-02T13:19:25.286369+00:00","context":{"id":"09GNSA61XAWSTCDDN9BBBB9BBB","parent_id":null,"user_id":"99910e56f76f999db74afe1db9f2f999"}}

If you want to read a specific json-tag, and only put this data in the result.txt, you can use the jq command
(jq is a json parser). use a |sign (pipe), followed by the jq and corresponding syntax.
In the example underneath, you only get the state of the switch

curl -s -X GET -H "Authorization: Bearer XXX" -H "Content-type:application/json" http://HA_IP:8123/api/states/switch.switch_14 | jq -r .state > result.txt

When you want to retrieve a sub-attribute (user_id for example), you need to ask for .context.user_id instead of state
Take care of the dot before context ! Sub-attributes are inside extra { } brackets (following the JSON specifications)
id , parent_id and user_id are here sub-attributes.

3. Change value of an attribute of an entity
In this example, you will see how we turn the same switch on/off.

curl -X POST -v -H "Authorization: Bearer XXX" -H "Content-type:application/json" -d "{\"entity_id\":\"switch.switch_14\"}" --url "http://HA_IP:8123/api/services/switch/turn_on"

* The same rules apply as for reading an entity. the switch/turn_on and entity/attribute names,
follows the same naming convention, as you would do when you do the same action as a service within HA itself.
* Passing the entity (and attributes), is done in JSON format, with the -d parameter.
* doublequotes inside doublequotes, need to be preceded by a \ (backslash).
* For special tasks, you can write your own service in PyScript
* By using the -v parameter, you will get a nice state-message.

More info can be found at:

This entry was posted in Blog, Home Assistant, Tutorials. Bookmark the permalink.

Leave a Reply

Your email address will not be published. Required fields are marked *