REST API reference

Each tablet can run a small HTTP server on your local network. It serves a web admin page and a JSON API for state, commands and configuration. It is off by default and meant for your LAN only.

Warning. The API uses plain HTTP, so the token can be read by anyone on the same Wi-Fi. Never forward the port to the internet. See Security.

Turn it on#

1. Open Settings, Connections, Remote access.
2. Turn on REST API & admin page. The status chip shows Running on port 2323.
3. Under API token tap Show or Copy. A token is created when you first turn remote access on.
4. The Admin page line shows the address, such as http://192.168.1.50:2323/.

The server listens on all network interfaces of the tablet. The examples below use TABLET_IP for its address and $KIOSKY_TOKEN for the token.

Authentication#

Every endpoint except GET /api/info needs the token in an Authorization header:

curl -H "Authorization: Bearer $KIOSKY_TOKEN" http://TABLET_IP:2323/api/state

The one exception is GET /api/camera/stream, which also accepts HTTP Basic with the username kiosky and the token as the password, for clients such as Home Assistant's MJPEG camera that cannot send a Bearer header. Tokens in the URL query are not supported.

Errors are JSON of the form {"error": "message"}. Responses carry Cache-Control: no-store. There is no CORS, so browsers on other sites cannot call the API.

Rate limits#

• Failed authentication is counted per client address. 5 failures within 60 seconds lock that address out for 60 seconds. Each further lockout doubles, up to 15 minutes.
• A successful request clears the address's record.
• A global ceiling guards against guessing from many addresses: 50 failures within 60 seconds from all clients combined lock everyone out for 60 seconds.
• Request bodies are limited to 256 KiB (413 above that). Command payloads are limited to 4096 characters.

Endpoints#

GET /api/info#

Public, so a client can confirm it found a Kiosky tablet before it has a token.

curl http://TABLET_IP:2323/api/info

{"app": "Kiosky", "name": "Hallway Tablet", "id": "hallway_tablet", "version": "0.1.0"}

id is a lower-case slug of the device name with underscores. It is the same id used in the mDNS records and in the MQTT topics (kiosk/hallway_tablet/...).

GET /api/state#

curl -H "Authorization: Bearer $KIOSKY_TOKEN" http://TABLET_IP:2323/api/state

{
  "battery": {"levelPercent": 87, "charging": true, "temperatureC": 29.5},
  "screenOn": true,
  "brightness": 120,
  "currentUrl": "http://homeassistant.local:8123/lovelace/0?kiosk",
  "lightLux": 85.0,
  "proximityNear": null,
  "motion": false,
  "network": {"ssid": "home", "rssiDbm": -52, "ipAddress": "192.168.1.50"},
  "appVersion": "0.1.0",
  "webViewVersion": "130.0.6723.58",
  "uptimeSeconds": 86400,
  "memoryFreeMb": 812,
  "storageFreeMb": 20480,
  "screenStage": "active",
  "kioskMode": "device_owner",
  "lastInteractionEpochMs": 1763040000000,
  "kioskPaused": false,
  "kioskPausedUntilEpochMs": null
}

MQTT publishes a flatter state with more keys (volume, dashboard, presence, tamper, voice). See the MQTT reference.

POST /api/command#

The body is a JSON object with a command name and optional args. args is either an object, or a single plain value that fills the command's main argument.

curl -X POST http://TABLET_IP:2323/api/command \
  -H "Authorization: Bearer $KIOSKY_TOKEN" -H "Content-Type: application/json" \
  -d '{"command": "brightness", "args": {"level": 128}}'

# the same, with a plain value
curl -X POST http://TABLET_IP:2323/api/command \
  -H "Authorization: Bearer $KIOSKY_TOKEN" -H "Content-Type: application/json" \
  -d '{"command": "brightness", "args": 128}'

Commands#

The command names and arguments are shared by REST, MQTT and the page bridge. In the table, Main arg is the one a plain args value fills.

Examples:

{"command": "toast", "args": {"text": "Dinner is ready", "duration": 10}}
{"command": "popup", "args": {"camera": "camera.front_door", "timeout": 30}}
{"command": "popup", "args": {"url": "https://example.com/alert", "title": "Alert"}}
{"command": "dashboard", "args": "Energy"}
{"command": "kiosk_pause", "args": {"minutes": 30}}

Sensitive commands (kiosk_pause, kiosk_lock with off, launch_app, exit_app_mode, restart_app, clear_cache, reboot) are refused with 403 unless you turned on Allow remote unlock & app control on the tablet. See Security. Everything else is benign and always allowed.

Configuration#

GET /api/config#

Returns the whole configuration as pretty-printed JSON. Secrets are never in it: the HA token, MQTT password, admin PIN, API token, Immich key and webhook URL are stored separately.

curl -H "Authorization: Bearer $KIOSKY_TOKEN" http://TABLET_IP:2323/api/config

