Repository navigation
API Reference
Single source of truth. The API is defined by the versioned API Contract (compatibility handshake, capabilities, authentication, errors, Zeroconf, breaking-change policy and a generated endpoint index) and the machine-readable
openapi.json. This page is a friendly summary; if it ever disagrees with those two files, they win.
Every instance also serves interactive docs at /docs (Swagger) and the live schema at
/openapi.json; behind a sub-path, prefix them with your ROOT_PATH.
GET /api/health is public in every authentication mode and answers with the handshake:
version, api_version, min_api_version, auth and the sorted capabilities list. A client
written for contract N is compatible when min_api_version <= N <= api_version; use
capabilities (not version) to enable optional features. Details in the
contract.
| Setup | Effect |
|---|---|
| Nothing set | Pure LAN usage: everything is open. |
APP_API_KEY only |
POST/PUT/DELETE, /api/config, /api/immich, /api/smart-mix, /api/tmdb, /api/activity need the key; other reads stay public. Sign in to the web UI with the key. |
ADMIN_PASSWORD |
Web UI login (admin + password). Everything needs a session or the API key except /api/health, the login and, while PUBLIC_IMAGE_ENDPOINTS=true, the image endpoints. |
-
API key. Send it as
X-API-Key: <key>,Authorization: Bearer <key>or?api_key=. WithADMIN_PASSWORDand noAPP_API_KEY, a key is generated into./data/secrets.json(readable by its owner only); the signed-in admin can view, copy and regenerate it (GET /api/auth/api-key,POST /api/auth/api-key/regenerate). A key set in.envis pinned and cannot be changed through the API it protects. -
Login.
POST /api/auth/loginsets a signedHttpOnly,SameSite=Strictsession cookie (Securebehind HTTPS, scoped toROOT_PATH), validSESSION_TTL_HOURS(one week). ChangingADMIN_PASSWORDsigns everyone out. Repeated failures are throttled per client (exponential backoff, up to 5 minutes). WithoutADMIN_PASSWORDbut with an API key, the login accepts the API key as the password. -
CSRF. Requests authenticated by the cookie that change something must send
X-Requested-With: SmartFrame; browsers cannot add it cross-site without a CORS preflight. API key requests are unaffected. -
GET /api/auth/sessiontells the mode (open,key,password) and whether the caller is signed in. Home Assistant sensors that poll/api/statusneed the API key onceADMIN_PASSWORDis set.
Runtime settings are stored in ./data/config.json and can be edited with
GET/PUT /api/config. Values saved there take precedence over .env, which in turn
takes precedence over built-in defaults. POST /api/config/reset removes saved values.
| Method | Path | Summary |
|---|---|---|
GET |
/api/activity |
Recent renders and log lines (newest first) |
GET |
/api/auth/api-key |
Show the API key |
POST |
/api/auth/api-key/regenerate |
Generate a new API key |
POST |
/api/auth/login |
Sign in to the web UI |
POST |
/api/auth/logout |
Sign out of the web UI |
GET |
/api/auth/session |
Current session |
GET |
/api/config |
Read the runtime configuration |
PUT |
/api/config |
Update the runtime configuration |
POST |
/api/config/reset |
Reset saved values to .env / defaults |
GET |
/api/config/schema |
JSON Schema of the runtime configuration |
POST |
/api/context |
Set ambient context fields (each expires on its own) |
GET |
/api/context |
The live ambient context |
DELETE |
/api/context |
Clear the ambient context |
GET |
/api/current.bin |
Current Fraimic frame buffer (.bin) |
GET |
/api/current.jpg |
Current image (enhanced, before dithering) |
GET |
/api/current_dithered.png |
Current image as rendered by the panel (6-color simulation) |
POST |
/api/display/immich |
Select and display an Immich photo |
POST |
/api/display/media |
Display a poster (alias of /api/display/tmdb) |
POST |
/api/display/now-playing |
Display the album cover of the track that is playing |
POST |
/api/display/smart-search |
Display a photo found by a contextual search |
POST |
/api/display/title-card |
Display a typographic card (title, subtitle, caption) |
POST |
/api/display/tmdb |
Display a movie or TV series poster |
POST |
/api/display/upload |
Display an uploaded image |
GET |
/api/fraimic/info |
Frame telemetry (battery, Wi-Fi, firmware) |
POST |
/api/fraimic/push |
Force push the current image to the frame |
POST |
/api/fraimic/wakeup |
Signal that the frame is awake (Home Assistant webhook) |
GET |
/api/health |
Liveness and compatibility handshake (always public) |
GET |
/api/immich/albums |
List albums |
GET |
/api/immich/people |
People known to each account (cached) |
POST |
/api/immich/people/refresh |
Reload the people lists from Immich |
POST |
/api/immich/test |
Test an Immich connection (saved or unsaved settings) |
GET |
/api/immich/thumbnail/{account}/{kind}/{item_id} |
Small thumbnail of an asset (album cover) or a person (face) |
POST |
/api/playground/render |
Render an image with several eInk profiles / dithers (never displayed) |
GET |
/api/preview.jpg |
Most recent render (enhanced, before dithering), pushed or not |
GET |
/api/preview_dithered.png |
Most recent render as the panel would show it (6-color simulation) |
GET |
/api/queue |
Inspect the upload queue |
DELETE |
/api/queue/ephemeral |
Cancel the ephemeral image (playback stopped) |
POST |
/api/refresh |
Re-run the active source rule |
GET |
/api/smart-mix |
Show the Smart Mix playlist |
POST |
/api/smart-mix/context |
Boost or override the Smart Mix temporarily |
DELETE |
/api/smart-mix/context |
Remove the Smart Mix boost |
GET |
/api/status |
System status |
GET |
/api/tmdb/search |
Search movies and series (for the web UI picker) |
POST |
/api/tmdb/test |
Test a TMDB API key |
KEY=your-api-key
# Show the next Immich photo and push it to the frame
curl -X POST http://localhost:8080/api/refresh -H "X-API-Key: $KEY"
# Show a movie poster for 30 minutes, then go back to the slideshow
curl -X POST http://localhost:8080/api/display/tmdb -H "X-API-Key: $KEY" \
-H 'Content-Type: application/json' -d '{"query": "Dune", "year": 2021, "ttl_minutes": 30}'
# Tell the engine who is home and what the weather is (expires by itself after 2 hours)
curl -X POST http://localhost:8080/api/context -H "X-API-Key: $KEY" \
-H 'Content-Type: application/json' \
-d '{"presence": ["Alice", "Bob"], "weather": "rainy", "ttl_minutes": 120}'
# Guests over: force Family Mode on for 6 hours
curl -X POST http://localhost:8080/api/context -H "X-API-Key: $KEY" \
-H 'Content-Type: application/json' -d '{"family_mode": {"value": true, "ttl_minutes": 360}}'
# Read, then clear the context
curl http://localhost:8080/api/context -H "X-API-Key: $KEY"
curl -X DELETE "http://localhost:8080/api/context?field=presence" -H "X-API-Key: $KEY"A push with "ephemeral": true (the default for posters, covers and smart searches) is
temporary: it never becomes the image to come back to, nor the rule replayed by
POST /api/refresh.
-
Expiry. Posters and covers carry an
expires_at. When it passes, the previous non-ephemeral image becomes the current image again. It is re-sent only if the frame may not be showing it: a deep-sleeping frame that never received the cover is left alone, and an expired image is dropped from the queue instead of being uploaded when the frame wakes up. -
Cancellation.
DELETE /api/queue/ephemeral(e.g. playback paused or stopped) drops a queued ephemeral image and restores the previous one immediately. It is idempotent ("cancelled": falsewhen nothing was ephemeral). - No previous image yet? A refresh of the active rule runs in the background instead.
- Ending an ephemeral image also lifts its
hold_minutesprotection; it does not restart the refresh timer.
| Endpoint | Purpose |
|---|---|
GET /api/queue |
The upload waiting for the frame (expired images are never listed), the last delivery, and the ephemeral image shown or queued with its expires_at
|
DELETE /api/queue/ephemeral |
Cancel the ephemeral image now: cancelled, dropped_pending, reverted, pushed_base, refreshing
|
GET /api/status includes the same ephemeral block. The last successful delivery is kept
in ./data/last_delivery.json, so what the frame shows is still known after a restart.
POST /api/display/now-playing shows the cover of the track that is playing with the
album template.
curl -X POST http://localhost:8080/api/display/now-playing -H 'Content-Type: application/json' \
-d '{"title": "So What", "artist": "Miles Davis", "album": "Kind of Blue",
"duration_seconds": 545, "position_seconds": 12, "style": "vinyl"}'| Request field | Meaning |
|---|---|
title, artist, album
|
Track details (media_title, media_artist, media_album_name in Home Assistant). artist is required, plus title or album
|
show_title |
Print the track title on the cover (default music.show_track_title, off). See below |
artwork_url, artwork_base64
|
Cover provided by the player (base64 is tried first) |
enrich_artwork |
When no usable cover was provided, look one up (default true; also music.enrich_artwork) |
style |
sleeve or vinyl (default music.default_style) |
duration_seconds, position_seconds, ttl_seconds
|
When the cover expires (see below) |
ephemeral, hold_minutes, push_to_fraimic
|
As for posters |
Track title and deduplication. By default the cover shows the artist and the album, not
the track title (music.show_track_title, or show_title per request). The title only
counts in the picture's identity when it is printed, so while an album plays, every track
resolves to the same picture: the call returns deduplicated: true, nothing is sent to
the frame (no e-ink refresh) and only the expiry is extended. The frame refreshes when the
album, the artist or the style changes. Without an album, the title is always printed (it is
the only thing that tells tracks apart). Keep calling the endpoint on every track change.
Breaking change: before, each track was a new picture with its title; set
music.show_track_title: true to get that back.
Cover lookup. No API key is needed: the
Deezer public search (1000x1000 cover_xl), then
MusicBrainz and the Cover Art Archive
(studio albums are preferred over compilations, live albums and videos; requests are
rate-limited to one per second as MusicBrainz asks and retried when it throttles). Covers
are requested for their on-panel size: Deezer at JPEG quality 100 (1000 px, or 1400 px
when the cover is displayed larger), the Cover Art Archive at 1200 px (its original when
larger is needed). Lookups are cached in memory
(music.lookup_cache_size). Without any cover, a typographic card is shown. Disable a
service with music.deezer_enabled / music.musicbrainz_enabled.
Lifetime. The cover expires when the track should be over: duration_seconds - position_seconds + music.ttl_grace_seconds (30), or ttl_seconds, or
music.default_ttl_minutes (10). Sending the track that is already displayed only moves
its expiry ("deduplicated": true in the response): nothing is rendered or sent again, so
the Home Assistant automation can fire on every attribute change without waking a
battery-powered frame.