During the command phase, the client attaches a unique identifier to each message. The server will add this identifier to each message so that the client can link each message to it’s origin.
-Each API message is a JSON serialized object containing a type key. After the authentication phase messages also must contain an id, an integer that contains the number of interactions.
Example of an auth message:
-{
- "type": "auth",
- "api_password": "supersecret"
-}
-{
+ "type": "auth",
+ "api_password": "supersecret"
+}
+{
- "id" 5,
- "type":"event",
- "event":{
- "data":{},
- "event_type":"test_event",
- "time_fired":"2016-11-26T01:37:24.265429+00:00",
- "origin":"LOCAL"
- }
-}
-{
+ "id" 5,
+ "type":"event",
+ "event":{
+ "data":{},
+ "event_type":"test_event",
+ "time_fired":"2016-11-26T01:37:24.265429+00:00",
+ "origin":"LOCAL"
+ }
+}
+When a client connects to the server, the server will test if the client is authenticated. Authentication will not be necessary if no api_password is set or if the user fulfills one of the other criteria for authentication (trusted network, password in url/header).
If no authentication is needed, the authentication phase will complete and the server will send an auth_ok message.
{
- "type": "auth_ok"
-}
-{
+ "type": "auth_ok"
+}
+If authentication is necessary, the server sends out auth_required.
{
- "type": "auth_required"
-}
-{
+ "type": "auth_required"
+}
+This means that the next message from the client should be an auth message:
-{
- "type": "auth",
- "api_password": "supersecret"
-}
-{
+ "type": "auth",
+ "api_password": "supersecret"
+}
+If the client supplies valid authentication, the authentication phase will complete by the server sending the auth_ok message:
{
- "type": "auth_ok"
-}
-{
+ "type": "auth_ok"
+}
+If the data is incorrect, the server will reply with auth_invalid message and disconnect the session.
{
- "type": "auth_invalid",
- "message": "Invalid password"
-}
-{
+ "type": "auth_invalid",
+ "message": "Invalid password"
+}
+During this phase the client can give commands to the server. The server will respond to each command with a result message indicating when the command is done and if it was successful.
{
- "id": 6.
- "type": "result",
- "success": true,
- // Can contain extra result info
- "result": null
-}
-{
+ "id": 6.
+ "type": "result",
+ "success": true,
+ // Can contain extra result info
+ "result": null
+}
+The command subscribe_events will subscribe your client to the event bus. You can either listen to all events or to a specific event type. If you want to listen to multiple event types, you will have to send multiple subscribe_events commands.
{
- "id": 18,
- "type": "subscribe_events",
- // Optional
- "event_type": "state_changed"
-}
-{
+ "id": 18,
+ "type": "subscribe_events",
+ // Optional
+ "event_type": "state_changed"
+}
+The server will respond with a result message to indicate that the subscription is active.
-{
- "id": 18,
- "type": "result",
- "success": true,
- "result": null
-}
-{
+ "id": 18,
+ "type": "result",
+ "success": true,
+ "result": null
+}
+For each event that matches, the server will send a message of type event. The id in the message will point at the original id of the listen_event command.
{
- "id": 18,
- "type":"event",
- "event":{
- "data":{
- "entity_id":"light.bed_light",
- "new_state":{
- "entity_id":"light.bed_light",
- "last_changed":"2016-11-26T01:37:24.265390+00:00",
- "state":"on",
- "attributes":{
- "rgb_color":[
- 254,
- 208,
- 0
- ],
- "color_temp":380,
- "supported_features":147,
- "xy_color":[
- 0.5,
- 0.5
- ],
- "brightness":180,
- "white_value":200,
- "friendly_name":"Bed Light"
- },
- "last_updated":"2016-11-26T01:37:24.265390+00:00"
- },
- "old_state":{
- "entity_id":"light.bed_light",
- "last_changed":"2016-11-26T01:37:10.466994+00:00",
- "state":"off",
- "attributes":{
- "supported_features":147,
- "friendly_name":"Bed Light"
- },
- "last_updated":"2016-11-26T01:37:10.466994+00:00"
- }
- },
- "event_type":"state_changed",
- "time_fired":"2016-11-26T01:37:24.265429+00:00",
- "origin":"LOCAL"
- }
-}
-{
+ "id": 18,
+ "type":"event",
+ "event":{
+ "data":{
+ "entity_id":"light.bed_light",
+ "new_state":{
+ "entity_id":"light.bed_light",
+ "last_changed":"2016-11-26T01:37:24.265390+00:00",
+ "state":"on",
+ "attributes":{
+ "rgb_color":[
+ 254,
+ 208,
+ 0
+ ],
+ "color_temp":380,
+ "supported_features":147,
+ "xy_color":[
+ 0.5,
+ 0.5
+ ],
+ "brightness":180,
+ "white_value":200,
+ "friendly_name":"Bed Light"
+ },
+ "last_updated":"2016-11-26T01:37:24.265390+00:00"
+ },
+ "old_state":{
+ "entity_id":"light.bed_light",
+ "last_changed":"2016-11-26T01:37:10.466994+00:00",
+ "state":"off",
+ "attributes":{
+ "supported_features":147,
+ "friendly_name":"Bed Light"
+ },
+ "last_updated":"2016-11-26T01:37:10.466994+00:00"
+ }
+ },
+ "event_type":"state_changed",
+ "time_fired":"2016-11-26T01:37:24.265429+00:00",
+ "origin":"LOCAL"
+ }
+}
+You can unsubscribe from previously created subscription events. Pass the id of the original subscription command as value to the subscription field.
-{
- "id": 19,
- "type": "unsubscribe_events",
- "subscription": 18
-}
-{
+ "id": 19,
+ "type": "unsubscribe_events",
+ "subscription": 18
+}
+The server will respond with a result message to indicate that unsubscribing was successful.
-{
- "id": 19,
- "type": "result",
- "success": true,
- "result": null
-}
-{
+ "id": 19,
+ "type": "result",
+ "success": true,
+ "result": null
+}
+This will call a service in Home Assistant. Right now there is no return value. The client can listen to state_changed events if it is interested in changed entities as a result of a service call.
The server will indicate with a message indicating that the service is done executing.
-{
- "id": 24,
- "type": "result",
- "success": true,
- "result": null
-}
-{
+ "id": 24,
+ "type": "result",
+ "success": true,
+ "result": null
+}
+This will get a dump of all the current states in Home Assistant.
-{
- "id": 19,
- "type": "get_states"
-}
-{
+ "id": 19,
+ "type": "get_states"
+}
+The server will respond with a result message containing the states.
-{
- "id": 19,
- "type": "result",
- "success": true,
- "result": [ … ]
-}
-{
+ "id": 19,
+ "type": "result",
+ "success": true,
+ "result": [ ... ]
+}
+This will get a dump of the current config in Home Assistant.
-{
- "id": 19,
- "type": "get_config"
-}
-{
+ "id": 19,
+ "type": "get_config"
+}
+The server will respond with a result message containing the config.
-{
- "id": 19,
- "type": "result",
- "success": true,
- "result": { … }
-}
-{
+ "id": 19,
+ "type": "result",
+ "success": true,
+ "result": { ... }
+}
+This will get a dump of the current services in Home Assistant.
-{
- "id": 19,
- "type": "get_config"
-}
-{
+ "id": 19,
+ "type": "get_config"
+}
+The server will respond with a result message containing the services.
-{
- "id": 19,
- "type": "result",
- "success": true,
- "result": { … }
-}
-{
+ "id": 19,
+ "type": "result",
+ "success": true,
+ "result": { ... }
+}
+This will get a dump of the current registered panels in Home Assistant.
-{
- "id": 19,
- "type": "get_panels"
-}
-{
+ "id": 19,
+ "type": "get_panels"
+}
+The server will respond with a result message containing the current registered panels.
-{
- "id": 19,
- "type": "result",
- "success": true,
- "result": [ … ]
-}
-{
+ "id": 19,
+ "type": "result",
+ "success": true,
+ "result": [ ... ]
+}
+If an error occurs, the success key in the result message will be set to false. It will contain an error key containing an object with two keys: code and message.
{
- "id": 12,
- "type":"result",
- "success": false,
- "error": {
- "code": 2,
- "message": "Message incorrectly formatted: expected str for dictionary value @ data['event_type']. Got 100"
- }
-}
-{
+ "id": 12,
+ "type":"result",
+ "success": false,
+ "error": {
+ "code": 2,
+ "message": "Message incorrectly formatted: expected str for dictionary value @ data['event_type']. Got 100"
+ }
+}
+