API Endpoints

API Endpoints#

banner

This page documents all HTTP endpoints exposed by the _Astra_ FastAPI application.

The API provides programmatic access to observatory control, monitoring, and data retrieval functions.

REST API Endpoints#

The following REST API endpoints are available for interacting with the Astra observatory system.

GET /api/allsky/latest#

Serve the latest All-Sky camera image.

Parameters:

  • name (str, optional) – Name of the specific all-sky camera. If not provided, returns the first camera.

Returns:

FileResponse: The image file with no-store cache headers.

POST /api/close#

Close observatory and stop all operations safely.

Stops running schedule if active and closes the observatory. Logs all actions for audit trail.

Returns:

dict: JSON response with operation status.

POST /api/complete_headers#

Complete FITS header processing for observatory images.

Returns:

dict: JSON response with operation status.

POST /api/cool_camera/{device_name}#

Initiate camera cooling to configured target temperature.

Gets camera configuration and starts cooling process to the specified set temperature with defined tolerance.

Path Parameters:

  • device_name (str) – Camera device name to cool.

Returns:

dict: JSON response with operation status and cooling details.

GET /api/db/guiding#

Get autoguider log data for plotting guiding performance.

Retrieves guiding corrections (post_pid_x, post_pid_y) from the autoguider_log table for visualization.

Parameters:

  • day (float) – Number of days back to retrieve data. Defaults to 1.

  • since (str) – Optional timestamp to get only newer records.

  • telescope (str) – Optional telescope name to filter data.

Returns:

dict: JSON response with guiding data including datetime,

telescope_name, post_pid_x, and post_pid_y values.

GET /api/db/polling/{device_type}#

Get device polling data from observatory database.

Uses an append-only in-memory cache keyed by device_type:

  • First request performs a full DB query (up to day days) and stores the result.

  • Subsequent requests fetch only the rows newer than last_cached_timestamp - 2 min, reprocess that overlap window to ensure the most-recent 60 s bucket is complete, merge into the cache, and prune rows older than the requested day window.

  • Concurrent requests share a single threading.Lock so only one DB fetch runs at a time; any waiter re-uses the freshly-updated cache.

Path Parameters:

  • device_type (str) – Type of device (e.g. ``’ObservingConditions’``).

Parameters:

  • day (float) – Days of history to include in the response. Defaults to 1.

  • since (str) – Optional ISO-format UTC timestamp; if supplied the response payload is filtered to rows newer than this value (the cache itself always holds the full window).

Returns:

dict: Processed polling data with safety limits and latest values.

POST /api/editschedule#

Update observatory schedule from web editor.

Parses JSONL schedule data and saves to observatory schedule file. A row that fails validation stops the write, because the scheduler would reject the file when it next loads it. Pass force to save a draft anyway.

Parameters:

  • schedule_data (str) – JSONL formatted schedule data.

  • force (bool) – Save even when a row fails validation.

Returns:

dict: Status response with success/error information.

GET /api/heartbeat#

Get observatory heartbeat status for health monitoring.

Returns:

dict: JSON response with heartbeat status data.

GET /api/latest_image_preview#

Serve the latest FITS image as a JPEG preview.

Returns the most recent observatory image converted to JPEG format, generated in-memory without disk I/O.

Returns:

StreamingResponse: JPEG image data with appropriate headers.

GET /api/log#

Get observatory log entries before specified datetime.

Parameters:

  • datetime (str) – Upper limit datetime for log entries.

  • limit (int) – Maximum number of log entries to return. Defaults to 100.

Returns:

list: Log entries as dictionary records.

POST /api/reconnect_devices#

Restart all device processes, connect again, and restart polling.

Use this to recover from lost devices without restarting Astra. The watchdog stops, every device process is replaced, the devices connect again, polling starts again, and the watchdog starts again. Device changes in the config file are used. The robotic switch stays off.

The work runs in a background thread; the log shows the progress. The request is refused while a schedule, a reconnect, or another task that uses the devices runs (an action or a guider).

Returns:

dict: JSON response with operation status.

POST /api/roboticswitch#

Toggle observatory robotic operation mode.

Returns:

dict: JSON response with current robotic switch state.

GET /api/schedule#

Get current observatory schedule with formatted times.

Returns:

list: Schedule items with start/end times formatted as HH:MM:SS,

or empty list if no schedule exists.

GET /api/sky_data#

Get celestial body positions for all-sky projection.

A plain def, so FastAPI runs it in a worker thread. The astropy calculation and the telescope location read can take seconds on the first call, and in the event loop they would stop the websocket messages.

Returns:

dict: JSON response with observatory location, time, and celestial body positions

POST /api/startschedule#

Start executing the observatory’s observation schedule.

Returns:

dict: JSON response with operation status.

POST /api/startwatchdog#

Start observatory watchdog monitoring system.

Resets error states and starts the watchdog process for continuous observatory health monitoring. Refused while a device reconnect runs, because the reconnect starts the watchdog itself.

Returns:

dict: JSON response with operation status.

POST /api/stopschedule#

Stop executing the observatory’s observation schedule.

Returns:

dict: JSON response with operation status.

POST /api/stopwatchdog#

Stop observatory watchdog monitoring system.

Returns:

dict: JSON response with operation status.

GET /api/timelapse/{camera}#

List the saved time-lapse frames for a camera, oldest first.

Path Parameters:

  • camera (str) – Camera id, as set in the feed’s ``timelapse_id``.

Returns:

dict: JSON response with frames (list of {file, time}) and

last_error.

GET /api/timelapse/{camera}/{frame}#

Serve one saved time-lapse frame.

Path Parameters:

  • camera (str) – Camera id.

  • frame (str) – Frame file name from ``/api/timelapse/{camera}``.

Returns:

FileResponse: The frame image. Frames never change, so browsers may cache them.

POST /api/uploadschedule#

Upload schedule file to replace current observatory schedule.

Parameters:

  • file (UploadFile) – Uploaded schedule file in JSONL format.

Returns:

dict: Upload status response with success/error information.

POST /api/validateschedule#

Check a schedule from the web editor without saving it.

Parameters:

  • schedule_data (str) – JSONL formatted schedule data.

Returns:

dict: Status response whose data holds the per-row errors.

GET /schedule#

Serve schedule editor page with current schedule data.

Loads raw JSONL schedule file preserving original datetime format for the web-based schedule editor interface.

Parameters:

  • request (Request) – FastAPI request object.

Returns:

TemplateResponse: HTML template with schedule editor and data.

WebSocket Endpoints#

WebSocket endpoints provide real-time bidirectional communication.

WebSocket /ws/log#

WebSocket endpoint for real-time log streaming.

Provides initial log history and streams new log entries as they are added to the database. Also includes schedule modification time.

Parameters:

  • websocket (WebSocket) – WebSocket connection object.

WebSocket /ws#

Main WebSocket endpoint for real-time observatory status updates.

Streams comprehensive observatory status including device polling data, system health, operational status, and latest images. Handles FITS to JPEG conversion for image display.

Parameters:

  • websocket (WebSocket) – WebSocket connection object.