# HTTP and WebSocket API

> Every route of the connector's JSON API, the settings, the status and the live WebSocket.

Source: https://deckconnector.com/docs/api/

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` |

```bash
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](https://deckconnector.com/docs/security/#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.

```json
{"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](https://deckconnector.com/docs/security/#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](#websocket) | control |
| `GET /api/status` | State of the connector, see [Status](#status) | control |
| `GET /api/config` | Settings, see [Settings](#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](https://deckconnector.com/docs/first-setup/#factory-reset), then a restart | admin |

### Deck

| Route | What it does | Level |
|---|---|---|
| `GET /api/screen` | What the deck shows, see [Screen](#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](#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](#pairing) | full |
| `DELETE /api/pairing/denied/<ip>` | Takes a host off the denied list | full |

### Matter

See [Matter](https://deckconnector.com/docs/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`](#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

```json
{"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](https://deckconnector.com/docs/hosts/#over-the-api) |
| `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](https://deckconnector.com/docs/security/#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.

```json
{"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

```json
{"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](#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](https://deckconnector.com/docs/hardware/#board) |
| `temp_c` | The chip temperature in °C. Missing until the first reading |
| `https_ca` | The short code of the connector's CA, see [HTTPS](https://deckconnector.com/docs/security/#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

```json
{"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`.

```json
{"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.

```json
{"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.

```json
{"t": "set", "id": 1, "brightness": 40}
{"t": "input", "id": 2, "key": 3}
{"t": "result", "id": 1, "status": 200, "reply": {"ok": true, "restart": false}}
```

Next: [Own server](https://deckconnector.com/docs/own-server/), [Home Assistant](https://deckconnector.com/docs/home-assistant/)
