Establish a WebSocket connection to receive real-time device updates.

Authentication

This endpoint requires a Bearer token.

• HTTP Header: Authorization: Bearer <TOKEN>

If authentication fails, the server will reject the WebSocket upgrade.

Message model (after connection)

After the WebSocket is established, the client sends JSON commands to control which updates it receives. The server then emits JSON messages when devices change.

Client → Server commands

Subscribe using a filter

Send a JSON command with a filter string:

{ "filter": "<query>" }

The filter query uses the Q query language.

Full reference:
https://lunaxio-dev.readme.io/docs/q-language-manual

Clear subscriptions

Send the clear command to undo the effects of any prior filters (equivalent to reconnecting):

{ "clear": {} }

Note: messages may still be in-flight after a clear.

Server → Client messages

After subscribing, the server emits messages of the following forms:

Update

A device object is delivered under update:

{ "update": { /* device object */ } }

Delete

If a device is removed from the workspace while subscribed:

{ "delete": "device-id" }

Error

If the filter is invalid (e.g., syntax error):

{ "error": { "filter_parse": "<explanation>" } }

Backpressure / rate limiting behavior

If the client cannot keep up with the rate of updates, the server may discard queued messages such that only the most recent undelivered message per device is retained. This ensures the latest state for each device is not dropped.

Unlike the REST "search" endpoint (which may limit searchable fields), the WebSocket filter can evaluate against the full device schema.