Skip to content
DeckConnectorSet it up
Skip to Content

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.

WayHowNotes
PasswordHTTP basic auth, any user nameEvery request that changes something also needs the header X-DeckConnector: 1
SessionPOST /api/login with {"password": "..."} and X-DeckConnector: 1Sets a cookie. Ends after 12 hours without use, or with POST /api/logout
API keyAuthorization: Bearer KEYNo X-DeckConnector header needed. Rights below
Setup Wi-FiA client on the setup Wi-FiRights 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/status

Access 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"}
codeMeaning
ota_too_shortThe file is too short to be a firmware file
ota_not_dbfwNot a .dbfw file
ota_not_signedNot signed with this connector's key
ota_wrong_targetFor another device or part
ota_too_oldBelow the security level
url_http_onlyThe URL must start with http:// or https://
no_releasesNo releases to check yet
rate_limitedGitHub limits the checks. Try again later
unreachableGitHub does not answer
probe_no_connectionNothing answers at this address
probe_no_answerThe address takes the connection but sends nothing within 3 s
probe_not_companionSomething answers, but it is not Companion Satellite
strip_outsideThe point is outside the touch strip
busyThe connector is busy. Try again
lockedToo many wrong passwords. The reply has retry in seconds, with status 429
pausedThis 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_passwordWrong password
needs_passwordNeeds the password, an API key is not enough
passkey_hostPasskeys need HTTPS and a name
passkey_refusedThe 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

RouteWhat it doesLevel
POST /api/login{"password": "..."}, sets the session cookieopen
POST /api/logoutEnds the sessionopen
POST /api/setup/claimBefore setup: a session without the password, see Password. 403 from another site's name, 409 with set up, claimed or too lateopen
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 pausedopen
GET /api/login/request/<id>state is pending, accepted, denied, expired or used. With accepted the reply sets the session cookie onceopen
DELETE /api/login/request/<id>Takes the request backopen
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 403open
POST /api/login/passkeyThe 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 notopen
POST /api/password/showThe deck shows the password for 30 s. 409 without a deck, 429 with pausedopen
POST /api/password/resetThe deck asks for 60 s whether to reset everything. Answers {"ok": true, "s": 60}. 409 without a deck, 429 with pausedopen
DELETE /api/password/resetEnds the questionopen

The open routes that do something need X-DeckConnector: 1.

Status and settings

RouteWhat it doesLevel
GET /apiEvery route with method, path and accesscontrol
OPTIONS /api/...The CORS preflight for the origins in cors_originsopen
GET /api/wsThe live WebSocketcontrol
GET /api/statusState of the connector, see Statuscontrol
GET /api/configSettings, see Settings. Secrets only show as wifi_pass_set, wifi2_pass_set and token_setfull
PUT /api/configChange settings. Send only the keys you change. The reply has restart and configfull
POST /api/configCompanion's Setup under Surfaces › Discover: {"host": "...", "port": 16622} as application/json. During setup the connector connects at once, later the deck asks for 60 sopen
GET /api/backupThe settings for a restore. ?secrets=1 adds the passwordsadmin
PUT /api/setup{"step": 3} keeps the web wizard's step, {"step": 0} ends itfull
POST /api/rebootRestartfull
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 0control
DELETE /api/apCloses the setup Wi-Fifull
POST /api/resetFactory reset, then a restartadmin

Deck

RouteWhat it doesLevel
GET /api/screenWhat the deck shows, see Screencontrol
GET /api/screen/<id>.jpgOne image of that picturecontrol
GET /api/screen.jpgThe whole picture as one JPEGcontrol
POST /api/inputPress, turn or touch, see Inputcontrol
GET /api/input/logThe newest 400 of the last 2000 inputs, oldest first. ?since=<seq> for newer ones, ?before=<seq> for older onescontrol
POST /api/menuOpen the deck menu. 409 without a deckcontrol
DELETE /api/menuClose the deck menu, the password, the reset question and a login requestcontrol
POST /api/screen{"on": false} turns every deck dark now, {"on": true} lights them again. No press is swallowedfull
POST /api/deck/reconnectTurn the USB port off and on. ?off_s=N (1 to 600) keeps it off for N secondscontrol
POST /api/deck/stallStop the image output as a hung deck would, for testsfull
POST /api/sound/streamThe 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 headerscontrol
POST /api/sound/selftestPlay 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 failsfull

