HTTP API (scripts & AI agents)

Everything the dashboard does goes through this JSON API on the local web port, so anything else can drive Starship the same way: a shell script, a notebook, a home-automation box, or an AI agent. This page is generated from the server's route table at release time, so it lists the routes of this build.

Basics

• Base URL: http://127.0.0.1:8765 by default ([web] host / port). To reach

it from another machine set [web] host = "0.0.0.0" and restart; keep the port off the public internet.

• Format: JSON in, JSON out. Every reply carries "ok": true|false and, on

failure, an "error" string. Send Content-Type: application/json.

• Authentication: off by default. [web] auth_enabled = true turns on HTTP

Basic Auth for every route except /api/version, /api/help and the login page.

• Activation: a compiled build that has no valid licence answers only

/api/version and the /api/license/* routes until it is activated.

• Jobs: long actions (capture, slew, autofocus, plate solve, flats) return a

job_id immediately. Poll GET /api/console/jobs (or /api/console/jobs/<id>) until the job is succeeded, failed or cancelled; a capture's result carries fits_path and rel_path, and rel_path is what the frame routes take.

• Plans: a sequence plan is TOML (see Plan format). The flow is

POST /api/sequencer/plans/validate -> POST /api/sequencer/plans/save -> POST /api/sequencer/start -> poll GET /api/sequencer/state.

• Safety stays in Starship. The safety supervisor, the sequencer's make-safe

phases, the park and roof interlocks and the health monitor act regardless of who is calling. An agent cannot bypass them and should not try; it reads state and asks for actions, and the rig says no when it must.

Playbook for an automation agent

What worked on real nights, in order:

1. GET /api/version, GET /api/state, GET /api/health/status - know the build,

the safety verdict and the memory headroom before touching anything.

1. POST /api/equipment/connect_all, then GET /api/ascom until every role you

need reports connected: true. PHD2 must be running for guided plans.

1. Write the plan as TOML, validate, then save with a dated id, then start.

Author the make-safe phases in the plan (on_error, on_suspend, on_end: close the cover, park) - that is what protects the rig when you are not looking.

1. Poll GET /api/sequencer/state every 15-30 s: watch current_step, the tail of

the journal, error and outcome. Poll GET /api/health/status for memory and GET /api/phd2 for guiding. Read the log only for diagnosis.

1. When a run ends, decide from state and outcome: succeeded -> start the next

plan; failed / stopped -> read the journal, fix, retry. Never start a plan on a mount that a safety layer just parked without understanding why.

1. At the end: verify at_park and the cover on /api/ascom, then, if your site

has one, POST /api/console/roof_close.

Things an agent should not do: analyse full-resolution frames on a small PC while a capture is downloading (before v22.2.3 that alone could trip the memory floor), issue mount commands while a job is moving the mount, or change config.toml on an operator's rig without being asked.

Routes

GET routes read; POST routes act. Body keys are listed where the handler reads them; a key in brackets is optional. Routes are grouped by area.

alerts

• GET /api/alerts/config - Alert channels and their settings (secrets redacted).
• POST /api/alerts/config Body: smtp_password.
• GET /api/alerts/history - Alerts sent tonight.
• POST /api/alerts/test

allsky

• GET /api/allsky - All-sky camera state.
• GET /api/allsky/snapshot.jpg - The latest all-sky image.
• POST /api/allsky/test Body: url, allow_insecure_tls.

alpaca

• GET /api/alpaca - The Alpaca slots, same shape as /api/ascom.
• POST /api/alpaca/... Body: channel, host, port, device_type, device_number, device_name.
• POST /api/alpaca/discover Body: host, port.

ascom

• GET /api/ascom - The ASCOM slots: for each role the ProgID, connected, and the live properties (mount RA/Dec/sidereal time/side_of_pier/at_park/tracking, camera temperatures, focuser position, filter names, cover_state, shutter_status).
• POST /api/ascom/... Body: channel.

audit

• GET /api/audit/log - The hash-chained audit log (paged): every command, verdict and event with its result.
• GET /api/audit/recent - The most recent audit events - the quickest way to see what just happened.
• GET /api/audit/verify - Re-verify the audit chain and report whether it is intact.

blockscript

• POST /api/blockscript/force_emergency - Force the EMERGENCY path now (make safe immediately).
• POST /api/blockscript/force_shutdown - Force the SHUTDOWN path now (orderly end of night).
• POST /api/blockscript/hold_resume - Hold ({"held": true}) or release the running blockscript.
• POST /api/blockscript/start - Start a saved blockscript: {"name": "..."}.
• GET /api/blockscript/status - The night automation state machine: state, current block, held flag, last transition.

cctv

• GET /api/cctv - CCTV sources.
• GET /api/cctv/snapshot/...
• POST /api/cctv/test Body: name.

config

• GET /api/config - The effective configuration (secrets redacted).
• POST /api/config - Save settings: the full config document; the reply says whether a restart is needed and which keys.
• POST /api/config/reset - Reset the configuration to defaults (confirm required).
• POST /api/config/restart - Restart the service to apply startup-only settings.
• POST /api/config/restore_backup - Restore the previous config.toml backup.

console

• POST /api/console/autofocus/adaptive-first-light - Self-finding first calibration: probes step size, range and backlash, then builds the V-curve (job).
• POST /api/console/autofocus/approve-focuser-report - Approve a measured backlash characterisation so it travels with the equipment profile.
• GET /api/console/autofocus/calibration - The learned focus position, step and recipe.
• POST /api/console/autofocus/clear - Forget the learned calibration.
• POST /api/console/autofocus/focus-star - Slew to a suitable focus star: mag_min, mag_max, alt_min_deg, max_dist_deg (moves the mount).
• POST /api/console/autofocus/focus-wizard - The wizard with explicit coarse_out / step (job).
• POST /api/console/autofocus/goto-focus - Move the focuser to the last learned focus position.
• POST /api/console/autofocus/linear - A plain linear sweep: start_offset, step, max_points (job).
• POST /api/console/autofocus/refocus - Run a refocus around the current position (job).
• POST /api/console/autofocus/run - Run the configured autofocus routine (job).
• POST /api/console/autofocus/wizard - Calibration sweep from a roughly focused start (resolution optional) (job).
• POST /api/console/capture - One exposure as a background job: exposure_s, light, binning, gain, offset, object_name, filter_name, frame_type. Returns detail.job_id; poll /api/console/jobs until the job is succeeded and read result.rel_path.
• POST /api/console/capture_abort - Abort a running capture: job_id.
• POST /api/console/center_here - Re-point so the clicked position of a solved frame is centred: rel_path plus the click.
• GET /api/console/cooler - Cooler state: temperature, setpoint, power, settle state.
• POST /api/console/cooler_ramp - Cool slowly: target_c over minutes.
• POST /api/console/cooler_ramp_cancel - Cancel a ramp.
• POST /api/console/cooler_set_power - Cooler on/off: {"on": true|false}.
• POST /api/console/cooler_set_target - {"temp_c": -10} sets the camera setpoint live.
• POST /api/console/cooler_warm_up - Warm the sensor up gently to target_c.
• POST /api/console/dome/abort - Stop dome motion.
• POST /api/console/dome/gohome - Go home: rotate to the remembered home azimuth (or [observatory] dome_home_azimuth_deg) without the sensor search; refused until a home azimuth is known.
• POST /api/console/dome/goto - Rotate the dome to azimuth.
• POST /api/console/dome/home - Find home: start the driver's home-sensor search (v22.2.10: returns at once with a job_id; watch at_home in the status). Starship remembers the azimuth the dome reports AtHome at.
• POST /api/console/dome/park - Park the dome.
• POST /api/console/dome/slave - Slave the dome to the mount: {"on": true|false}.
• GET /api/console/dome/status - Dome/roof state: shutter, azimuth, slaving, at-home/at-park.
• POST /api/console/dome/sync - Record a sync point for the dome geometry solver at the current pointing.
• POST /api/console/dome/sync-clear - Delete all sync points.
• POST /api/console/dome/sync-delete - Delete one sync point: pier_side, index.
• GET /api/console/dome/sync-list - The recorded sync points.
• GET /api/console/filterwheel - Filter wheel position and names.
• POST /api/console/filterwheel_set_position - Move the wheel to position (slot index).
• GET /api/console/flat - Auto Flat state and the per-filter plan.
• POST /api/console/flat/auto - Run the Auto Flat plan (job).
• POST /api/console/flat/sky - Twilight (sky) flats as a job: {"when": "dawn"|"dusk", "park_on_end"?: bool, "close_roof_on_end"?: bool}. Waits for the sun window ([flat] sky_sun_alt_*), opens the roof claim and the flat cover, slews to the flat spot with tracking off, shoots every [flat].filters row ordered by sky sensitivity and meters each saved frame. Returns detail.job_id; progress on /api/console/jobs/{id} and the flat.progress bus event; the job result has the Auto Flat shape plus order, sun_alt_start, sun_alt_end and per-filter off_target.
• POST /api/console/flat_calibrator - Flat panel: {"on": true, "brightness": 0-255}.
• POST /api/console/flat_cover - {"action": "open"|"close"} on the flat cover; read cover_state back on /api/ascom (3 = open, 1 = closed).
• POST /api/console/focuser_diag - Focuser diagnostics (travel, backlash probe).
• POST /api/console/focuser_halt - Stop the focuser.
• POST /api/console/focuser_move - Move the focuser: position (absolute, or relative: true).
• POST /api/console/follower_start - Start the piggyback follower train.
• POST /api/console/follower_stop - Stop the piggyback follower train.
• POST /api/console/frame_hfd - Star metrics on a saved frame: {"rel_path": "<file from a job result>"} -> hfr_median, n_stars, eccentricity_median, background.
• POST /api/console/free_memory - Drop caches and run garbage collection now.
• POST /api/console/halt_all - Emergency stop: abort every motion and capture.
• GET /api/console/jobs - Background jobs (captures, slews, autofocus, plate solves): id, state (running / succeeded / failed / cancelled), progress, result (a capture's fits_path and rel_path), error.
• GET /api/console/jobs/...
• POST /api/console/jobs/... Body: answer.
• GET /api/console/jobs/<id> - One job: state, progress, result, error.
• POST /api/console/jobs/<id>/cancel - Cancel a running job (a capture is aborted, a slew stopped).
• POST /api/console/jobs/<id>/confirm - Answer a job that paused for a confirmation: {"answer": true|false}.
• POST /api/console/jog_heartbeat - Keep a jog alive (it stops itself when the heartbeat stops).
• POST /api/console/jog_start - Start a manual jog: direction, rate_fraction; keep it alive with jog_heartbeat.
• POST /api/console/jog_stop - Stop a jog.
• GET /api/console/last_frame - Metadata of the last captured frame and its preview.
• POST /api/console/mount_abort - Abort the current slew.
• POST /api/console/mount_find_home - Run the mount's find-home routine.
• POST /api/console/mount_home - Send the mount to its home position.
• POST /api/console/mount_park - Park and wait for the driver to report parked (the wait says why if it does not).
• POST /api/console/mount_set_tracking - {"on": true|false}.
• POST /api/console/mount_slew - Slew (ra_hours, dec_degrees, optional sync, frame) as a job.
• POST /api/console/mount_unpark - Unpark.
• POST /api/console/plate_solve - Solve a saved frame: rel_path, optional ra_hint_hours / dec_hint_degrees, blind (job).
• POST /api/console/polar_align - Start the plate-solved polar alignment routine (job).
• POST /api/console/polar_align_stop - Stop it.
• GET /api/console/power - Power box switches and their states.
• POST /api/console/power_set - Switch a power channel: switch_id, on (confirm_off to cut power to a device that is in use).
• POST /api/console/precise_slew - Slew, solve, sync and re-slew until the target is centred: ra_hours, dec_degrees (job).
• POST /api/console/pulse_guide - A guide pulse: direction, duration_ms.
• POST /api/console/resolve_target - Resolve a name to coordinates: name. CDS Sesame first (https; a mirror whose certificate the PC cannot verify is retried over plain http), then the built-in OpenNGC catalogue when no mirror answers (source says which, note says why). The error names every mirror and its reason.
• POST /api/console/roof_close - Close the roof / shutter. Refused unless the mount is parked (or confirm_unparked is true).
• POST /api/console/roof_open - Open the roof / shutter (subject to the safety verdict).
• POST /api/console/rotate_to_pa - Rotate the field to a sky position angle: target_pa_deg (plate-solved).
• GET /api/console/rotator - Rotator position and state.
• POST /api/console/rotator_halt - Stop the rotator.
• POST /api/console/rotator_move - Move the rotator to position_deg.
• POST /api/console/target_get_selected - Read the target selected in the planetarium.
• POST /api/console/target_send - Send a target to the planetarium: ra_hours, dec_degrees, object_name.

diagnostics

• GET /api/diagnostics - The diagnostics ring buffer (recent log lines and events).

equipment

• POST /api/equipment/connect_all - Connect every configured device on every transport (and PHD2). Returns per-role results and the cooling-on-connect state.
• POST /api/equipment/connect_done - Tell the cooling-on-connect window that a manual bring-up is finished.
• POST /api/equipment/connect_plan - The ordered bring-up plan (which roles connect in which order); bringup selects a saved plan.
• POST /api/equipment/disconnect_all - Disconnect every device on every transport.
• POST /api/equipment/disconnect_plan - The ordered shutdown plan.
• POST /api/equipment/step - Connect or disconnect ONE role: {"transport": "ascom"|"alpaca", "role": "camera", "action": "connect"|"disconnect"}.

equipment profiles

• GET /api/equipment_profiles - Saved equipment profiles.
• POST /api/equipment_profiles/apply Body: name.
• POST /api/equipment_profiles/delete Body: name.
• POST /api/equipment_profiles/save Body: name.

filters

• GET /api/filters - The filter library.

fits

• GET /api/fits - FITS module state: watched folder, last file, preview status.
• GET /api/fits/header/...
• GET /api/fits/header/<rel_path> - The FITS header of a saved frame.
• GET /api/fits/list - FITS files under IMAGES, newest first (name, rel_path, size_bytes, mtime). v22.2.7: ?limit= (default 100, max 5000), ?offset=, ?since= / ?until= (unix seconds or ISO 8601, on the file mtime) and ?prefix= (a rel_path / subfolder prefix such as NGC_300/ or flats_L) let a client enumerate a whole night; the reply carries count, limit, offset. v22.2.8: a listing with since, until or prefix always looks into subfolders (flats_<filter>/, a capture's subfolder), whatever [fits] watch_recursive says; the plain listing still follows that setting.
• GET /api/fits/preview/...
• GET /api/fits/preview/<rel_path> - A stretched preview image (PNG) of a saved frame.

framing

• POST /api/framing/create_sequence - Turn a framed target or mosaic into a sequence plan (appends to the library).
• GET /api/framing/fov - The camera's field of view from the optics or the connected camera.
• POST /api/framing/to_scheduler - Turn a framed target or mosaic into scheduler goals.

guardian

• POST /api/guardian/simulate - Inject a fault for a role (scenario) to exercise the ladder - test rigs only.
• GET /api/guardian/status - The self-heal ladder: attempts per device, current rung, cooldowns.

health

• POST /api/health/dismiss_memory - Dismiss a SOFT memory countdown (attended testing). The HARD floor cannot be dismissed.
• GET /api/health/status - Health level (HEALTHY / DEGRADED / CRITICAL) with every check's detail (memory, disk, cpu, threads, heartbeats, devices) and the escalation counters.

help

• GET /api/help - The help topic list for this edition.
• GET /api/help/...
• GET /api/help/<topic> - One help topic rendered to HTML.

license

• POST /api/license/activate - Activate this computer with a supporter key: {"activation_key": "ASW-..."}.
• POST /api/license/refresh - Refresh the licence from the licence server now.
• GET /api/license/status - Edition, licence validity, licensee, expiry, machine id, whether the gate is enforced.

night report

• GET /api/night_report - Tonight's tally: frames per target and filter, integration, rejects, autofocus runs, guiding RMS samples, alerts, suspends.
• GET /api/night_report/nights - The nights a report exists for.

pete

• POST /api/pete/check Body: kind, plan_id, toml, plan, blockscript, name.

phd2

• GET /api/phd2 - PHD2 state (guider.app_state, RMS total/RA/Dec, SNR, star_lost, settling, last event).
• POST /api/phd2/test - Try a PHD2 connection: host, port.

planetarium

• GET /api/planetarium - Planetarium connection state.

platesolve

• GET /api/platesolve - Plate-solver configuration and last-solve state.
• POST /api/platesolve/test - Check an ASTAP installation: {"astap_path": "..."}.

profiles

• GET /api/profiles - Configuration profiles.
• POST /api/profiles/delete Body: name.
• POST /api/profiles/load Body: name.
• POST /api/profiles/save Body: name.

scheduler

• POST /api/scheduler/... Body: position_angle, name, ra_h, dec_deg, priority, min_alt_deg, completion_mode, template, goals, precise_point, id, project_id, filter, exposure_s, goal_count, binning, gain, doc, description, replace.
• POST /api/scheduler/goals/add - Add a goal (target + filter + frames) to a project: ra_h, dec_deg, position_angle, ...
• POST /api/scheduler/goals/delete - Delete a goal.
• POST /api/scheduler/goals/update - Update a goal.
• GET /api/scheduler/history - What the dispatcher did on past nights.
• GET /api/scheduler/projects - Projects with their goals and progress from the ledger.
• POST /api/scheduler/projects/add - Add a project: name, priority, min_alt_deg, completion_mode, template, goals.
• POST /api/scheduler/projects/delete - Delete a project.
• POST /api/scheduler/projects/update - Update a project's fields.
• GET /api/scheduler/schedules - Saved named schedules.
• POST /api/scheduler/schedules/delete - Delete a saved schedule.
• POST /api/scheduler/schedules/recall - Replace the current schedule with a saved one.
• POST /api/scheduler/schedules/save - Save the current projects/goals as a named schedule.
• POST /api/scheduler/simulate - Dry-run the schedule for tonight (or several nights): per-target timeline and skip reasons.
• POST /api/scheduler/start - Start dispatching the current schedule.
• GET /api/scheduler/status - Dispatcher state, the current target/goal and the readiness gates.
• POST /api/scheduler/stop - Stop the dispatcher (the running sequence finishes its step).
• GET /api/scheduler/target_preview - Plain-words readiness of each target now (rising, Moon too close, sets in N min).
• GET /api/scheduler/templates - Sequence templates a project can use.
• POST /api/scheduler/templates/get - One template's document.

sequencer

• GET /api/sequencer - Sequencer module state and the plan library summary.
• GET /api/sequencer/checkpoints - Runs that can be resumed after a crash or restart.
• POST /api/sequencer/pause - Pause at the next step boundary.
• GET /api/sequencer/plans - The plan library: id, filename, name, notes, step_count, modified.
• GET /api/sequencer/plans/...
• POST /api/sequencer/plans/...
• GET /api/sequencer/plans/<id> - The plan's TOML and metadata.
• POST /api/sequencer/plans/<id>/delete - Delete (soft) a plan from the library.
• POST /api/sequencer/plans/estimate - Estimated duration of a plan: {"toml": "..."}.
• POST /api/sequencer/plans/from_structured - Compile the structured editor's document into plan TOML.
• POST /api/sequencer/plans/save - Save a plan into the library: {"id": "my-plan", "toml": "..."}.
• POST /api/sequencer/plans/validate - Compile a plan without saving it: {"toml": "..."} -> ok, step_count, the compiled steps, or the validation error.
• POST /api/sequencer/resume - Resume a manual pause (a weather suspend can only be resumed by the supervisor).
• POST /api/sequencer/resume_run - Resume an interrupted run from its checkpoint: {"plan_id": "..."}.
• POST /api/sequencer/start - Start a run from the library ({"plan_id": "my-plan"}) or from inline TOML ({"toml": "..."}). Returns run_id, plan_name, step_count. Refused while a run is active.
• GET /api/sequencer/state - The running or last run: state (idle / running / paused / stopping / stopped / succeeded / failed), plan name, run id, current_step / total_steps, error, outcome (label, subs, targets) and the journal (every step event with timestamps).
• POST /api/sequencer/stop - Stop the active run. The plan's on_end phase runs (park / close cover if authored); the state goes stopping -> stopped.
• GET /api/sequencer/templates - Saved sequence templates (settings minus targets).
• POST /api/sequencer/templates/delete - Delete a template by name.
• POST /api/sequencer/templates/load - Load a template by name.
• POST /api/sequencer/templates/save - Save a template: name, doc.

skyhunter

• GET /api/skyhunter/... Query: maxmag, q, cat, limit, id, ra, dec, radius, minalt, hours, minel, visible.
• GET /api/skyhunter/catalog-status
• POST /api/skyhunter/custom Body: elements.
• GET /api/skyhunter/field Query: ra, dec, radius.
• GET /api/skyhunter/object Query: id.
• GET /api/skyhunter/passes Query: hours, minel, visible, id.
• GET /api/skyhunter/search Query: q, cat, limit.
• GET /api/skyhunter/tonight Query: cat, minalt, limit.

solo

• GET /api/solo/last

state

• GET /api/state - One snapshot of everything: the safety verdict (safety.state SAFE / WARNING / UNSAFE / UNKNOWN / DISABLED with reasons), the Solo sensor values, site, optics and module states.

system

• POST /api/system/terminate - Shut the service down cleanly (devices disconnected first). Body must be {"confirm": "SHUTDOWN"}.

version

• GET /api/version - Build, version, edition, product name and the Pro capability map. Always reachable, even before activation.

Notes

• A route that is not in this build answers 404; the page you are reading was generated from the same build.
• Every command lands in the audit log (GET /api/audit/recent) with its result, so a night driven by an agent can be reviewed step by step.