← Docs

API Reference

Kairos exposes the same REST API that Hades itself is built on — sources, libraries, channels, scheduling, scrapers, discovery, chapters, and more. This is the surface to build against if you want to script Pantheon or write an alternate client. It's a large, actively-growing API; if something here looks off, the source of truth is always kairos/src/api/services/ in the repo.

💡 Base URL & auth. Every path below is relative to your Kairos host — direct (default :8081) or through Hermes' gateway (default :8000), which transparently proxies the entire /api/* surface to Kairos. Authenticate once with POST /api/auth/login, then send the returned token as Authorization: Bearer <token> on every subsequent request (a ?token= query param also works, for contexts that can't set headers — e.g. an <img> tag or an EventSource stream).

# Log in, grab a token, list channels
curl -sX POST http://your-server:8081/api/auth/login \
  -H 'Content-Type: application/json' \
  -d '{"username":"admin","password":"••••••••"}'
# → {"token":"...", "user": {"role":"admin", ...}}

curl -s http://your-server:8081/api/channels \
  -H 'Authorization: Bearer <token>'

GET read

POST create / action

PATCH partial update

DELETE remove

public no token required

auth any logged-in user

admin admin role required

Auth & Users #

Method	Path	Description	Auth
GET	`/api/auth/setup`	Whether initial admin setup is still needed	public
POST	`/api/auth/setup`	Create the first admin accountbody: username, password	public
POST	`/api/auth/login`	Body: username, password → token	public
POST	`/api/auth/logout`	No-op without a token	public
GET	`/api/auth/me`	Current user profile	auth
GET	`/api/users`	List all users	admin
POST	`/api/users`	Create a userbody: username, password, role	admin
PATCH	`/api/users/:id`	Change password/rolebody: password, role	admin
DELETE	`/api/users/:id`	Blocked for self-delete or the last remaining admin	admin
PATCH	`/api/users/:id/restriction`	Set parental-control ceilingsbody: restricted, max_tv_rating, max_movie_rating, max_channel_rating	admin
GET	`/api/users/:id/overrides`	Per-title allow/block overrides for a user	admin
POST	`/api/users/:id/overrides`	Body: entity_type (show/movie/channel), entity_id, mode (allow/block)	admin
DELETE	`/api/users/:id/overrides/:entity_type/:entity_id`	Remove an override	admin
POST	`/api/auth/cast-token`	Mint a viewer-capped token for Cast/relay handoff	auth
GET	`/api/auth/sessions`	List the caller's own device/Cast sessionsquery: purpose (default cast)	auth
DELETE	`/api/auth/sessions/:id`	Revoke one of the caller's own sessions	auth

Sources & Libraries #

Method	Path	Description	Auth
GET	`/api/sources/types`	Supported source types (plex, jellyfin, emby, local)	admin
GET	`/api/sources`	List configured sources	admin (GET also public, for internal service use)
POST	`/api/sources`	Add a sourcebody: source_id, source_type, display_name, base_url	admin
POST	`/api/sources/test`	Test a connection before savingbody: source_type, base_url, token, user_id	admin
DELETE	`/api/sources/:id`	Remove a source	admin
GET	`/api/sources/:id/libraries/available`	Libraries discoverable on the remote server	admin
GET	`/api/sources/:id/fs`	Browse local filesystem subdirectories (local source only)query: path	admin
GET	`/api/sources/:id/libraries`	Libraries registered on this source	admin
POST	`/api/sources/:id/libraries`	Register a librarybody: external_lib_id, display_name, library_type (show/movie/mixed), preferred_scraper, preferred_language, include_anidb	admin
PATCH	`/api/sources/:id/libraries/:lid`	Update a librarybody: display_name, library_type, preferred_scraper, preferred_language, include_anidb, skip_scraping, show_on_home	admin
GET	`/api/sources/:id/libraries/:lid/scraper-priority`	Scraper priority orderquery: item_type	admin
PUT	`/api/sources/:id/libraries/:lid/scraper-priority`	Body: item_type, order[]	admin
DELETE	`/api/sources/:id/libraries/:lid`	Remove a library	admin
POST	`/api/sources/:id/sync`	Trigger an incremental sync	admin
POST	`/api/sources/:id/hard-sync`	Wipe source_mapping and resync from scratch	admin
GET	`/api/sources/:id/browse/playlists`	Remote playlists visible on this source	admin
GET	`/api/sources/:id/browse/collections`	Remote collectionsquery: library_id	admin
GET	`/api/sources/:id/browse/playlists/:eid`	Items inside a remote playlist	admin
GET	`/api/sources/:id/browse/collections/:eid`	Items inside a remote collection	admin
GET	`/api/sources/:id/sample-path`	One sample file path, for the Path Map UI	admin
GET	`/api/sync/status`	Whether any sync is currently running	admin

