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.

One protocol, two transports. MQTT uses the same resources, operations, validation rules, and result codes; only how messages travel differs. Read capabilities to see what the connected firmware supports.

Sections

Connect to a device

Devices announce themselves on the local network with mDNS and DNS-SD (IPv4). Browse _espectre._tcp.local. to find them.

Direct HTTP listens on TCP port 62587 under /espectre/v1. The hostname is espectre-<device-id>.local, or you can use the device's IP address.

Every request, even from command-line tools, needs 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

First read capabilities: protocol_version, resources, operations, and events tell you what the device supports. Newer v1 firmware may add fields, so ignore the ones you don't know.

Read resources

A successful GET returns the resource itself. Not every firmware has every resource, so check capabilities first.

Path	Purpose
`/health`	Online state, uptime, and monotonic timestamp
`/device`	Stable identity, label, frontend, firmware, chip, and CSI profile
`/capabilities`	Supported resources, operations, events, and CSI features
`/sensing`	Detector state, readiness, profile, threshold, filtering, and traffic mode
`/wifi`	Connection and radio state (never the stored password)
`/wifi/access-points`	Wi-Fi scan progress and the latest access-point results
`/mqtt`	Native MQTT settings, without the password
`/ota`	Firmware update state and release information
`/diagnostics`	The list of available values, or the values you select with `fields`
`/devices`	Nearby ESPectre devices found through mDNS and DNS-SD

Add /espectre/v1 before each path. The API reference defines every field and which firmware supports each resource.

Without fields, diagnostics lists the available values with their types and units. Select values with {"fields":["traffic_tx_pps","csi_hw_error_total"]}, or ["*"] for all. In a GET request, pass the array URL-encoded in the fields query parameter. The answer includes timestamp_ms and uptime; missing values are null.

Run operations

Send request bodies as JSON with Content-Type: application/json. Unknown fields are rejected. A completed change returns HTTP 200; work that is queued, or that disconnects the device, returns 202 once started.

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 change returns a result object, sometimes with extra output in data.

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

Follow live events

GET /espectre/v1/events opens a Server-Sent Events stream in JSON. It sends the resource updates and events listed in capabilities, such as health, device, sensing, wifi, ota, motion, and fault. Missed events are not resent: after reconnecting, read the resources again.

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

A motion event has the time of the decision, the state, and the score:

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

Collect raw CSI

GET /espectre/v1/csi opens a binary CSI stream if capabilities.features.csi is true. Only one stream can be open at a time, and closing it ends the capture. While it is open, motion and other derived events stop. Capture and traffic keep running, and resource events stay published. Changes that conflict with it return HTTP 409.

The CSI stream is binary. It contains CSI V8 records in order, each with a 60-byte little-endian header. See the API reference for the exact format.

Handle errors and security

Check the HTTP status and Content-Type before parsing. Application errors come as a JSON result object. Malformed requests, a rejected Origin, bodies that are too large, rate limits, and an overloaded device can return plain text instead.

Direct HTTP is meant for a trusted local network. It listens only on the Wi-Fi network, accepts only listed browser origins, limits resource use, and never returns stored Wi-Fi or MQTT passwords. Never expose it to the internet.

Protocol references

The API reference defines every field, limit, status code, and versioning rule. The discovery reference covers mDNS, DNS-SD, browser discovery, and the /devices resource.

SDK guide