Direct HTTP API

Use Direct HTTP to read a device's state, change its configuration, stream motion events, or collect raw CSI on the local network.

Direct HTTP uses the shared device protocol. MQTT uses the same resources, operations, validation rules, and result codes. Framing and delivery differ. Read the capability catalog to learn what the connected firmware supports.

Connect to a device

Direct HTTP listens on TCP port 62587 and uses the versioned base path /espectre/v1. The stable mDNS hostname is espectre-<device-id>.local. Clients can also connect to the device's private IP address.

Every request, including requests from command-line clients, must include an allowed Origin header. Published firmware accepts https://espectre.dev.

curl -H 'Origin: https://espectre.dev' \
  http://espectre-<device-id>.local:62587/espectre/v1/capabilities

After connecting, read capabilities.protocol_version, resources, operations, and events. Treat the returned catalog as authoritative. Firmware compatible with v1 may add fields and capabilities, so clients must ignore additions they do not understand.

Read resources

A successful GET returns the resource object directly. Frontends and custom builds can expose different resource sets; check capabilities before requesting one.

Path	Purpose
`/health`	Online state, uptime, and monotonic timestamp
`/device`	Stable identity, label, frontend, firmware, chip, and CSI profile
`/capabilities`	Negotiated resources, operations, events, and CSI support
`/sensing`	Detector state, readiness, profile, threshold, filtering, and traffic mode
`/wifi`	Connection and radio state without stored credentials
`/wifi/access-points`	Wi-Fi scan progress and the latest access-point results
`/mqtt`	Redacted Native MQTT configuration
`/ota`	Firmware update state and resolved release information
`/diagnostics`	On-demand runtime, CSI, memory, and transport diagnostics
`/devices`	Nearby ESPectre devices found through mDNS and DNS-SD

Add /espectre/v1 before each path in the table. The application contract defines every field and lists the resources supported by each frontend.

Run operations

Send a JSON object for requests with a body and set Content-Type: application/json. The device rejects unknown fields. A completed mutation returns HTTP 200; queued or disruptive work returns 202 after dispatch.

curl -X PATCH \
  -H 'Origin: https://espectre.dev' \
  -H 'Content-Type: application/json' \
  -d '{"detector":"high_accuracy","threshold":0.5}' \
  http://espectre-<device-id>.local:62587/espectre/v1/sensing

Method and path	Operation
`PATCH /device`	Set or clear the device label
`PATCH /sensing`	Update supported detector and traffic settings
`POST /sensing/calibrations`	Start recalibration
`POST /wifi/scans`	Start an access-point scan
`PUT` or `DELETE /wifi/bssid`	Set or clear the preferred access point
`DELETE /wifi/credentials`	Return Native firmware to provisioning
`PATCH` or `DELETE /mqtt`	Set or clear the Native broker configuration
`POST /ota/checks`	Check a firmware channel
`POST /ota/updates`	Start an update from a firmware channel

Every mutation returns a result object. Some operations also return output in data.

{"accepted":true,"code":"ok","message":"operation accepted","data":{}}

Follow live events

GET /espectre/v1/events opens the JSON Server-Sent Events stream. It publishes the resource snapshots and events listed in capabilities, which can include health, device, sensing, wifi, ota, motion, and fault. The stream has no replay. After reconnecting, read the resources again to refresh local state.

curl -N -H 'Origin: https://espectre.dev' \
  http://espectre-<device-id>.local:62587/espectre/v1/events

A motion payload contains the monotonic evaluation timestamp, state, and detector score:

{"timestamp_ms":42000,"state":"motion","score":0.7312}

Collect raw CSI

GET /espectre/v1/csi opens one exclusive binary CSI collection session when capabilities.features.csi is true. Closing the response ends collection. While the stream is active, sensing readiness is false and derived events are paused. Conflicting mutations return HTTP 409.

CSI uses binary framing. The response contains ordered CSI V8 records with the established 60-byte little-endian HTTP prefix. Follow the framing contract when parsing or storing records.

Handle errors and security

Check the HTTP status and Content-Type before parsing a response. Application errors use the JSON result object. Malformed framing, Origin rejection, oversized bodies, rate limiting, and service saturation can return plain text before application dispatch.

Direct HTTP is a trusted-LAN interface. Firmware binds it to the station network, enforces exact browser Origin allowlists and bounded resources, and never returns stored Wi-Fi or MQTT passwords. Keep the service off the public internet.

Protocol references

API.md defines every payload field, limit, status mapping, and versioning rule. DISCOVERY.md defines mDNS, DNS-SD, browser discovery, and the /devices resource.