Sources and pairing

RouteWhat it doesLevel
POST /api/sources/retry{"host": "..."} with a server URL or the Satellite address. Connects now instead of after the waitcontrol
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 turnfull
GET /api/companion/foundCompanions that announce Satellite over mDNS. The first call starts a 2 s searchfull
POST /api/dockPairing, see Pairingfull
DELETE /api/pairing/denied/<ip>Takes a host off the denied listfull

Matter

See Matter. While matter.running is false, GET /api/matter, {"pair": true}, {"show": true} and POST /api/matter/press answer 409.

RouteWhat it doesLevel
GET /api/matterqr (the text of the QR code), code (the pairing code) and qr_bitsfull
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 sfull
DELETE /api/matterRemoves every Matter app, makes a new pairing code and restartsfull
POST /api/matter/pressFor tests: the body of POST /api/input, sent to Matter alone. No host, menu or input log sees itfull

Network

RouteWhat it doesLevel
GET /api/wifi/scanNetworks in reach, strongest first: ssid, bssid, rssi, channel, open. 2.4 GHz only. Takes 2 to 3 sfull
POST /api/wifi/join{"ssid": "...", "pass": "...", "bssid": ""}. Answers 202. network.wlan.join in the status goes from testing to ok or failed within 15 sfull

Firmware

RouteWhat it doesLevel
POST /api/otaA signed .dbfw file as the body. Goes into the next slot and restarts. ?slot=N writes into slot N, ?boot=0 keeps the running firmwarefull
POST /api/ota/url{"url": "https://..."}, the connector loads the file itself, also behind a redirect. Progress comes over the WebSocketfull
POST /api/ota/inspectThe first 144 bytes of a file. Answers target, version, length, sha256, and ok with errorfull
GET /api/update/check{"current": "v1.0.0", "latest": null, ...}full
GET /api/slotsThe four slots with state, version, running, next, bootable and why_notfull
POST /api/slots/<n>/bootRestart into slot N. 409 when it cannot startfull
GET /api/frontendThe web page in use: source (partition or builtin), api, and version for an uploaded onecontrol
PUT /api/frontendA signed web page as the body. Served at oncefull
DELETE /api/frontendBack to the page in the firmwarefull
GET /api/bootBootloader and partition table. ?raw=bootloader or ?raw=ptable gives the bytesfull

Access

RouteWhat it doesLevel
GET /api/tokensThe API keys, name and rightadmin
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 onceadmin
DELETE /api/tokenThe key in the request ends itself. Home Assistant does this when you remove the integrationcontrol
GET /api/passkeysThe passkeys, with id, name and rp, the name each one works atadmin
POST /api/passkeysThe 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 8admin
PUT /api/passkeys/<id>{"name": "Laptop"}, 1 to 23 bytesadmin
DELETE /api/passkeys/<id>Removes that passkeyadmin
GET /api/certThe HTTPS certificate as PEMopen
GET /api/caThe 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 pausedopen
PUT /api/tls{"cert": "<PEM>", "key": "<PEM>"} checks your own certificate. With "apply": true it is kept and the connector restartsadmin
DELETE /api/tlsBack to the connector's own certificate, with a restartfull

Diagnostics

