Skip to content

Streams

Streams are the subscribe/publish half of the WebSocket protocol, on /v1/ws/stream. You subscribe to a named stream with a filter; the server sends event_* messages whenever new data matches.

The hub retains recent entries per resource. When you subscribe, the server sends you the latest known entry for each resource you named immediately, then continues with new entries as they arrive.

The StreamName enum lists what’s available:

Stream Carries Source Required filter
device_snapshot Per-device live state (position, temperature, exposure state, …) SkyNode for each connected device device_uids
telescope_snapshot Per-telescope aggregate state SkyNode telescope_uids
instrument_snapshot Per-instrument state — combinations of devices that together carry out an observation type SkyNode, built from its devices’ state resources (instrument references)
telescope_log Telescope log lines — significant events, errors, operator notes SkyNode telescope_uids
constraint_snapshot Operational constraint state SkyNode constraint_uids
constraint_status_snapshot Constraint safe/unsafe status with latest evaluation SkyNode constraint_uids
manual_control_lease Manual control lease lifecycle events Hub telescope_uids and/or device_uids
shutdown_interlock_snapshot Active shutdown interlocks Hub, when an interlock changes telescope_uids
observation_event An observation’s asset was added (its bytes are importable) or its current processing output changed Hub observation_uids

Send a subscribe_stream message identifying the stream and filter:

{
"kind": "subscribe_stream",
"id": "<client-chosen request id>",
"stream": "device_snapshot",
"filter": {
"device_uids": ["00000000-0000-0000-0000-000000000000"]
},
"options": {
"min_interval_ms": 1000
}
}

The id is a client-chosen request id. The server answers with an ack that echoes it and carries the server-assigned subscription_id, or with an error that echoes it. The server stamps that subscription_id on every event_* message delivered for the subscription.

Every subscription names the resources it watches; there is no wildcard. The required filter key for each stream is in the table above, and every resource you name must pass its own permission check (VIEW on the telescope, device or constraint; view on the observation), or the whole subscribe is refused with forbidden. Filter keys:

  • device_uids, telescope_uids, constraint_uids, observation_uids — the resources to watch.
  • resources — a list of {resource_type, uid} references; instrument_snapshot reads its instruments from here.
  • include_origin_uids / exclude_origin_uids — keep or drop deliveries by the UID of the installation that published them.

Options (both optional):

  • min_interval_ms — at most one delivery per resource per interval; entries in between are skipped.
  • max_queue — accepted but not acted on today.

To stop receiving:

{
"kind": "unsubscribe_stream",
"id": "<client-chosen request id>",
"subscription_id": "<the subscription_id from the ack>"
}

Deliveries arrive as event_* messages:

{
"kind": "event_device_snapshot",
"subscription_id": "<your-subscription-id>",
"device_uid": "<the device's uid>",
"origin_uid": "<uid of the publishing installation>",
"payload": { /* DeviceSnapshot record */ }
}

Each event names its resource (device_uid, telescope_uid, instrument_uid, constraint_uid or observation_uid), and the snapshot and log events also carry the origin_uid of the installation that published them. The shape of payload matches the corresponding schema:

  • event_device_snapshot → DeviceSnapshot (with polymorphic deviceType discriminator)
  • event_telescope_snapshot → TelescopeSnapshot
  • event_instrument_snapshot → InstrumentSnapshot
  • event_constraint_snapshot → ConstraintSnapshot
  • event_constraint_status_snapshot → ConstraintStatusSnapshot
  • event_manual_control_lease → ManualControlLease, or null when the telescope or device has no lease (on subscribe you get one of these per telescope or device you named)
  • event_shutdown_interlock_snapshot → TelescopeShutdownInterlockSnapshot
  • event_telescope_log → TelescopeLogEntry
  • event_observation_asset → ObservationAssetEvent (event is asset_added or asset_updated). It carries identifiers and classification only; re-list the observation’s assets over REST for the full record.

SkyNode installations publish snapshots to the hub, normally over the SkyNode gateway’s stream connection (the public API’s /v1/ws/stream accepts the same messages from an installation). The publish messages have shape:

{
"kind": "publish_device_snapshot",
"id": "<request id>",
"device_uid": "<the device's uid>",
"payload": { /* DeviceSnapshot */ }
}

These are not useful for external integrations — only SkyNode installations are authorized to publish; a user’s publish is refused with forbidden. They’re listed here for completeness so the protocol is fully described.

Subscribe to telescope_log and manual_control_lease with your telescope’s UID in telescope_uids, to device_snapshot with its devices’ UIDs in device_uids, and to constraint_status_snapshot with its constraints’ UIDs in constraint_uids (read the UIDs from the REST API first). That gives you everything a dashboard needs: live device state, constraint go/no-go, log entries, and operator takeover events.

For monitoring several telescopes, subscribe to telescope_snapshot with every telescope’s UID in telescope_uids — you’ll receive the latest snapshot per telescope and updates as they change. A subscription that names no telescopes is refused.

The protocol doesn’t currently expose a cursor — event_* messages are new entries from the moment of subscription forward, after the latest retained entry per resource. To backfill historical state, use the REST API’s snapshot endpoints, then subscribe for new data.

  • Keep-alive — send a ping (with a ts timestamp) periodically; the server answers with a pong. The server closes a connection that sends nothing for 30 minutes, and intermediaries may close one sooner; the website pings every 30 seconds.
  • Reconnect — on disconnect, reconnect with the same access token and re-subscribe. The server doesn’t persist subscriptions across reconnects.
  • Error — when an error message arrives, log the code and message. A forbidden error means your token doesn’t have permission for the requested stream/filter (details.rule_failed says which check failed) — fix the filter or get a token with the right access rather than retrying.

The full message envelope and per-stream shapes are in the API reference schemas (StreamWsMessage).