WebSocket Channels

For real-time query results and fleet status updates, use WebSocket channels instead of polling the REST API.

Connection

Connect to the WebSocket endpoint with your API key: 

wss://hyprwatch.cloud/api/socket/websocket?token=hw_live_xxx

Channels

query:{org_id}

Execute queries and receive results in real-time as they arrive from each host.

Events: result, complete, error

org:{org_id}

Subscribe to fleet-wide events like host online/offline status changes.

Events: host_online, host_offline, host_enrolled

JavaScript Example

Using the Phoenix JavaScript client: 

import {Socket} from "phoenix"

// Connect with API key
const socket = new Socket("wss://hyprwatch.cloud/api/socket", {
params: {token: "hw_live_xxx"}
})
socket.connect()

// Join query channel
const channel = socket.channel(`query:${orgId}`, {})
channel.join()
.receive("ok", () => console.log("Joined query channel"))
.receive("error", ({reason}) => console.log("Failed to join", reason))

// Execute a query
channel.push("run", {
sql: "SELECT * FROM processes LIMIT 10",
target: "all"
})

// Receive results as they arrive
channel.on("result", ({host_id, hostname, rows}) => {
console.log(`Results from ${hostname}:`, rows)
})

// Query complete
channel.on("complete", ({query_id, summary}) => {
console.log("Query complete:", summary)
})

Python Example

Using websocket-client: 

import json
import websocket

def on_message(ws, message):
data = json.loads(message)
if data.get("event") == "result":
    print(f"Results: {data['payload']}")

def on_open(ws):
# Join channel
ws.send(json.dumps({
    "topic": f"query:{org_id}",
    "event": "phx_join",
    "payload": {},
    "ref": "1"
}))

ws = websocket.WebSocketApp(
f"wss://hyprwatch.cloud/api/socket/websocket?token=hw_live_xxx",
on_open=on_open,
on_message=on_message
)
ws.run_forever()

When to Use Channels vs REST

Use Case Recommendation
One-off query, wait for all results REST API POST /query
Interactive query, show results as they arrive WebSocket channel
Dashboard with live fleet status WebSocket channel
CI/CD pipeline, automation script REST API
Long-running query on large fleet WebSocket channel