Realtime Updates (SSE)

Instead of polling GET /api/v1/flags, a client can open a Server-Sent Events connection and receive flag changes as they happen.

Connect

GET /api/v1/stream?sdkKey=<your environment's SDK key>
Accept: text/event-stream

const source = new EventSource(
  `https://your-flagpulse-host/api/v1/stream?sdkKey=${sdkKey}`
);

source.onmessage = (event) => {
  const payload = JSON.parse(event.data);
  switch (payload.type) {
    case "flag_created":
      // payload.flag_id — refetch or add locally
      break;
    case "flag_updated":
      // payload has the full updated flag_value fields merged in
      break;
    case "flag_deleted":
      // payload.flag_id — remove locally
      break;
    case "sdkKeyChanged":
      // the key used to connect is no longer valid (rotated/revoked) — reconnect with the new key
      source.close();
      break;
  }
};

Event types

type	Sent when	Payload
flag_created	A new flag is created on the project	{ type, flag_id }
flag_updated	A flag's value is edited or toggled in this environment	{ type, flag_id, is_enabled, rollout_percentage, ... }
flag_deleted	A flag is deleted	{ type, flag_id }
sdkKeyChanged	The SDK key used to open the connection is invalid (never existed, or was rotated after connecting)	{ type } — the connection is then closed server-side

Reconnection

EventSource reconnects automatically on connection drop by default. Because connection state lives in memory on a single backend process (see Architecture), a backend restart drops all open streams — clients should treat a closed connection as routine and simply reconnect, falling back to a one-off GET /api/v1/flags to resync state after reconnecting in case any events were missed while disconnected.

Dashboard presence stream

A second, JWT-authenticated stream exists for the dashboard itself:

GET /api/v1/stream/dashboard?environment_id=<envId>

This is used to show how many SDK clients are currently connected to an environment (presence events with a count) — it's not intended for use from application SDKs.