RouteWhat it doesLevel
GET /api/logThe last 16 KB of the log as text. ?boot=prev for the start beforefull
GET /api/eventsEvents, 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 textcontrol
GET /api/metricsCPU, RAM and PSRAM every 5 s for 10 minutes, and flash usecontrol
GET /api/profileTime per route and CPU per task since the last callfull
GET /api/coredumpThe last crash. ?raw=1 gives the dump. 404 when there is noneadmin
DELETE /api/coredumpClears itfull

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}
KeyValues
name1 to 31 letters, digits and dashes, no dash at the start or end. Also the host name
controller, hostThe source that draws, see Sources
brightness0 to 100. One press on a deck at 0 sets it to 50
volumeThe speaker, 0 (off, the default) to 100
speakerA 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, wlandhcp, or ip and mask with an optional gateway and dns
wifi_ssid, wifi_passwifi_pass has 8 to 63 characters, 64 hex digits, or is empty for an open network
wifi_bssidLock to one access point, empty for any
wifi2_ssid, wifi2_passThe backup Wi-Fi, same values as wifi_ssid and wifi_pass. Empty turns it off
serversUp to 4 ws:// or wss:// URLs. Empty finds servers over mDNS
server_pinsSHA-256 per server, same position as in servers
satelliteCompanion's address: host, host:port or a ws:// or wss:// URL. Empty turns it off
satellite_pinSHA-256 for a wss:// Companion
tokenSent 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_autoMove Companion from the dock to Satellite by itself
https_onlyTurn plain HTTP off
cors_originsComma separated origins that may call the API with a key
menu_chordauto, keys, encoders or off
langWhat the deck's own screens speak: de or en
menu_hold_ms500 to 10000
usb_speedauto or full
max_decks1 to 4 decks at once, 2 by default
screen_off_sSeconds without input until the screen saver starts, 10 to 86400. 0 means never and is the default
screen_dimWhat 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_untilThe 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_onlyOnly paired dock hosts get in
qr_loginLogin QR code on the deck until setup is done
ntp_serverEmpty uses the one from DHCP, then pool.ntp.org
trusted_proxyA reverse proxy's IPv4 address, empty for none. See Behind a reverse proxy
mattertrue starts Matter at once. false restarts the connector if Matter runs
admin_pass6 to 23 characters. Password only
setup_donePassword 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}}
FieldMeaning
idThe MAC address. Stays when the name changes
writerWho 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
deviceThe first deck, null without one. decks lists every deck with its slot (0 for deck 1) and number (1 for deck 1)
decks[].lockedCompanion 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_limitDecks plugged in but dark because of max_decks
sourcesEvery host. chosen marks the one that draws when no menu covers it. Servers and Satellite also have error, since_s and iface
boot.reasonpower, pin, restart, crash, watchdog, brownout or other
setupstep of the web wizard, active until setup is done
menu_openThe menu, the password, the reset question or a login request covers the deck
screen_offEvery 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
brightnessThe brightness setting. decks[].brightness is what each deck shows
network.lan.deadThe cable is in, but the gateway does not answer
network.wlan.backupThe connector is on the backup Wi-Fi, ssid names it
matteron, running, controllers (paired apps) and pairing (open for a new app)
pairingDock pairing, see Pairing
countersImages, replaced images, USB errors, deck reconnects, inputs and lost inputs
decks[].writerWho draws on that deck, values as writer
decks[].hubThe deck is behind a USB hub
speakerA speaker is connected. The board has a speaker output and speaker is on in the settings, see Hardware
temp_cThe chip temperature in °C. Missing until the first reading
https_caThe 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.

tWhen
stateAt once, then on every change. The status without uptime, signal, counters, temp_c, boot_ms, memory, via_ap and pairing.open_s
screenThe picture of the deck in deck (its serial) changed
inputSomeone used the deck in deck. simulated is true for an API press without "real". An API key never gets simulated presses
otaUpdate progress: target, state, pct, and error
pingEvery 5 s. Without any message for 12 s, connect again
logNew log text, only after {"t": "log"}. Needs the password or a full key
eventA 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}}

On this page