WebSocket

Nodelets has two WebSockets on the API host. Both use JSON-RPC 2.0 messages, one per WebSocket text message.

Socket	Address	Subprotocol	Authentication
Bridge stream	wss://api.staging.nodelets.com/bridges/{bridgeId}/stream	nodelets.client.v1	An authenticate message
Account feed	wss://api.staging.nodelets.com/observations/stream	nodelets.feed.v1	Authorization: Bearer nlt_... header

A connection without the right subprotocol is refused.

Bridge stream

One socket serves every Nodelet on one bridge. A Nodelet’s summary gives its bridge’s address as streamUrl. A bridge that does not exist or is disabled refuses the connection with 403.

Messages from the client

Every message from the client has "jsonrpc": "2.0", a string id and a method. A message is at most 262,144 bytes.

Method	Params	Result
authenticate	{"apiKey": "nlt_..."}	{"authenticated": true}
subscribe	{"nodeletId", "operation", "name"}, where operation is observeproperty or subscribeevent	{"subscriptionId": "sub_..."}
unsubscribe	{"subscriptionId"}	{"unsubscribed": true}
interact	{"nodeletId", "operation", "name", "input"}, where operation is readproperty, writeproperty or invokeaction, and input is the value or action input	{"value": ...}

Send authenticate first, within 30 seconds of opening. Until it succeeds, any other message, a failed authentication or the 30 seconds running out closes the socket with code 1008. The key must belong to the bridge’s owner.

nodeletId must name a Nodelet on this socket’s bridge; any other answers NOT_FOUND. input is left out for a read and for an action with no input. subscribe needs Watch live value for a property and Receive event for an event. interact needs the permission for its operation, as on REST. The result of subscribe is sent once the subscription is in place at the device.

Messages from the cloud

Method	Params	Meaning
observation	{"subscriptionId", "nodeletId", "operation", "name", "value", "receivedAt"}	A live value or an event. receivedAt is milliseconds since the epoch, cloud time
subscriptionEnded	{"subscriptionId", "error": {"code", "message"}}	The subscription stopped. Subscribe again to carry on

A request that fails answers with an error, and the socket stays open:

{"jsonrpc": "2.0", "id": "7", "error": {"code": -32000, "message": "Operation failed", "data": {"code": "PERMISSION_DENIED", "message": "PERMISSION_DENIED", "outcome": "not-executed", "detail": "PERMISSION_DENIED"}}}

data.code and data.outcome have the meanings in Outcomes and errors.

When the socket closes

Code	Reason
1008	Authentication failed or expired, the key was deleted, or a message was invalid
1011	Sending to the client failed

A socket opened before keys had permissions is closed with Reconnect required; connecting again fixes it. A message that is not valid JSON-RPC, with no request ID to answer, closes the socket.

Account feed

The feed carries each saved reading, as it is saved, from every Nodelet whose history the key may read. It needs Read history on at least something; a key with none is refused.

The client sends nothing. A message from the client closes the socket with 1008.

Messages from the cloud

{"jsonrpc": "2.0", "method": "observation", "params": {"nodeletId": "nl_5c0e8a2f-7d41-4b9e-a3c6-2f8d1e4b7a90", "name": "temperature", "value": 21.44, "receivedAt": 1794060190140, "sequence": 815, "sampleInterval": 12}}

Field	Meaning
nodeletId, name	The Nodelet and property
value	The saved value
receivedAt	When the cloud received it, in milliseconds since the epoch
sequence	Its number in that Nodelet’s sequence, which runs across all of the Nodelet’s properties
sampleInterval	How many readings it stands for, itself included

The feed replays nothing, and a delivery can be missed. A skip in a Nodelet’s sequence shows what to fetch from saved readings. An account can have at most 64 feed sockets open; past that, a new one is refused with 503. Deleting the key closes its sockets.