Observatories
The Observatory API covers the hardware side of Skynet — sites, observatories, telescopes, instruments, devices, device models, snapshots, and the operational-constraint family.
Endpoints at a glance
Section titled “Endpoints at a glance”| Resource | What it is |
|---|---|
/v1/sites |
Physical sites (lat/lon/elevation). Read and edit via PATCH; no create endpoint |
/v1/observatories |
Observatory records on a site. Read and edit via PATCH; creation (under /v1/users/{slug}/observatories or /v1/organizations/{slug}/observatories) is staff-only |
/v1/telescopes |
Telescope records — the unit observers ultimately submit against. Read and edit; creation is staff-only; no delete |
/v1/instruments |
Instruments — combinations of devices that fulfill an observation type. Create, read, edit; no delete |
/v1/devices |
Polymorphic device records (mount, camera, filter wheel, …). CRUD |
/v1/device-models |
Device-model templates that devices reference for defaults (read-only) |
/v1/device-snapshots |
Live device state — usually you’d consume via WebSocket rather than poll |
/v1/telescope-snapshots |
Aggregate telescope state — same; prefer WebSocket |
/v1/operational-constraint-snapshots |
Current statuses of operational constraints |
/v1/operational-constraints |
Constraint records — polymorphic on constraintType |
/v1/shutdown-interlocks |
Shutdown interlocks (the strong “stop now” version of a constraint) |
/v1/filter-specifiers |
Filter specifiers — the filter names requests list in filterSpecifierIds: single filters and filter groups (filterSpecifierType) |
Permissions model
Section titled “Permissions model”Reading and editing hardware records is gated by roles, not by a telescope’s public flag: you can see a telescope if you own it, hold a role in its owning organization that covers telescopes (for example telescope_viewer or device_manager), or hold a role grant on that telescope; editing needs a managing role. Being able to observe with a telescope is separate — that comes from observing grants, and those telescopes are listed by GET /v1/me/observing-access/telescopes. See Telescope access for the model and Access grants for the grant lifecycle.
Snapshots — REST vs WebSocket
Section titled “Snapshots — REST vs WebSocket”*-snapshots endpoints exist as REST resources for ergonomics (point-in-time queries, debugging), but for live tracking you should subscribe to the relevant WebSocket streams — device_snapshot, telescope_snapshot, instrument_snapshot, constraint_status_snapshot. Polling the REST endpoint works but wastes round-trips and won’t keep up under load.
Common task recipes
Section titled “Common task recipes”- Discover what telescopes you can observe with.
GET /v1/me/observing-access/telescopeslists them with their instruments and filters.GET /v1/telescopesinstead lists the telescopes whose hardware records you can see (paginated; see Conventions), andGET /v1/public/telescopeslists public telescopes. - Inspect a telescope’s hardware.
GET /v1/telescopes/{uid}/detailreturns the telescope with its devices and instruments;GET /v1/telescopes/{uid}/graphreturns the same relationships as a graph. Telescope paths accept the uid or the slug. - Add a new telescope. Site, observatory, and telescope registration is handled by Skynet staff — see Onboarding.