API Reference

REST API & WebSocket

All endpoints are served from a single Axum server on port 7624. REST for commands, WebSocket for real-time events.

base URLs

HTTP:  http://localhost:7624/api/v1
WS:    ws://localhost:7624/ws

Authentication

Local access (default): no authentication required. For remote access, pass the token in the Authorization header.

request header

Authorization: Bearer <token>
# Token saved in ~/.config/openskylab/config.toml

Mount

Mount Control

GET

/mount/status

Current RA/DEC, Alt/Az, tracking mode, slewing state, pier side, time to flip

POST

/mount/gotobody: { ra, dec }

Slew to J2000 coordinates (ra in hours, dec in degrees)

POST

/mount/syncbody: { ra, dec }

Sync mount position to solved coordinates

POST

/mount/park

Park the mount at configured park position

POST

/mount/unpark

Unpark and resume tracking

POST

/mount/trackingbody: { mode: "sidereal"|"lunar"|"solar"|"off" }

Set tracking mode

POST

/mount/abort

Emergency stop all mount movement

GET

/mount/alignment

List alignment points in the pointing model

POST

/mount/alignment/addbody: AlignPoint

Add a solved alignment point

POST

/mount/alignment/clear

Clear all alignment points

Camera

Camera Control

GET

/camera/status

Sensor info, cooler status, current exposure progress

POST

/camera/exposebody: ExposureParams

Start an exposure (duration, gain, offset, binning, frame type)

POST

/camera/abort

Abort current exposure

GET

/camera/frame/latest

Download the most recent captured frame

POST

/camera/coolerbody: { enabled, target_c }

Set cooler on/off and target temperature

POST

/camera/livestack/start

Start live stacking incoming frames

POST

/camera/livestack/stop

Stop live stacking

POST

/camera/livestack/reset

Clear accumulated stack

GET

/camera/livestack

Current live stack status and preview

Focuser

Focuser Control

GET

/focuser/status

Position, temperature, moving state, max position

POST

/focuser/movebody: { position }

Move to absolute position (steps)

POST

/focuser/move-relbody: { steps }

Move relative (positive = out, negative = in)

POST

/focuser/autofocus

Start V-curve autofocus routine

Guiding (PHD2)

Guiding Control

GET

/guiding/status

Guide state, RMS RA/DEC, star position, calibration state

POST

/guiding/start

Start autoguiding (connects to PHD2)

POST

/guiding/stop

Stop autoguiding

POST

/guiding/ditherbody: { pixels, settle_time }

Dither by N pixels, wait for settle

Sequencer

Sequence Management

GET

/sequences

List all saved sequences

POST

/sequencesbody: Sequence

Create a new sequence

GET

/sequences/{id}

Get sequence by ID

DELETE

/sequences/{id}

Delete a sequence

Sequencer Control

GET

/sequencer/status

Current state, step, frame, elapsed time, ETA

POST

/sequencer/startbody: { sequence_id }

Start running a sequence

POST

/sequencer/pause

Pause after current exposure

POST

/sequencer/resume

Resume paused sequence

POST

/sequencer/abort

Abort and discard remaining

GET

/sequencer/checkpoint

Get recovery checkpoint (for crash resume)

Scheduler

Observation Planning

GET

/scheduler/plans

List observation plans

POST

/scheduler/plansbody: SchedulerPlan

Create a multi-target plan

GET

/scheduler/status

Scheduler state, current target, progress

POST

/scheduler/start

Start automated observation

POST

/scheduler/pause

Pause scheduler

POST

/scheduler/resume

Resume scheduler

POST

/scheduler/abort

Abort and park

POST

/scheduler/skip-target

Skip current target, move to next

Plate Solver

Plate Solving

POST

/solver/solvebody: { image_path, ra_hint?, dec_hint? }

Solve a FITS image. Uses ASTAP, falls back to astrometry.net

GET

/solver/result/{id}

Get solve result (RA, DEC, position angle, pixel scale)

GET

/solver/indexes

List available ASTAP and astrometry.net databases

POST

/solver/download-indexbody: { database }

Download a solver database

More Endpoints

Additional endpoint groups include: filter wheel, rotator, flat panel, dome, weather, safety, catalog, mosaic, profiles, templates, cloud sync, publish (OpenSkyLab Cloud image/acquisition upload), dew heater, switches, sky flat, storage, session, advanced sequencer, GNSS, blink comparator, distortion analysis, sub-exposure calculator, HiPS tiles, calibration library, polar alignment, telemetry, license, ASCOM bridge, and logs. See the OpenAPI 3.1 spec for the complete reference.

WebSocket Events

Connect to ws://localhost:7624/ws for real-time events. All events follow this shape:

event shape

interface WsEvent {
  type: string;      // e.g. "mount.status"
  ts: number;        // Unix milliseconds
  data: unknown;     // type-specific payload
}

Event Types

Event	Frequency	Description
mount.status	10Hz / 1Hz	Position, tracking state (fast when slewing)
camera.frame_ready	On complete	Frame downloaded and saved
camera.expose_progress	1Hz	Exposure progress percentage
focuser.status	On change	Position, moving state, temperature
guiding.stats_update	1Hz	RA/DEC RMS, corrections
guiding.state_changed	On change	Guiding, Paused, Lost, Calibrating
sequencer.step_changed	On change	New step/filter/target started
sequencer.frame_saved	Per frame	Frame saved with HFR, star count
solver.result	On solve	Solve result with coordinates
solver.download_progress	On progress	Solver index download: database, name, downloaded/total MB, percent
solver.download_complete	On complete	Solver index download finished
solver.download_error	On error	Solver index download failed
catalog.download_progress	On progress	Catalog database download progress
catalog.download_complete	On complete	Catalog database download finished
catalog.download_error	On error	Catalog database download failed
ascom_bridge.started	On start	COM→Alpaca bridge process started: port, pid
ascom_bridge.stopped	On stop	COM→Alpaca bridge process stopped
device.connected	On connect	Device connected event
device.disconnected	On disconnect	Device disconnected event
weather.update	60s	Weather conditions
session.started	On start	Imaging session started
session.ended	On end	Imaging session ended
scheduler.state_changed	On change	Scheduler engine state transition
scheduler.target_started	On change	New observation target
scheduler.target_completed	On complete	Current target finished
scheduler.target_skipped	On skip	Target skipped, moved to next
scheduler.plan_completed	On complete	Entire multi-target plan finished
scheduler.meridian_flip_started	On start	Automated meridian flip beginning
scheduler.meridian_flip_completed	On complete	Automated meridian flip succeeded
scheduler.meridian_flip_failed	On error	Automated meridian flip failed
scheduler.safety_alert	On event	Weather unsafe, stopping
scheduler.error	On error	Scheduler encountered an error
dome.status	On change	Shutter state, azimuth, parked state
dome.shutter_changed	On change	Shutter state transition
dome.rotating	On event	Dome azimuth rotation in progress
dome.parking	On event	Dome parking in progress
cloud.sync_complete	On complete	WebDAV cloud sync finished
polar_alignment.state_changed	On change	Polar alignment routine state transition
polar_alignment.error_computed	On compute	Alt/Az error in arcmin
hips.predownload_progress	On progress	HiPS sky-cache pre-download progress
hips.predownload_complete	On complete	HiPS sky-cache pre-download finished
sky_flat.state_changed	On change	Twilight sky flat automation state transition
sky_flat.exposure_done	Per frame	Sky flat exposure captured
alert	On event	info, warning, error, critical