Skip to content

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 for api.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).

The connection URLs are:

wss://api.skynetgo.org/v1/ws/stream
wss://api.skynetgo.org/v1/ws/commands

Use the appropriate base URL for your environment (see Environments). In production that’s wss://api.skynetgo.org/v1/ws/stream and so on.

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:

  • Authorization header — Authorization: Bearer <access-token>. For non-browser clients, which can set handshake headers.

  • Sec-WebSocket-Protocol header — the preferred carrier for browser clients. The browser WebSocket API can’t set custom headers, but it can offer subprotocols: offer skynet-token first 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 carries Sec-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.

Every message on the WebSocket carries a kind discriminator (WsMessageKind). The full set:

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)
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
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

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).

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.

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.