Sky Scan API

The Sky Scan API drives the rotor through a systematic grid pattern while collecting RSSI (Received Signal Strength Indicator) readings from the SDR at each position. This produces a map of signal levels across the sky, useful for locating interference sources, characterizing antenna patterns, and building sky noise baselines.

List Sessions

Returns all scan sessions, ordered by most recent first.

GET /api/skyscan/sessions

Response

[
  {
    "id": 3,
    "rotor_id": 1,
    "status": "completed",
    "az_start": 0.0,
    "az_end": 360.0,
    "el_start": 18.0,
    "el_end": 65.0,
    "step_deg": 2.0,
    "rssi_iterations": 10,
    "total_points": 4320,
    "completed_points": 4320,
    "progress_pct": 100.0,
    "started_at": "2026-02-14T02:00:00",
    "finished_at": "2026-02-14T05:42:00",
    "notes": null
  }
]

Session Status Values

Status	Description
pending	Session created, scan not yet started
running	Rotor is moving and collecting data
paused	Scan suspended, rotor holds position
completed	All grid points measured
cancelled	Scan stopped by user before completion

---

Start Scan

Begin a new sky scan session. Defines the azimuth and elevation bounds, step size, and number of RSSI samples to average at each grid point. The rotor must be configured and reachable via rotctld.

POST /api/skyscan/start

Request Body

{
  "rotor_id": 1,
  "az_start": 0.0,
  "az_end": 360.0,
  "el_start": 18.0,
  "el_end": 65.0,
  "step_deg": 2.0,
  "rssi_iterations": 10
}

Field	Type	Default	Description
rotor_id	int	—	ID of the rotor configuration to use (required)
az_start	float	0.0	Starting azimuth in degrees
az_end	float	360.0	Ending azimuth in degrees
el_start	float	18.0	Starting elevation in degrees
el_end	float	65.0	Ending elevation in degrees
step_deg	float	2.0	Angular step between grid points in degrees
rssi_iterations	int	10	Number of RSSI samples to average at each point

Response

Returns the created session object (same shape as the list endpoint).

{
  "id": 4,
  "rotor_id": 1,
  "status": "pending",
  "az_start": 0.0,
  "az_end": 360.0,
  "el_start": 18.0,
  "el_end": 65.0,
  "step_deg": 2.0,
  "rssi_iterations": 10,
  "total_points": 4320,
  "completed_points": 0,
  "progress_pct": 0.0,
  "started_at": null,
  "finished_at": null,
  "notes": null
}

Errors

Status	Detail
404	Rotor not found
503	Cannot connect to rotctld
400	Rotor does not support RSSI

Tip

The total_points field is computed from the grid dimensions: the number of azimuth steps multiplied by the number of elevation steps. A full-sky scan at 2-degree resolution produces (360 / 2) * ((65 - 18) / 2) → roughly 4,000+ data points. Smaller step sizes give higher resolution but take proportionally longer.

Caution

The rotor must be connected and responding via rotctld before starting a scan. The endpoint probes the controller for RSSI capability and will reject the request if the rotor does not support signal strength readings.

---

Get Session

Retrieve details and current progress for a specific scan session.

GET /api/skyscan/{session_id}

Parameters

Name	Type	Required	Description
session_id	int	Yes	Scan session ID (path parameter)

Response

Returns a single session object (same shape as the list endpoint).

Errors

Status	Detail
404	Scan session not found

---

Get Data Points

Retrieve all collected scan data points for a session, ordered by measurement sequence.

GET /api/skyscan/{session_id}/data

Parameters

Name	Type	Required	Description
session_id	int	Yes	Scan session ID (path parameter)

Response

[
  {
    "azimuth": 0.0,
    "elevation": 18.0,
    "rssi_reads": 10,
    "rssi_average": -92,
    "rssi_current": -91,
    "measured_at": "2026-02-14T02:00:15"
  },
  {
    "azimuth": 2.0,
    "elevation": 18.0,
    "rssi_reads": 10,
    "rssi_average": -94,
    "rssi_current": -95,
    "measured_at": "2026-02-14T02:00:22"
  }
]

Data Point Fields

Field	Type	Description
azimuth	float	Rotor azimuth in degrees at measurement time
elevation	float	Rotor elevation in degrees at measurement time
rssi_reads	int	Number of RSSI samples taken at this position
rssi_average	int	Mean RSSI across all samples (dBm)
rssi_current	int	Last RSSI sample value (dBm)
measured_at	string or null	ISO 8601 timestamp of the measurement

Errors

Status	Detail
404	Scan session not found

Tip

The data points form a grid that can be plotted as a heatmap with azimuth on the x-axis and elevation on the y-axis. The rssi_average field is generally more reliable than rssi_current since it smooths out transient noise by averaging across rssi_iterations samples.

---

Pause Scan

Pause a running scan session. The rotor holds its current position and no further data points are collected until the session is resumed.

POST /api/skyscan/{session_id}/pause

Parameters

Name	Type	Required	Description
session_id	int	Yes	Scan session ID (path parameter)

Response

{
  "status": "pausing",
  "session_id": 4
}

Errors

Status	Detail
404	Scan session not found
400	Cannot pause scan in ‘<current_status>’ state (must be running)

---

Resume Scan

Resume a paused scan session. The rotor picks up from where it left off and continues collecting data points.

POST /api/skyscan/{session_id}/resume

Parameters

Name	Type	Required	Description
session_id	int	Yes	Scan session ID (path parameter)

Response

{
  "status": "resuming",
  "session_id": 4
}

Errors

Status	Detail
404	Scan session not found
400	Cannot resume scan in ‘<current_status>’ state (must be paused)

---

Cancel Scan

Cancel a running, paused, or pending scan session. The rotor stops and the session is marked as cancelled. Already-collected data points are preserved.

POST /api/skyscan/{session_id}/cancel

Parameters

Name	Type	Required	Description
session_id	int	Yes	Scan session ID (path parameter)

Response

{
  "status": "cancelling",
  "session_id": 4
}

Errors

Status	Detail
404	Scan session not found
400	Cannot cancel scan in ‘<current_status>’ state (must be running, paused, or pending)

Note

Cancelling a session does not delete any data points already collected. You can still retrieve partial scan data via the data points endpoint. This is useful if you need to abort a long scan but want to keep what was measured so far.

---

WebSocket: Real-Time Progress

A WebSocket endpoint provides live progress updates during an active scan session.

ws:///ws/skyscan/{session_id}

Message Format

Each message is a JSON object pushed to the client as a new data point is measured or the session status changes.

{
  "session_id": 4,
  "status": "running",
  "point": {
    "azimuth": 14.0,
    "elevation": 20.0,
    "rssi_reads": 10,
    "rssi_average": -88,
    "rssi_current": -87,
    "measured_at": "2026-02-14T02:05:30"
  },
  "progress_pct": 12.3,
  "completed": 531,
  "total": 4320
}

Field	Type	Description
session_id	int	The scan session being reported on
status	string	Current session status
point	object or null	The most recently measured data point (null on status-only updates)
progress_pct	float	Completion percentage (0.0 → 100.0)
completed	int	Number of data points collected so far
total	int	Total number of grid points in the scan

Tip

Use the WebSocket feed to render a live heatmap in the UI. Each incoming point message adds one cell to the grid. The progress_pct field drives progress bar updates without requiring a separate polling request.