Settings reference

Environment variables (container)

Serving from a subpath

Set APP_BASE_PATH and point the proxy at the container. No rebuild, and no prefix-stripping middleware — the app recognises its own prefix, rewrites the asset URLs in the shell it serves, and publishes the prefix to the SPA so the router and API client use it too.

services:
  shortlist:
    image: ghcr.io/stevezau/shortlist:latest
    environment:
      - APP_BASE_PATH=/shortlist

Traefik — router and service only:

http:
  routers:
    shortlist:
      rule: "Host(`media.example.com`) && PathPrefix(`/shortlist`)"
      service: shortlist
  services:
    shortlist:
      loadBalancer:
        servers:
          - url: "http://shortlist:5959/"

nginx — two blocks. location /shortlist on its own is a prefix match, so it would also swallow a sibling app at /shortlistings; ^~ /shortlist/ matches only the real subtree, and the exact-match block redirects the bare URL people actually type. Note there is no trailing slash on proxy_pass — that is what forwards the prefix intact:

location = /shortlist {
    return 308 /shortlist/;
}

location ^~ /shortlist/ {
    proxy_pass http://shortlist:5959;
    proxy_set_header Host $host;
    proxy_set_header X-Forwarded-Proto $scheme;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
}

A proxy that strips the prefix anyway still works — an already-stripped path simply doesn’t match and is passed through untouched. That is also why the container’s own healthcheck, which requests an unprefixed /api/system/health on localhost, keeps working.

Leaving it unset serves the shell’s bytes exactly as they shipped.

Test through the proxy, at https://host/shortlist/. A blank page at the container’s own port — or at any URL without the prefix — is expected, not a fault: the app still answers there (that is how the healthcheck works), but the SPA it serves is built for the prefix and renders nothing outside it.

If it is blank through the proxy, check the container log first: it states the base path it is using at startup, and warns if APP_BASE_PATH held something it could not use (a query, a fragment, a space, an escaped or relative path) — in which case it ignores it and serves from the root, which on its own looks exactly like a proxy problem.

Settings keys (DB-backed; Settings UI or PUT /api/settings)

What web search costs in practice. Measured on a 46-user server (run 18, 3 Sep 2026): 662 billable Exa searches in one nightly run, 380 more served from the shared 7-day cache — a 36% hit rate — for $7.94 a night at deep-lite. Cost scales with distinct recent watches across the roster, not with user count, because a title many people watched is searched once for everyone. The per-run figure appears on the Web search card in Settings (“Last run: N web searches”) so it never has to be estimated.

Per-row request overrides

Any per-person row may override these in the row editor; the column is the collections column name, and NULL always means “inherit the global requests.* setting”.

requests.enabled, requests.rating_source, requests.mdblist.apikey, requests.max_per_run and the Arr URLs and API keys are server-wide and cannot be overridden per row — the first four are the run’s ceilings and its one rating account, and the last two mean a row files into a different folder on the SAME Radarr, not a second one.

Shared rows carry none of these: built from already-watched titles, they surface nothing missing.

How settings take effect

What particular keys above actually mean, what a save is checked against, and what changes on Plex without waiting for a run.

The AI provider (curator.provider) does not rank candidates or write reasons — the engine does the diversification and writes the genre-template reasons itself. The provider has exactly one job, the llm_web source: it turns a person’s recent watches into web searches for what to watch next. So a run needs a provider only when llm_web is enabled; every other source is provider-free, and with curator.provider = none you still get full rows ranked by score with plain reasons.

PUT /api/settings validates values, not just keys. plextv.throttle_s must be 0–60 (0 = fire as fast as plex.tv accepts, with adaptive 429 backoff), row.size must be 5–40, paused_all must be a real boolean, and candidates.sources / curator.provider are checked against their known values.

null on a schedule key means “use the built-in default”. For any of the six *_cron keys, PUT /api/settings {"values": {"sync.check_cron": null}} DELETES the stored value rather than writing one, putting the job back on the built-in cron GET /api/schedule reports as default_cron, and the live APScheduler trigger is rebuilt in the same request, not at the next restart. It is the only way back for sync.check_cron, where a stored "" means OFF rather than “inherit”; writing the default expression itself would pin a copy of today’s value instead. For the other five, null and "" land in the same place, because a blank already means “inherit”.

