WebSocket protocol
The WebSocket protocol is how you get realtime state out of Skynet and (where permitted) how you push commands at telescopes. Two distinct WebSocket endpoints are exposed by the public API:
/v1/ws/stream— subscribe/publish for snapshots, events, and log entries. The common case./v1/ws/commands— command publish + command-result events. For sending commands at telescopes and receiving their results. Manual control through the hub is a per-server switch; it is on forapi.skynetgo.org(see Commands).
The message types are in the OpenAPI document, so types generated from it include them as a discriminated union.
This section is structured as:
- Streams — snapshots and events you subscribe to.
- Commands — the command protocol (mount, imager, filter wheel, focuser, rotator, enclosure, IP camera, lease).
Connection
Section titled “Connection”The connection URLs are:
wss://api.skynetgo.org/v1/ws/streamwss://api.skynetgo.org/v1/ws/commandsUse the appropriate base URL for your environment (see Environments). In production that’s wss://api.skynetgo.org/v1/ws/stream and so on.
Authentication
Section titled “Authentication”Bearer token, passed on the handshake via one of the carriers below. When a handshake carries more than one, the server uses the first it finds, in this order:
-
Authorizationheader —Authorization: Bearer <access-token>. For non-browser clients, which can set handshake headers. -
Sec-WebSocket-Protocolheader — the preferred carrier for browser clients. The browser WebSocket API can’t set custom headers, but it can offer subprotocols: offerskynet-tokenfirst and the token second.Sec-WebSocket-Protocol: skynet-token, <access-token>const socket = new WebSocket("wss://api.skynetgo.org/v1/ws/stream",["skynet-token", accessToken],);The server selects
skynet-token(its handshake response carriesSec-WebSocket-Protocol: skynet-token) and never echoes the token. Unlike a query string, the header stays out of browser history and out of the access logs of the proxies in front of the API. -
Query string (legacy) —
?token=<access-token>. Still accepted, so existing clients keep working, but the full URL, token included, lands in browser history and in proxy access logs. New clients should use one of the headers.
The token is the same OAuth access token used for REST requests. See Auth. A handshake without a valid token is refused.
A token issued with scopes (a least-privilege personal token or a third-party OAuth client) is default-denied on the WebSocket the same way it is on REST: it may open /v1/ws/stream only when it holds observation-events:subscribe, and then only subscribe to the observation_event stream, never the telemetry streams its user could see. It cannot open /v1/ws/commands at all. A token issued without scopes carries the user’s full authority.
The server closes a connection that sends nothing for 30 minutes, and re-checks every 5 minutes that the token’s user or installation still exists.
Whichever carrier you use, the token never reaches the API’s logs: the value of token (and of any other credential-bearing query parameter) is redacted from the server’s access log before the line is written, so a ?token= URL does not leave a replayable copy behind in log storage. The query string is still the least private of the three (it lands in your client’s history and is visible to the proxies in front of the API), so prefer the Authorization header when your client can set it.
Message envelope
Section titled “Message envelope”Every message on the WebSocket carries a kind discriminator (WsMessageKind). The full set:
Lifecycle
Section titled “Lifecycle”| Kind | Direction | Purpose |
|---|---|---|
ping |
client → server | Liveness check; carries a ts timestamp |
pong |
server → client | Response to ping, echoing its ts |
ack |
server → client | Acknowledges a request by its id; carries the subscription_id for a subscribe and the command_id for a published command |
error |
server → client | Error envelope (see below) |
Stream messages (on /v1/ws/stream)
Section titled “Stream messages (on /v1/ws/stream)”| Kind | Direction | Purpose |
|---|---|---|
subscribe_stream |
client → server | Subscribe to one or more streams |
unsubscribe_stream |
client → server | Unsubscribe |
publish_device_snapshot |
client → server (SkyNode) | Publish a new device snapshot |
publish_telescope_snapshot |
client → server (SkyNode) | Publish a new telescope snapshot |
publish_instrument_snapshot |
client → server (SkyNode) | Publish a new instrument snapshot |
publish_constraint_snapshot |
client → server (SkyNode) | Publish a new constraint snapshot |
publish_constraint_status_snapshot |
client → server (SkyNode) | Publish constraint status |
publish_telescope_log |
client → server (SkyNode) | Publish a telescope log line |
event_device_snapshot |
server → client | Subscribed-stream device snapshot delivery |
event_telescope_snapshot |
server → client | Telescope snapshot delivery |
event_instrument_snapshot |
server → client | Instrument snapshot delivery |
event_constraint_snapshot |
server → client | Constraint snapshot delivery |
event_constraint_status_snapshot |
server → client | Constraint status delivery |
event_manual_control_lease |
server → client | Manual control lease state change |
event_telescope_log |
server → client | Telescope log delivery |
event_shutdown_interlock_snapshot |
server → client | Shutdown interlock snapshot delivery |
event_observation_asset |
server → client | Observation asset added or updated |
Command messages (on /v1/ws/commands)
Section titled “Command messages (on /v1/ws/commands)”| Kind | Direction | Purpose |
|---|---|---|
subscribe_commands |
client → server | Subscribe to command and command-result streams |
unsubscribe_commands |
client → server | Unsubscribe |
publish_command |
client → server | Publish a command at a telescope |
cancel_command |
client → server | Cancel a previously-published command |
publish_command_result |
client → server (SkyNode) | SkyNode publishes a command result |
publish_command_catalog |
SkyNode → gateway | SkyNode publishes which commands its telescope can run (read it over REST: GET /v1/telescopes/{uid}/manual-command-catalog) |
publish_command_progress |
SkyNode → gateway | SkyNode reports a running command’s progress |
event_command |
server → client | Command delivery to subscribers |
event_command_result |
server → client | Command result delivery |
event_command_progress |
server → client | Progress of a command this connection published |
Error envelope
Section titled “Error envelope”WebSocket errors carry more structure than REST errors:
{ "kind": "error", "id": "<optional correlation id>", "code": "invalid | forbidden | not_found | conflict | internal", "message": "<human-readable message>", "details": { /* per-error structured detail */ }}The code field is from a fixed enum so clients can dispatch without parsing message. The id echoes the id of the request that failed. A refusal with a more specific, stable reason carries it in details.error_code (for example manual_control_disabled, duplicate_command or telescope_busy; see Commands); a refused subscription names the failed check in details.rule_failed (for example missing_filter or telescope_view_forbidden).
Subscribe/publish model
Section titled “Subscribe/publish model”The fundamental pattern: open the WebSocket, send a subscribe_* message with a request id identifying what you want, wait for the ack that carries the server-assigned subscription_id, and start receiving event_* messages. Multiple subscriptions are fine on a single connection; each subscription has its own filter.
For the specific filter shapes and what each stream carries, see Streams.
Message types
Section titled “Message types”The WebSocket message types are in the API reference schemas: StreamWsMessage and CommandsWSMessage are the discriminated unions. Types generated from the OpenAPI document include them.