HTTP and WebSocket API
Every route of the connector's JSON API, the settings, the status and the live WebSocket.
Everything the web UI does goes through this API, on port 80 and over HTTPS on port 443. GET /api lists every route with its access level.
Login
Use one of these.
| Way | How | Notes |
|---|---|---|
| Password | HTTP basic auth, any user name | Every request that changes something also needs the header X-DeckConnector: 1 |
| Session | POST /api/login with {"password": "..."} and X-DeckConnector: 1 | Sets a cookie. Ends after 12 hours without use, or with POST /api/logout |
| API key | Authorization: Bearer KEY | No X-DeckConnector header needed. Rights below |
| Setup Wi-Fi | A client on the setup Wi-Fi | Rights of the password. Changes still need X-DeckConnector: 1 |
curl -u admin:PASSWORD http://192.168.1.50/api/status
curl -u admin:PASSWORD -H 'X-DeckConnector: 1' -X PUT -d '{"brightness": 60}' http://192.168.1.50/api/config
curl -H 'Authorization: Bearer KEY' http://192.168.1.50/api/statusAccess levels
Each route has one level, in the last column of the tables below. API keys explains the levels.
No API key changes admin_pass, setup_done or qr_login. Those answer 403.
While the deck shows the password or the setup login code, or the setup Wi-Fi is open, an API key gets 403 for the routes that act on a deck. The deck picture (/api/screen, its images, /api/screen.jpg) also answers 403 to an API key while the deck shows the password, in the menu or a setup page.
Errors
Errors are JSON with a matching HTTP status. error is English text. code, where present, stays the same when the text changes.
{"ok": false, "error": "not signed for this DeckConnector", "code": "ota_not_signed"}code | Meaning |
|---|---|
ota_too_short | The file is too short to be a firmware file |
ota_not_dbfw | Not a .dbfw file |
ota_not_signed | Not signed with this connector's key |
ota_wrong_target | For another device or part |
ota_too_old | Below the security level |
url_http_only | The URL must start with http:// or https:// |
no_releases | No releases to check yet |
rate_limited | GitHub limits the checks. Try again later |
unreachable | GitHub does not answer |
probe_no_connection | Nothing answers at this address |
probe_no_answer | The address takes the connection but sends nothing within 3 s |
probe_not_companion | Something answers, but it is not Companion Satellite |
strip_outside | The point is outside the touch strip |
busy | The connector is busy. Try again |
locked | Too many wrong passwords. The reply has retry in seconds, with status 429 |
paused | This address put a question on the deck that ended without a Yes less than a minute ago. Status 429, retry in seconds and Retry-After |
wrong_password | Wrong password |
needs_password | Needs the password, an API key is not enough |
passkey_host | Passkeys need HTTPS and a name |
passkey_refused | The connector did not accept the passkey |
Routes
Routes that act on a deck take ?deck=<serial> from decks in the status. Without it they act on the first deck. A deck that is not attached gets 404.
Login and password
| Route | What it does | Level |
|---|---|---|
POST /api/login | {"password": "..."}, sets the session cookie | open |
POST /api/logout | Ends the session | open |
POST /api/setup/claim | Before setup: a session without the password, see Password. 403 from another site's name, 409 with set up, claimed or too late | open |
POST /api/login/request | {"who": "iPhone · Safari"}, up to 48 characters. The deck asks someone to let this browser in. Answers {"id": "...", "s": 60}. 409 without a deck, 429 within 3 s of the last request or with paused | open |
GET /api/login/request/<id> | state is pending, accepted, denied, expired or used. With accepted the reply sets the session cookie once | open |
DELETE /api/login/request/<id> | Takes the request back | open |
POST /api/passkeys/challenge | {"login": true} for a login, false for a new passkey. Answers {"challenge": "<hex>"}. It works once, for 2 minutes, from this address. 30 per 10 s and address, else 429. Over HTTPS by name only, else 403 | open |
POST /api/login/passkey | The reply of navigator.credentials.get(), with id, clientDataJSON, authenticatorData and signature in base64url. The passkey must verify the user. Sets the session cookie. A refused passkey counts like a wrong password, an unknown or used challenge does not | open |
POST /api/password/show | The deck shows the password for 30 s. 409 without a deck, 429 with paused | open |
POST /api/password/reset | The deck asks for 60 s whether to reset everything. Answers {"ok": true, "s": 60}. 409 without a deck, 429 with paused | open |
DELETE /api/password/reset | Ends the question | open |
The open routes that do something need X-DeckConnector: 1.
Status and settings
| Route | What it does | Level |
|---|---|---|
GET /api | Every route with method, path and access | control |
OPTIONS /api/... | The CORS preflight for the origins in cors_origins | open |
GET /api/ws | The live WebSocket | control |
GET /api/status | State of the connector, see Status | control |
GET /api/config | Settings, see Settings. Secrets only show as wifi_pass_set, wifi2_pass_set and token_set | full |
PUT /api/config | Change settings. Send only the keys you change. The reply has restart and config | full |
POST /api/config | Companion's Setup under Surfaces › Discover: {"host": "...", "port": 16622} as application/json. During setup the connector connects at once, later the deck asks for 60 s | open |
GET /api/backup | The settings for a restore. ?secrets=1 adds the passwords | admin |
PUT /api/setup | {"step": 3} keeps the web wizard's step, {"step": 0} ends it | full |
POST /api/reboot | Restart | full |
POST /api/sound | {"sound": "find"} plays ready, connected, lost or find. volume 0 to 100 overrides the setting. Without it, find plays at 60 at least. 409 while speaker is false, and for every sound but find while the volume is 0 | control |
DELETE /api/ap | Closes the setup Wi-Fi | full |
POST /api/reset | Factory reset, then a restart | admin |
Deck
| Route | What it does | Level |
|---|---|---|
GET /api/screen | What the deck shows, see Screen | control |
GET /api/screen/<id>.jpg | One image of that picture | control |
GET /api/screen.jpg | The whole picture as one JPEG | control |
POST /api/input | Press, turn or touch, see Input | control |
GET /api/input/log | The newest 400 of the last 2000 inputs, oldest first. ?since=<seq> for newer ones, ?before=<seq> for older ones | control |
POST /api/menu | Open the deck menu. 409 without a deck | control |
DELETE /api/menu | Close the deck menu, the password, the reset question and a login request | control |
POST /api/screen | {"on": false} turns every deck dark now, {"on": true} lights them again. No press is swallowed | full |
POST /api/deck/reconnect | Turn the USB port off and on. ?off_s=N (1 to 600) keeps it off for N seconds | control |
POST /api/deck/stall | Stop the image output as a hung deck would, for tests | full |
POST /api/sound/stream | The body is raw PCM: 16 kHz, mono, 16 bit little-endian, with Content-Length. For a stream of unknown length, send a larger Content-Length (at most 2147483647) and shut down the sending side of the connection at the end. Plays it at the volume setting and answers {"ok": true, "stopped": false} when it has played. While data is late it plays silence. stopped is true when find, a newer stream, speaker false or 5 seconds without data ended it. The connector skips other sounds while it plays. A reset connection stops it at once. The connector buffers 3 seconds, so send no more than a second ahead. 409 while speaker is false, 503 when the codec fails. No CORS headers | control |
POST /api/sound/selftest | Play find and record it with the connector's microphone, for tests. Three controls: another pitch (1500 Hz) in the same recording, find at volume 0, and find with the amplifier off. heard is true when the tone is more than 10 times each of them. Optional: volume 1 to 100 (60), gain 0 to 42 dB (24). Takes about 6 seconds. 503 with the reason when a run fails | full |
Sources and pairing
| Route | What it does | Level |
|---|---|---|
POST /api/sources/retry | {"host": "..."} with a server URL or the Satellite address. Connects now instead of after the wait | control |
POST /api/sources/probe | {"addr": "host:port", "pin": ""} tries Companion once and returns its version, or a code for what failed (probe_no_name, probe_refused, probe_timeout, probe_no_connection, probe_cert, probe_tls, probe_not_ws, probe_no_answer, probe_not_companion). About 6 s at most. The web page tries several forms of an address in turn | full |
GET /api/companion/found | Companions that announce Satellite over mDNS. The first call starts a 2 s search | full |
POST /api/dock | Pairing, see Pairing | full |
DELETE /api/pairing/denied/<ip> | Takes a host off the denied list | full |
Matter
See Matter. While matter.running is false, GET /api/matter, {"pair": true}, {"show": true} and POST /api/matter/press answer 409.
| Route | What it does | Level |
|---|---|---|
GET /api/matter | qr (the text of the QR code), code (the pairing code) and qr_bits | full |
POST /api/matter | {"on": true} starts Matter at once, {"on": false} takes effect after a restart. {"pair": true} opens pairing for 15 minutes. {"show": true} shows the code on the decks for 60 s | full |
DELETE /api/matter | Removes every Matter app, makes a new pairing code and restarts | full |
POST /api/matter/press | For tests: the body of POST /api/input, sent to Matter alone. No host, menu or input log sees it | full |
Network
| Route | What it does | Level |
|---|---|---|
GET /api/wifi/scan | Networks in reach, strongest first: ssid, bssid, rssi, channel, open. 2.4 GHz only. Takes 2 to 3 s | full |
POST /api/wifi/join | {"ssid": "...", "pass": "...", "bssid": ""}. Answers 202. network.wlan.join in the status goes from testing to ok or failed within 15 s | full |
Firmware
| Route | What it does | Level |
|---|---|---|
POST /api/ota | A signed .dbfw file as the body. Goes into the next slot and restarts. ?slot=N writes into slot N, ?boot=0 keeps the running firmware | full |
POST /api/ota/url | {"url": "https://..."}, the connector loads the file itself, also behind a redirect. Progress comes over the WebSocket | full |
POST /api/ota/inspect | The first 144 bytes of a file. Answers target, version, length, sha256, and ok with error | full |
GET /api/update/check | {"current": "v1.0.0", "latest": null, ...} | full |
GET /api/slots | The four slots with state, version, running, next, bootable and why_not | full |
POST /api/slots/<n>/boot | Restart into slot N. 409 when it cannot start | full |
GET /api/frontend | The web page in use: source (partition or builtin), api, and version for an uploaded one | control |
PUT /api/frontend | A signed web page as the body. Served at once | full |
DELETE /api/frontend | Back to the page in the firmware | full |
GET /api/boot | Bootloader and partition table. ?raw=bootloader or ?raw=ptable gives the bytes | full |
Access
| Route | What it does | Level |
|---|---|---|
GET /api/tokens | The API keys, name and right | admin |
POST /api/tokens | {"name": "home-assistant", "right": "control"}. Shows the key once. name has 1 to 23 letters, digits, - or _ | admin |
DELETE /api/tokens/<name> | Ends that key at once | admin |
DELETE /api/token | The key in the request ends itself. Home Assistant does this when you remove the integration | control |
GET /api/passkeys | The passkeys, with id, name and rp, the name each one works at | admin |
POST /api/passkeys | The reply of navigator.credentials.create(), with name, id, clientDataJSON, authenticatorData, publicKey (SPKI) and publicKeyAlgorithm (-7), binary parts in base64url. ES256 with user verification only, up to 8 | admin |
PUT /api/passkeys/<id> | {"name": "Laptop"}, 1 to 23 bytes | admin |
DELETE /api/passkeys/<id> | Removes that passkey | admin |
GET /api/cert | The HTTPS certificate as PEM | open |
GET /api/ca | The connector's CA as DER, to trust once. The deck shows its short code, https_ca in the status, but not while this address is paused | open |
PUT /api/tls | {"cert": "<PEM>", "key": "<PEM>"} checks your own certificate. With "apply": true it is kept and the connector restarts | admin |
DELETE /api/tls | Back to the connector's own certificate, with a restart | full |
Diagnostics
| Route | What it does | Level |
|---|---|---|
GET /api/log | The last 16 KB of the log as text. ?boot=prev for the start before | full |
GET /api/events | Events, newest first, 200 at most. ?before=<seq> for older ones, ?since=<unix time> to stop there, ?n= for fewer. Each has seq, at, since_s, boot, kind, code, level, args and the English text | control |
GET /api/metrics | CPU, RAM and PSRAM every 5 s for 10 minutes, and flash use | control |
GET /api/profile | Time per route and CPU per task since the last call | full |
GET /api/coredump | The last crash. ?raw=1 gives the dump. 404 when there is none | admin |
DELETE /api/coredump | Clears it | full |
Settings
{"name": "deckconnector-a1b2c3", "controller": "companion", "host": "satellite", "brightness": 80,
"lan": {"dhcp": true, "ip": "", "mask": "", "gateway": "", "dns": ""},
"wlan": {"dhcp": true, "ip": "", "mask": "", "gateway": "", "dns": ""},
"wifi_ssid": "studio", "wifi_pass_set": true, "wifi_bssid": "", "wifi2_ssid": "", "wifi2_pass_set": false,
"servers": ["ws://192.168.1.20:8765/deckconnector", "", "", ""],
"server_pins": ["", "", "", ""], "satellite": "192.168.1.10", "satellite_auto": true, "satellite_pin": "",
"https_only": false, "cors_origins": "", "menu_chord": "auto", "menu_hold_ms": 2000, "lang": "de", "usb_speed": "auto",
"max_decks": 2, "screen_off_s": 0, "screen_dim": 0, "star_off": false, "star_fw": "v1.0.0", "star_until": 0, "dock_paired_only": false, "qr_login": true, "ntp_server": "", "trusted_proxy": "", "setup_done": true, "token_set": false, "matter": false}| Key | Values |
|---|---|
name | 1 to 31 letters, digits and dashes, no dash at the start or end. Also the host name |
controller, host | The source that draws, see Sources |
brightness | 0 to 100. One press on a deck at 0 sets it to 50 |
volume | The speaker, 0 (off, the default) to 100 |
speaker | A speaker is connected. A new connector starts with false until setup in the web UI asks. With false it plays no sound and /api/sound answers 409 |
lan, wlan | dhcp, or ip and mask with an optional gateway and dns |
wifi_ssid, wifi_pass | wifi_pass has 8 to 63 characters, 64 hex digits, or is empty for an open network |
wifi_bssid | Lock to one access point, empty for any |
wifi2_ssid, wifi2_pass | The backup Wi-Fi, same values as wifi_ssid and wifi_pass. Empty turns it off |
servers | Up to 4 ws:// or wss:// URLs. Empty finds servers over mDNS |
server_pins | SHA-256 per server, same position as in servers |
satellite | Companion's address: host, host:port or a ws:// or wss:// URL. Empty turns it off |
satellite_pin | SHA-256 for a wss:// Companion |
token | Sent as Authorization: Bearer to the servers in servers, never to one found over mDNS. Up to 47 characters, empty for none. GET shows only token_set |
satellite_auto | Move Companion from the dock to Satellite by itself |
https_only | Turn plain HTTP off |
cors_origins | Comma separated origins that may call the API with a key |
menu_chord | auto, keys, encoders or off |
lang | What the deck's own screens speak: de or en |
menu_hold_ms | 500 to 10000 |
usb_speed | auto or full |
max_decks | 1 to 4 decks at once, 2 by default |
screen_off_s | Seconds without input until the screen saver starts, 10 to 86400. 0 means never and is the default |
screen_dim | What the screen saver does. 0 turns every deck dark and is the default. 10 to 90 in steps of 10 dims them to that percent |
star_off, star_fw, star_until | The web UI's star note. star_off hides it for good. star_until hides it until this Unix time. star_fw is the firmware someone last closed it on. After an update to a newer one it shows once |
dock_paired_only | Only paired dock hosts get in |
qr_login | Login QR code on the deck until setup is done |
ntp_server | Empty uses the one from DHCP, then pool.ntp.org |
trusted_proxy | A reverse proxy's IPv4 address, empty for none. See Behind a reverse proxy |
matter | true starts Matter at once. false restarts the connector if Matter runs |
admin_pass | 6 to 23 characters. Password only |
setup_done | Password only. To run setup again, use PUT /api/setup with {"step": 1} |
brightness, volume, speaker, controller, host, servers, server_pins, satellite, satellite_auto, satellite_pin, https_only, cors_origins, trusted_proxy, menu_chord, menu_hold_ms, lang, max_decks, screen_off_s, screen_dim, star_off, star_fw, star_until, wifi2_ssid, wifi2_pass, qr_login, dock_paired_only and setup_done work at once. Every other change restarts the connector. The reply then has reach, the addresses where the connector will be.
{"ok": true, "restart": true, "reach": ["http://192.168.1.50", "http://deckconnector-a1b2c3.local"]}A refused value gets 400 with the reason, and the connector saves nothing. The reply of GET /api/config is a backup without passwords or the token. A PUT of it restores the settings. GET /api/backup?secrets=1 adds admin_pass, wifi_pass, wifi2_pass and token. No backup holds API keys, passkeys, paired dock hosts, an uploaded HTTPS certificate or Matter's paired apps. Create, pair or upload them again.
Status
{"via_ap": false, "id": "a0b1c2a1b2c3", "name": "deckconnector-a1b2c3", "firmware": "v1.0.0",
"wlan_firmware": "3.0.10", "uptime_s": 23, "boot": {"reason": "restart", "at": 1794012139},
"setup": {"active": false, "step": 0, "rerun": false}, "controller": "companion", "writer": "satellite",
"menu_open": false, "screen_off": false, "brightness": 80,
"device": {"model": "Stream Deck +", "serial": "EL00K1A00001", "firmware": "2.0.3.7", "keys": 8, "encoders": 4,
"width": 800, "height": 480},
"network": {"lan": {"cable": true, "dead": false, "ip": "192.168.1.50"},
"wlan": {"ssid": "studio", "ip": "192.168.1.51", "bssid": "aa:bb:cc:dd:ee:ff", "channel": 1,
"lock": "", "backup": false, "rssi": -48, "join": "", "join_error": ""},
"ap": {"on": false, "ssid": ""}},
"sources": [{"kind": "companion", "host": "192.168.1.10", "via": "satellite", "name": "studio",
"connected": true, "chosen": true, "drawing": true}],
"counters": {"images": 7, "superseded": 0, "rejected": 0, "usb_errors": 0, "usb_recoveries": 0,
"usb_speed": "high", "inputs": 0, "inputs_dropped": 0}}| Field | Meaning |
|---|---|
id | The MAC address. Stays when the name changes |
writer | Who draws now: ui, server1 to server4, dock1 to dock4, or satellite. ui while the menu is open, an update runs, or the chosen host is not connected |
device | The first deck, null without one. decks lists every deck with its slot (0 for deck 1) and number (1 for deck 1) |
decks[].locked | Companion over Satellite draws on the deck and locked it with its PIN. The deck shows the number pad. pin_count is the number of digits typed, pin_wrong is true for 600 ms after a wrong PIN |
decks_over_limit | Decks plugged in but dark because of max_decks |
sources | Every host. chosen marks the one that draws when no menu covers it. Servers and Satellite also have error, since_s and iface |
boot.reason | power, pin, restart, crash, watchdog, brownout or other |
setup | step of the web wizard, active until setup is done |
menu_open | The menu, the password, the reset question or a login request covers the deck |
screen_off | Every deck is dark, from the screen saver or POST /api/screen. The first input wakes them and reaches no host. decks[].brightness is 0 then. A dimmed deck is not off |
brightness | The brightness setting. decks[].brightness is what each deck shows |
network.lan.dead | The cable is in, but the gateway does not answer |
network.wlan.backup | The connector is on the backup Wi-Fi, ssid names it |
matter | on, running, controllers (paired apps) and pairing (open for a new app) |
pairing | Dock pairing, see Pairing |
counters | Images, replaced images, USB errors, deck reconnects, inputs and lost inputs |
decks[].writer | Who draws on that deck, values as writer |
decks[].hub | The deck is behind a USB hub |
speaker | A speaker is connected. The board has a speaker output and speaker is on in the settings, see Hardware |
temp_c | The chip temperature in °C. Missing until the first reading |
https_ca | The short code of the connector's CA, see HTTPS. Empty with your own certificate, then https_custom is true |
The status also has api, simulated_input, boot_ms, memory, https_fingerprint and https_custom_unread, and copies of the settings volume, screen_off_s, screen_dim and max_decks.
Screen
{"writer": "satellite", "width": 800, "height": 480,
"keys": [{"x": 13, "y": 12, "w": 120, "h": 120}], "touch": [{"x": 0, "y": 380, "w": 800, "h": 100}],
"encoders": 4, "menu_chord": {"on": "encoders", "first": 0, "last": 3, "hold_ms": 2000},
"images": [{"x": 13, "y": 12, "w": 120, "h": 120, "url": "/api/screen/9.jpg"}]}strips lists every display strip, also the info bar of the Stream Deck Neo, which takes no touch. Draw the JPEGs in order at their place to get the picture. An image keeps its URL until something covers it, so a browser may cache it. A URL that is gone answers 404.
Input
POST /api/input acts as if someone used the deck. Keys and dials count from 0. Coordinates are those of /api/screen.
{"key": 3}
{"key": 3, "action": "down"}
{"encoder": 0, "action": "turn", "ticks": -2}
{"touch": "tap", "x": 100, "y": 430}
{"touch": "long", "x": 100, "y": 430}
{"touch": "swipe", "x": 700, "y": 430, "x2": 100, "y2": 430}action is press (the default), down, up, or turn for dials. Positive ticks turn right.
{"pin": 3} types one digit of Companion's PIN on a locked deck, also on a deck that cannot show the number pad. It needs "real" and answers 409 when the deck is not locked.
Real presses
Companion, the Elgato app and the Satellite connection get an API press only with "real", because their keys switch real things. Without it, the press reaches only the connector's own screens and your own servers. "real": true is for a person at a web page. A script names the host instead, "real": "192.168.1.10", and the press goes out only while that host draws.
Restart, reset, the LAN settings, the setup Wi-Fi and the keys that let a host in work only on the deck itself.
Pairing
POST /api/dock takes one of these. pairing opens pairing for 0 to 3600 seconds.
{"accept": true, "ip": "192.168.1.15"}
{"accept": false, "ip": "192.168.1.15"}
{"pairing": 300}
{"pairing": 0}
{"forget": "192.168.1.15"}
{"forget": true}pairing in the status has only_paired, the waiting request, open and open_s while pairing is open, denied and the paired hosts. An answer that names another host than the waiting one gets 409.
WebSocket
/api/ws uses the same login as the other routes. A page from another site is refused. Every message is one JSON object, and t says what it is.
t | When |
|---|---|
state | At once, then on every change. The status without uptime, signal, counters, temp_c, boot_ms, memory, via_ap and pairing.open_s |
screen | The picture of the deck in deck (its serial) changed |
input | Someone used the deck in deck. simulated is true for an API press without "real". An API key never gets simulated presses |
ota | Update progress: target, state, pct, and error |
ping | Every 5 s. Without any message for 12 s, connect again |
log | New log text, only after {"t": "log"}. Needs the password or a full key |
event | A new event in event, as GET /api/events has it |
To change something, send the keys of PUT /api/config or POST /api/input with an id. An input goes to the first deck, or to the one whose serial is in deck. GET /api/input/log names the deck the same way.
{"t": "set", "id": 1, "brightness": 40}
{"t": "input", "id": 2, "key": 3}
{"t": "result", "id": 1, "status": 200, "reply": {"ok": true, "restart": false}}