HTTP API

HTTP API

NyxScope exposes a JSON HTTP API on port 8765 for status, control, message tails, audio streaming, and IQ streaming. It runs always-on alongside the Tauri GUI and also runs standalone in --headless-api mode (no GUI).

Useful for: Home Assistant integrations, Node-RED flows, custom dashboards, CLI tooling, headless deployments on a server with no display.

• Conventions
• Status + health
• Device control
• Scanner control
• Decoded messages
• Trunking
• HD Radio
• Satellite decoders
• Bluetooth LE
• Signal identification
• Aircraft (ADS-B)
• LoRa
• IQ recording + cases
• Talkgroups
• Channel banks
• Spectrum + waterfall
• Events stream
• Settings
• Debug
• Common patterns

Conventions

• Base URL: http://127.0.0.1:8765
• Auth: none. The server binds to localhost by default — anything on your machine can call it. To expose remotely, put it behind a reverse proxy with auth.
• Methods: mostly GET for reads, POST for actions. JSON request bodies; JSON responses.
• Errors: non-2xx status code, body is {"error": "message"}.

Status + health

Method	Path	Description
GET	/api/health	Liveness check. Returns {"ok": true} if the API is up.
GET	/api/scan/status	Scanner state (running / locked / discovery), active range, current frequency.
GET	/api/device/status	Connected SDR info: model, sample rate, gain, frequency.
GET	/api/vfo/states	All VFOs: frequency, mode, squelch, mute, audio level, decoder badge.

curl http://127.0.0.1:8765/api/scan/status

Device control

Method	Path	Description
GET	/api/devices	List discovered SDRs (USB-attached + network).
GET	/api/device/mdns_scan	Re-trigger mDNS auto-discovery for network SDRs.
POST	/api/device/connect	Body: {"device_id": "..."}. Connect to the named device.
POST	/api/device/disconnect	Disconnect the current SDR.
POST	/api/device/test	Probe a device without connecting.
POST	/api/device/gain	Body: {"gain": 30.0} (dB).
POST	/api/device/ppm	Body: {"ppm": 12}. Frequency correction.
POST	/api/device/sample_rate	Body: {"rate": 2400000} (Hz).
POST	/api/device/hackrf_amp	Body: {"enabled": true}. HackRF RF amp toggle.
POST	/api/scanner/squelch	Body: {"squelch": -45.0} (dB).
GET	/api/slots	List active SDR slots (multi-SDR mode).
GET	/api/instances	List running NyxScope instances.
POST	/api/receiver_location	Body: {"lat": ..., "lon": ...}. Set receiver position (used by satellite az/el + maps).

Scanner control

Method	Path	Description
POST	/api/scan/start	Body: {"ranges": ["FM Broadcast"]} (optional — defaults to active).
POST	/api/scan/stop	Halt scanning.
POST	/api/scan/lock	Body: {"frequency_hz": 96100000, "mode": "wfm"}. Lock onto a specific frequency.
POST	/api/scan/unlock	Release the locked frequency, resume scan.
POST	/api/scan/adsb	Switch to ADS-B mode.
POST	/api/scan/ais	Switch to AIS mode.
POST	/api/scan/acars	Switch to ACARS mode.
POST	/api/scan/aero	Switch to Aero (Inmarsat ACARS) mode.
POST	/api/scan/ble	Switch to Bluetooth LE scan mode.
POST	/api/scan/lora	Body: {"region": "US915"} (optional).
POST	/api/scan/identify_protocol	Auto-identify the digital mode at the locked frequency.
POST	/api/scanner/max-vfos	Body: {"max": 8}. Per-instance VFO ceiling.

VFO control

Method	Path	Description
GET	/api/vfo/states	All VFOs with current state.
GET	/api/vfo/diagnostics	Per-VFO decoder diagnostics.
GET	/api/vfo/:id/rds	RDS data for a specific VFO (WFM only).
POST	/api/vfo/:id/volume	Body: {"volume": 0.75}.
POST	/api/vfo/:id/mute	Body: {"muted": true}.
POST	/api/vfo/:id/audio_agc	Body: {"enabled": true}.

Decoded messages

NyxScope tracks decoded messages by category. All endpoints support ?since=<cursor> for incremental polling.

Method	Path	Description
GET	/api/decoded_messages	Multimon-ng output: POCSAG, FLEX, CTCSS/DCS, DTMF, EAS, etc.
GET	/api/protocol_messages	Non-multimon decoders: APRS, AIS, ACARS, VDL2, native decoders.
GET	/api/rtl433_messages	rtl_433 sensor messages — smart meters, weather stations, TPMS, etc.
GET	/api/intercept_results	Signal classification + protocol identification results.

# Tail FLEX/POCSAG pager messages since cursor 0
curl http://127.0.0.1:8765/api/decoded_messages?since=0

The response includes a cursor field — pass that as since=<cursor> next time to get only new messages.

Trunking

