Configuration & API Reference

Back to Docs

Complete reference for all configuration options and REST API endpoints.

Important

This page is the source of truth for configuration precedence, settings, and REST API behavior. For installation and setup flows, use Getting Started. For operations, webhooks, and troubleshooting, use Guides & Troubleshooting.

Configuration Priority
Media Servers
Processing Options
Environment Variables
Web Interface Settings
Webhook Settings
Path Mappings
REST API
WebSocket Events
Rate Limiting

Related Docs

Configuration Priority

settings.json (at /config/settings.json) is the sole source of truth for application configuration. On first start, environment variables are migrated into settings.json as seed values. After that, all configuration is managed via the Web UI (Setup Wizard and Settings page).

Infrastructure environment variables remain active and are not migrated (see Infrastructure Variables).

Media Servers

Every server the app talks to — any number of Plex, Emby, and Jellyfin entries — is stored as an array under media_servers in settings.json. Managed from the Servers page (or via the REST API below). Each entry has the shape:

{
  "id": "plex-household",
  "type": "plex",
  "name": "Household Plex",
  "url": "http://192.168.1.100:32400",
  "enabled": true,
  "auth": {
    "method": "token",
    "token": "..."
  },
  "libraries": [
    {"id": "1", "name": "Movies", "enabled": true},
    {"id": "2", "name": "TV Shows", "enabled": true}
  ],
  "path_mappings": [
    {"remote_prefix": "/data", "local_prefix": "/media", "webhook_prefixes": []}
  ],
  "plex_config_folder": "/plex"
}

Per-vendor notes:

