HTTP API
Every board has a small JSON API. Requests send form-encoded bodies
(application/x-www-form-urlencoded) and get JSON back.
Authentication
Once an admin password is set, every
endpoint needs it (HTTP Basic, user admin) except /stream.sdp,
/usbip.sh and /usbip.ps1:
curl -u admin:PASSWORD http://etherjax-XXXX.local/api/status
Scripts and curl work from anywhere. Browsers can call a board's API from
pages served by that board or by another board it has found on the network.
A browser POST from any other site is refused.
Endpoints
| Endpoint | |
|---|---|
GET /api/status | live state |
GET /api/config | saved settings |
POST /api/config | save settings and reboot (see below) |
POST /api/reboot | reboot |
POST /api/ota | body: a raw build/etherjax.bin. Installs it and reboots (see firmware updates) |
POST /api/password | password=… sets the admin password; password= removes it |
GET /api/auth | the credentials the calling page signed in with (same-origin only; the matrix uses it) |
GET /api/peers | this board and every other board found over mDNS: hostname, IP, role, name, stream |
GET /matrix | the routing matrix page |
Encoder
| Endpoint | |
|---|---|
GET /stream.sdp | the stream's SDP, for media players. No password. |
Decoder
| Endpoint | |
|---|---|
GET /api/streams | streams heard over SAP |
GET /api/route | the current group, port, source, link offset, media clock offset and detected stream channels |
POST /api/route | mcast=…&port=…, optionally source=, link_ms=, mclk_offset= and encoding=L16 or L24. Switches at once and saves. mcast= (empty) stops. source is the IP address of the sender to play; without it, the decoder takes the announced sender if only one announces that address, else the first sender it hears. mclk_offset and encoding default to the stream's announcement, else 0 and L24. |
GET /api/volume | {volume, volume_db, mute} |
POST /api/volume | volume=0…100 and/or mute=…. Applied at once, saved after 2 s. |
POST /api/volume_db | volume_db=-80…12 and/or mute=… |
POST /api/mute | mute=1, 0 or toggle |
Serial server
| Endpoint | |
|---|---|
GET /api/serial | the adapter, and each port's settings, clients and counters |
POST /api/serial | port=1…4 plus any of enabled, mode (raw or rfc2217), tcp_port, baud, data_bits, parity (none, odd, even, mark, space), stop_bits (1, 1.5, 2), label, allow. Applied at once and saved. |
USB/IP server
| Endpoint | |
|---|---|
GET /api/usbip | the device, the attached host, traffic and settings |
POST /api/usbip | enabled, allow. Applied at once and saved. detach=1 drops the attached host. |
GET /usbip.sh | the Linux host setup script. No password. |
GET /usbip.ps1 | the Windows host setup script. No password. |
See USB/IP server for using the scripts.
Saving settings
POST /api/config takes the same fields as the Settings form: role
(encoder, decoder, serial or usbip), hostname, name, mcast,
port, channels, link_ms, ext_link_ms, ptp_priority1, sap, static_ip, ip,
mask and gw. The board checks them, saves them and reboots.
sap and static_ip are checkboxes: present means on, absent means off. To
change one setting, read GET /api/config and send it back whole.
Examples
# Switch a decoder to another stream
curl -u admin:PASSWORD -d 'mcast=239.200.171.18&port=5004&source=192.0.2.10' http://etherjax-ab12.local/api/route
# Set a decoder's volume to -6 dB
curl -u admin:PASSWORD -d 'volume_db=-6' http://etherjax-ab12.local/api/volume_db
# Update firmware
curl -u admin:PASSWORD --data-binary @build/etherjax.bin http://etherjax-ab12.local/api/ota