API reference

This page lists every HTTP endpoint the server offers: what it is for, who may call it, what to send, what comes back, and the status codes and limits. It is for developers who write a client (the kiosk, a script, a test) or a widget route. All examples use https://example.com/frames/ as the site address, which is the frames_url in config.php.

Everything on this page was taken from the routes in web/app/routes/ and web/app/widgets/*/routes.php and admin_routes.php. If you add a route, add it here.

Conventions

Four kinds of caller

The frame-facing API is versioned (/api/v1/). Shipped kiosks cannot be updated in one step, so version 1 changes only by adding: new endpoints, new response keys, new optional request fields. Clients must ignore keys they do not know. The admin API is unversioned and moves with the admin page.

Requests and responses

• JSON bodies need Content-Type: application/json (else 415) and must be a JSON object. A field the endpoint does not list is a 422. Each endpoint caps the body (listed below).
• Raw bodies (photos, APKs, screenshots) need an exact or image/* content type, as listed per endpoint.
• Responses are application/json; charset=utf-8 with Cache-Control: no-store, except images, files and assets, which say otherwise.
• A 201 carries a Location header. A 405 carries Allow. A HEAD request is treated as a GET.
• Timestamps are Unix seconds. Frame ids are 32 lowercase hex characters; keys are 64.

Errors

Every error has this shape. The client should branch on code, never on the text.

{ "error": "human readable message", "code": "stable_code" }

A validation failure (422) adds the offending fields:

{ "error": "validation failed", "code": "invalid", "fields": { "name": "name must be 1-64 characters" } }

Specific 403 codes: id_mismatch (a frame asked for another frame's data), not_active (the frame is not claimed), revoked (body also has "status": "revoked"), header_required, bad_origin, bad_csrf, reauth_required, expired.

Rate limits

IPv6 addresses are counted by their /64. The drop and card limits can be changed for photos under widgets.photos in config.php.

Body size limits

Apache enforces the first number; the app enforces the exact value.

How a frame joins

sequenceDiagram
    participant K as Kiosk
    participant S as Server
    participant A as Admin
    K->>S: POST /api/v1/frames {id, key, app_version}
    S-->>K: 201 {status: unclaimed, pairing_code, pairing_expires_in}
    loop every 10 s while unclaimed
        K->>S: GET /api/v1/frames/{id}
        S-->>K: 200 {status: unclaimed, pairing_code}
    end
    A->>S: GET /admin/api/frames?pairing_code=123456
    S-->>A: 200 [the unclaimed frame, enrolled_at, enrolled_ip]
    A->>S: PATCH /admin/api/frames/{id} {status: active, pairing_code, name}
    S-->>A: 200 frame
    K->>S: GET /api/v1/frames/{id}
    S-->>K: 200 {status: active, config_version, display, ...}
    loop every poll_seconds
        K->>S: GET /api/v1/frames/{id}
        K->>S: PUT /api/v1/frames/{id}/telemetry
    end

Frame API

All paths are under /frames/api/v1. "Frame auth" means the Authorization: Frame <id>.<key> header or the fk cookie; a request for another frame's id gets 403 id_mismatch.

POST /frames enroll

Body (at most 1 KiB):

The pairing code is six digits and is valid for 24 hours. pairing_expires_in counts seconds from the response, so the kiosk needs no synchronized clock.

GET /frames/{id} self GET

The answer depends on the frame's status.

Active body:

The three header-only keys are absent, not empty, on a cookie request, because page script must never see them.

PUT /frames/{id}/telemetry

A PUT replaces the stored report: an omitted optional field is stored as empty. The one exception is ha_dashboards. Body limit 16 KiB. Answer 204.

ha_dashboards entries: path matches ^[a-z0-9][a-z0-9_-]{0,63}$; title is at most 80 characters, and one with control or format characters is replaced by its path. Any bad entry is a 422 with fields.ha_dashboards.

PUT /frames/{id}/screenshot

The admin asks for a live view; the self GET delivers a request id; the kiosk captures its screen and uploads it here.

Query: request_id (32 hex), dimmed (0 or 1), age_ms (0 to 60,000). Body: the raw JPEG, Content-Type: image/jpeg, at most 600 KiB, between 1 × 1 and 1920 × 1200 pixels.

The capture time is the server's time minus age_ms; the frame's clock is not trusted.

GET /frames/{id}/dashboard

Returns what the page draws. Cache-Control: no-store.

{
  "now": 1790000000,
  "v": "1789999000:12",
  "tz": "America/Chicago",
  "idle_home_seconds": 120,
  "pages": [ { "widget": "weather", "label": "Weather", "icon": "weather" } ],
  "widgets": { "clock": {}, "weather": { "place": "Home", "now": {}, "hourly": [], "daily": [] } }
}

• v is <newest app file modification time>:<config_version>. When it changes, the page reloads itself.
• pages lists the rail items the frame should show.
• widgets has an entry for each enabled widget and none for the others. A widget with nothing to say is {}.

What each widget puts in its entry:

GET /frames/{id}/kiosk-releases/{sha256}

Downloads the kiosk update. Header auth only: a cookie request gets 403 header_required. The sha256 (64 lowercase hex) must be the hash of this frame's current target release, or the answer is 404. The file is chosen from the database row, never from the URL.

GET /frames/{id}/photos/{photoId}.jpg

Returns one frame-sized photo from the local library. photoId is a positive integer. Auth is frame header or cookie.

• 200 image/jpeg with a strong ETag (the content hash). If-None-Match gets 304. Also X-Content-Type-Options: nosniff, Content-Security-Policy: default-src 'none'; sandbox, Cross-Origin-Resource-Policy: same-origin, Cache-Control: private, max-age=86400.
• 404 unless the photos widget is on for this frame, its source is the local library, and the photo is in the frame's current approved catalog.

GET, PATCH /frames/{id}/notes/{cardId}

Part of the cards widget.

• GET returns the full card: {id, from, sent_at, opened_at, cover, stamp, message, signature, signature_text}. 404 if the card is another frame's, cards are off, or it has aged out of the mailbox.
• PATCH with {"opened": true} (the only accepted body) marks it opened and returns {opened_at}, the server's time.

Page, assets and widget scripts

Frame auth, active frames only. These are what the WebView loads.

Assets carry an ETag and answer 304. With a valid ?v= query they are cached for a year (private, max-age=31536000, immutable); without one, no-cache.

Admin API

All paths are under /frames/admin/api. Rules for every endpoint:

1. A signed-in session cookie is required, else 401 auth_required with WWW-Authenticate: Cookie realm="frame-admin".
2. The request must be same-origin (Sec-Fetch-Site: same-origin, or a matching https Origin), reads included, else 403 bad_origin.
3. Anything but a GET needs the header X-CSRF-Token (from GET /api/session), else 403 bad_csrf.
4. JSON bodies are at most 16 KiB.
5. The "Re-auth" column marks endpoints that need the password entered in the last five minutes. They fail with 403 reauth_required until POST /api/session/reauthentications succeeds.

Every Location header is built from frames_url.

Session

Frames

PATCH /frames/{id} accepts any of these fields (others are a 422):

Re-auth is required when the request revokes or restores a frame, changes display_kind or display_url, or includes kiosk_target_id. The answer is 200 with the frame (below). Specific errors: 409 invalid_transition, 409 pairing_failed (wrong or expired code; counts toward the 5-per-10-minutes limit), 409 pick_time_unavailable (another active frame picks at the exact same UTC minute), 409 not_active, 409 release_not_proven, 422.

A frame object:

{
  "id": "0123456789abcdef0123456789abcdef", "short_id": "01234567", "name": "Kitchen", "status": "active",
  "online": true, "last_seen": 1790000000, "last_ip": "192.0.2.10",
  "app_version": 10, "local_ip": "192.0.2.20", "mac": "02:00:00:00:00:01", "ssid": "home", "rssi": -52, "uptime": 86400,
  "layout": "dashboard", "location": "Home", "display_kind": "dashboard", "display_url": null,
  "tz": "America/Chicago", "idle_home_seconds": 120, "pick_time": "05:00", "bedtime": null, "wake_time": null,
  "config_version": 12, "enrolled_at": 1780000000, "enrolled_ip": "192.0.2.10", "pin_set": true,
  "kiosk": { "version_code": 14, "watchdog": true, "target": null, "status": "none", "failure": null },
  "screenshot": null, "screenshot_supported": true
}

online means seen in the last 120 seconds. kiosk.status is none (no target), unknown (no report yet), current, pending or failed. kiosk.target is {id, version_code, version_name}; kiosk.failure is {sha256, reason} and only shows when it is about the current target.

POST /frames/{id}/screenshot-requests answers 202 {request: {id, requested_at, expires_at}} with a Location to the status. A second call while one is pending returns the same body. Errors: 404, 409 not_active, 409 unsupported (the kiosk's app_version is below 9), 429 with Retry-After (under 10 seconds since the last request). Poll GET …/screenshot until latest.request_id equals the id you got; if request becomes null without a match, it expired.

GET /frames/{id}/screenshot answers {request: {id, requested_at, expires_at} or null, latest: {request_id, captured_at, uploaded_at, dimmed, width, height, bytes, image_url} or null}.

Library: locations and calendars

Creating returns 201 with a Location. A duplicate name or address is 409. A calendar is returned as {id, label, host, color, created_at, state}; the full address is never returned. state is {last_ok, last_err, fail_count, next_at} or null.

Widgets on a frame

GET returns a list. Enabled widgets come first, ordered by when they were switched on, then the rest in registry order. Each row:

{
  "widget": "weather", "label": "Weather", "icon": "w-weather", "description": "Current conditions and forecast for a location.",
  "settings": { "location_id": "location" }, "enabled": true, "position": 1, "enabled_at": 1780000000,
  "config": { "location_id": 1 }, "info": {}
}

settings maps each setting key to its type. config omits secret settings. info appears only for widgets that have an info hook.

PUT body: {enabled: bool, position: 0 to 99, config: {…}}. Answer 204. 404 for an unknown widget id; 422 with fields.config (a setting failed), fields.enabled or fields.position. A secret setting you leave out is kept; "" clears it. Any real change bumps the frame's config_version.

Kiosk releases

A release object: {id, version_code, version_name, sha256, size, notes, uploaded_at, uploaded_by, running_on, targeted, proven}. running_on counts frames reporting that version, targeted counts frames told to install it, proven is whether a frame has downloaded it and then reported running it.

POST /kiosk-releases : the body is the raw APK. Headers: Content-Type: application/vnd.android.package-archive and X-Release-Signature: <base64 DER ECDSA signature>. At most 16 MiB.

POST /kiosk-releases/{id}/rollouts answers 200 {targeted: [frame ids], already: [frame ids]}, or 409 release_not_proven if no frame has proven the release. DELETE answers 204, or 409 release_targeted while a frame still targets it.

Setting a single frame's target is PATCH /frames/{id} with kiosk_target_id. A frame without the rollback watchdog may only be given a proven release (409 release_not_proven).

The same upload exists on the command line: php app/bin/kiosk-release.php add <apk> [<sig>] [--notes "…"].

Photo library (photos widget)

Where an endpoint takes or returns a photo, the item is:

{
  "id": 41, "album_id": 3, "status": "pending", "width": 1280, "height": 720, "bytes": 183422,
  "added_at": 1790000000, "approved_at": null, "added_by": "Aunt Sue", "drop_link_id": 7,
  "thumb_url": "/frames/admin/api/photos/41/thumb.jpg", "image_url": "/frames/admin/api/photos/41/image.jpg"
}

status is pending or approved; approved_at is null while pending. added_by is "admin" for admin uploads and otherwise the link's name when the photo arrived. width, height and bytes describe the stored, resized JPEG.

GET /photo-library

{
  "limits": { "library_bytes": 5368709120, "album_photos": 5000, "drop_per_day": 300, "upload_bytes": 31457280, "pending_album": 500, "pending_bytes": 536870912 },
  "usage": { "bytes": 123456789, "photos": 812, "pending": 3 },
  "imagick": { "ok": true, "code": null, "heic": true },
  "sandbox": { "mode": "bwrap", "active": true }
}

The key imagick kept its old name; it describes the image decoder. code is decoder_unavailable or sandbox_unavailable when ok is false (then uploads answer 503). heic is false when iPhone photos cannot be processed. sandbox.mode is bwrap, user, auto or none.

Albums: an album is {id, name, created_at, count (approved), pending, bytes (all), newest_at, used_by: [{frame_id, name}]}. Create answers 201 with Location; 409 for a duplicate name.

GET /photo-albums/{a}/photos takes status (pending or approved; omit for both), before (a photo id) and limit (1 to 200, default 60). It answers {items: [photo], next_before: id or null}, newest first.

POST /photo-albums/{a}/photos : the body is one raw image, Content-Type: image/* or application/octet-stream. The bytes decide the type: JPEG, PNG, WebP and HEIC are accepted.

Admin uploads are approved at once.

Deletions and approvals take {ids: [1, 2, …]} with 1 to 500 integers. Deletions answer {deleted: [ids], missing: [ids]}; approvals answer {approved: [ids], missing: [ids]}. missing lists ids not in that album. Approving an already approved photo counts as approved.

Images are image/jpeg, nosniff, Content-Security-Policy: default-src 'none'; sandbox, Cross-Origin-Resource-Policy: same-origin. Approved photos are cached (private, max-age=86400, with an ETag); pending ones are no-store.

GET /frames/{f}/photo-set answers {enabled, album: {source, host, name, count} or null, tz, pick_time, picked_for, picked_at, next_pick_at, stale, photos: [{id, new, added_at, thumb}]}. It never picks a set or records anything.

Saving the source for a frame uses the widget endpoint: PUT /frames/{f}/widgets/photos with config: {source: "nextcloud" | "local", album_url, local_album, seconds}. album_url is a secret (omit to keep). GET returns info: {source, sources: [{id, label}], album_set, host, name, count, pending, error}.

Drop links (photos widget)

A drop link belongs to one album. The page it opens is public and write-only.

A link object: {id, album_id, name, created_at, last_used_at, expires_at, revoked_at, photos, pending}. name is 1 to 40 characters, unique within the album. expires_at must be in the future and at most 366 days away; the default is 90 days.

Create answers 201 {drop_link, link}, where link is https://example.com/frames/drop/<43 characters>. Rotating answers 200 with the same shape. The link is shown once and is never returned again. Responses that carry a link are Cache-Control: no-store. Restoring a revoked link (revoked: false) makes the old link work again; rotate if it may have leaked.

Cards (notes widget)

Cards are greeting cards sent from family through personal links. The admin never reads their text.

Sender objects are {id, frame_id, name, created_at, revoked_at, last_used_at, cards_sent}. The link is never part of a sender.

Art uploads send the raw image with Content-Type: image/jpeg, image/png or image/webp (at most 4 MiB, minimum and maximum pixel sizes apply). Designs also need ?category=<slug>. A new image answers 201; an image already in the library answers 200, or 409 duplicate if it is already filed under another category. An item is {id, [category], url, width, height, bytes, enabled, created_at, uses}.

/note-cards items are {id, frame_id, frame, sender_id, from, category, created_at, opened_at, cover_url, stamp_url} with next_before.

Public endpoints

These need no account. They need the secret from a link.

Drop page and upload

<token> is 43 characters from A-Za-z0-9_-. Pages and API replies carry Referrer-Policy: no-referrer and X-Robots-Tag: noindex, nofollow. A cross-site request (Sec-Fetch-Site other than same-origin or none, or a foreign Origin) is 403 bad_origin.

GET /api/v1/drops/<token> answers:

{ "link": "Aunt Sue", "album": "Family", "limits": { "upload_bytes": 31457280 },
  "remaining": { "hour": 97, "day": 280 }, "expires_at": 1797776000 }

remaining is only this link's own quota.

POST /api/v1/drops/<token>/photos : one raw image per request, Content-Type: image/* or application/octet-stream. The photo lands pending. Success is always the same answer, whether the photo is new, a duplicate of a pending one or a duplicate of an approved one:

{ "received": true }

(status 202). Errors use the standard shape:

Card page and API

POST …/cards body (at most 32 KiB):

Answers: 201 with the card and Location: cards/<id>; 409 not_enabled, 409 sender_full (10 unopened), 409 mailbox_full (30 unopened on the frame); 422; 429. A link that is revoked is 403 revoked; a frame that is not active is 403 not_active.

Related

• Security: why the authentication and limits are what they are
• Kiosk update protocol: the offer, download and telemetry in context
• Writing a widget: adding routes
• Database: the tables behind these endpoints