Skip to content

Observatories

The Observatory API covers the hardware side of Skynet — sites, observatories, telescopes, instruments, devices, device models, snapshots, and the operational-constraint family.

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)

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

  • Discover what telescopes you can observe with. GET /v1/me/observing-access/telescopes lists them with their instruments and filters. GET /v1/telescopes instead lists the telescopes whose hardware records you can see (paginated; see Conventions), and GET /v1/public/telescopes lists public telescopes.
  • Inspect a telescope’s hardware. GET /v1/telescopes/{uid}/detail returns the telescope with its devices and instruments; GET /v1/telescopes/{uid}/graph returns 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.