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 a bi-directional streaming API, check out the WebSocket 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. If you have not set an api_password in the http section of your configuration.yaml file then you use your modern browser to read the messages. A command-line option is curl:

$ curl -X GET -H 'Authorization: Bearer ABCDEFGH' \
-H "Content-Type: application/json" http://localhost:8123/api/stream

Will no longer work with the new Authentication system.

You can create a convenient view for this by creating an HTML file (sse.html) in the www folder of your Home Assistant configuration directory (.homeassistant). Paste this snippet into the file:

<!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?api_password=YOUR_PASSWORD");
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

A simple way to consume server-sent events is to use a command-line http client like httpie. Installation info is on the site (if you use Homebrew, it's brew install httpie). Once installed, run this snippet from your terminal:

$ http --stream http://localhost:8123/api/stream 'Authorization:Bearer ABCDEFGH' content-type:application/json

Website

Will no longer work with the new Authentication system.

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

Python

If you want to test the server-sent events without creating a website, the Python module sseclient can help. To install (assuming Python and pip3 are already installed):

$ pip3 install sseclient

A simple script to consume SSE in Python looks like this:

from sseclient import SSEClient
auth = {"Authorization": "Bearer ABCDEFGH"}
messages = SSEClient("http://localhost:8123/api/stream", headers=auth)
for msg in messages:
print(msg)