Candidate sources are set globally (candidates.sources) and can be overridden per row (collections.candidate_sources, [] = inherit the global set; valid values: tmdb_similar, tmdb_discover, trakt, llm_web). llm_web proposes titles to watch next from a live web search, each resolved via TMDB search then library-verified. It works on every AI provider via llm_web.search_provider, which names exactly ONE backend: native (the default) uses the provider’s own web-search tool (Claude, GPT, or Gemini), exa uses the hosted Exa API (exa.apikey), and searxng uses your own SearXNG instance (searxng.url). Either external backend is a path for a local model, which cannot search on its own. Only the named backend runs, so a title is never searched — or billed — twice. A fourth value, auto (native unioned with an external), was removed in 1.3; migration 0063 pins every install to the backend it was actually using. When a source’s dependency is missing, the Settings UI keeps the toggle usable but shows an inline fix (enter the key right there, or set up an AI provider). It never reads as on while silently doing nothing.

Config changes reconcile onto Plex immediately, without waiting for a run. Deleting a row, disabling a user, and dropping a user from a row’s audience all remove the now-stale collections (a removal, so gate-exempt); renaming a row retitles its collections in place for every user (privacy-neutral, since the hiding filter is keyed on the row’s label, which never changes). A per-person row’s per-user collection is found by the exact title the last run delivered for it (the run’s persisted breakdown), scoped to that user’s own label, so a reconcile can never touch another user’s row or a foreign (Kometa) collection. Each row also has a Remove from Plex action, under Remove or delete on the row (POST /api/collections/{id}/cleanup, dry-run-able), for an on-demand sweep. Every reconcile is audited.

A row builds a Plex collection in each library it targets (collections.library_keys, a list of Plex section keys; [] = every library of the row’s media type. The default). A row’s media is derived from the types of its selected libraries. This lets an owner point a row at a specific library (e.g. only “4K Movies”) on a server with several libraries of one type. A row builds per library: each targeted library seeds from its own watched history and fills to row.size on its own, so a movies-and-TV watcher gets a full movie row AND a full TV row.

Placement is per row and held once per audience: collections.placement for the owner’s own collection and collections.placement_friends for each friend’s (both both | home | library | off, default both). Each decodes to two of Plex’s three promotion flags. home is promotedToOwnHome on the owner’s side and promotedToSharedHome on the friends’ side, library is promotedToRecommended, and off claims neither surface (the collection still exists and is still browse-hidden, so it stays reachable from the library’s Collections tab). Exception: when a run cannot map an existing collection back to its row, that collection keeps its audience’s Home flag for that run, never the Recommended shelf, which is the one surface the owner cannot filter.

When a row appears (collections.show_days)

Placement decides where a row shows; show_days decides which days. It is a list of ISO weekdays (1 = Monday .. 7 = Sunday); [] means every day, which is what every row carries after migration 0088, so upgrading changes nothing. There is deliberately no way to spell “never” — switching the row off already means that, and the editor will not let you deselect the last day.

On a day it is off, the row resolves to placement off for that day: the collection, its label, its titles and its custom order all stay exactly as they are, and only Plex’s three promotion flags are cleared. So a day off costs one ~5ms visibility write per collection and coming back costs another — neither pays the membership-write cost (up to ~26s per operation on a large TV library) that rebuilding a row would.

Applied by the rows.visibility job, which runs at midnight (rows.visibility_cron, default 0 0 * * *) and again immediately whenever you change a row’s days. Midnight rather than with the nightly run at 03:30: a Monday row would otherwise stay up until 03:30 on Tuesday, and a row that rebuilds weekly for days. The job holds no state — it recomputes today’s answer from the schedule every time, so anything one pass cannot do the next one does. On a server where no row narrows its days (all seven selected is stored as none, so that is every server until somebody picks a subset) it does nothing at all: one query, no clients built, no Plex or plex.tv calls. Where a row IS scheduled it runs nightly, costing a share-filter merge plus one ~5ms visibility write per collection. It deliberately does not reorder the Recommended shelf — the nightly run owns position — so a row shown at midnight sits in its library’s default slot until the run places it.

Showing a row re-merges every account’s share filters first and refuses to promote anything if that fails (plex-safety rule 1): somebody may have joined the server while the row was hidden, and their share carries no label!= exclude for it yet. A paused person’s rows are never brought back by a schedule.

Days are the server’s local days — the same clock a row’s rebuild cron runs on. A viewer in another timezone sees a row turn over at the server’s midnight, not their own. Some Plex clients cache the Home screen; a Roku re-reads it on its own, a Shield needs you to leave Home and come back.

The two sides are independent because every person gets their own Plex collection, so promotedToRecommended is set per collection rather than once for the row. That is what lets an owner keep their own row on the Recommended shelf without every friend’s row landing there too. The one thing it cannot do is the reverse: a friend’s row on the Recommended shelf is also visible to the owner, because the owner has no share filter to hang a label!= exclude on. Shortlist says so at the control rather than pretending otherwise. A shared row is one public collection rather than one per person, so it has nothing to split on, so it takes both Home flags and the union of the two library settings.

