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.
Stream names
Section titled “Stream names”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 |
Subscribing
Section titled “Subscribing”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_snapshotreads 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>"}Receiving
Section titled “Receiving”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 polymorphicdeviceTypediscriminator)event_telescope_snapshot→TelescopeSnapshotevent_instrument_snapshot→InstrumentSnapshotevent_constraint_snapshot→ConstraintSnapshotevent_constraint_status_snapshot→ConstraintStatusSnapshotevent_manual_control_lease→ManualControlLease, ornullwhen the telescope or device has no lease (on subscribe you get one of these per telescope or device you named)event_shutdown_interlock_snapshot→TelescopeShutdownInterlockSnapshotevent_telescope_log→TelescopeLogEntryevent_observation_asset→ObservationAssetEvent(eventisasset_addedorasset_updated). It carries identifiers and classification only; re-list the observation’s assets over REST for the full record.
Publishing (SkyNode only)
Section titled “Publishing (SkyNode only)”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.
Patterns
Section titled “Patterns”Per-telescope dashboard
Section titled “Per-telescope dashboard”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.
Multi-telescope monitoring
Section titled “Multi-telescope monitoring”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.
Backfill from a known cursor
Section titled “Backfill from a known cursor”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.
Lifecycle
Section titled “Lifecycle”- Keep-alive — send a
ping(with atstimestamp) periodically; the server answers with apong. 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
errormessage arrives, log thecodeandmessage. Aforbiddenerror means your token doesn’t have permission for the requested stream/filter (details.rule_failedsays which check failed) — fix the filter or get a token with the right access rather than retrying.
Reference
Section titled “Reference”The full message envelope and per-stream shapes are in the API reference schemas (StreamWsMessage).