Realtime WebSocket Updates

The Luna Locate WebSocket API lets you subscribe to real-time device updates rather than polling the REST API. Instead of repeatedly querying for device state, you establish a persistent connection and receive updates as they happen.

📘

Delivery is best-effort. High throughput or network conditions may result in dropped messages to ensure stream stability. The server guarantees the most recent update for any given device is never dropped, but intermediate updates may be skipped.

Authentication

All WebSocket connections require a Bearer token in the Authorization header:

Authorization: Bearer <your_api_token>

Contact your Luna representative to obtain your API token.

Connect

wss://prod.lunalocate.com/api/v2/ws

Sending Commands

Once connected, you interact with the API by sending JSON commands. The two commands available are filter and clear.

filter

Subscribe to device updates matching a query:

{ "filter": "<query>" }

See Websocket Filter Examples for ready-made patterns, or the Q Language Manual for full filter syntax.

clear

Reset the connection to its initial state, undoing all active filters:

{ "clear": {} }

Note that messages already in-flight may still arrive after sending this command.

Filter Syntax

Filters use the same Q language as the REST API's q parameter, with one addition: the @ prefix lets you reference a field's previous value, so you can filter on transitions rather than state.

For example, this fires only when a device comes back online — not on every update while it's already online:

not @network.is_connected and network.is_connected

Without the @ prefix, the filter would match any update where network.is_connected is true, including devices that were already online.

If your filter is invalid, you'll receive an error:

{ "error": { "filter_parse": "a just barely human-readable explanation" } }

Receiving Messages

The server sends two types of messages:

Update — a device matched your filter:

{ "update": { .. device object .. } }

Delete — a device was removed from your workspace while you were subscribed:

{ "delete": "device-id" }