{
  "version": 1,
  "device": {"name": "Hallway Tablet", "theme": "auto"},
  "browser": {
    "dashboards": [{"name": "Home", "url": "http://homeassistant.local:8123/lovelace/0"}],
    "allowedHosts": [],
    "reloadIntervalMinutes": 0,
    "zoomPercent": 100
  },
  "kiosk": {"enabled": true, "mode": "browser"},
  "power": {
    "keepScreenOn": "when_charging",
    "idle": {"dimAfterSeconds": 120, "screensaverAfterSeconds": 300, "offAfterSeconds": 900},
    "brightness": {"mode": "auto", "min": 10, "max": 255}
  },
  "server": {"enabled": true, "port": 2323},
  "remote": {"allowUnlock": false, "allowSecurityChanges": false}
}

The real response includes every section with all its defaults. The example above is cut for length.

PATCH /api/config#

PATCH changes only the fields you send. The body is a partial JSON object that is deep-merged onto the current configuration: objects merge key by key, while arrays and scalar values replace the current value. Anything you leave out keeps its current value. This is the safe way to make a change.

# 1. check it without saving: dim after 1 minute
curl -X PATCH "http://TABLET_IP:2323/api/config?dryRun=true" \
  -H "Authorization: Bearer $KIOSKY_TOKEN" -H "Content-Type: application/json" \
  -d '{"power": {"idle": {"dimAfterSeconds": 60}}}'

# 2. save it
curl -X PATCH http://TABLET_IP:2323/api/config \
  -H "Authorization: Bearer $KIOSKY_TOKEN" -H "Content-Type: application/json" \
  -d '{"power": {"idle": {"dimAfterSeconds": 60}}}'

Because arrays replace, to change one dashboard send the whole browser.dashboards array.

The merge is repeated inside the atomic save, so a change made at the same moment to other fields is not lost. dryRun is only active for the exact value true. Always dry-run first. The remote settings cannot be changed over REST.

PUT /api/config#

PUT replaces the entire configuration with the body. Fields you leave out go back to their defaults, they are not kept. Use it only when you really want to replace everything, for example to restore a backup: GET /api/config, edit, then PUT the full document. It supports ?dryRun=true and returns the same statuses as PATCH.

curl -s -H "Authorization: Bearer $KIOSKY_TOKEN" http://TABLET_IP:2323/api/config > config.json

# restore or replace: check first, then save
curl -X PUT "http://TABLET_IP:2323/api/config?dryRun=true" \
  -H "Authorization: Bearer $KIOSKY_TOKEN" -H "Content-Type: application/json" \
  --data @config.json
curl -X PUT http://TABLET_IP:2323/api/config \
  -H "Authorization: Bearer $KIOSKY_TOKEN" -H "Content-Type: application/json" \
  --data @config.json

If a PUT body has no remote key, the tablet keeps its own remote settings. Files with a newer version than the app supports are rejected.

Protected settings#

Some settings decide who can control or reach the tablet. A PUT or PATCH that changes any of them returns 403 and saves nothing, unless Allow remote security changes is on in the tablet's settings. The remote settings themselves can never be changed over REST.

Changing the Home Assistant origin or the MQTT host also deletes the saved HA token or MQTT password, so a secret never follows a changed address.

Config reference#

These are the settings most often changed, with their defaults. Times are local HH:mm.

Other endpoints#

Screenshot#

GET /api/screenshot returns a PNG of the screen (image/png), or 503 with "No visible screen to capture" when nothing is on screen.

curl -H "Authorization: Bearer $KIOSKY_TOKEN" http://TABLET_IP:2323/api/screenshot -o screen.png

Camera#

GET /api/camera/snapshot returns a JPEG no older than a couple of seconds, or 503 ("Camera unavailable"). GET /api/camera/stream returns multipart/x-mixed-replace MJPEG. It answers 404 ("Camera stream is disabled") unless the stream is turned on, and 503 when 2 viewers are already connected or the camera does not start within 15 seconds. See Camera & sensors.

Logs#

GET /api/logs?lines=200 returns plain text. lines defaults to 500 and is limited to 1 to 2000. Tokens and passwords are masked.

Admin page#

Open http://TABLET_IP:2323/ in a browser, paste the API token and tap Connect. The page offers quick actions (reload, screen on and off, restart app, brightness, load a URL), live state, and a JSON editor for the configuration with Reload from device, Validate and Save. It talks to the same API.

Discover tablets on the network (mDNS)#

While the server runs, the tablet announces itself over mDNS/DNS-SD as both _kiosk._tcp and _http._tcp. The service name is the device name (Android may append (2) if there is a conflict), and the TXT records are:

Android cannot publish a .local host name, so resolve the service name to an address and port instead:

# macOS
dns-sd -B _kiosk._tcp local
dns-sd -L "Hallway Tablet" _kiosk._tcp local

# Linux
avahi-browse -rt _kiosk._tcp

Then call GET /api/info on the address and port to confirm. If mDNS is blocked on your network, use the IP address shown in the app (Settings, Device, or Connections, Remote access) and the port.

Home Assistant without MQTT#

You can drive a tablet from Home Assistant with rest_command:

rest_command:
  kiosky_hallway_toast:
    url: "http://192.168.1.50:2323/api/command"
    method: POST
    headers:
      Authorization: !secret kiosky_hallway_bearer   # "Bearer <token>"
      Content-Type: application/json
    payload: '{"command": "toast", "args": {"text": "{{ message }}", "duration": 8}}'

Keep the token in secrets.yaml, never in a file you share.