Method	Path	Description
POST	/api/trunking/start	Body: {"system": "..."}. Activate a configured trunked system.
POST	/api/trunking/stop	Stop trunking; return to scan mode.
POST	/api/trunking/lock	Lock onto a specific talkgroup (hold it, ignore other grants).
GET	/api/trunking/status	Active system, current TG, source ID, encryption flag.
GET	/api/trunking/calls	Call history (recent grants).
POST	/api/trunking/import	Body: JSON or CSV with talkgroup / system definitions.
POST	/api/trunking/zone/active	Set the active zone.
POST	/api/trunking/zone/upsert	Create or update a zone.
POST	/api/trunking/zone/delete	Delete a zone.

Discovery

Method	Path	Description
POST	/api/trunking/discovery/start	Body: {"bands": ["800 MHz PS"]} (optional).
POST	/api/trunking/discovery/stop
GET	/api/trunking/discovery/snapshot	Current candidates + confirmed CCs in one Vec.
GET	/api/trunking/discovery/results	Confirmed CCs only.
POST	/api/trunking/discovery/clear	Wipe candidates + confirmed list.
GET	/api/trunking/discovery/log	Persistent discovery log (every CC ever confirmed).
POST	/api/trunking/discovery/log/clear	Clear the persistent log.
POST	/api/trunking/discovery/delete	Remove one logged discovery.
POST	/api/trunking/discovery/notes	Attach a note to a logged discovery.
POST	/api/trunking/discovery/identify	Re-run system identification on a logged CC.
POST	/api/trunking/discovery/promote	Promote a discovery into a configured trunked system.

HD Radio

Method	Path	Description
GET	/api/hd_radio/status	Sync state, current program, BER/PER, station info.
GET	/api/hd_radio/messages	PSD/SIS history (title/artist changes, station name).
GET	/api/hd_radio/check	Whether nrsc5 is available + correctly configured.
GET	/api/hd_radio/aas/:filename	Album-art / logo files sent by the station.

Satellite decoders

Each satellite decoder follows the same shape: status, enable, and (where it produces messages) messages / clear. check reports whether the decoder's sidecar or feature pack is installed.

Method	Path	Description
GET	/api/stdc/status · /api/stdc/messages	Inmarsat STD-C state + decoded EGC/safety messages.
POST	/api/stdc/enable · /api/stdc/clear	Enable/disable; clear the message buffer.
GET	/api/stdc/check	Decoder availability.
GET	/api/iridium/status · /api/iridium/messages	Iridium burst decoder state + parsed frames (IRA ring alerts etc.).
POST	/api/iridium/enable · /api/iridium/clear · /api/iridium/quick-start	Enable, clear, or one-shot tune+enable.
GET	/api/iridium/check	Decoder availability.
GET	/api/aero/status · /api/aero/messages	Aero (Inmarsat ACARS) state + decoded messages.
POST	/api/aero/enable · /api/aero/clear	Enable/disable; clear.
GET	/api/aero/check · /api/aero/stderr	Availability; sidecar stderr for diagnostics.
GET	/api/gps/status	GPS L1 acquisition — PRNs heard, SNR, Doppler.
POST	/api/gps/enable · /api/gps/clear
GET	/api/glonass/status	GLONASS L1 acquisition.
POST	/api/glonass/enable · /api/glonass/clear
GET	/api/goes_lrit/status · /api/goes_lrit/check	GOES LRIT decoder state; SatDump availability.
POST	/api/goes_lrit/enable · /api/goes_lrit/satellite	Enable; select GOES satellite (affects az/el pointing).

Bluetooth LE

Method	Path	Description
POST	/api/scan/ble	Start the BLE advertising scanner (2.4 GHz channels 37/38/39).
GET	/api/ble/devices	Discovered devices — MAC, vendor, RSSI, parsed advertisements.
GET	/api/ble/status	Scanner state.
POST	/api/ble/clear	Forget discovered devices.
POST	/api/ble/file	Offline analysis: decode BLE advertisements from an IQ file.

Signal identification

Method	Path	Description
POST	/api/vfo/:id/identify	Classify the signal on a live VFO (scan mode only).
POST	/api/signal_id/file	Robust offline analysis of a recorded IQ file.
GET	/api/signal_id/fingerprints	Stored signal fingerprints (also /:id for one).
POST	/api/signal_id/fingerprints/match	Match a capture against stored fingerprints.
POST	/api/signal_id/segment_bursts	Split a capture into individual bursts.
POST	/api/signal_id/polyphase_extract	Extract a sub-channel from a wideband capture.
GET	/api/spectrum_occupancy	Long-run band-occupancy statistics.

Aircraft (ADS-B)

Method	Path	Description
GET	/api/aircraft/lookup	Query: ?icao=ABCDEF. Returns registration, type, operator.

Live aircraft position data is in /api/protocol_messages (filter by protocol=adsb or protocol=uat).

LoRa

Method	Path	Description
GET	/api/lora/messages	Decoded LoRa packets + LoRaWAN MAC parsing.
POST	/api/lora/clear	Clear the message buffer.
GET	/api/lora/regions	List supported regional plans (US915, EU868, etc.).

IQ recording + cases

