Reading and Writing HA data using the REST API

Getting Started

I found that loading the File Editor Add-on made configuration changes quite easy. To load the File Editor, select the Supervisor item, then Add-on Store:

With the File Editor option you be able to modify your /config/configuration.yaml file. For this you’ll need to add an api: statement.

After I made these changes I restarted my HA application, by the “Configuration” -> “Server Controls”.

Next I needed to create a user token. Select your user and then click on “Create Token” in the Long-Lived Access Tokens section. This token is very long and it only is shown once, so copy and paste it somewhere save.

Access the REST API with CURL

Curl is a command line utility that exists on Linux, Mac OS and Windows. I work in Linux mostly and it’s pre-installed with Ubuntu. If you’re working in Windows you’ll need to install CURL.

Getting started with curl isn’t required and you got straight to programming in your favourite language, however I found that it was usefully testing things out in curl before I did any programming.

The REST API is essentially an HTTP URL with some headers and parameters passed to it. For a full definition see the HA API document. The key items in REST API are:

Request type – GET or POST (note: there are other types) Authorization – this is where the user token is passed Data – is used for setting and defining tags URL – the Home Assistant URL and the end point (option to view or set)

To check that the HA API is running a curl GET command can used with the endpoint of /api/

$ curl -X GET -H "Authorization: Bearer TOKEN" http://192.168.1.11:8123/api/

{"message": "API running."}

The user token is super long so your can use the \ character to break up your command. For example:

$ curl -X GET \

-H "Authorization: Bearer TOKEN" \

http://192.168.1.11:8123/api/states

Read a Specific HA Item

To get a specific HA item you’ll need to know its entity id. This can found by looking at the “Configuration” -> “Entities” page:

Examples

Read my Evohome entity for my Study created by ramses_cc curl -X GET -H "Authorization: Bearer TOKEN" http://192.168.1.11:8123/api/states/climate.study

Set the HW Boost on curl -X POST -H "Authorization: Bearer TOKEN" -H "Content-Type: application/json" -d '{"entity_id": "water_heater.stored_hw"}' http://192.168.1.11:8123/api/services/ramses_cc/set_dhw_boost

Reset the System Mode curl -X POST -H "Authorization: Bearer TOKEN" -H "Content-Type: application/json" -d '{"entity_id": "climate.controller"}' http://192.168.1.11:8123/api/services/ramses_cc/reset_system_mode

Set the System Mode to Heating Off curl -X POST -H "Authorization: Bearer TOKEN" -H "Content-Type: application/json" -d '{"entity_id": "climate.controller", "mode": "heat_off"}' http://192.168.1.11:8123/api/services/ramses_cc/set_system_mode

Set the Study setpoint to 21C for 30 mins curl -X POST -H "Authorization: Bearer TOKEN" -H "Content-Type: application/json" -d '{"entity_id": "climate.study", "mode": "temporary_override", "setpoint": "21", "duration": {"minutes": "30"}}' http://192.168.1.11:8123/api/services/ramses_cc/set_zone_mode

To get a Zone's schedule you need to first issue the following command curl -X POST -H "Authorization: Bearer TOKEN" -H "Content-Type: application/json" -d '{"entity_id": "climate.study"}' http://192.168.1.11:8123/api/services/ramses_cc/get_zone_schedule

and then read that zone's states and extract the schedule from the returned json curl -X GET -H "Authorization: Bearer TOKEN" http://192.168.1.11:8123/api/states/climate.study

To set a Zone's schedule you need to format your schedule in the same format as the returned json. curl -X POST -H "Authorization: Bearer TOKEN" -H "Content-Type: application/json" -d '{ "entity_id": "climate.study", "schedule": "[{\"day_of_week\":0,\"switchpoints\":[{\"time_of_day\":\"08:00\",\"heat_setpoint\":21.0},{\"time_of_day\":\"16:00\",\"heat_setpoint\":8.0}]},{\"day_of_week\":1,\"switchpoints\":[{\"time_of_day\":\"08:00\",\"heat_setpoint\":21.0},{\"time_of_day\":\"16:00\",\"heat_setpoint\":8.0}]},{\"day_of_week\":2,\"switchpoints\":[{\"time_of_day\":\"08:00\",\"heat_setpoint\":21.0},{\"time_of_day\":\"16:00\",\"heat_setpoint\":8.0}]},{\"day_of_week\":3,\"switchpoints\":[{\"time_of_day\":\"08:00\",\"heat_setpoint\":21.0},{\"time_of_day\":\"16:00\",\"heat_setpoint\":8.0}]},{\"day_of_week\":4,\"switchpoints\":[{\"time_of_day\":\"08:00\",\"heat_setpoint\":21.0},{\"time_of_day\":\"16:00\",\"heat_setpoint\":8.0}]},{\"day_of_week\":5,\"switchpoints\":[{\"time_of_day\":\"09:00\",\"heat_setpoint\":19.0},{\"time_of_day\":\"21:00\",\"heat_setpoint\":8.0}]},{\"day_of_week\":6,\"switchpoints\":[{\"time_of_day\":\"09:00\",\"heat_setpoint\":19.0},{\"time_of_day\":\"21:00\",\"heat_setpoint\":8.0}]}]" }' http://192.168.1.11:8123/api/services/ramses_cc/set_zone_schedule

The easiest way to format a command is to use the Developer Tools in HA and then test the command first before then moving to create the same in CURL. Use a YAML to JSON converter to format the data that you need to pass.