server/API.md

Tronbyt Server API v0 Reference

Base URL: http://<server>:8000

Authentication

All API endpoints require authentication via Bearer token:

Authorization: Bearer <api-key>

API keys are generated per-device in the web UI. Each key is scoped to a single device.

---

Devices

List Devices

GET /v0/devices

Returns all devices accessible to the authenticated API key.

Response:

{
  "devices": [
    {
      "id": "gen1",
      "type": "gen1",
      "displayName": "My Tronbyt",
      "notes": "",
      "intervalSec": 30,
      "brightness": 100,
      "nightMode": {
        "enabled": false,
        "app": "",
        "startTime": "",
        "endTime": "",
        "brightness": 0
      },
      "dimMode": {
        "startTime": null,
        "brightness": null
      },
      "pinnedApp": null,
      "interstitial": {
        "enabled": false,
        "app": null
      },
      "lastSeen": "2024-01-01T00:00:00Z",
      "info": {
        "firmwareVersion": "1.0.0",
        "firmwareType": "gen1",
        "protocolVersion": 1,
        "macAddress": "aa:bb:cc:dd:ee:ff"
      },
      "autoDim": false
    }
  ]
}

Get Device

GET /v0/devices/{id}

Returns details for a specific device.

Update Device

PATCH /v0/devices/{id}
Content-Type: application/json

Update device settings. All fields are optional.

Request:

{
  "brightness": 80,
  "intervalSec": 60,
  "nightModeEnabled": true,
  "nightModeApp": "clock",
  "nightModeBrightness": 10,
  "nightModeStartTime": "22:00",
  "nightModeEndTime": "07:00",
  "dimModeStartTime": "20:00",
  "dimModeBrightness": 30,
  "pinnedApp": "weather"
}

Response: Updated device payload (same shape as GET).

Reboot Device

POST /v0/devices/{id}/reboot

Sends a reboot command to the device via WebSocket. Returns immediately; the device reboots asynchronously.

Response: 200 OK — "Reboot command sent."

Update Firmware Settings

POST /v0/devices/{id}/update_firmware_settings
Content-Type: application/json

Update low-level firmware settings. All fields are optional.

Request:

{
  "skipDisplayVersion": true,
  "skipBootAnimation": true,
  "preferIPv6": false,
  "apMode": false,
  "swapColors": false,
  "wifiPowerSave": 0,
  "imageUrl": "http://example.com/image.webp",
  "hostname": "tronbyt.local",
  "sntpServer": "pool.ntp.org",
  "syslogAddr": "192.168.1.100:514"
}

Response: 200 OK — "Firmware settings updated."

---

Installations (Apps)

List Installations

GET /v0/devices/{id}/installations

Returns all app installations on a device.

Response:

{
  "installations": [
    {
      "id": "my-clock",
      "appID": "clock",
      "enabled": true,
      "pinned": false,
      "pushed": false,
      "renderIntervalMin": 0,
      "displayTimeSec": 30,
      "lastRenderAt": 1704067200,
      "isInactive": false,

      "startTime": "09:00",
      "endTime": "17:00",
      "days": ["monday", "wednesday", "friday"],

      "useCustomRecurrence": false,
      "recurrenceType": "",
      "recurrenceInterval": 0,
      "recurrencePattern": null,
      "recurrenceStartDate": null,
      "recurrenceEndDate": null,

      "autoPin": false,
      "colorFilter": null,
      "showFullAnimation": null
    }
  ]
}

App config is not returned. It holds whatever the app's schema defines, which for many apps includes API keys and OAuth tokens, and a device API key is a lower bar than a logged-in session. Config can be written (see below) but never read back.

Get Installation

GET /v0/devices/{id}/installations/{iname}

Returns details for a specific app installation.

Update Installation

PATCH /v0/devices/{id}/installations/{iname}
Content-Type: application/json

Update installation settings. All fields are optional; omitting one leaves it alone.

Request:

{
  "enabled": true,
  "pinned": false,
  "renderIntervalMin": 5,
  "displayTimeSec": 30,

  "startTime": "09:00",
  "endTime": "17:00",
  "days": ["monday", "wednesday", "friday"],

  "autoPin": false,
  "colorFilter": "dimmed",
  "showFullAnimation": "true",

  "config": { "timezone": "America/New_York" }
}

