Reading and Writing HA data using the REST API by @brucemiranda - zxdavb/ramses_cc GitHub Wiki

Getting Started

The File Editor Add-on helps you set this up. To install the File Editor, select Settings > Add-on Store. Next, start the File Editor and open the /config/configuration.yaml file.

To use the HomeAssistant REST API, you’ll need to add a line api: if it is not yet present in the configuration file. After I made this change, I restarted my HA application using Configuration and the three dots menu.

Next I needed to create a user token. In Home Assistant, 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 safe.

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 a REST API command 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 confirm that the HA API is running, a curl GET command can be 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. It 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 to 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

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

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

Download the history of the last 24hours for an entity

curl -X GET -H "Authorization: Bearer TOKEN" http://192.168.1.11:8123/api/history/period?filter_entity_id=climate.study

The easiest way to create 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.