Vendor	`auth.method` values	Extra fields
Plex	`token` (OAuth is the acquisition flow — the result is stored as `auth.token`)	`plex_config_folder` (where BIF bundles are written), `server_identity` (Plex's `clientIdentifier`, used to disambiguate webhooks)
Emby	`password`, `api_key`	`auth.user_id`, `auth.access_token`
Jellyfin	`password`, `quick_connect`, `api_key`	`auth.user_id`, `auth.access_token`

Runtime state, not persisted. Jellyfin's Media Preview Bridge plugin presence is probed live via JellyfinServer.check_plugin_installed() and surfaced in the /previews-readiness payload — it isn't stored on the server entry.

Legacy flat keys. Older single-Plex installs had top-level plex_url, plex_token, plex_config_folder, and selected_libraries. These are migrated into the first enabled Plex entry of media_servers[] on first boot. Reads still work via a compatibility shim, so existing scripts that query GET /api/settings and look at plex_url keep working — but new writes should use media_servers[] via /api/servers.

Tip

Use the Setup Wizard to sign in. Plex OAuth, Jellyfin Quick Connect, and Emby username/password exchange all happen through the wizard without you pasting tokens by hand. Exactly one "first server" is configured via the wizard; add more from the Servers page.

Processing Options

Per-GPU Configuration (gpu_config)

GPU settings are configured per-GPU in Settings → Processing Options. Each entry in gpu_config has:

Field	Type	Description
`device`	string	GPU device identifier (e.g. `/dev/dri/renderD128`)
`name`	string	Display name (e.g. "Intel UHD Graphics 630")
`type`	string	`nvidia`, `intel`, `amd`, `apple`
`enabled`	boolean	Whether this GPU is used for processing
`workers`	int	Number of worker threads for this GPU (0–32)
`ffmpeg_threads`	int	CPU threads per FFmpeg job on this GPU (0–32, 0 = no limit). Recommended: 2

Other Processing Settings

Setting	Web UI	Default	Description
`cpu_threads`	Yes	`1`	Number of CPU worker threads (0–32)
`thumbnail_quality`	Yes	`4`	Preview quality 1-10 (2=highest)
`thumbnail_interval`	Yes	`10`	Interval between preview images (1–60 s). Matches Plex/BIF community convention (see sidecar `-{width}-10.bif` files).
`selected_libraries`	Yes	All	Library IDs to process
`sort_by` (per-run)	Yes	`newest`	Order items are processed: `newest`, `oldest`, `random`, or empty for Plex's natural order. Set per manual run (New Job modal) or per schedule — not a global setting.

Frame Reuse Cache (frame_reuse)

When the same canonical file fires multiple webhooks within the cache TTL (e.g. Sonarr fires immediately, Plex's library.new follows 30 min later), this cache reuses the FFmpeg-extracted frames across siblings instead of re-running FFmpeg. Tuned per-server under Settings → Performance:

Field	Default	Description
`enabled`	`true`	Master toggle for cross-server frame reuse
`ttl_minutes`	`60`	How long to keep extracted frames in the cache
`max_cache_disk_mb`	`2048`	Disk cap for the cache (oldest entries evicted first)

Tip

Multi-disk libraries (unraid shfs, mergerfs, JBOD): pick Random as the Processing Order on the New Job modal or on a scheduled full-library scan. With alphabetical order, parallel workers tend to read sequential files from the same physical disk; shuffling spreads reads across disks so disk I/O stops being the bottleneck. Webhook jobs and Recently Added scans are unaffected — they touch too few files for ordering to matter.

Note

When a GPU worker can't process a file (unsupported codec, hardware-accelerator error, driver crash), the same worker retries on CPU in-place and the UI shows a warning badge with the reason. No separate fallback pool is needed — increase cpu_threads if you want more dedicated CPU concurrency for files that never hit the GPU.

Environment Variables

Infrastructure Variables (always active)

These are not migrated to settings.json and remain in effect:

Variable	Default	Description
`CONFIG_DIR`	`/config`	Directory for settings.json, auth, schedules
`WEB_PORT`	`8080`	Web server port
`PUID`	`1000`	User ID (Unraid: `99`)
`PGID`	`1000`	Group ID (Unraid: `100`)
`TZ`	Host	Timezone (e.g. `America/New_York`)
`CORS_ORIGINS`	`*`	Allowed CORS origins (comma-separated)
`HTTPS`	`false`	Enable HTTPS for cookies
`DEV_RELOAD`	`false`	Enable Flask auto-reload (development)
`WEB_AUTH_TOKEN`	Auto-generated	Fixed authentication token (overrides wizard-set token)
`AUTH_METHOD`	`internal`	Set to `external` to disable built-in auth when using a reverse proxy or VPN (see below)
`FLASK_SECRET_KEY`	Auto-generated	Override the Flask session signing key. Auto-generated and persisted to `/config/flask_secret.key` if not set. Set this only when you need a fixed key across rebuilds.
`LOG_FORMAT`	`pretty`	Log output format. Set to `json` to emit one JSON object per log line — useful when shipping logs to Loki / Datadog / similar aggregators.
`PLEX_DATA_ROOT`	`/`	Restricts where Plex data paths can be validated to. Defaults to the whole filesystem; tighten to e.g. `/plex` if you want the path validator to refuse anything outside that root.
`MEDIA_ROOT`	`/`	Same as `PLEX_DATA_ROOT` but for media paths.
`RATELIMIT_STORAGE_URL`	`memory://`	Backend for rate-limit counters. The default in-memory store is fine for a single-container deploy; set to `redis://host:port/0` if you run behind a load balancer with multiple replicas.

External Authentication (AUTH_METHOD)

If you secure access via a reverse proxy (Authelia, Authentik, Caddy Security, nginx basic auth, etc.) or a VPN (Tailscale, WireGuard), you can disable the built-in login screen:

environment:
  - AUTH_METHOD=external

When set to external:

The login page is bypassed; all browser and API requests are treated as authenticated.
Webhook authentication (webhook_secret / Bearer token) is not affected — external services like Radarr and Sonarr still need their shared secret.
The setup wizard still runs on first boot.
Removing the variable (or setting it back to internal) instantly re-enables built-in auth.

Caution

Only use AUTH_METHOD=external when you are certain that network-level access control is in place. Without it, anyone who can reach the web UI has full access.

Deprecated (no longer used)

These env vars are deprecated and silently ignored at startup with a warning logged. Configure via Settings instead:

Variable	Replacement
`GPU_SELECTION`	Per-GPU enable/disable in Settings → Processing Options
`GPU_THREADS`	Per-GPU workers in `gpu_config`
`FFMPEG_THREADS`	Per-GPU `ffmpeg_threads` in `gpu_config`
`PLEX_LIBRARIES`	Per-server library toggles (Settings → Media Servers → Libraries)
`REGENERATE_THUMBNAILS`	Tick "Regenerate" when starting a job from the UI
`SORT_BY`	Pick sort order when starting a job
`NICE_LEVEL`	Removed — process priority is no longer configurable
`FALLBACK_CPU_THREADS`	Removed in v3.x — CPU retry now happens in-place inside the GPU worker

One-time seed values (migrated on first start)

On first run, these env vars are migrated into settings.json. After that, settings.json is the source of truth:

PLEX_URL, PLEX_TOKEN, PLEX_CONFIG_FOLDER, PLEX_VERIFY_SSL, PLEX_TIMEOUT
PLEX_BIF_FRAME_INTERVAL / THUMBNAIL_INTERVAL (alias), THUMBNAIL_QUALITY, TONEMAP_ALGORITHM, CPU_THREADS
MEDIA_PATH, TMP_FOLDER, LOG_LEVEL

Web Interface Settings

The web UI is served by gunicorn (a Python web server) using thread workers — Docker handles launching it, you don't need to know about this unless you're running outside Docker. Listening port and related knobs live in Infrastructure Variables — WEB_PORT, CORS_ORIGINS, HTTPS, and DEV_RELOAD.

Webhook Settings

Settings for automatic preview generation when media is imported via Radarr or Sonarr.

Setting	Default	Web UI	Description
`webhook_enabled`	`true`	Yes	Master enable/disable for webhook processing
`webhook_delay`	`60`	Yes	Delay before processing (10–300 s). Incoming webhooks are queued per source; a batch runs only after this many seconds with no new imports, so every file gets at least this long for Plex to add it before we process.
`webhook_secret`	(empty)	Yes	Dedicated secret for webhook auth (falls back to API token)
`plex_webhook_enabled`	`false`	Yes	Enable the Plex direct webhook (`/api/webhooks/plex`). Requires Plex Pass on the server-owner account.
`plex_webhook_public_url`	(empty)	Yes	URL Plex Media Server should POST to. Defaults to the URL you registered through. Override for reverse-proxy / split-network setups.

Webhook processing respects selected_libraries; paths outside unchecked libraries are ignored.

The Recently Added Scanner is not configured via settings keys any more — it's a first-class schedule type (see Schedules Endpoints below). Create one through the Automation page (Triggers tab) "Create default scanner" shortcut, or through the Schedules tab modal with Scan mode → Recently added only.

Important

The Plex direct webhook and Recently Added schedules trigger only on new library items (new ratingKeys). They do not detect in-place file upgrades — Plex keeps the same item when Sonarr/Radarr replaces a file. Use the existing Sonarr/Radarr webhooks (which fire on On Upgrade) for that case.

Tip

Configure webhooks on the Automation page (/automation, Triggers tab) in the web UI. See Webhook Integration for setup instructions. The legacy /webhooks and /schedules URLs still work — they 302-redirect to the relevant tab.

Path Mappings

Important

Essential for Docker deployments where your media server sees files at different paths than this container does. Path mappings are stored per-server — each Plex / Emby / Jellyfin entry in media_servers[] carries its own list — because different servers can mount the same media at different paths.

Why Path Mappings?

Component	Sees files at
Media server (Plex / Emby / Jellyfin)	`/data/media/Movies/film.mkv`
This Container	`/media/Movies/film.mkv`

Without mapping, you'll see "Skipping as file not found" errors.

Configuration (Web UI)

Open Servers → Edit on the server that needs mapping, and add rows in the Path Mappings section. Each row has:

Path on server — The folder path the media server reports for the file (e.g. /data). Called remote_prefix in the API.
Path in this app — The folder path this app uses for the same files (e.g. /mnt/data). Called local_prefix in the API.
Webhook path (if different) — Only needed when Sonarr, Radarr, Tdarr, etc. use a different path than the media server (e.g. they use /data while Plex uses /data_disk1). Leave blank if they match. Called webhook_prefixes in the API.

Add as many rows as you need (e.g. one per disk when the server has multiple roots). Each server manages its own list independently.

Legacy env (semicolon pair)

Variable	Description
`PLEX_VIDEOS_PATH_MAPPING`	Path(s) as Plex sees them; semicolon-separated for multiple roots (seed value, first-boot only)
`PLEX_LOCAL_VIDEOS_PATH_MAPPING`	Path as this app sees them (seed value, first-boot only)

The saved path_mappings on each media_servers[] entry take precedence. Existing semicolon-based values are converted into mapping rows on the first enabled Plex entry at migration time.

When a server uses multiple roots (e.g. mergerfs)

If a server has several roots (e.g. /data_disk1, /data_disk2) but Sonarr/Radarr see one path (/data):

Add one row per server root, each with the same Path in this app (e.g. /data).
In Webhook path, enter /data on one of the rows so imports from Sonarr/Radarr still match.

Examples

Situation	Path on server	Path in this app	Webhook path
Different paths in Docker	`/data`	`/mnt/data`	(blank)
Multiple disks, Sonarr sees one path	`/data_disk1`	`/data`	`/data`
Same (second disk)	`/data_disk2`	`/data`	(blank)

How to Find Your Paths

Plex path: Plex Web → Settings → Libraries → Edit → Folders.
Emby path: Emby Dashboard → Libraries → Edit → Folders.
Jellyfin path: Jellyfin Dashboard → Libraries → Edit → Folders.
Container path: Check your -v volume mount.

No Mapping Needed

If both Plex and this container see files at the same path (e.g., both use /media), skip this configuration.

Exclude Paths

Under the same Media path mapping settings you can add Exclude paths: paths or folders to skip for preview generation. These are applied to the local path (as this app sees the file after path mapping).

Path prefix — Any file under this folder is skipped (e.g. /mnt/media/archive skips everything under that path).
Regex — The full local path is matched against the pattern (e.g. .*\.iso$ to skip ISO files).

Add one row per path or pattern. Excluded items are not queued for full-library runs and are skipped for webhook-triggered runs.

REST API

All API endpoints (except /api/health and /api/setup/status) require authentication.

Authentication

Include the authentication token in requests using one of these methods:

# X-Auth-Token header
curl -H "X-Auth-Token: YOUR_TOKEN" http://localhost:8080/api/jobs

# Authorization Bearer header
curl -H "Authorization: Bearer YOUR_TOKEN" http://localhost:8080/api/jobs

Get your token from Authentication Token, or set a fixed token with WEB_AUTH_TOKEN.

Setup & Settings Endpoints

GET /api/setup/status

Check if setup is complete. No authentication required.

{
  "configured": true,
  "setup_complete": true,
  "current_step": 0,
  "plex_authenticated": true
}

GET /api/setup/state

Get current setup wizard state.

{
  "step": 2,
  "data": {
    "server_name": "My Plex Server"
  }
}

POST /api/setup/state

Save setup wizard progress.

Request:

{
  "step": 2,
  "data": {
    "server_name": "My Plex Server"
  }
}

POST /api/setup/complete

Mark setup as complete. Returns {"success": true, "redirect": "/"}.

GET /api/setup/token-info

Get information about the current authentication token (used by Step 5 of the setup wizard).

{
  "env_controlled": false,
  "token": "abc123xyz...",
  "token_length": 43,
  "source": "config"
}

Field	Type	Description
`env_controlled`	boolean	Whether token is set via `WEB_AUTH_TOKEN` env var
`token`	string	The current authentication token
`token_length`	number	Length of the token
`source`	string	Either `"environment"` or `"config"`

POST /api/setup/set-token

Set a custom authentication token during setup.

Request:

{
  "token": "my-custom-password",
  "confirm_token": "my-custom-password"
}

Returns {"success": true} on success, or {"success": false, "error": "..."} with details:

"Tokens do not match."
"Token must be at least 8 characters long."
"Token is controlled by WEB_AUTH_TOKEN environment variable and cannot be changed."

GET /api/settings

Get current settings.

{
  "plex_url": "http://192.168.1.100:32400",
  "plex_token": "****",
  "plex_name": "My Server",
  "plex_config_folder": "/plex",
  "selected_libraries": ["1", "2"],
  "media_path": "/media",
  "plex_videos_path_mapping": "",
  "plex_local_videos_path_mapping": "",
  "path_mappings": [
    {"remote_prefix": "/data", "local_prefix": "/mnt/data", "webhook_prefixes": []}
  ],
  "gpu_config": [
    {"device": "/dev/dri/renderD128", "name": "Intel UHD 630", "type": "intel", "enabled": true, "workers": 4, "ffmpeg_threads": 2}
  ],
  "cpu_threads": 2,
  "thumbnail_interval": 10,
  "thumbnail_quality": 4
}

path_mappings keys: remote_prefix is the canonical key as of the multi-server refactor (works for Plex, Emby, and Jellyfin). The legacy plex_prefix is still accepted as an alias on read; new writes should use remote_prefix.

POST /api/settings

Update settings. Send only the fields to change.

{
  "gpu_config": [{"device": "/dev/dri/renderD128", "enabled": true, "workers": 4, "ffmpeg_threads": 2}],
  "cpu_threads": 2,
  "thumbnail_interval": 10,
  "plex_url": "http://192.168.1.100:32400"
}

Plex OAuth Endpoints

POST /api/plex/auth/pin

Create a new Plex OAuth PIN.

{
  "id": 12345,
  "code": "ABCD1234",
  "auth_url": "https://app.plex.tv/auth#?clientID=...&code=ABCD1234"
}

GET /api/plex/auth/pin/{id}

Check if PIN has been authenticated. Returns {"authenticated": true, "auth_token": "..."} or {"authenticated": false, "auth_token": null}.

GET /api/plex/servers

Get list of user's Plex servers.

{
  "servers": [
    {
      "name": "My Server",
      "machine_id": "abc123",
      "host": "192.168.1.100",
      "port": 32400,
      "ssl": false,
      "owned": true,
      "local": true
    }
  ]
}

GET /api/plex/libraries

Get libraries from connected Plex server. Optional query parameters: url, token.

{
  "libraries": [
    { "id": "1", "name": "Movies", "type": "movie" },
    { "id": "2", "name": "TV Shows", "type": "show" }
  ]
}

POST /api/plex/test

Test Plex connection. Request: {"url": "...", "token": "..."}. Returns {"success": true, "server_name": "...", "version": "..."}.

Processing state (global pause)

Method	Endpoint	Description
GET	`/api/processing/state`	Get global processing pause state
POST	`/api/processing/pause`	Set global pause (no new jobs start; active job stops dispatch after current tasks)
POST	`/api/processing/resume`	Clear global pause

GET /api/processing/state — Response: {"paused": true} or {"paused": false}. State is persisted and survives restarts.

POST /api/processing/pause — Response: {"paused": true}.

POST /api/processing/resume — Response: {"paused": false}.

Jobs Endpoints

Method	Endpoint	Description
GET	`/api/jobs`	List all jobs
POST	`/api/jobs`	Create new job
GET	`/api/jobs/{id}`	Get job details
POST	`/api/jobs/{id}/cancel`	Cancel job
POST	`/api/jobs/{id}/pause`	Global pause (delegates to `/api/processing/pause`)
POST	`/api/jobs/{id}/resume`	Global resume (delegates to `/api/processing/resume`)
DELETE	`/api/jobs/{id}`	Delete job

GET /api/jobs

{
  "jobs": [
    {
      "id": "job-123",
      "status": "running",
      "library_id": "1",
      "library_name": "Movies",
      "progress": 45,
      "total_items": 100,
      "completed_items": 45,
      "created_at": "2024-01-15T10:30:00Z",
      "started_at": "2024-01-15T10:30:05Z"
    }
  ]
}

POST /api/jobs

Request: {"library_id": "1", "library_name": "Movies"}

Response: {"id": "job-123", "status": "pending", "message": "Job created successfully"}

GET /api/jobs/{id}

{
  "id": "job-123",
  "status": "running",
  "library_id": "1",
  "library_name": "Movies",
  "progress": 45,
  "total_items": 100,
  "completed_items": 45,
  "failed_items": 0,
  "created_at": "2024-01-15T10:30:00Z",
  "started_at": "2024-01-15T10:30:05Z",
  "workers": [
    {
      "id": 0,
      "type": "gpu",
      "status": "working",
      "current_item": "Movie Title"
    }
  ]
}

Schedules Endpoints

Method	Endpoint	Description
GET	`/api/schedules`	List schedules
POST	`/api/schedules`	Create schedule
PUT	`/api/schedules/{id}`	Update schedule
DELETE	`/api/schedules/{id}`	Delete schedule
POST	`/api/schedules/{id}/run`	Run now

POST /api/schedules

Cron request — full library scan (default):

{
  "name": "Nightly Movies",
  "library_id": "1",
  "cron_expression": "0 2 * * *"
}

Interval request — full library scan:

{
  "name": "Every 4 Hours",
  "library_id": "1",
  "interval_minutes": 240
}

Recently Added scanner schedule:

{
  "name": "Recently Added Scanner",
  "library_id": null,
  "interval_minutes": 15,
  "enabled": true,
  "config": {
    "job_type": "recently_added",
    "lookback_hours": 1
  }
}

config.job_type accepts:

"full_library" (default — optional, omit to get the same behaviour) — schedule runs a full library scan via the standard job pipeline, processing every item in library_id that's missing previews.
"recently_added" — schedule runs a Recently Added scan instead. Requires config.lookback_hours (float, clamped to 0.25–720). Scans only items added within the lookback window (Plex addedAt, Emby/Jellyfin DateCreated), queuing each through the webhook job pipeline. When library_id is null, the scan falls back to the globally selected libraries in Settings (or every supported library when no global filter is set); when set, only that section is scanned. Works for Plex, Emby, and Jellyfin — each vendor's processor implements scan_recently_added against its native API.

System Endpoints

Method	Endpoint	Auth	Description
GET	`/api/health`	No	Health check
GET	`/api/system/status`	Yes	System status (GPUs, workers, job counts)
GET	`/api/system/config`	Yes	Current configuration
GET	`/api/libraries`	Yes	Aggregated library list across every configured server

Multi-Media-Server Endpoints

For full design and per-vendor details see Multi-Media-Server.

Method	Endpoint	Description
GET	`/api/servers`	List configured servers (auth redacted)
POST	`/api/servers`	Add a new server (auto-generates id)
GET	`/api/servers/<id>`	Fetch one server (auth redacted)
PUT/PATCH	`/api/servers/<id>`	Update; redacted auth values are kept
DELETE	`/api/servers/<id>`	Remove a server
POST	`/api/servers/test-connection`	Test a candidate config without saving
POST	`/api/servers/<id>/refresh-libraries`	Re-fetch the server's library list
GET	`/api/servers/owners?path=...`	Diagnose which servers own a given path
GET	`/api/servers/<id>/output-status?path=...&item_id=...`	Whether publisher output files exist for a path on this server. `item_id` is required for Plex servers (the bundle hash is keyed by item id); optional for Emby and Jellyfin. Plex requests without `item_id` return `{"needs_item_id": true}`.
POST	`/api/servers/auth/emby/password`	Username+password → Emby token
POST	`/api/servers/auth/jellyfin/password`	Username+password → Jellyfin token
POST	`/api/servers/auth/jellyfin/quick-connect/initiate`	Begin Quick Connect ceremony
POST	`/api/servers/auth/jellyfin/quick-connect/poll`	Poll for approval
POST	`/api/servers/auth/jellyfin/quick-connect/exchange`	Exchange approved secret for token
GET	`/api/servers/<id>/health-check`	Per-server settings audit. Returns `{vendor, issues, issue_count, fixable_count}`; `issues[]` carries `{flag, label, severity, current, recommended, rationale, library_id, library_name, fixable}`. Works for Plex (server-wide prefs via `/:/prefs`), Emby and Jellyfin (per-library `LibraryOptions`). Replaces the older Jellyfin-only `/jellyfin/trickplay-status` route.
POST	`/api/servers/<id>/health-check/apply`	Apply settings to one or more flags. Three body shapes (all backwards-compatible): `{}` = fix every issue at recommended value; `{"flags": ["FlagName", ...]}` = fix only named flags toward recommended; `{"set": [{"flag": "X", "value": true\|false, "library_ids": ["id"]\|null}]}` = set each flag to the EXPLICIT value (enables disable-direction toggles on the Previews readiness card). Returns `{ok, results}` keyed `<library_id>:<flag>` (or `:<flag>` for server-wide prefs).
GET	`/api/servers/<id>/previews-readiness`	Unified readiness payload for every vendor. Returns `{vendor, overall_ok, sections: [{id, title, docs_anchor, ok, severity, checks: [{id, label, docs_anchor, tooltip, ok, severity, current, recommended, actions: {enable?, disable?}, reason, meta}]}]}`. Drives the unified Previews readiness card on the Edit Server modal. See the Previews readiness guide.
POST	`/api/servers/<id>/install-plugin`	Jellyfin only. Adds the Media Preview Bridge manifest URL to Jellyfin's plugin repos, queues the package install, and restarts Jellyfin. Returns `{ok, steps: [{step, ok, detail}], error}`.
POST	`/api/servers/<id>/uninstall-plugin`	Jellyfin only. Removes the Media Preview Bridge plugin (`DELETE /Packages/{GUID}`; 404 treated as success — already gone) and restarts Jellyfin. Repo URL stays in place for possible re-install. Same response shape as `/install-plugin`.
GET	`/api/bif/servers/<id>/search?q=<query>`	Multi-server BIF Viewer search; returns `preview_kind` (`bif` or `trickplay`) per result so the viewer renders the right format
GET	`/api/bif/trickplay/info?server_id=...&path=...`	Parse a Jellyfin trickplay manifest + report sheet metadata
GET	`/api/bif/trickplay/frame?server_id=...&sheets_dir=...&index=N&tile_width=10&tile_height=10`	Slice and serve a single thumbnail JPEG from a trickplay tile sheet

Webhook Endpoints

Inbound webhook endpoints for Radarr/Sonarr/Custom integration. Webhook endpoints accept X-Auth-Token, Authorization: Bearer, or a configured webhook_secret.

Tip

The new universal webhook URL at POST /api/webhooks/incoming auto-detects the vendor (Plex / Emby / Jellyfin / Sonarr / Radarr / templated path) so you only need one URL across every server. Falls back to per-server URLs at POST /api/webhooks/server/<server_id> for ambiguous setups (rare). See Multi-Media-Server — Webhook configuration for details.

POST /api/webhooks/incoming

Universal webhook router. Inspect the request body, classify it as Plex / Emby / Jellyfin / Sonarr / Radarr / generic-{path: ...}, and dispatch to every server that owns the resolved canonical path. Works alongside the per-vendor URLs below — you can keep using those, or replace them all with this one.

Returns 200 with the dispatch result (status, kind, canonical_path, publishers[], frame_count) on success, 202 with status: "ignored" for noise events the router intentionally drops (e.g. Jellyfin PlaybackStart), 400 for unrecognised payloads, 401 for bad auth, 413 for payloads above the 1 MiB cap.

POST /api/webhooks/server/{server_id}

Same as /api/webhooks/incoming but pins dispatch to one configured server. Useful when two configured servers (e.g. Plex + Jellyfin) own the same path and the source can't tell them apart — the URL itself carries the disambiguation. Returns 404 when the server id isn't configured.

POST /api/webhooks/radarr

Receive a Radarr webhook payload.

Download event request:

{
  "eventType": "Download",
  "movie": {
    "title": "Inception",
    "folderPath": "/movies/Inception (2010)"
  }
}

Response (202): {"success": true, "message": "Processing queued for 'Inception'"}

Test event: {"eventType": "Test"} → Response (200): {"success": true, "message": "Radarr webhook configured successfully"}

POST /api/webhooks/sonarr

Same authentication and response patterns as Radarr.

Download event request:

{
  "eventType": "Download",
  "series": { "title": "Breaking Bad" },
  "episodeFile": { "relativePath": "Season 01/S01E01.mkv" }
}

POST /api/webhooks/custom

Receive a custom webhook payload from any external tool (Tdarr, scripts, etc.). Accepts one or more file paths to process.

Single file request:

{
  "file_path": "/media/movies/Movie (2024)/Movie.mkv"
}

Multiple files request:

{
  "file_paths": [
    "/media/tv/Show/Season 01/S01E01.mkv",
    "/media/tv/Show/Season 01/S01E02.mkv"
  ],
  "title": "Optional display label"
}

Field	Type	Required	Description
`file_path`	string	One of `file_path` / `file_paths`	Single absolute file path
`file_paths`	array of strings	One of `file_path` / `file_paths`	Multiple absolute file paths
`title`	string	No	Display label for history/jobs
`eventType`	string	No	Set to `"Test"` to verify connectivity

Response (202): {"success": true, "message": "Processing queued for 1 file"}

Test event: {"eventType": "Test"} → Response (200): {"success": true, "message": "Custom webhook configured successfully"}

Error (400): {"success": false, "error": "Payload must include 'file_path' (string) or 'file_paths' (array of strings)"}

POST /api/webhooks/plex

Receive a native Plex webhook (Plex Pass feature). Plex POSTs multipart/form-data with a payload part containing the JSON event body. Only library.new events trigger work; other events (media.play, media.rate, library.on.deck, etc.) are acknowledged with 200 and ignored.

The endpoint also accepts a synthetic test.ping event used by the Test reachability button on the Automation page (Triggers tab).

library.new payload (excerpt):

{
  "event": "library.new",
  "owner": true,
  "Metadata": {
    "ratingKey": "153037",
    "type": "movie",
    "title": "Some Movie",
    "Media": [{ "Part": [{ "file": "/data/movies/Some Movie/Some Movie.mkv" }] }]
  }
}

When Media[].Part[].file is missing from the payload (Plex doesn't always include it), the app fetches the item by ratingKey via the Plex API to recover the file paths.

Authentication: same as the other webhook endpoints — X-Auth-Token header, Authorization: Bearer, or HTTP Basic password.

Important

Plex's library.new webhook is wired through the same code path as mobile push notifications. If push notifications are disabled on your Plex server, library events are silently dropped — enable them under Plex Web → Settings → General (toggle Enable mobile push notifications). See the Auto-trigger from Plex guide for full details.

POST /api/settings/plex_webhook/register

Register the Plex direct webhook (/api/webhooks/plex) with the user's plex.tv account, using the configured Plex token.

Request body:

{ "public_url": "http://your-host:8080/api/webhooks/plex" }

public_url is optional — when omitted the server uses <request scheme>://<host>/api/webhooks/plex.

Response (200): {"success": true, "registered_in_plex": true, "public_url": "..."}

Errors:

400 — token missing
403 — Plex Pass required (reason: "plex_pass_required")
502 — registration call to plex.tv failed

POST /api/settings/plex_webhook/unregister

Remove the Plex direct webhook from the user's plex.tv account and turn off the local toggle. Returns {"success": true, "registered_in_plex": false}.

GET /api/settings/plex_webhook/status

Probe live state. Returns the configured public URL, whether it is currently registered with Plex, and Plex Pass detection.

{
  "enabled_in_settings": true,
  "registered_in_plex": true,
  "public_url": "http://your-host:8080/api/webhooks/plex",
  "default_url": "http://your-host:8080/api/webhooks/plex",
  "has_plex_pass": true,
  "error": null,
  "error_reason": null
}

POST /api/settings/plex_webhook/test

Self-POST a synthetic test.ping payload to the configured public URL to verify reachability. The receiving endpoint records a "test" history entry. Returns {"success": true, "status_code": 200, ...} on success.

To run a Recently Added scan immediately, call POST /api/schedules/<id>/run on the scanner schedule — it's a standard user schedule now, not a dedicated settings endpoint.

GET /api/webhooks/history

Get recent webhook events (newest first, max 100). For events with status: "triggered" (a debounced batch that was processed), the response may include job_id, path_count, and files_preview (up to 20 basenames) so the UI can show which files were in the batch. File lists are also available on the Dashboard job queue (expand with the chevron next to "Sonarr: N files" / "Radarr: N files" / "Custom: N files") and on the Automation page (Triggers tab) Activity Log (expand triggered rows).

{
  "events": [
    {
      "timestamp": "2026-02-12T10:30:00+00:00",
      "source": "sonarr",
      "event_type": "Download",
      "title": "sonarr",
      "status": "triggered",
      "job_id": "abc-123",
      "path_count": 3,
      "files_preview": ["S01E01.mkv", "S01E02.mkv", "S01E03.mkv"]
    }
  ]
}

DELETE /api/webhooks/history

Clear all webhook history. Returns {"success": true}.

Error Responses

All errors follow this format:

{
  "error": "Error message",
  "code": "ERROR_CODE"
}

Code	HTTP Status	Description
`UNAUTHORIZED`	401	Missing or invalid authentication token
`NOT_FOUND`	404	Resource not found
`VALIDATION_ERROR`	400	Invalid request data
`SERVER_ERROR`	500	Internal server error

WebSocket Events

The dashboard uses Flask-SocketIO with WebSocket for real-time updates. The client connects to the /jobs namespace.

const socket = io('/jobs', {
    transports: ['websocket', 'polling'],
    reconnection: true
});

Event	Description
`job_progress`	Job progress update
`job_complete`	Job finished
`job_error`	Job failed
`worker_update`	Worker status change

Example payload:

{
  "event": "job_progress",
  "data": {
    "job_id": "job-123",
    "progress": 50,
    "completed": 50,
    "total": 100,
    "current_item": "Movie Title"
  }
}

Complete Endpoint Index

The sections above cover the endpoints most integrations need. This index catalogues the remaining routes — mostly internal APIs the web UI calls, but documented here so you can drive them from scripts if you want. All require the same X-Auth-Token / Authorization: Bearer auth as the rest of the API unless noted.

Auth & token management

Method	Endpoint	Description
GET	`/api/auth/status`	Session auth state — used by the UI on page load
POST	`/api/auth/login` · `/api/auth/logout`	Session login/logout (cookie-based)
POST	`/api/token/regenerate`	Rotate the stored API token (disabled when `WEB_AUTH_TOKEN` is set)
POST	`/api/token/set`	Set a custom token — min 8 chars; returns `{success: false, error: ...}` on validation failure

Jobs (beyond the basics in Jobs Endpoints)

Method	Endpoint	Description
POST	`/api/jobs/manual`	Submit one or more absolute file paths — `{"file_paths": ["/a.mkv", "/b.mkv"], "force_regenerate": false, "priority": 2, "server_id": "..."}`. Bypasses library scan.
POST	`/api/jobs/{id}/priority`	Change a pending/running job's priority (`{"priority": 1\|2\|3}`; 1 = high)
POST	`/api/jobs/{id}/reprocess`	Re-run a finished job with the same config
POST	`/api/jobs/{id}/retry-now`	Skip the retry back-off on a chain-head job whose next attempt is currently in the back-off countdown. Returns 200 + `{"fired": true, ...}` on success, 409 when no retry is pending, 400 if the job isn't a chain head.
POST	`/api/jobs/{id}/fire-webhook-now`	Skip the debounce window on a webhook-batch job that's still waiting to dispatch. Looks up the in-memory batch by `job_id` and cancels its threading timer, then dispatches the same callback synchronously. 202 on success, 404 when the job has no live pending batch (already fired, never had one, or container restart cleared the in-memory dict).
GET	`/api/jobs/{id}/logs`	Paginated log stream — `?offset=&limit=` (limit capped at 5000); or legacy `?last=N` for the tail
GET	`/api/jobs/{id}/files`	Per-file outcomes — paginated `?page=&per_page=` (per_page capped at 500), plus optional `?outcome=` and `?search=` filters. The underlying per-job JSONL is itself soft-capped at 5000 rows; past that, a `truncated` marker row appears and aggregate counts remain in `progress.outcome`.
POST	`/api/jobs/clear`	Delete completed/failed jobs from the queue
GET	`/api/jobs/stats`	Totals grouped by status
GET	`/api/jobs/workers`	Current worker-pool snapshot (type, state, current item)
POST	`/api/workers/add` · `/api/workers/remove`	Spawn/shutdown pool workers live (`{"type": "gpu"\|"cpu", "count": N}`)
POST	`/api/jobs/{id}/workers/add` · `/api/jobs/{id}/workers/remove`	Per-job worker adjustment while the job runs

Schedules

Method	Endpoint	Description
POST	`/api/schedules/{id}/enable` · `/api/schedules/{id}/disable`	Toggle a schedule without deleting it
GET · POST	`/api/quiet-hours`	Read / write the multi-window quiet-hours policy (days of week + start/stop times)

Settings & setup

Method	Endpoint	Description
PUT	`/api/settings/log-level`	Change runtime log verbosity (`{"level": "DEBUG"\|"INFO"\|...}`)
POST	`/api/settings/validate-local-path`	Pre-flight a mount/volume path before saving (exists + readable)
POST	`/api/settings/validate-plex-config-folder`	Pre-flight a Plex config folder (looks for `Cache/Media/Metadata`)
GET	`/api/settings/backups`	List rolling settings.json backup snapshots
POST	`/api/settings/backups/restore`	Restore a prior settings.json snapshot
POST	`/api/setup/skip`	Skip the setup wizard (advanced — saves `setup_complete=true` with minimal state)
POST	`/api/setup/validate-paths`	Pre-flight wizard path fields in bulk

Servers (beyond the basics in Multi-Media-Server Endpoints)

Method	Endpoint	Description
POST	`/api/servers/{id}/test-connection`	Re-test a saved server's live connection
PATCH	`/api/servers/{id}/enabled`	Enable/disable a server entry without deleting (`{"enabled": true\|false}`)
POST	`/api/servers/{id}/vendor-extraction`	Toggle vendor-side preview generation (Plex `enableBIFGeneration`, Emby/Jellyfin trickplay extraction)
GET	`/api/servers/{id}/vendor-extraction/status`	Current aggregate state (e.g. "stopped on 3/5 libraries")
GET	`/api/servers/{id}/trickplay-readiness`	(Jellyfin) Legacy audit endpoint — kept for scripts. New integrations should use `/previews-readiness`.
POST	`/api/servers/{id}/trickplay-fix-all`	(Jellyfin) Apply all recommended trickplay flags

Webhooks (beyond the basics in Webhook Endpoints)

Method	Endpoint	Description
POST	`/api/webhooks/sportarr`	Sonarr-compatible feed for Sportarr (falls back to flat `filePath`)
GET	`/api/webhooks/pending`	Batches currently debouncing — per-source key, countdown, and queued paths
POST	`/api/webhooks/pending/{debounce_key}/fire-now`	Skip the debounce timer and dispatch the batch immediately

System & diagnostics

Method	Endpoint	Description
GET	`/api/system/timezone`	Container TZ + source (env var vs `/etc/localtime`)
GET	`/api/system/media-servers`	Multi-server aggregate health (per-vendor connection + library counts)
GET	`/api/system/vulkan`	Vulkan ICD probe result (device, driver version, ICD files loaded)
GET	`/api/system/vulkan/debug`	Plain-text diagnostic bundle for attaching to GitHub issues (DV Profile 5 troubleshooting)
POST	`/api/system/rescan-gpus`	Re-probe all GPUs (refreshes `gpu_config` candidate list)
GET	`/api/system/version`	App version + commit SHA + build date
GET	`/api/system/notifications`	In-app notification list (health checks, deprecations, warnings)
POST	`/api/system/notifications/{id}/dismiss`	Session-only dismiss
POST	`/api/system/notifications/{id}/dismiss-permanent`	Persistent dismiss (stored in settings)
POST	`/api/system/notifications/reset-dismissed`	Clear all permanent dismissals
GET	`/api/system/whats-new`	Release-notes viewer payload (version + changes since last-seen)
POST	`/api/system/whats-new/dismiss`	Mark the current version's notes as seen
GET	`/api/system/browse`	Safe filesystem browser, scoped to `MEDIA_ROOT` / `PLEX_DATA_ROOT` (used by path pickers)
GET	`/api/logs/history`	Persisted log history — `?limit=` (default 500, max 2000), `?level=` (minimum level filter), `?before=` (ISO-8601 timestamp cursor for older-than paging)

Rate Limiting

Endpoint	Limit
`POST /login`	5 per minute
`POST /api/auth/login`	10 per minute
Default	200 per day, 50 per hour

Rate limit headers are included in responses:

X-RateLimit-Limit
X-RateLimit-Remaining
X-RateLimit-Reset

Next Steps

Complete install and setup in Getting Started
Use operational workflows in Guides & Troubleshooting

Back to Docs | Main README

FilesExpand file tree

reference.md

Latest commit

History

reference.md

File metadata and controls

Configuration & API Reference

Contents

Related Docs

Configuration Priority

Media Servers

Processing Options

Per-GPU Configuration (gpu_config)

Other Processing Settings

Frame Reuse Cache (frame_reuse)

Environment Variables

Infrastructure Variables (always active)

External Authentication (AUTH_METHOD)

Deprecated (no longer used)

One-time seed values (migrated on first start)

Web Interface Settings

Webhook Settings

Path Mappings

Why Path Mappings?

Configuration (Web UI)

Legacy env (semicolon pair)

When a server uses multiple roots (e.g. mergerfs)

Examples

How to Find Your Paths

No Mapping Needed

Exclude Paths

REST API

Authentication

Setup & Settings Endpoints

GET /api/setup/status

GET /api/setup/state

POST /api/setup/state

POST /api/setup/complete

GET /api/setup/token-info

POST /api/setup/set-token

GET /api/settings

POST /api/settings

Plex OAuth Endpoints

POST /api/plex/auth/pin

GET /api/plex/auth/pin/{id}

GET /api/plex/servers

GET /api/plex/libraries

POST /api/plex/test

Processing state (global pause)

Jobs Endpoints

GET /api/jobs

POST /api/jobs

GET /api/jobs/{id}

Schedules Endpoints

POST /api/schedules

System Endpoints

Multi-Media-Server Endpoints

Webhook Endpoints

POST /api/webhooks/incoming

POST /api/webhooks/server/{server_id}

POST /api/webhooks/radarr

POST /api/webhooks/sonarr

POST /api/webhooks/custom

POST /api/webhooks/plex

POST /api/settings/plex_webhook/register

POST /api/settings/plex_webhook/unregister

GET /api/settings/plex_webhook/status

POST /api/settings/plex_webhook/test

GET /api/webhooks/history

DELETE /api/webhooks/history

Error Responses

WebSocket Events

Complete Endpoint Index

Auth & token management

Jobs (beyond the basics in Jobs Endpoints)

Schedules

Settings & setup

Servers (beyond the basics in Multi-Media-Server Endpoints)

Webhooks (beyond the basics in Webhook Endpoints)

System & diagnostics