Field	Notes
startTime / endTime	"HH:MM". "" clears. A start later than the end wraps overnight.
days	Lowercase day names. [] means every day.
colorFilter	One of the filters the app config page offers. "" or "inherit" falls back to the device setting.
showFullAnimation	"true" / "false", or "auto" to inherit. Lets an animation run past the app's display time.
config	Replaces the app's whole config map — there is no per-key merge, so send the full object. Write-only: it is never returned by GET or in this response.

Response: Updated installation object, in the same shape GET returns.

Delete Installation

DELETE /v0/devices/{id}/installations/{iname}

Removes an app installation and its associated WebP files.

Response: 200 OK — "App deleted."

---

Push (Render & Display)

Push App

POST /v0/devices/{id}/push_app
Content-Type: application/json

Renders an app and pushes it to the device. If background is false, the device immediately interrupts its current display and shows the pushed image.

Request:

{
  "app_id": "clock",
  "installationID": "my-clock",
  "config": {
    "timezone": "America/New_York"
  },
  "background": false
}

Field	Required	Description
app_id	No*	The app identifier (e.g. "clock", "weather"). Required only if installationID is not provided or references a non-existent installation.
installationID	No	Installation name. If provided and valid, the app path is inferred from the existing installation, and its saved config is used if config is omitted.
config	No	App configuration. If omitted and installationID is provided, uses saved config from that installation.
background	No	If true, saves the image without interrupting the device (default: false)

Response: 200 OK — "App pushed."

Examples:

Push with explicit app_id (required when not using installationID):

curl -X POST \
  -H "Authorization: Bearer <key>" \
  -H "Content-Type: application/json" \
  -d '{"app_id": "clock", "config": {"timezone": "America/New_York"}, "background": false}' \
  http://localhost:8000/v0/devices/gen1/push_app

Activate an existing installation (app_id inferred from installation):

curl -X POST \
  -H "Authorization: Bearer <key>" \
  -H "Content-Type: application/json" \
  -d '{"installationID": "851", "background": false}' \
  http://localhost:8000/v0/devices/gen1/push_app

Push Raw Image

POST /v0/devices/{id}/push
Content-Type: application/json

Pushes a base64-encoded WebP image directly to the device.

Request:

{
  "installationID": "my-image",
  "image": "<base64-encoded-webp>",
  "background": false
}

Field	Required	Description
installationID	No	Identifier for the pushed image
image	Yes	Base64-encoded WebP image bytes
background	No	If true, saves without interrupting (default: false)

Response: 200 OK — "WebP received."

Example:

curl -X POST \
  -H "Authorization: Bearer <key>" \
  -H "Content-Type: application/json" \
  -d '{
    "installationID": "custom",
    "image": "'$(base64 -w0 image.webp)'",
    "background": false
  }' \
  http://localhost:8000/v0/devices/gen1/push

---

Common Patterns

Activate an existing app immediately

1. Push using the installationID — app path and config are inferred from the installation:

curl -X POST \
  -H "Authorization: Bearer <key>" \
  -H "Content-Type: application/json" \
  -d '{"installationID": "851", "background": false}' \
  http://localhost:8000/v0/devices/gen1/push_app

Enable/disable an app

curl -X PATCH \
  -H "Authorization: Bearer <key>" \
  -H "Content-Type: application/json" \
  -d '{"enabled": false}' \
  http://localhost:8000/v0/devices/gen1/installations/851

Pin an app (always show it)

curl -X PATCH \
  -H "Authorization: Bearer <key>" \
  -H "Content-Type: application/json" \
  -d '{"pinned": true}' \
  http://localhost:8000/v0/devices/gen1/installations/851

Set device brightness

curl -X PATCH \
  -H "Authorization: Bearer <key>" \
  -H "Content-Type: application/json" \
  -d '{"brightness": 50}' \
  http://localhost:8000/v0/devices/gen1

---

Error Responses

Status	Meaning
400	Invalid JSON, missing fields, or bad values
401	Missing or invalid API key
404	Device or installation not found
500	Internal server error

Error responses are plain text with a brief message.