Skip to content

API Reference

ant1fr edited this page Nov 19, 2026 · 2 revisions

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.

Check compatibility first

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.

Authentication

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=. With ADMIN_PASSWORD and no APP_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 .env is pinned and cannot be changed through the API it protects.
  • Login. POST /api/auth/login sets a signed HttpOnly, SameSite=Strict session cookie (Secure behind HTTPS, scoped to ROOT_PATH), valid SESSION_TTL_HOURS (one week). Changing ADMIN_PASSWORD signs everyone out. Repeated failures are throttled per client (exponential backoff, up to 5 minutes). Without ADMIN_PASSWORD but 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/session tells the mode (open, key, password) and whether the caller is signed in. Home Assistant sensors that poll /api/status need the API key once ADMIN_PASSWORD is 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.

Endpoints

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

Examples

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"

Ephemeral images and the queue

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": false when 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_minutes protection; 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.

Now playing (music)

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.


Home · Report an issue · Roadmap

Clone this wiki locally