Skip to main content

​
Overview

/api/events is a Server-Sent Events (SSE) endpoint that streams a lightweight notification whenever any device’s state changes. Use it to keep a UI or integration updated without polling /status repeatedly.

​
Endpoint

GET http://your-server:8082/api/events

​
Response

The endpoint sends an SSE stream. Each event has: 
data: {"serial": "02AB01AC012345678"}

data: {"serial": "02AB01AC012345678"}
The event payload only contains the serial number of the device that changed. To get the new state, follow up with a GET /status?serial={serial} call.

​
Response Headers

Content-Type: text/event-stream
Cache-Control: no-cache
X-Accel-Buffering: no
The X-Accel-Buffering: no header is included for nginx compatibility. Without it, nginx may buffer the stream and delay delivery of events.

​
Examples

const source = new EventSource('http://your-server:8082/api/events');

source.onmessage = async (event) => {
  const { serial } = JSON.parse(event.data);
  console.log(`Device changed: ${serial}`);

  // Fetch updated status
  const resp = await fetch(`http://your-server:8082/status?serial=${serial}`);
  const status = await resp.json();
  console.log(`New temperature: ${status.current_temperature}°C`);
};

source.onerror = (err) => {
  console.error('SSE connection error', err);
};

​
Behavior

  • The connection stays open indefinitely until the client disconnects.
  • Events are emitted whenever a device state change is processed (subscribe PUT, command execution).
  • There is no initial burst of events on connection — only future changes are sent.
  • If the server restarts, the SSE connection will drop and the client must reconnect.

​
Use Case: Live Dashboard

// Auto-reconnecting SSE client
function connectEvents(onDeviceChange) {
  let source = null;

  function connect() {
    source = new EventSource('http://your-server:8082/api/events');
    source.onmessage = async (e) => {
      const { serial } = JSON.parse(e.data);
      const resp = await fetch(`http://your-server:8082/status?serial=${serial}`);
      onDeviceChange(await resp.json());
    };
    source.onerror = () => {
      source.close();
      setTimeout(connect, 5000); // reconnect after 5s
    };
  }

  connect();
  return () => source?.close();
}

GET /status

Get full device state after an event

POST /notify-device

Manually trigger a push to subscribers