Method	Path	Description
POST	/api/iq_recording/start · /api/iq_recording/stop	Record raw IQ to disk.
GET	/api/iq_recording/status	Active IQ recording state.
POST	/api/recording/iq/capture	One-shot timed IQ capture.
POST	/api/recording/iq/stop	Stop a one-shot capture early.
GET/POST	/api/recordings/annotations	Notes attached to recordings (also /:id).
GET/POST	/api/cases	Investigation cases — group captures, decodes, and notes (also /:id, /:id/attach, /attachments/:att_id).

Talkgroups

Method	Path	Description
GET	/api/talkgroups	All TGs across all systems.
GET	/api/talkgroups/systems	Configured trunked systems.
POST	/api/talkgroups/update	Update a single TG (priority, alpha tag, etc.).
POST	/api/talkgroups/delete-system	Body: {"name": "Pinellas P25"}.
GET	/api/talkgroups/export	Dump all TGs to JSON for backup.
POST	/api/talkgroups/import	Bulk import from JSON/CSV.

Channel banks

Method	Path	Description
GET	/api/channels/banks	List all channel banks.
POST	/api/channels/banks/create	Body: {"name": "Local Repeaters"}.
POST	/api/channels/import	Import channels from CHIRP / CSV / RadioReference.
POST	/api/channels/scan/start	Start scanning a bank.
POST	/api/channels/scan/stop
GET	/api/channels/bank-scan-config	Current bank-scan configuration.

Spectrum + waterfall

Method	Path	Description
GET	/api/spectrum	Current FFT snapshot (frequency bins + dBFS magnitudes).

Events stream

Method	Path	Description
GET	/api/events	Server-Sent Events stream — every scanner / VFO / decoder / trunking event in real time.

# Tail every event the app emits
curl -N http://127.0.0.1:8765/api/events

Each event is a JSON object with a type field (scanner-state, vfo-update, frequency-found, talkgroup-active, hd-radio-status, etc.) and event-specific payload. Useful for live dashboards.

Settings

Method	Path	Description
GET	/api/settings	Full settings document.
POST	/api/settings	Replace settings (also accepts partial JSON for diff-merge).

Blacklist

Method	Path	Description
GET	/api/blacklist	Blocked frequencies.
POST	/api/blacklist/add	Body: {"frequency_hz": 152300000}.
POST	/api/blacklist/remove
POST	/api/blacklist/clear	Wipe permanent blacklist.
POST	/api/blacklist/clear-temporary	Wipe session blacklist only.

Transcription

Method	Path	Description
POST	/api/transcription/start	Body: {"vfo_id": 0, "engine": "whisper-local"}.
POST	/api/transcription/stop
GET	/api/transcription/status	Active jobs + queue depth.
GET	/api/transcription/transcripts	Completed transcripts.

Debug

These are for diagnostics, not stable contracts. Format may change between releases.

Method	Path	Description
GET	/api/debug/stats	Atomic counters — sync events, frames decoded, throughput, etc.
GET	/api/debug/log	In-memory log buffer.
GET	/api/debug/log/tail	Last N log lines.
GET	/api/debug/dsd_stderr	Digital-voice decoder stderr (trunking voice path).
GET	/api/debug/locked_dsd_stderr	Digital-voice decoder stderr (locked-frequency path).
GET	/api/debug/p2_voice_stderr	P25 Phase 2 voice decoder stderr.
GET	/api/debug/provoice_stderr	ProVoice decoder stderr.
GET	/api/debug/vdl2_stderr	dumpvdl2 sidecar stderr.
GET	/api/debug/rtl433_stderr	rtl_433 sidecar stderr.
GET	/api/debug/multimon_raw	multimon-ng raw output.
GET	/api/debug/p25_acq · /api/debug/p25_squelch	P25 acquisition + squelch state.
GET	/api/debug/classifications	Signal-classification raw scores.
GET	/api/debug/noise_floor	Adaptive noise-floor tracker state.
GET	/api/debug/trunking/per_cc_stats	Per-CC TSBK counts, sync stats.

Common patterns

Poll for new messages

cursor=0
while sleep 1; do
  resp=$(curl -s "http://127.0.0.1:8765/api/decoded_messages?since=$cursor")
  cursor=$(echo "$resp" | jq .cursor)
  echo "$resp" | jq .messages
done

Listen to events live

curl -N http://127.0.0.1:8765/api/events | while read line; do
  echo "$line" | jq .
done

Connect a device + lock to a frequency

curl -X POST http://127.0.0.1:8765/api/device/connect \
  -H "Content-Type: application/json" \
  -d '{"device_id": "rtl-sdr:0"}'

curl -X POST http://127.0.0.1:8765/api/scan/lock \
  -H "Content-Type: application/json" \
  -d '{"frequency_hz": 96100000, "mode": "wfm"}'

Headless deployment

Run NyxScope with no GUI:

nyxscope.exe --headless-api

The API is the only surface. Useful for Pi-hole-style deployments where the SDR is on a server elsewhere on the LAN.

---

For deeper diagnostics, see Troubleshooting. For the conceptual overview of what NyxScope does, see the README and MANUAL.md.