Home Assistant

Server-sent Events

The server-sent events feature is a one-way channel from your Home Assistant server to a client which is acting as a consumer. For bi-directional communication check the RESTful API and Python API.

The URI that is generating the data is /api/stream.

A requirement on the client-side is existing support for the EventSource interface.

There are various ways to access the stream. One is curl:

$ curl -X GET -H "x-ha-access: 12345" \
       -H "Content-Type: application/json" http://localhost:8123/api/stream

For more comfort put the HTML snippet below in a file sse.html in your www folder of your Home Assistant configuration directory (.homeassistant)

<!DOCTYPE html>
<html>
<body>
    <h1>Getting Home Assistant server events</h1>
    <div id="events"></div>
    <script type="text/javascript">
        var source = new EventSource("/api/stream");
        source.onmessage = function(event) {
            document.getElementById("events").innerHTML += event.data + "<br>";
        };
    </script>
</body>
</html>

Visit http://localhost:8123/local/sse.html to see the stream of events.

Examples

The simplest way to consume server-sent events is curl.

$ curl http://localhost:8123/api/stream?api_password=MYPASS

Website

The home-assistant-sse repository contains an more advanced example.

Python

If you want test the server-sent events without creating a website then the Python module sseclient can help. Install it first:

$ pip3 install sseclient

The simplest script to consume the SSE looks like the following snipplet.

from sseclient import SSEClient

messages = SSEClient('http://localhost:8123/api/stream?api_password=MYPASS')
for msg in messages:
    print(msg)