+ Rest API +
++ + +
Home Assistent runs a webserver accessible on port 8123.
+ +-
+
- http://127.0.0.1:8123/ is an interface to control Home Assistant. +
- http://localhost:8123/api/ is a Rest API. +
In the package homeassistant.remote
a Python API on top of the HTTP API can be found.
The API accepts and returns only JSON encoded objects. All API calls have to be accompanied by the header X-HA-Access: YOUR_PASSWORD
(as specified in your home-assistant.conf
).
Note
+You can append ?api_password=YOUR_PASSWORD
to any url to log in automatically.
+
Successful calls will return status code 200 or 201. Other status codes that can return are:
+ +-
+
- 400 (Bad Request) +
- 401 (Unauthorized) +
- 404 (Not Found) +
- 405 (Method not allowed) +
The api supports the following actions:
+ +/api - GET
+Returns message if API is up and running.
1 +2 +3 + |
|
/api/events - GET
+Returns an array of event objects. Each event object contain event name and listener count.
1 +2 +3 +4 +5 +6 +7 +8 +9 +10 + |
|
/api/services - GET
+Returns an array of service objects. Each object contains the domain and which services it contains.
1 +2 +3 +4 +5 +6 +7 +8 +9 +10 +11 +12 +13 +14 +15 + |
|
/api/states - GET
+Returns an array of state objects. Each state has the following attributes: entity_id, state, last_changed and attributes.
1 +2 +3 +4 +5 +6 +7 +8 +9 +10 +11 +12 +13 +14 +15 +16 +17 + |
|
/api/states/<entity_id> - GET
+Returns a state object for specified entity_id. Returns 404 if not found.
1 +2 +3 +4 +5 +6 +7 +8 +9 + |
|
/api/states/<entity_id> - POST
+Updates or creates the current state of an entity.
Return code is 200 if the entity existed, 201 if the state of a new entity was set. A location header will be returned with the url of the new resource. The response body will contain a JSON encoded State object.
+
+parameter: state - string
+optional parameter: attributes - JSON object
1 +2 +3 +4 +5 +6 +7 +8 +9 + |
|
/api/events/<event_type> - POST
+Fires an event with event_type
+optional body: JSON encoded object that represents event_data
1 +2 +3 + |
|
/api/services/<domain>/<service> - POST
+Calls a service within a specific domain. Will return when the service has been executed or 10 seconds has past, whichever comes first.
+optional body: JSON encoded object that represents service_data
Returns a list of states that have changed since the start of this service call.
+ +1 +2 +3 +4 +5 +6 +7 +8 +9 +10 +11 +12 +13 +14 +15 +16 +17 + |
|
/api/event_forwarding - POST
+Setup event forwarding to another Home Assistant instance.
+parameter: host - string
+parameter: api_password - string
+optional parameter: port - int
1 +2 +3 + |
|
/api/event_forwarding - DELETE
+Cancel event forwarding to another Home Assistant instance.
+parameter: host - string
+optional parameter: port - int
If your client does not support DELETE HTTP requests you can add an optional attribute _METHOD and set its value to DELETE.
+ +1 +2 +3 + |
|