WHERE in that shelf it sits is the Position control (collections.hub_anchor, per library: {"top": true}, {"row": "<row slug>", "before": bool}, or {"anchor": "<collection>", "before": bool}); it replaces the old pin_top toggle (still honoured for rows not yet re-saved). This order is Plex’s Managed Recommendations, which are server-wide, because Plex exposes no per-viewing-user hub order.

A row can be positioned relative to another Shortlist row (row, a row slug) or to a foreign collection (anchor, a title) — one or the other, never both; row is what the engine reads first. It is a slug and not a title because a per-person row is one Plex collection PER PERSON, so a title names one account’s copy and would place the row for that account alone. The rows of a library are then applied in dependency order, so a row always lands after the one it follows has itself been placed. Two rows pointing at each other, or a row pointing at itself, is refused when you save it; if an anchor row has nothing in that library yet, the rows following it are left where they are for that run rather than falling back to a different slot.

Request tags are three-layered: the global requests.tag setting, a per-user request_tag (PATCH /api/users/{id}), and a per-row request_tag (collections, per-person rows only: shared rows never request). A requested title is tagged with the union of the global tag, every wanting user’s tag, and the tag of every per-person row that user is in the audience of; the queued tags round-trip through GET /api/requests (tags[]) and are applied on send.

The per-user layer can also be filled in automatically. With requests.auto_user_tag on, a user who has no request_tag of their own contributes their SLUG instead, so every request is attributable to a person in Sonarr/Radarr without hand-setting a tag on each user. An explicit request_tag REPLACES the slug rather than stacking with it — carrying both is the clutter the automatic tag was dropped for in 2026-07. A row may override the switch either way (req_auto_user_tag; NULL inherits), and the override governs only the automatic slug: a tag the owner typed on a person is never dropped.

Slugs are sanitized to the Arr tag charset (a-z, 0-9, -) before being sent, so moo_house becomes moo-house. Note what the tag can and cannot tell you: a title the Arr ALREADY tracks is skipped entirely by add_movie/add_series, tags included, so the tag records who triggered the original add — not everyone who has wanted the title since. The full wanters list lives in the Requests inbox (why[]), which never reaches the Arr.

Before queuing, the request pass reconciles the missing pool against the Arrs (one bulk fetch each, failing open on error): a title Sonarr/Radarr already tracks is dropped, since it is not really “missing”, just not imported into Plex yet. Matched on tmdbId for movies and tvdbId for shows (the candidate’s TVDB id is resolved once and reused for the send). A title on an Arr import-exclusion list (usually a past delete) is kept but flagged (excluded on GET /api/requests) and never auto-sent, so the inbox can warn that approving it is a no-op until the exclusion is removed in the Arr. A sent title records the Arr’s titleSlug (arr_slug on GET /api/requests) so the Sent log deep-links straight to its Sonarr/Radarr page; each candidate also carries TMDB’s poster_path ("/abc.jpg", or "" when TMDB has no artwork). A path and not a URL, because the image host and size buckets are TMDB’s to change, so the web UI builds the URL itself and draws a placeholder tile when the path is empty. It also carries TMDB’s synopsis (overview, "" when TMDB has none or the row predates the field), so an unfamiliar title can be judged in the inbox; both ride in the same TMDB list response, so neither costs an extra call, and both backfill on the next run that re-surfaces the title. Clear (POST /api/requests/clear) hides a sent entry via a hidden flag without deleting the tombstone that stops a still-downloading title being re-requested.

All endpoints except /api/system/health require the owner session; mutations require the x-shortlist-csrf: 1 header.

Programmatic access (API token). For scripting, generate an owner token in Settings → Advanced → API access (or POST /api/system/api-token) and send it as Authorization: Bearer <token>. It grants the same owner-level access as the browser session and needs no CSRF header (a browser never sends it automatically). The token is stored encrypted at rest (Fernet, like the Plex/AI-provider keys) and stays revealable to the owner. The Settings card and GET /api/system/api-token show it (owner-gated) so you can copy it any time; it never appears in GET /api/settings. Regenerating or revoking (DELETE /api/system/api-token) invalidates the old token immediately.

curl -H "Authorization: Bearer <token>" https://<host>/api/runs

Files under /config

shortlist.db (SQLite: settings, users, runs, restriction snapshots, and the durable plex-account-id → slug map a row’s label is built from) · secret.key (Fernet, 600) · session.secret · logs/.