Config & Settings #

Method	Path	Description	Auth
GET	`/api/config/settings`	Full runtime settings	admin
GET	`/api/config/public-settings`	Subset of settings needed by Hephaestus/Hades	public
PATCH	`/api/config/settings`	Body: epg_debug, sync_debug, sync_threads, stream_buffer_size, image_cache_ttl_hours, verbose_transcode_logs, cast_app_id	admin
POST	`/api/config/epg/clear-all`	Wipe all materialized schedule data	admin
POST	`/api/logs/client`	Frontend error reportingbody: level, message	public (internal: Hades)
POST	`/api/config/library/reset`	Wipe the entire media index (keeps sources/channels/users)	admin
GET	`/api/config/debug-dump`	Download a sanitized SQLite snapshot of library/matching tables	admin
GET	`/api/config/credentials`	Per-source token/user-id presence flags (not the values)	admin
GET	`/api/config/credentials/:source_id`	Same, for one source	admin
PUT	`/api/config/credentials/:source_id`	Body: token, user_id	admin
DELETE	`/api/config/credentials/:source_id`	Clear stored credentials	admin
GET	`/api/config/path-maps/:source_id`	Path maps for a source	admin
PUT	`/api/config/path-maps/:source_id`	Body: maps: [{from, to}]	admin
GET	`/api/tv/manifest`	Layout contract for native TV/mobile renderers (pantheon-android, Hades' own /tv route) — nav structure, filter-pills fields, and a theme block of style tokens generated from Hades' own design system so native clients stay visually in sync without duplicating hand-written token values	public

Arr Integration — Sonarr / Radarr #

Method	Path	Description	Auth
GET	`/api/config/arr`	Sonarr/Radarr connection config	admin
PATCH	`/api/config/arr`	Body: sonarr_url, sonarr_api_key, radarr_url, radarr_api_key	admin
POST	`/api/arr/lookup`	Search Sonarr/Radarr by title or external idbody: type (show/movie), title \| tvdb_id \| tmdb_id \| imdb_id	admin
GET	`/api/arr/options/:type`	Quality profiles + root folders	admin
POST	`/api/arr/add`	Push a title to Sonarr/Radarrbody: type, add_data	admin

Content Requests #

Method	Path	Description	Auth
GET	`/api/requests`	Admin sees every request, viewer sees only their own	auth
POST	`/api/requests`	Request a piece of contentbody: content_type, source, external_id, title, year, poster_url	auth
PATCH	`/api/requests/:id`	Approve/reject, optionally auto-push to arrbody: status (approved/rejected), arr_add {type, add_data}	admin
DELETE	`/api/requests/:id`	Remove a request	auth (owner or admin)

Channels #

Method	Path	Description	Auth
GET	`/api/channels`	List channels (parental-filtered)	public (GET)
GET	`/api/channels/:id/access-check`	Parental-control gate before live playback	auth
POST	`/api/channels`	Body: name, number, timezone, advance_mode	admin
PATCH	`/api/channels/:id`	Body: name, timezone, offline media, stream_resolution/bitrates, seed, content_tag, anchor_hashes, and more	admin
DELETE	`/api/channels/:id`	Remove a channel	admin
GET	`/api/channels/:id/logo`	Serves local file or redirects to a remote logo URL	public
GET	`/api/channels/:id/export`	Export channel config as JSONquery: depth (deep/shallow)	admin
POST	`/api/channels/import/preview`	Preview an exported channel JSON before importing	admin
POST	`/api/channels/import`	Import a previously exported channel	admin
POST	`/api/channels/:id/filler`	Add a channel-level filler entrybody: content_type, content_id, advancement, weight, season_filter	admin
PATCH	`/api/channels/:id/filler/:eid`	Body: advancement, weight	admin
DELETE	`/api/channels/:id/filler/:eid`	Remove a filler entry	admin

Blocks, Content & Bumpers #

A block owns a recurring time window on a channel; content and filler/bumper entries hang off it.

Method	Path	Description	Auth
GET	`/api/channels/:id/blocks`	List blocks on a channel	admin
POST	`/api/channels/:id/blocks`	Full block object: block_type, day_mask, start_time, priority, advancement, etc.	admin
PATCH	`/api/channels/:id/blocks/:bid`	~25 optional fields — scheduling/filler/bumper tuning	admin
DELETE	`/api/channels/:id/blocks/:bid`	Remove a block	admin
POST	`/api/channels/:id/blocks/:bid/content`	Add a show/movie/list to a block	admin
PATCH	`/api/channels/:id/blocks/:bid/content/:cid`	Body: season_filter, position, weight, run_count, include_specials, episode_order	admin
DELETE	`/api/channels/:id/blocks/:bid/content/:cid`	Remove a content entry	admin
DELETE	`/api/channels/:id/blocks/:bid/content/:cid/cursor`	Reset a content item's playback cursor	admin
POST	`/api/channels/:id/blocks/:bid/playlist`	Materialize block content into a Kairos playlist, optionally push to Plexbody: title, source_id	admin
POST	`/api/channels/:id/blocks/:bid/filler`	Body: content_id, content_type, advancement, weight, season_filter	admin
PATCH	`/api/channels/:id/blocks/:bid/filler/:eid`	Update a block-level filler entry	admin
DELETE	`/api/channels/:id/blocks/:bid/filler/:eid`	Remove it	admin
GET	`/api/channels/:id/bumpers`	List bumpers on a channel	admin
POST	`/api/channels/:id/bumpers`	Body: content_type, content_id, mode (between/...), every_n, season_filter	admin
PATCH	`/api/channels/:id/bumpers/:bid`	Update a bumper	admin
DELETE	`/api/channels/:id/bumpers/:bid`	Remove a bumper	admin

Episode Groups & Show Specials Linking #

Method	Path	Description	Auth
GET	`/api/shows/:id/groups`	Multi-part episode groupings	auth
POST	`/api/shows/:id/groups`	Body: name, group_type	admin
DELETE	`/api/shows/:id/groups/:gid`	Remove a grouping	admin
POST	`/api/shows/:id/groups/:gid/members`	Body: episode_id, part_num	admin
DELETE	`/api/shows/:id/groups/:gid/members/:mid`	Remove a member	admin
GET	`/api/shows/:id/grouping-candidates`	Auto-detected multi-part groupings for one show	auth
GET	`/api/grouping-candidates`	Same, across every show with an unconfirmed candidate	auth
POST	`/api/shows/:id/specials/scan`	Scan the movie library for this show's OVA/special	admin
GET	`/api/shows/:id/specials/candidates`	Candidate matches awaiting confirmation	admin
GET	`/api/shows/:id/specials`	Specials already linked via `episode.linked_movie_id`	admin
POST	`/api/shows/:id/specials/candidates/:cid/accept`	Confirm a link	admin
POST	`/api/shows/:id/specials/candidates/:cid/reject`	Dismiss a candidate	admin

Shows, Movies & Episodes #

The largest single resource group — library browsing, metadata editing, matching state, and writeback.

Method	Path	Description	Auth
GET	`/api/content/:type/:id/access-check`	Parental gate used before VOD starttype: movie \| episode \| show	auth
GET	`/api/images/proxy`	Fetch + cache any external image URLquery: url	public
POST	`/api/shows/:id/refresh-metadata`	Re-pull metadata from the confirmed scraper match	admin
POST	`/api/movies/:id/refresh-metadata`	Same, for a movie	admin
PATCH	`/api/shows/:id/skip-scraping`	Body: skip_scraping	admin
PATCH	`/api/movies/:id/skip-scraping`	Body: skip_scraping	admin
PATCH	`/api/shows/:id/find-specials`	Opt in/out of auto specials scanningbody: find_specials	admin
PATCH	`/api/shows/:id/episode-display-order`	Body: episode_display_order (season/aired)	admin
GET	`/api/libraries`	List libraries	auth
PATCH	`/api/libraries/:id/home-visibility`	Body: show_on_home	admin
GET	`/api/metadata/values`	Distinct values for a metadata field, for filter autocompletequery: field, type, library_id	auth
GET	`/api/shows`	Search/browse, paginated + parental-filteredquery: q, genre, year, content_rating, label, network, actor, country, collection, studio, sort, library_id, limit, offset	auth
GET	`/api/shows/:id/episodes`	Query: season	auth
GET	`/api/shows/:id/seasons`	Season list	auth
GET	`/api/shows/:id/languages`	Probed audio/subtitle languages	auth
GET	`/api/shows/:id/videoinfo`	Probed codec/resolution/bit-depth	auth
GET	`/api/episodes`	Searchquery: show_id, q, season, limit, offset	auth
GET	`/api/movies`	Search/browse — same filter family as /api/shows	auth
GET	`/api/shows/:id`	Full detail incl. every linked source (404 instead of 403 if restricted)	auth
PATCH	`/api/shows/:id`	Manual metadata edit, records a per-field overridebody: title, overview, studio, status, content_rating, genres, tags, labels, network, actors, countries, collections, year, imdb_id, tvdb_id, tmdb_id, thumb, art	admin
POST	`/api/shows/:id/writeback`	Push metadata back to Plex/Jellyfin — 403 unless the match is human-confirmed	admin
POST	`/api/shows/:id/merge`	Merge a duplicate show into this onebody: duplicate_id, confirm	admin
GET	`/api/shows/:id/thumb`, `/art`	Proxied poster/art	auth
GET	`/api/episodes/:id/thumb`	Proxied episode thumbnail	auth
GET	`/api/movies/:id`	Full detail	auth
PATCH	`/api/movies/:id`	Similar field set to shows (incl. tags), minus season/network	admin
POST	`/api/movies/:id/writeback`	Same confirmed-match gate as shows	admin
POST	`/api/movies/:id/merge`	Body: duplicate_id, confirm	admin
GET	`/api/movies/:id/thumb`, `/art`	Proxied poster/art	auth
GET	`/api/movies/:id/languages`, `/videoinfo`	Probed language/video info	auth

Chapters #

Ad-break / intro-outro detection and manual chapter markers. Not yet consumed by the scheduler.

Method	Path	Description	Auth
GET	`/api/chapters/review`	Browse detected chapters for QA against the actual mediaquery: media_type, chapter_type, q, limit, offset	admin
GET	`/api/episodes/:id/chapters`, `/api/movies/:id/chapters`	Chapters for an item	auth
POST	`/api/episodes/:id/chapters`, `/api/movies/:id/chapters`	Add a chapter manuallybody: type, start, end (see ChapterRepository)	admin
PATCH	`/api/chapters/:id`	Edit a chapter	admin
DELETE	`/api/chapters/:id`	Remove a chapter	admin
POST	`/api/episodes/:id/chapters/sync`, `/api/movies/:id/chapters/sync`	Re-probe existing chapter markers from the source file	admin
POST	`/api/shows/:id/chapters/sync`	Same, looped over every episode	admin
POST	`/api/shows/:id/chapters/detect`, `/api/movies/:id/chapters/detect`	Trigger async ffmpeg-based scene/ad-break detection (202 accepted)	admin
GET	`/api/chapters/detect/status`	Detection job status	admin
POST	`/api/chapters/:id/writeback`	Stub — currently returns 501 Not Implemented	admin

Playlists #

Named, orderable item lists. Three independent axes on the same resource: static (explicit item list) vs smart (items periodically recomputed from a stored filter_expr — the same filter language as /api/shows//api/movies); linked-to-a-remote-list or not (Plex playlist/collection, or a generic Jellyfin/Emby playlist via source-sync); and shown as a Home page shelf or not (a shelf is just a smart playlist with show_on_home=1 — there's no separate shelf table). Distinct from the M3U/XMLTV IPTV feed (see Scheduler below).

Method	Path	Description	Auth
GET	`/api/playlists`	List playlists (admin — full editing internals)	admin
GET	`/api/playlists/browse`	Lightweight tile listing for the Library's Playlists section — title, mode, item_count, total_ms, poster_source, first few items for a client-side poster-collage fallback	auth
GET	`/api/home-playlists`	Every smart playlist with show_on_home=1 whose active window (home_active_start/end, MM-DD, empty = always) includes today, ordered by home_order — the extra Home-page shelves layered alongside the built-in ones	public
POST	`/api/playlists/plex-sync-all`, `/source-sync-all`, `/refresh-smart-all`	Bulk: pull every Plex-linked list, every source-linked list, or recompute every smart playlist's items from its filter_expr	admin
POST	`/api/playlists`	Body: title, mode	admin
GET	`/api/playlists/:id`	Detail (admin — full editing internals incl. filter_expr)	admin
GET	`/api/playlists/:id/items`	Resolved item list — any authenticated viewer	auth
GET	`/api/playlists/:id/resolve-play-target`	Resolves Play/Restart/Shuffle to a concrete playable item, honoring watch progress	auth
POST	`/api/playlists/:id/plex-sync`	Pull from a linked Plex listbody: source_id, external_id, plex_type (playlist/collection)	admin
POST	`/api/playlists/:id/source-sync`	Pull from a linked Jellyfin/Emby (or Plex) listbody: source_id, external_id, list_kind	admin
POST	`/api/playlists/:id/push`	Writeback — create or reconcile the linked remote list to match this playlist's current items (adds/removes both directions)	admin
POST	`/api/playlists/:id/refresh-smart`	Recompute this smart playlist's items from filter_expr now, instead of waiting for the regular sync-cycle pass	admin
DELETE	`/api/playlists/:id/plex-link`, `/source-link`	Unlink from the remote list (items are kept locally)	admin
PATCH	`/api/playlists/:id`	Body: title, mode (sequential/show_collection), membership (static/smart), filter_expr, smart_type (show/movie), smart_sort, smart_limit, poster_source, show_on_home, home_order, home_tile_limit, home_active_start, home_active_end	admin
DELETE	`/api/playlists/:id`	Remove a playlist	admin
GET	`/api/playlists/:id/export`	Portable JSON export of a playlist's definition + items	admin
POST	`/api/playlists/import`, `/import/preview`	Import a previously-exported playlist; preview first shows what would be created/matched without writing	admin
POST	`/api/playlists/:id/items`	Body: item_type, item_id (static playlists only)	admin
POST	`/api/playlists/:id/items/bulk`	Body: items: [{item_type, item_id}]	admin
DELETE	`/api/playlists/:id/items/:iid`	Remove an item	admin
PATCH	`/api/playlists/:id/items/:iid`	Reorderbody: position	admin

Filler Lists #

Same CRUD shape as Playlists, as a separate resource used for channel gap-filling. All routes are admin-gated with the same body shapes as their Playlists equivalents.

Method	Path	Description
GET	`/api/filler-lists`	List filler lists
POST	`/api/filler-lists/plex-sync-all`, `/source-sync-all`	Sync all linked lists
POST	`/api/filler-lists`	Create a list
GET	`/api/filler-lists/:id`	Detail + items
POST	`/api/filler-lists/:id/plex-sync`, `/source-sync`	Sync one list
DELETE	`/api/filler-lists/:id/plex-link`, `/source-link`	Unlink from remote list
PATCH	`/api/filler-lists/:id`	Update
DELETE	`/api/filler-lists/:id`	Remove
POST	`/api/filler-lists/:id/items`	Add an item
POST	`/api/filler-lists/:id/items/bulk`	Add items in bulk
DELETE	`/api/filler-lists/:id/items/:iid`	Remove an item

Activity, Logs & Metrics #

Method	Path	Description	Auth
POST	`/api/sync/all`	Trigger sync on every source (no admin check — any logged-in user)	auth
POST	`/api/sync/all-hard`	Force a hard sync on every source	admin
GET	`/api/logs/stream`	Server-Sent-Events log tail	public
GET	`/api/system/metrics`	CPU/RAM for this process + host	public

Downloads — yt-dlp #

Method	Path	Description	Auth
GET	`/api/config/download`	Configured download destination path	admin
PUT	`/api/config/download`	Body: path	admin
POST	`/api/download/jobs`	Start a yt-dlp jobbody: url, path	admin
GET	`/api/download/jobs`	List jobs with progress/log	admin

Scrapers & Matching #

Method	Path	Description	Auth
GET	`/api/scrapers/config`	Scraper configuration	admin
PATCH	`/api/scrapers/config`	Body: match_threshold, configs: [{source, api_key, language, enabled, language_weight, pin}]	admin
POST	`/api/scrapers/match`	Trigger a match pass (202 async, or already_running)body: target_id, item_type	admin
GET	`/api/scrapers/match/status`	Match job status	admin
GET	`/api/scrapers/stats`	Counts by match_status	admin
GET	`/api/scrapers/queue`	Review queue with candidatesquery: status, limit, offset	admin
POST	`/api/scrapers/queue/:kairos_id/manual-match`	Body: item_type, source, external_id, title, year, poster_url, overview	admin
POST	`/api/scrapers/queue/:id/accept`	Confirm a candidate match	admin
POST	`/api/scrapers/queue/:id/reject`	Reject a candidate match	admin
GET	`/api/scrapers/anidb/poster/:aid`	Redirects to the image proxy	public
GET	`/api/scrapers/search`	Direct scraper search — powers the Discovery featurequery: q, type	public
GET	`/api/scrapers/metadata/:item_type/:kairos_id`	External IDs + alternate titles	auth
POST	`/api/scrapers/metadata/:item_type/:kairos_id`	Body: external_ids[], alternate_titles[]	admin
POST	`/api/scrapers/metadata/:item_type/:kairos_id/refresh`	Re-fetch alternate titles/external ids	admin

Scheduler, EPG & IPTV Feed #

The endpoints DVR clients (XTeve, TiViMate, Plex Live TV) actually consume, alongside the EPG preview/materialization API Hades uses.

Method	Path	Description	Auth
GET	`/playlist.m3u`	The IPTV M3U playlist	public
GET	`/api/media/languages`	Library-wide distinct audio/subtitle languages (sampled, cached 1h)	public
GET	`/epg.xml`, `/api/epg.xml`, `/api/xmltv.xml`, `/api/channels.xml`	All four alias the same XMLTV generatorquery: hours (max 72)	public
GET	`/api/channels/:id/now`	What's playing right now, with filler/offline fallbackquery: at	public
GET	`/api/channels/:id/next`	What plays next	public
POST	`/api/channels/:id/played`	Report playback completion, advances the cursorbody: item_type, item_id, block_id, duration_actual_ms	public
POST	`/api/channels/:id/epg/preview`	Preview a schedule without committing — supports draft blocks + a seed overridebody: hours, seed, blocks[]	auth
POST	`/api/channels/:id/epg/clear`	Clear cached preview/materialization	auth
GET	`/api/channels/:id/epg`	Materialized EPG gridquery: hours, from	public

Timeslots #

Fixed-time rotating slots inside a block (e.g. a 7pm "Toonami" slot). Every route here relies solely on the global Bearer-token requirement — none currently add an explicit admin-role check, unlike the rest of the scheduling API.

Method	Path	Description	Auth
POST	`/api/blocks/:bid/slots`	Create a timeslot	auth
PATCH	`/api/blocks/:bid/slots/:sid`	Body: slot_offset_mins, slot_duration_mins, overflow, late_start_mins, early_start_secs, align_to_mins, start_scope	auth
DELETE	`/api/blocks/:bid/slots/:sid`	Remove a slot	auth
POST	`/api/blocks/:bid/slots/reorder`	Body: [{slot_id}]	auth
POST	`/api/blocks/:bid/slots/:sid/cursor/reset`	Reset the slot's rotation cursor	auth
POST	`/api/blocks/:bid/slots/:sid/queue`	Add a rotating show/movie to the slot	auth
PATCH	`/api/blocks/:bid/slots/:sid/queue/:eid`	Body: premiere_date, pre_premiere_behavior	auth
DELETE	`/api/blocks/:bid/slots/:sid/queue/:eid`	Remove from the rotation	auth
POST	`/api/blocks/:bid/slots/:sid/queue/reorder`	Body: [{entry_id}]	auth

Roku Devices #

Pairing and management for the native pantheon-roku channel.

Method	Path	Description	Auth
GET	`/api/roku-devices`	Caller's own paired devices	auth
POST	`/api/roku-devices`	Create + start an ECP-launch pairing flowbody: name, ip_address	auth
GET	`/api/roku-devices/:id`	Own devices only	auth
DELETE	`/api/roku-devices/:id`	Unpair a device	auth
POST	`/api/roku-devices/:id/confirm-pairing`	Confirm pairingbody: pairing_token	auth (internal: relayed by Hermes from the Roku device itself)

Playback & Watch Progress #

Method	Path	Description	Auth
GET	`/api/playback/:content_type/:id`	Resolve a library item to a playable file path — also resolves linked specials through their movie	public (internal: called by Hephaestus)
GET	`/api/watch-progress`	Caller's continue-watching listquery: limit	auth
PUT	`/api/watch-progress/:content_type/:id`	Upsert position, auto-clears at ≥95% watchedbody: position_ms, duration_ms	auth
DELETE	`/api/watch-progress/:content_type/:id`	Clear saved progress	auth