Watch live values

Live values arrive on a WebSocket, one per bridge. A client authenticates with an API key, subscribes to the properties and events it wants, and receives each value as the device reports it.

Only HTTP devices have live values. A property needs an observeproperty binding in its definition, and the device must stream text/event-stream. MQTT devices have no live values yet. The practice thermostat streams its temperature.

The key needs Watch live value for properties and Receive event for events.

Find the bridge’s stream address

Each Nodelet’s summary gives the address of its bridge’s stream:

curl -fsS -H "Authorization: Bearer $NODELETS_KEY" \
  https://api.staging.nodelets.com/nodelets/$NODELET

The streamUrl field has the form wss://api.staging.nodelets.com/bridges/br_.../stream. One socket serves every Nodelet on that bridge.

Subscribe

This Node.js program, for Node 22 or later, watches the practice thermostat’s temperature. Save it as watch.mjs:

const [streamUrl, key, nodeletId] = process.argv.slice(2);
const socket = new WebSocket(streamUrl, "nodelets.client.v1");

socket.addEventListener("open", () => {
  socket.send(JSON.stringify({
    jsonrpc: "2.0", id: "auth", method: "authenticate",
    params: { apiKey: key },
  }));
});

socket.addEventListener("message", ({ data }) => {
  const message = JSON.parse(data);
  if (message.id === "auth" && message.result?.authenticated) {
    socket.send(JSON.stringify({
      jsonrpc: "2.0", id: "sub", method: "subscribe",
      params: { nodeletId, operation: "observeproperty", name: "temperature" },
    }));
  } else if (message.method === "observation") {
    const { name, value, receivedAt } = message.params;
    console.log(new Date(receivedAt).toISOString(), name, value);
  } else {
    console.log(JSON.stringify(message));
  }
});

socket.addEventListener("close", ({ code, reason }) => {
  console.log("closed", code, reason);
});

Run it with the stream address, your key and the Nodelet ID:

node watch.mjs "wss://api.staging.nodelets.com/bridges/br_9a4f2c71-3e8b-4d06-b5a2-c1e7f0d38b64/stream" \
  "$NODELETS_KEY" "$NODELET"

{"jsonrpc":"2.0","id":"sub","result":{"subscriptionId":"sub_..."}}
2026-11-07T14:02:05.120Z temperature 21.42
2026-11-07T14:02:10.131Z temperature 21.43

Authenticate within 30 seconds of opening the socket, or it closes. A failed authentication also closes it.

To receive an event instead, subscribe with "operation": "subscribeevent" and the event’s name. Events arrive as observation messages too, with that operation.

When a subscription ends

The cloud sends subscriptionEnded with a code when a subscription stops, for example because the bridge’s connection changed or the definition changed:

{"jsonrpc":"2.0","method":"subscriptionEnded","params":{"subscriptionId":"sub_...","error":{"code":"BRIDGE_UNAVAILABLE","message":"Bridge connection changed"}}}

Subscribe again to carry on. If the socket itself closes, open a new one, authenticate and subscribe again.

What live values do not do

• Values are forwarded as they arrive and are not replayed. A client that was not connected misses them. Saved readings can fill the gap: see Read history.
• If a device sends values faster than the bridge’s connection carries them, the bridge drops that device’s oldest queued values. The loss shows in history as an uncertain interval.
• Deleting the key closes the socket.

The full message set is in the WebSocket reference.