Prerequisites

What you need before installing Diskovarr.

Required

Network Access

Diskovarr must be able to reach your Plex server and Tautulli over HTTP/HTTPS. If they run on the same machine, http://localhost:PORT works. If they're on separate machines, use local IPs or hostnames.

Optionally, expose Diskovarr externally (via Nginx Proxy Manager or similar) so users can access it from outside your home network. An external URL is also required if you want Discord bot avatar upload to work.

Optional Services

Installation

Docker is the recommended installation method - it handles all dependencies, isolates Diskovarr from your host, and makes updates a one-liner. Native installation is also supported if you prefer to run directly on the host.

docker run -d \
  --name diskovarr \
  --restart unless-stopped \
  -p 3232:3232 \
  -v ./data:/app/data \
  -e ADMIN_PASSWORD=your_admin_password \
  -e SESSION_SECRET=$(openssl rand -hex 32) \
  -e PLEX_URL=http://192.168.1.x:32400 \
  -e PLEX_TOKEN=your_plex_admin_token \
  -e PLEX_SERVER_ID=your_plex_machine_identifier \
  -e PLEX_SERVER_NAME=Your\ Server\ Name \
  lebbi/diskovarr:latest

mkdir -p /opt/diskovarr && cd /opt/diskovarr

services:
  diskovarr:
    image: lebbi/diskovarr:latest
    container_name: diskovarr
    restart: unless-stopped
    ports:
      - "3232:3232"
    volumes:
      - ./data:/app/data
    environment:
      # ── Required ────────────────────────────────────────────────
      - ADMIN_PASSWORD=change_this_to_a_secure_password
      - SESSION_SECRET=change_this_to_a_long_random_string
      - PLEX_URL=http://192.168.1.x:32400
      - PLEX_TOKEN=your_plex_admin_token
      - PLEX_SERVER_ID=your_plex_machine_identifier
      - PLEX_SERVER_NAME=Your Server Name
      # ── Optional (can be configured in admin panel instead) ─────
      - TAUTULLI_URL=http://192.168.1.x:8181
      - TAUTULLI_API_KEY=your_tautulli_api_key
      - TMDB_API_KEY=your_tmdb_api_key
      - PLEX_MOVIES_SECTION_ID=1
      - PLEX_TV_SECTION_ID=2
      - APP_URL=http://localhost:3232
      - PORT=3232

openssl rand -hex 32

docker compose up -d

docker compose logs -f diskovarr

docker compose pull && docker compose up -d

services:
  diskovarr:
    image: lebbi/diskovarr:latest
    container_name: diskovarr
    restart: unless-stopped
    ports:
      - "3232:3232"
    volumes:
      - ./data:/app/data
    environment:
      - ADMIN_PASSWORD=your_password
      - SESSION_SECRET=your_secret
    networks:
      - media

networks:
  media:
    external: true    # name of your existing Docker network

node -v

# Install nvm
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash
source ~/.bashrc

# Install and use Node.js 23
nvm install 23
nvm use 23

git clone https://github.com/Lebbitheplow/diskovarr.git
cd diskovarr

npm install
cd server && npm install

cp server/.env.example server/.env
nano server/.env

npm run build

cd server && npm start

cd server && npm run dev

npm run dev

sudo nano /etc/systemd/system/diskovarr.service

[Unit]
Description=Diskovarr
After=network.target

[Service]
Type=simple
User=your-user
WorkingDirectory=/home/your-user/diskovarr/server
ExecStart=/usr/bin/node server.js
Restart=on-failure
RestartSec=5
EnvironmentFile=/home/your-user/diskovarr/server/.env

[Install]
WantedBy=multi-user.target

sudo systemctl daemon-reload
sudo systemctl enable --now diskovarr
sudo systemctl status diskovarr

cd /home/your-user/diskovarr
git pull
npm install
cd server && npm install
cd .. && npm run build
sudo systemctl restart diskovarr

First-Time Setup

After starting Diskovarr for the first time, follow these steps to get the core services connected. Once done, Diskovarr will be fully functional - optional integrations (Overseerr, Radarr, Sonarr, Riven, Agregarr) can be added any time from the Connections tab.

Admin Panel - Connections

Configure all external services. Each service follows the same pattern: toggle to enable/disable, enter credentials, Test, then Save. Saved values are stored masked (shown as ••••••••).

Use the sidebar links to jump to a specific service:

Default Request Service

Visible when two or more request services are enabled. Sets which service handles new requests by default. Users with access to multiple services can switch via the Advanced button in the request dialog.

Alternate Request App Access

Controls who sees the Advanced service selector button in request dialogs:

• All Users - any user can choose which service to route their request to
• Admin Only - only admins and elevated users see the alternate service option

Connection - Plex

Plex is required. It provides the library, user authentication via Plex OAuth, and poster images. All other features depend on this connection being healthy.

What you need

• The IP address or hostname of your Plex server
• Your Plex server's port (default 32400)
• Your Plex admin token - retrieved automatically via the Sign in button, or manually if preferred

Entering the connection

In Admin → Connections → Plex:

Getting your token - Sign in to Plex (recommended)

Click the Sign in to Plex button on the Connections → Plex page. A Plex OAuth window opens - sign in with the account that owns the server. Diskovarr retrieves the token automatically and fills it in. No digging through URLs required.

Getting your token - manually

If you prefer to paste the token directly:

1. Open Plex Web (app.plex.tv) and sign in as the server owner.
2. Click any movie or show → ⋮ menu → Get Info → View XML.
3. In the new tab's address bar, copy the value after X-Plex-Token= - that's your 20-character token.

Enter the address, port, and token, then click Test. A green success message confirms Diskovarr can reach your Plex server. Click Save.

Connection - Tautulli

Tautulli is required for personalized recommendations. It tracks what every user has watched on your Plex server - Diskovarr uses that history to score and rank titles for each person.

What is Tautulli?

Tautulli is a free, open-source monitoring and tracking tool for Plex. If you don't have it installed yet, grab it from tautulli.com - it runs as a Docker container or native service and takes about 5 minutes to set up. It must be pointed at the same Plex server you connected in the previous step.

Finding your Tautulli API key

Entering the connection

In Admin → Connections → Tautulli:

Click Test then Save. Once saved, Diskovarr will start pulling watch history for recommendations.

Connection - TMDB

The Movie Database (TMDB) provides metadata, poster art, trailers, cast info, and discovery data. The API is completely free for personal use - no credit card required.

What TMDB enables

• Diskovarr Requests tab - genre/trending discovery, personalized TMDB picks, request actions
• Item detail modals - genres, ratings, cast, director credits, synopsis, trailer embeds
• Search autocomplete - title suggestions in the nav bar search
• Season data - TV season counts and episode info in request dialogs

Without a TMDB key the Requests tab is hidden for all users. The home recommendation page still works since it reads from your existing Plex library.

Getting a free TMDB API key

Entering the connection

In Admin → Connections → TMDB, paste your key into the API Key (v3) field and click Test then Save. The Diskovarr Requests tab appears immediately for all users.

Connection - Overseerr

Overseerr (or Jellyseerr) handles the actual download trigger when a user submits a request in Diskovarr. It connects to your Radarr and Sonarr instances and manages approvals, quality profiles, and notifications on its own side. Use this if you already have Overseerr running - or use Radarr/Sonarr directly instead.

Getting your Overseerr API key

Entering the connection

In Admin → Connections → Overseerr:

Click Test then Save. Users will now see a request button on all items not in the library.

Connection - Radarr

Direct movie request routing without needing Overseerr. When a user's movie request is approved in Diskovarr, it's sent straight to Radarr which handles searching, downloading, and adding it to your library.

Getting your Radarr API key

Entering the connection

In Admin → Connections → Radarr:

Click Test to load quality profiles, select one, then click Save. Movies requested through Diskovarr will now be added directly to Radarr.

Connection - Sonarr

Direct TV show request routing. Works the same as Radarr but for TV series - when a TV request is approved, Diskovarr sends it to Sonarr which handles downloading and library management.

Getting your Sonarr API key

In Sonarr, go to Settings → General → Security. Your API Key is shown there - copy it.

Entering the connection

In Admin → Connections → Sonarr:

Click Test to load profiles, select one, then click Save.

Connection - DUMB / Riven

DUMB (Debrid Unlimited Media Bridge) is an all-in-one Docker stack that bundles 25+ media automation services - including Riven, Zurg, rclone, Radarr, Sonarr, Tautulli, Plex, and more - into a single, modular deployment. Riven is one component within DUMB responsible for media automation: it finds debrid-cached torrents and symlinks them into your library without downloading anything locally. Diskovarr connects to the Riven component inside DUMB (or a standalone Riven install) to route requests and provides an Overseerr-compatible bridge for automatic request polling.

What this connection does

• Request routing - approved requests from Diskovarr are sent to Riven (inside DUMB) which finds a cached torrent on your debrid service and adds it to your library automatically
• Overseerr-compatible bridge - Diskovarr exposes an Overseerr-compatible API endpoint so Riven's poller can pull approved requests on its own schedule
• Overseerr-compatible bridge - Diskovarr exposes an Overseerr-compatible API endpoint so Riven's poller can pull approved requests on its own schedule

Prerequisites

• DUMB running with the Riven service enabled (recommended), or a standalone Riven instance
• An active Real-Debrid (or All-Debrid) subscription - Riven uses debrid for cached torrent access
• Riven already configured and connected to your Plex library within DUMB

Step 1 - Connect Diskovarr to Riven

In Admin → Connections → DUMB/Riven:

Click Test then Save. Once saved, request routing to Riven is active.

Step 2 - Set up the DUMB request bridge (recommended)

The DUMB integration lets Riven automatically pull and process approved requests from Diskovarr without any manual intervention. Diskovarr exposes an Overseerr-compatible endpoint - configure Riven to point at it using the Overseerr Compat Key from Admin → General.

How the bridge works

In Pull mode, Riven periodically calls Diskovarr's /api/v1/request endpoint (Overseerr-compatible format). Approved requests appear with media.status=3 (PROCESSING). Riven picks these up and triggers downloads via your debrid service. When content becomes available, Riven calls PUT /api/v1/media/:id/available which Diskovarr uses to mark the request as fulfilled and send a "Request Available" notification to the requester.

Using Riven without DUMB

If you're running Riven standalone (not inside DUMB), the connection works exactly the same way - enter your Riven URL and follow the same bridge steps above. Request routing and Overseerr-compatible polling both function identically. DUMB is recommended because it manages Riven alongside all the supporting services (rclone, Zurg, Tautulli, etc.) in one place, but it's not a hard requirement.

Connection - Agregarr

Agregarr is a Plex collection manager that can automatically request missing items from your collections. Diskovarr provides an Overseerr-compatible API shim so Agregarr can send those requests to Diskovarr as if it were Overseerr - they show up in your request queue with a bot badge and go through the same approval and routing as user requests.

How it works

When Agregarr finds a movie or show that belongs in one of your Plex collections but isn't in your library, it sends a request to Diskovarr's /api/v1/ shim endpoint. Diskovarr processes it as a regular request, auto-approves it if your settings allow, and routes it to whichever download service you have configured (Overseerr, Radarr, Sonarr, or Riven). Each collection type gets its own service user account in Diskovarr (e.g. "TmdbAgregarr", "ImdbAgregarr") that appears in the request queue.

Setting up the connection

Settings reference

For more details on the Agregarr integration workflow, see Integrations - Agregarr.

Admin Panel - General

The General tab contains app-wide settings: public URL, theme, library sync, logging, and the API key.

App Public URL

Enter the full external URL where Diskovarr is accessible (e.g. https://diskovarr.example.com). This is used when uploading a Discord bot avatar - without it, the avatar upload will fail. It does not affect Plex authentication.

Theme Color

Pick an accent color for the entire app. Changes apply immediately - all users see the new color on their next page load without a restart.

• Preset swatches - click any swatch to apply instantly
• Custom color picker - enter any hex value or use the color wheel
• Apply button - confirms your selection

Library Sync

Diskovarr maintains an in-memory library cache synced from Plex every 2 hours. The General tab shows the current state and lets you trigger a manual sync.

Synced Libraries

Choose which Plex libraries Diskovarr syncs. Below the sync stats, a summary reads X of Y libraries synced with an Add/Edit Libraries button that opens the selection modal.

Verbose Logging

When enabled, Diskovarr writes detailed HTTP request logs including headers, query params, and response times. Useful for debugging connection issues.

# View live logs (systemd)
journalctl -u diskovarr -f

# Or if running directly
npm start 2>&1 | tee diskovarr.log

API Key

Generate a token for external API access (scripts, automation tools, etc.). The key is shown once - copy it immediately. You can regenerate at any time, which invalidates the old key.

• Eye button - toggle visibility of the masked key field
• Copy button - copies key to clipboard
• Generate / Regenerate - creates a new key (old key is immediately invalid)

Pass the key in requests using the header: X-Api-Key: your-key-here

Overseerr Compat API

Diskovarr exposes an Overseerr-compatible API at /api/v1/ so external apps that speak the Overseerr API can connect to it directly. Supported apps include DUMB (Riven request polling), Agregarr (collection auto-requests), and Homarr (media stats and request list widgets).

API Endpoint Reference

A collapsible table of public API endpoints is shown below the API Key section. It documents every endpoint's method, path, parameters, and purpose. See the full API Reference section in this documentation.

Admin Panel - Users

Manage all users on your server: request limits, auto-approve, elevated privileges, bulk actions, and cache controls.

Server Owner

Select which Plex user is the designated server owner. The owner's elevated privileges toggle is permanently locked - they cannot have admin access removed. Choose yourself or a trusted admin account.

Watchlist Mode

Controls how the Watchlist feature works:

• Plex Watchlist - reads and writes to the user's actual Plex watchlist. Requires the user to be connected via Plex OAuth.
• Diskovarr Playlist - Diskovarr manages its own per-user playlist independent of Plex. Useful if users don't use Plex's native watchlist.

Individual Season Requests

When enabled, TV show request dialogs show a checkbox list of individual seasons so users can request only specific seasons rather than the whole show. When disabled, TV requests are submitted for the full series.

User Table

Lists all known Plex users who have signed in. Columns:

• Checkbox - select for bulk operations
• User - avatar, username, and Plex user ID
• Watched - number of items in their Tautulli watch history
• Requests - total number of requests submitted
• Last Visit - when they last accessed Diskovarr
• Settings ⚙ - opens the per-user settings page (when Diskovarr Requests is enabled)

The table paginates at 10 users per page. Use the per-page dropdown (10 / 25 / 50) to show more. Pagination controls are always visible.

Bulk Edit

Select one or more users via the row checkboxes, then click Bulk Edit Settings to apply settings to all selected users at once. Each field has a three-state selector - No change means that field is skipped for all selected users, so only fields you explicitly set will be updated.

Bulk editable fields: request limit overrides (movies and TV seasons), auto-approve (movies and TV), elevated privileges (grant or revoke).

Cache Management

These buttons affect all users at once. Use when troubleshooting stale data:

Global Request Limits

Set defaults applied to all users. Individual users can have overrides set on their per-user settings page.

• Movies - check Unlimited for no limit, or enter a count and window in days (e.g. "3 movies per 7 days")
• TV Seasons - same format, counted per season requested (not per show)

Auto-Approve

When enabled, requests skip the queue entirely and route directly to the configured service (Overseerr, Radarr, Sonarr, etc.) without waiting for admin approval.

• Auto-Approve Movies - toggle for all movie requests
• Auto-Approve TV Shows - toggle for all TV requests

Per-user overrides can enable or disable auto-approve independently of the global setting.

Auto-Request Watchlist

When enabled, adding an item to the Diskovarr watchlist automatically submits a request for it. Works per-media-type:

• Auto-Request Movies from Watchlist
• Auto-Request TV Shows from Watchlist

Disable All Requests

A global kill switch in the Request Limits section. When toggled on, the Request button is hidden site-wide and any attempt to submit a request is blocked. Individual users can be granted a bypass via their per-user settings page (Override Global → enable requests for that user).

Admin Panel - Automation

The Automation tab automates both ends of library management: Auto Request watches external lists and requests new items for you, and Deletion Profiles clean up content matching criteria you define. Both are off until you configure them - with no lists and no profiles, Diskovarr requests and deletes nothing.

Auto Request

Auto Request monitors lists from around the web and turns new entries into Diskovarr requests automatically - a built-in replacement for Agregarr. Each list syncs on its own schedule, deduplicates against your library and existing requests, and routes new requests through your normal service selection (Radarr, Sonarr, Overseerr, or Riven/DUMB).

Adding a List

Click + Add List and pick one of three source kinds. The Validate & preview button fetches the source and shows resolved titles before you save anything.

• Presets - IMDb Top 250 and Most Popular, Trakt trending/popular/anticipated, TMDB charts (popular, top rated, now playing, upcoming), and Top 10 charts per network/streamer (Netflix, Max, Disney+, Apple TV+, Prime Video, Hulu, Paramount+, Peacock).
• Pasted URLs - public lists from Trakt (user lists and charts), IMDb (charts and ls… lists), TMDB lists, Letterboxd lists, MDBList, and AniList anime lists.
• Criteria - define the list with the same criteria vocabulary as Content Monitors instead of an external source (see below).

Criteria Lists

A criteria list continuously requests content matching rules you define - no external list needed. It uses the same criterion types as Content Monitors: Genre, Cast Member, Director, Writer, Producer, Studio, Network, Production Company, Collection, Keyword, Country, and Language, combined with Match ALL or Match ANY. Where monitors notify you when matching content happens to appear, a criteria list actively goes and finds it.

Examples: Genre: Horror + Cast Member: Toni Collette (ALL) auto-requests her horror films; Network: Netflix keeps up with popular Netflix shows; Collection: The Lord of the Rings grabs every film in the saga; Director: Denis Villeneuve (with a collection enabled) builds a director collection on your Plex home screen.

Values are matched on TMDB at sync time - person, company, keyword, and collection names resolve through TMDB search, so use Validate & preview to confirm a name resolves to the right entity. Results are ordered by TMDB popularity and capped at 100 per sync, with your Max requests per sync still applying on top.

Plex Collections from Lists

Any list can also maintain a Plex collection mirroring its in-library items. Items are added as they arrive and removed when they drop off the source list. Choose where the collection is promoted:

• Home page + Recommended - pinned to the server home screen (yours and shared users') and the library's Recommended tab
• Library Recommended tab - promoted only inside the library
• Library only - a plain collection with no promotion

A list set to Movies + TV produces two collections (the TV one named "Name (TV)"), since Plex collections live in a single library section. Deleting a list asks whether to remove its Plex collection too.

Source Credentials

Two sources need free credentials, entered at the bottom of the Auto Request section. Everything else works out of the box.

• Trakt Client ID - create an app at trakt.tv/oauth/applications; only the client ID is needed (no OAuth login).
• MDBList API Key - free from mdblist.com/preferences.

Deletion Profiles

Deletion profiles automatically clean up library content matching criteria you define. The safety model is layered:

• No profiles = nothing is ever deleted. The deletion job exits immediately.
• New profiles start in dry-run mode and report matches without touching anything.
• An empty profile (no criteria) matches nothing - it can never mean "delete everything".
• Items on any user's watchlist are protected by default, plus optional exclusions by collection, label, or minimum library age.
• Every run is capped by Max deletions per run, and every action is recorded in a permanent history.

Modes

Criteria

A profile targets movies or TV shows and matches when all of its criteria are true. Available criteria:

• Watch data - never played, not played in the last X days (includes never played), total plays across all users
• Age - added to library more than X days ago, release year
• Quality & size - resolution (4K/1080/720/480/SD), file size in GB, runtime
• Ratings - audience rating, critic rating, content rating (unrated items never match rating thresholds)
• Metadata - genre, cast member, director, writer, producer, studio/network, country, collection, label, edition

The Preview matches button in the editor evaluates the profile right now - including unsaved changes - and lists exactly what would be deleted, with the reasons each title matched and the total space involved.

How Deletion Works

Deletion is tiered so files are removed cleanly and don't come back:

1. Radarr / Sonarr first - if the item is managed there, it's deleted with its files, optionally adding an import exclusion so the *arr never re-grabs it (the Block re-download toggle).
2. Plex fallback - otherwise Diskovarr uses Plex's own delete API, which requires Allow media deletion in your Plex server's library settings. If Plex refuses, the item is marked failed with a clear explanation.
3. Riven / DUMB cleanup - when Riven is configured, the item is also removed from Riven, and any old Diskovarr requests for the title are purged so DUMB's request polling can't immediately re-add it. Titles on monitored Auto Request lists are flagged so they're never re-requested either.
4. Trash handling - after a deletion run, the affected library sections are refreshed and Plex's trash is emptied automatically, so deleted items don't linger as "unavailable" entries.

Activity

The Activity section is the audit trail for deletion automation:

• Pending Review - select items matched by review-mode profiles and delete or dismiss them in batches; each entry shows why it matched, its size, and play stats.
• Dry-Run Matches - what dry-run and automatic profiles currently match (automatic profiles delete these once the grace period elapses).
• Deletion History - everything deleted, failed, or dismissed, with the method used (Radarr, Sonarr, or Plex) and space freed.

Admin Panel - Notifications

Diskovarr can notify users and admins through multiple channels: the in-app bell, Discord (shared channel webhook and/or personal bot DMs), Pushover push notifications, and eight additional agents - Webhook, Slack, Gotify, ntfy, Telegram, Pushbullet, Email, and WebPush. All can be active simultaneously with independent settings and per-type toggles. Notifications include clickable hyperlinks that open the relevant item in Diskovarr. This page walks through setting up each one from scratch.

Broadcast Message

Type a message in the editor and click Notify All Users. The message is delivered simultaneously to the in-app bell for all users, plus Discord and Pushover if configured. Broadcast bell notifications open a full-text modal when clicked rather than navigating away.

Font Styles

The broadcast editor is a rich-text field with a formatting toolbar. Each button toggles a style on the current selection and highlights while that style is active, so you can see at a glance what is applied; pressing it again removes the style. Keyboard shortcuts work too.

• Bold (Ctrl+B)
• Italic (Ctrl+I)
• Underline (Ctrl+U)
• Strikethrough (Ctrl+Shift+S)
• Code (Ctrl+E) - monospaced inline code
• Highlight (Ctrl+Shift+H) - emphasizes text with the app accent color

On submit, the formatting is converted to Discord-flavored markdown so bold, italic, underline, strikethrough, and code render natively in Discord webhooks and bot DMs, and the styled text is shown in the in-app notification bell and modal.

Notification Types

All notification services share the same 10 event types. Each service has its own independent set of checkboxes - you can enable "Request approved" on Discord but not Pushover, for example. The recipient column shows who receives each type:

Discord - Webhook Setup

A webhook posts notification embeds to a single Discord channel. It's the simplest way to get shared visibility - everyone in that channel sees new requests, approvals, and alerts. No bot account needed.

Step 1 - Create the webhook in Discord

Step 2 - Enter the URL in Diskovarr

Paste the webhook URL into the Webhook URL field in Admin → Notifications → Discord Webhook. Toggle the enable switch on, choose your notification types, then click Save. Click Test to verify a test embed arrives in the channel.

Webhook Settings Reference

Discord - Bot Setup

A bot sends personal DMs to individual users. Each user receives only notifications relevant to them (their own requests, their own issues) rather than a shared channel flood. Both webhook and bot can be active at the same time with independent notification type selections.

Step 1 - Create a Discord application and bot

Step 2 - Enter the token in Diskovarr

Paste the bot token into Bot Token in Admin → Notifications → Discord Bot. Enable the toggle, configure your notification types, and click Save. Click Test - if your own Discord User ID is set in your My Settings, you should receive a test DM from the bot.

Step 3 - Create a non-expiring invite link (recommended)

Users need to be in your Discord server to receive DMs. Create a permanent invite: right-click your server → Invite People → click Edit invite link → set expiry to Never → copy the link. Paste it into the Discord Server Invite Link field in Diskovarr. This shows a "Join Server" button on each user's My Settings page.

Step 4 - Users configure their Discord User ID

Each user who wants bot DMs must enter their own Discord User ID in My Settings → Discord. To find a user ID:

1. In Discord, go to User Settings → Advanced → enable Developer Mode
2. Right-click any user's name → Copy User ID (a numeric string like 123456789012345678)
3. Paste that into the Discord User ID field in Diskovarr My Settings → Save

Bot Settings Reference

Pushover Setup

Pushover delivers push notifications to iOS and Android phones. The Pushover app costs a one-time $5 per platform (free 30-day trial). Once set up, it's highly reliable and works even when Discord DMs are blocked.

Step 1 - Create a Pushover account and install the app

Step 2 - Enter keys in Diskovarr (Admin)

In Admin → Notifications → Pushover:

• Application API Token - paste the token from the application you just created
• User or Group Key - paste your personal 30-character user key from the pushover.net dashboard. This is the admin's own key - it receives admin-type notifications (new request, new issue, etc.).

Choose a notification sound, configure your notification types, click Save, then click Test. Your phone should buzz within a few seconds.

Step 3 - Users add their own Pushover key

Each user who wants Pushover notifications must enter their own Pushover User Key in My Settings → Pushover. They follow the same signup process (pushover.net account + app install), then copy their user key and paste it in Diskovarr. They do not need to create a separate application - they all share the same application token you created as admin.

Pushover Settings Reference

Pushover Groups (for multi-admin setups)

If you have multiple admins who all need to receive admin-type notifications (new request, new issue), create a Pushover Group: on pushover.net → Your Groups → Create a Group. Add each admin's user key to the group. Paste the group key into Diskovarr's User or Group Key field. All group members receive the notification simultaneously.

Webhook

Send notifications to any HTTP endpoint as JSON. Supports customizable JSON templates, custom headers, and variable substitution. Works with tools like n8n, Make, Home Assistant, and custom scripts.

Configuration

Slack

Send notification messages to a Slack channel using an Incoming Webhook. Uses Slack's Block Kit for formatted messages with emoji icons, description text, and clickable links.

Step 1 - Create a Slack Incoming Webhook

Step 2 - Enter in Diskovarr

Paste the webhook URL into Admin → Notifications → Slack. Enable the toggle, select notification types, and click Save. Click Test to verify a message appears in your Slack channel.

Gotify

Send notifications to a self-hosted Gotify server. Gotify delivers push notifications to your phone and desktop with minimal setup.

Configuration

Messages are sent in Markdown format with a clickable link to the relevant Diskovarr page.

ntfy

Send notifications via ntfy - a simple pub-sub notification service. Use the free public server (ntfy.sh) or self-host your own instance.

Configuration

Messages include a clickable link that opens directly in Diskovarr.

Telegram

Send personal notifications through the Telegram Bot API. Each user can configure their own Telegram chat ID to receive DMs from the bot. Supports MarkdownV2 formatting, inline buttons, and poster images.

Step 1 - Create a Telegram Bot

Step 2 - Configure in Diskovarr

Each notification includes an inline View in Diskovarr button. Users can optionally configure their own Telegram chat ID in My Settings → Telegram to receive personal notifications (approved, denied, available).

Pushbullet

Send push notifications through Pushbullet. Messages are delivered to your linked devices (phone, desktop app, browser extension). Supports note-style messages and link-type messages with clickable URLs.

Configuration

Users can optionally set their own Pushbullet access token in My Settings → Pushbullet to receive personal notifications on their own devices.

Email

Send notification emails via SMTP. Supports custom sender name, HTML-formatted messages with poster images, and TLS/STARTTLS. Users with email addresses on file receive personal notifications.

Configuration

Emails are sent as formatted HTML with poster images. Each notification includes a clickable button to open the relevant page in Diskovarr.

WebPush

Send native browser push notifications using the Web Push API. Works even when the browser tab is closed. Users subscribe from their browser - no server-side email or phone setup required.

How It Works

WebPush uses VAPID keys (auto-generated on first use) to authenticate push messages. Users subscribe from My Settings → WebPush by clicking Subscribe and allowing browser notifications. Each subscription is stored and used to deliver push notifications to the user's browser.

Configuration

Admins receive WebPush notifications for admin-type events. Regular users receive personal notifications for events relevant to them (request approved, available, etc.). Users manage their subscription from My Settings → WebPush.

Page - Queue

The request queue shows all submitted requests. Regular users see their own requests ("My Requests"). Admins and elevated users see all requests ("Request Queue") with full approval controls.

Filter Tabs

All · Pending (with count) · Requested · Approved · Available · Denied. Click any tab to filter the table. The Available tab shows approved requests whose title has already arrived in the Plex library.

Search & Filters

Above the table is a filter row that narrows results server-side and combines with the active tab:

• Search - type a title to filter the queue by name. Input is debounced and matched on the server, so it works across every page of results, not just the rows currently shown.
• User (admin view) - a searchable dropdown of everyone who has submitted a request, to show one user's queue at a time.
• Date range - limit the queue to requests submitted between two dates.

Active filters persist as you page through results. A Clear control resets search, user, and date range back to the full queue.

Bulk Selection (Admin / Elevated)

Admin view adds a checkbox column. Tick individual rows, or use the header checkbox to select or deselect every request on the page. When at least one row is selected, a bulk action bar appears showing the selected count with Clear and Delete selected actions. Bulk delete asks for confirmation, then removes all chosen requests in a single call.

Sortable Columns

Click any column header to sort the queue by that column. Click again to reverse direction. An arrow indicator (↑ or ↓) shows the active sort. Sortable columns: Title, User, Type, Age, Status. Sort state is server-side - applies across all pages of results.

Table Columns

• Title - poster thumbnail (52 × 78 px), title, year, rating. If a request was denied, the denial note appears below in red.
• User - requester's avatar and name (admin view only)
• Type - Movie (gold) or TV (blue) badge
• Age - relative time since request was submitted (e.g. "3 hours ago")
• Status - Pending / Requested / Available / Denied badge
• Actions - varies by status and role (see below)

For TV requests, season chips appear below the title: S1 S2 S3… For shows with more than 9 seasons selected, the list truncates to an ellipsis followed by the last 8.

Request Actions (Admin / Elevated)

All actions update the row in place - no page scroll or reload.

Pagination

25 / 50 / 100 items per page. The per-page preference is saved to localStorage and restored on next visit. Previous/Next buttons plus page indicator.

Page - Issues

Users report playback problems with library content. Admins manage and resolve them.

Reporting an Issue

Any library item's detail modal has a Report Issue button. Clicking it opens the issue form:

• Description - text area for the problem details
• Scope (TV only) - Entire Series / Specific Season / Specific Episode
• Season number (if Specific Season selected)
• Season + Episode number (if Specific Episode selected)

User View ("My Issues")

Shows the user's own reports with scope label, status badge, and a Details button. Filter by All / Open / Resolved / Closed.

Admin View ("Issue Reports")

Shows all reports from all users. Additional columns: poster, reporter name. Additional actions: Resolve, Close, Delete.

Search & Filters

Both views provide the same status tabs (All / Open / Resolved / Closed) plus a server-side filter row:

• Search - filter reports by item title across all pages of results.
• User (admin view) - a searchable dropdown of everyone who has filed an issue, to focus on a single reporter.
• Date range - limit reports to those filed between two dates.

Filters combine with the active status tab and persist across pages. A Clear control resets them.

Bulk Selection (Admin)

Admin view adds a checkbox column with a select-all header checkbox. Selecting one or more reports reveals a bulk action bar with the selected count, Clear, and Delete selected. Bulk delete confirms first, then removes all chosen reports at once.

Status Badges

• Open (orange) - awaiting admin action
• Resolved (green) - admin has addressed the issue
• Closed (gray) - issue closed without resolution (e.g. user error, duplicate)

Details Modal

Shows full description, scope breakdown, reporter (admin view), status, and admin note. Contains a threaded comment section:

• Both user and admin can leave comments
• Admin comments send a notification to the reporter
• User comments send a notification to all admins
• Admin can delete any comment

Admin Actions

All actions update the row in place.

Page - Diskovarr Home

The home page shows personalized recommendations from your own Plex library for each user, based on their watch history.

Hero Controls

Recommendation Sections

Four carousels load in parallel after the page opens:

• Top Picks for You - highest-scored items across all types, labeled "Personalized"
• Movies - top-scored movies from your library's extended TMDB neighborhood
• TV Shows - top-scored TV series
• Anime - TV items tagged with the "Anime" genre

Sections show a shimmer skeleton while loading and are replaced with live cards on fetch.

In December, a Wrapped banner tile appears on the home page with "Wrapped {year}", "Your year in review is ready — take the tour", and an "Unwrap →" button. See Diskovarr Wrapped.

Most Popular on the Server

Below the personalized carousels, two server-wide rows show what everyone has been watching - Most Popular Movies on the Server and Most Popular TV Shows on the Server. Both carry a Last 90 Days badge.

• Ranked by server-wide watch statistics from Tautulli over the last 90 days
• Respect the Show Mature Content toggle - mature titles are hidden unless it's on
• Only appear when there's data to show
• Each card supports + Watchlist, opening the detail modal, and a "Not interested" dismissal, and marks titles you've already watched

Cards

Each card shows a poster with title, year, and rating below. On hover:

• + Watchlist - saves the item to the user's watchlist
• ✕ Dismiss - hides the item from all future recommendations for that user
• Clicking the poster opens the detail modal

Detail Modal

Clicking a poster opens the item detail modal, with an Overview tab (backdrop, ratings, recommendation reason tags, synopsis, trailer, and actions like Play on Plex, Cast to TV, Watchlist, and Report Issue) and a Cast & Crew tab. See Item Detail Modal for the full breakdown.

Recommendation Engine

The engine builds a scored list of items from your library for each user by:

• Fetching TMDB recommendations and similar titles for everything the user has watched
• Scoring each candidate using: TMDB similarity (40pts), shared director (30pts), shared actor (35pts), keyword overlap (25pts), same collection (30pts), shared studio (10pts), genre match (8pts/genre), same decade (8pts), high rating bonus
• Subtracting points for previously dismissed items
• Filtering out items already in the user's library

Caches are pre-warmed every 25 minutes per user in the background so the page loads instantly.

Page - Diskovarr Requests

Shows personalized picks from TMDB that are not yet in your library. Users can request titles directly from this page. Requires TMDB API key to be configured in Admin → Connections → TMDB.

Hero Controls

Sections

• Top Picks for You - highest-scored non-library items, "Outside Your Library" badge
• Movies - top-scored movie candidates
• TV Shows - top-scored TV candidates
• Anime - anime candidates (sourced from Japanese-language TMDB discover)
• Trending Movies - TMDB weekly trending movies not in your library
• Trending TV Shows - TMDB weekly trending TV not in your library
• Browse by Genre - grid of 18 genre tiles with gradient backgrounds and emoji icons; clicking a genre navigates to Search filtered to that genre
• Upcoming Movies - movies releasing in the future, "Coming Soon" badge; shown when 8+ items are available
• Upcoming TV Shows - TV shows releasing in the future, "Coming Soon" badge; shown when 8+ items are available

Genre Browse

A genre browse section displays clickable genre cards (Action, Comedy, Drama, Horror, etc.) with gradient backgrounds and emoji icons. Clicking a genre card navigates to the Search page filtered to that genre, showing all TMDB results for that genre not in your library.

Coming Soon

Coming Soon sections show upcoming movies and TV shows with release dates in the future. Each card displays a "Coming Soon" badge (or "Requested" if already requested). These sections help users discover and request content before it's released.

Request Badges & Buttons

TMDB Pipeline

Candidate discovery is optimized to minimize API calls:

• A shared candidate pool is pre-fetched once per unique region+language+mature combination across all users (8-hour TTL)
• Full item details (genres, cast, keywords, ratings, trailers) are cached in the database permanently once fetched
• Per-user scoring runs every 28 minutes in the background against the shared candidates
• Region and language preferences (set in My Settings) are applied to TMDB discover queries at fetch time

Page - Filter

Browse your own Plex library with a rich set of filters and sorts. Every item shown is already in your library. Filters update results in real time.

Common Filters

The most-used filters sit inline as chips at the top of the control bar:

More Filters

A More filters drill-down menu (with back navigation) holds the rest:

Advanced Facets

People and catalog facets are also under More filters. High-cardinality facets (Director, Actor, Writer, Producer) are search-as-you-type; the rest load their full value list when opened:

• Director, Actor, Writer, Producer - searchable multi-select
• Country, Collection, Studio, Edition, Label - multi-select

Sorting

16 sort options are available: Highest Rated (default), Critic Rating, Content Rating, Recently Added, Last Episode Added, Release Date (Newest), Release Date (Oldest), Newest First, Oldest First, Longest Duration, Shortest Duration, Unwatched First, Your Rating, Recently Viewed, Most Played, and A–Z.

Applied Filters & Results

Every active filter appears as a removable chip below the control bar, each with its own ✕, plus a Clear All button. Results load as a card grid with a Load More button. Clicking a card opens the item detail modal with Play on Plex and Cast to TV. Items you've already watched show a small green checkmark badge.

Page - Search

Search across both your Plex library and TMDB simultaneously. Supports text search, genre-based browsing, and advanced filtering.

Nav Bar Search

The search input is always visible in the navigation bar on desktop. On mobile it collapses to a magnifying glass icon - tapping it expands a full-width overlay input.

As you type, TMDB autocomplete suggestions appear in a dropdown showing title, year, and type (Movie/TV). Select a suggestion or press Enter to go to the full search results page.

Search Results Page (/search?q=…)

• Results from your Plex library appear first with an "In Library" indicator
• Library items you've already watched show a small green checkmark badge on the poster
• TMDB results not in your library appear below with a Request or Coming Soon button
• Library items open the full detail modal including Cast to TV and Report Issue
• Non-library items open the request dialog
• Load More button fetches additional TMDB results
• Back button returns to the previous page or falls back to the configured landing page

Filter Section

When viewing search results or genre-browse results, a collapsible filter section lets you narrow down what's shown:

More Like This

When viewing search results or item details, a More Like This section shows similar titles based on TMDB recommendations and local metadata overlap. It scores candidates by shared directors, cast, genres, keywords, collections, and language - then re-ranks them so the most relevant results appear first. The Hide in Library toggle also applies to this section, so you can see only items you don't already have.

Item Detail Modal

Clicking any poster - on Home, Requests, Filter, Search, Watchlist, or Blacklist - opens the detail modal. It has two tabs: Overview and Cast & Crew.

Overview Tab

• Backdrop hero image and poster thumbnail
• Title, year, content rating, and audience/critic ratings
• Recommendation reason tags (e.g. "Similar to Breaking Bad", "Director match")
• Genre chips and synopsis
• Embedded YouTube trailer when available
• Action row: Play on Plex, Cast to TV (library items - see Cast to TV), + Watchlist / ★ In Watchlist, Monitor (quick-create a content monitor from this title), and Report Issue

Cast & Crew Tab

A visual, clickable browse of everyone involved in the title, sourced from TMDB. Loads on demand the first time you open the tab.

People without a TMDB photo fall back to a silhouette placeholder. If no cast/crew data is available, the tab shows "No cast or crew information available."

Cast to TV

Cast to TV sends playback of any library item to a Plex player (smart TV, streaming stick, Roku, Apple TV, etc.) directly from the detail modal. As of v2.5.3, it works from anywhere — for the server admin at home and for remote users — because the playback command is delivered from your browser, which shares Wi-Fi with your TV, rather than from the server.

How It Works

When you click the cast button, Diskovarr performs three steps:

1. Prepare (server-side) — Diskovarr calls your Plex server to create a PlayQueue for the chosen title, then looks up your players via plex.tv/api/v2/resources using your own Plex account token. It returns the player's connection URIs and ready-made playMedia parameters.
2. Deliver (browser-side) — your browser sends the playMedia command directly to the player over your local network. This is what makes remote casting work: the server can never reach a TV inside another household's network, but your browser can because it's on the same Wi-Fi as your TV.
3. Stream — the player pulls the stream from the Plex server via its public *.plex.direct address (standard Plex remote access, not Plex Pass relay).

Browser Support

Requirements

Using the Cast Picker

1. Open any library item's detail modal (click a poster on the home page or filter page)
2. Click the Cast to TV button in the action row (button initially shows … while loading devices)
3. A dropdown expands showing all Plex player devices registered to your account, displayed as Name · Product. If the list is empty, see Troubleshooting below.
4. Click the device you want to cast to. The button shows "Casting…" while the command is sent.
5. Playback starts on your TV. A confirmation toast appears: "Playing on {name}".

Troubleshooting

Cast picker is empty — no devices listed

Devices appear but cast fails or nothing happens on the TV

Cast works for the server admin but not for friends

Page - User Profile

Every user has a public profile with a bio, favorite genres and titles, and their full review history. Your own profile is also where your Watchlist and Blacklist now live.

What's on a Profile

Editing Your Profile

On your own profile, click Edit Profile to open the editor. You can change your bio (with a live character count), pick up to 5 favorite genres from a searchable dropdown, and add up to 5 favorite titles via search (each shown with a poster thumbnail). Save to apply - changes appear on your profile immediately. Only the profile owner can edit.

Watchlist & Blacklist Tabs

Your profile has three tabs: Profile, Watchlist, and Blacklist. The Watchlist and Blacklist tabs are visible only to you - other users viewing your profile see just the Profile tab.

Page - Reviews

A social, Letterboxd-style feed of community reviews. Users rate and review what they've watched, react to and comment on each other's reviews, follow reviewers, and share reviews publicly.

Writing a Review

Reviews are created from the Watch History page - you can only review something you've actually watched in Plex. Click Write Review (or Edit on an existing one) next to any watched item to open the review modal.

After posting, a success panel offers to Share Review, Copy Link, or Download Share Image. You can delete your own review from the same modal.

The Reviews Feed

The Reviews page is an infinitely-scrolling feed of reviews from everyone on your server. Each post shows the reviewer's avatar and name, a timestamp, the media poster/title/year, the star rating, and the review text.

Sharing Reviews

Every review can be shared from the Share button (on a posted review or in the feed), which opens a share sheet. Each review has a public link (/review/:id) that opens without logging in, and an auto-generated share image rendered server-side - a landscape card (/og/review/:id.png) for link previews and downloads, plus a square card (/og/review/:id/square.png) for Instagram and mobile share sheets.

The Share Sheet

Page - Watch History

A chronological table of everything you've watched in Plex - movies, episodes, and viewing sessions - with completion progress and a one-click path to writing a review.

The History Table

TV Episode Grouping

Episodes of the same series watched in one session collapse into a single parent row showing the series title, an episode-count badge, an "X/Y watched" progress summary, and total time spent. Expand it to see and individually review each episode.

Filters, Sorting & Pagination

Diskovarr Wrapped

A personal, Spotify-Wrapped-style year-in-review for every user. One stat per slide, told in story style, with each slide individually shareable as a card image. Available year-round from your profile and pushed to the home page every December.

Accessing Wrapped

• ✦ Wrapped button on your own profile page — available year-round
• December banner tile on the home page — "Wrapped {year}" / "Your year in review is ready — take the tour" / "Unwrap →"
• Direct URL — /wrapped (latest year) or /wrapped/2025 (specific year)
• Year-picker pills for browsing past years' Wrapped archives

The Story

Wrapped presents your year as a slide-by-slide story. Use keyboard arrows, click, or swipe to navigate. Slides with no data are skipped automatically:

1. Your year in numbers — total hours watched
2. Your top movie — most-watched film of the year
3. Your top show — most-watched series
4. Blast from the past — the oldest title you watched
5. Your genres — genre breakdown of your viewing
6. When you watched — month-by-month chart, peak weekday, and peak hour
7. Binges & streaks — longest viewing sessions and consecutive-day streaks
8. Where you rank — your Top X% percentile among server users
9. Your taste age — average release year of what you watched
10. Show buddy — the show you watched most with others on the server
11. Your Diskovarr personality — one of 12 archetypes (Adventurer, Voyager, Thrill Seeker, Detective, Comedian, Romantic, Scholar, Dreamer, Daredevil, Maestro, Insider, Omnivore) with trait chips (Night Owl, Early Bird, Marathoner, Binger, Completionist, Movie Buff, Series Devotee, Time Traveler)
12. The critic — your reviews for the year (shown only if you wrote any)
13. Your year on Diskovarr — reviews written, requests made, reactions given
14. Server leaderboard — everyone's hours and plays, shown with real usernames
15. That's a wrap — finale slide with a playlist button and "See you next December!"

Sharing

Every slide has a Share button. Clicking it generates a server-rendered share-card image (wide Open Graph variant and square variant) that you can post to any platform: Facebook, X, Threads, Reddit, Bluesky, Mastodon, LinkedIn, Telegram, WhatsApp, Discord (copy link), Email, native share, or download.

The share text reads: "My {year} Diskovarr Wrapped — {statLine}".

Wrapped Playlist

One click on the finale slide builds (or rebuilds) a "Diskovarr Wrapped {year}" playlist in your own Plex account, containing your top 10 movies and top 5 shows from the year.

Privacy & Visibility

Each user sees only their own Wrapped data. The server leaderboard slide shows everyone's hours and plays by real username — this is the only cross-user visibility in Wrapped.

Data & Accuracy

Admin Tools

Admins have two controls on the Wrapped page:

• Recompute this year — recalculates all users' Wrapped data for the selected year from current watch history
• Backfill full Tautulli history — pages through all of Tautulli's historical watch data. Recommended to run once on installs that are newer than the year being wrapped, so Wrapped has complete data

My Settings

Each user's personal preferences: region and language for TMDB discovery, landing page, and notification preferences. Accessible from the user menu (avatar button).

Content Preferences

Connected Accounts

Connect external accounts to sync your ratings outward. Today this is TMDB (The Movie Database). Only your star rating is sent when you push a review - review text and watch dates stay local. See Ratings & Sync for how this fits with the automatic Plex rating sync.

Once connected, a Push rating to TMDB checkbox appears in the review modal. See Reviews.

Notification Preferences

Checkboxes for each notification type. Standard users see: Request Approved, Declined, Available, Issue Resolved, Issue Comment, Auto-Requested from Watchlist, and Monitor match (see Content Monitors). Elevated users also see: New Request Pending, Auto-Approved, Processing Failed, New Issue Reported.

Monitors

The Monitors tab is where you create and manage content monitors - saved sets of criteria (genre, cast, director, studio, and more) that notify you when matching content is added to Plex or becomes available to request.

Discord

Pushover

Telegram

Pushbullet

Email

WebPush

Content Monitors

Monitors let each user describe the content they care about and get notified the moment a match becomes available - either newly added to Plex or newly requestable. Set them up under My Settings → Monitors, or create one in a click from any title's detail modal.

Creating a Monitor

From the Monitors tab, click + Create Monitor to open the editor:

Criteria Types

Each criterion is a type plus a value. Most values offer search-as-you-type suggestions; Media Type is a simple dropdown.

• Media Type - Movie or TV Series
• Genre
• Cast Member, Director, Writer, Producer
• Studio, Network, Production Company
• Collection, Keyword
• Country, Language

Values are matched case-insensitively. For example, a monitor with Genre: Horror + Cast Member: Toni Collette in Match ALL mode notifies you only about horror titles featuring that actor.

Quick Monitors from a Title

Every item detail modal has a Monitor button. It opens a dropdown of one-click monitors built from that title - monitor the exact movie/series, or everything matching its genre, studio/network, collection, director, or a cast member. Single-criterion picks are created instantly; you can also open the full editor pre-filled to refine them.

How Notifications Work

Diskovarr evaluates monitors automatically as content moves through the system:

• Added to Plex - when library sync or the real-time Plex connection picks up a new item, it's checked against monitors with "Notify when added to Plex" enabled.
• Available to request - when requestable content surfaces through TMDB-powered discovery, it's checked against monitors with "Notify when available to request" enabled.

A match raises a Monitor match notification (e.g. "Hereditary" matches "Horror With Favorite Actors") that explains which criteria matched. It's delivered to your in-app bell and any channels you've enabled, and respects the Monitor match toggle in notification preferences. Multiple matches at once are bundled to avoid spam.

Managing Monitors

The Monitors list shows each monitor with its match mode, a criteria preview, and a created date. Use the inline toggle to enable/disable, Edit to change it, or Delete to remove it.

Page - Watchlist

A personal save list. Add items from any card or detail modal; review and remove them from your profile.

Adding Items

The + Watchlist button appears on card hover overlays and in detail modals across all pages (home, explore, filter, search). Once added, the button changes to ★ In Watchlist.

Watchlist Page

Shows a grid of saved items with poster, title, year, and rating. Clicking a poster opens the same detail modal. The ✕ Remove button on each card removes it with a fade animation.

Auto-Request from Watchlist

If enabled in Admin → Users → Auto-Request Watchlist, adding an item to the watchlist automatically submits a request for it. This works per-media-type (movies and TV can be configured separately). Per-user overrides are available in the per-user settings page.

Page - Blacklist

A single place to review and manage every item you have marked "Not Interested". Whenever you dismiss a recommendation, it lands here so you can see what is hidden and restore anything you dismissed by mistake.

What Appears Here

The blacklist is a unified view of all your dismissals, gathered from two places:

• Library - items hidden from Diskovarr Home recommendations (dismissed from a card or detail modal on the Home page).
• Diskovarr Requests - non-library TMDB suggestions dismissed from the Requests page.

Each card carries a small source badge so you can tell which list an item came from. Dismissed items are enriched with poster, title, and year (library items from the Plex library, Requests items from TMDB).

Managing Items

Click any poster to open the standard detail modal. Each card has a ✕ Remove button that lifts the dismissal: library items return to your Home recommendations, and Requests items become eligible to surface again on the Requests page. Removing an item refreshes its recommendation cache so the change takes effect on your next visit to that page.

Integration - Plex Real-Time Sync

Diskovarr keeps a persistent Server-Sent Events (SSE) stream open to your Plex server, the same notification endpoint Tautulli uses, to detect newly added library content in real time. No Plex Pass required. No setup needed.

How It Works

On startup, Diskovarr connects to the SSE stream at /:/eventsource/notifications on your Plex server. Plex pushes timeline events over this connection whenever items are added or updated. Diskovarr only acts on fully analyzed items (timeline state 5) so a title is not announced before Plex has finished processing it. When it sees a new library item, it:

• Invalidates the library cache
• Checks all pending requests against the new content
• Sends "Request Available" notifications to requesters whose titles just arrived

This happens within seconds of Plex finishing the scan, with no polling interval and no Plex Pass subscription needed.

Verifying It's Connected

Check your Diskovarr service logs for:

[plex sse] Connected to Plex notification stream

If the stream drops (e.g. Plex restarts), Diskovarr automatically reconnects.

Integration - Agregarr Setup

Connect Agregarr to Diskovarr so collection-based auto-requests route through Diskovarr's queue instead of directly to Overseerr.

Step 1 - Get the Overseerr Compat Key

In Admin → General → Overseerr Compat API, enable the toggle and copy the Compat Key using the copy icon.

Step 2 - Configure Agregarr

In the Agregarr web UI, add an Overseerr source:

• Overseerr URL - your Diskovarr URL (e.g. https://diskovarr.example.com)
• API Key - the Compat Key from Step 1

What Happens

When Agregarr syncs a collection:

• Agregarr sends requests to Diskovarr's /api/v1/ shim (Overseerr-compatible)
• Diskovarr creates service user accounts per collection type (e.g. "TmdbAgregarr")
• Requests appear in the Diskovarr queue with a bot badge
• If auto-approve is enabled, they route to your configured service immediately
• If rate limits are hit, Diskovarr returns a silent 201 so Agregarr's sync continues uninterrupted

After Updating the Key

If you regenerate the Overseerr Compat Key (Admin → General), update it in Agregarr's source configuration and restart the Agregarr container. Note this also invalidates the key for any other connected apps (DUMB, Homarr) - update those too.

Ratings & Sync

When a user rates something in a review, Diskovarr can push that star rating outward to Plex and TMDB. Two separate integrations handle this - one automatic, one opt-in.

Plex Rating Sync

Automatic. Saving a review with a star rating writes that rating to Plex for the same item, attributed to the reviewing user via their own Plex token. The half-star scale (0.5–5) is converted to Plex's 0–10 scale. Deleting a review clears the rating in Plex. No setup is required - it happens server-side as part of saving the review.

TMDB Rating Sync

Opt-in. Users first connect their TMDB account under My Settings → Connected Accounts. Once connected, the review modal shows a Push rating to TMDB checkbox. Only the star rating is sent - review text and watch dates stay local to Diskovarr.

API Reference

All public API endpoints. Authenticate with a session cookie (browser) or the X-Api-Key: your-key header (external tools). Generate your API key in Admin → General.

Authentication

Recommendations & Discovery

Library & Search

Watchlist

Blacklist

Requests

Issues

Notifications & Settings

Plex Integration

Watch History

Content Monitors

Reviews

Reviews - Social

Review Sharing (Public)

Unauthenticated endpoints that back shareable review links and social previews.

Profiles & Follows

Connected Accounts (TMDB)

Admin - Library Sync

Admin-only endpoints (require an authenticated admin session) for choosing and syncing Plex libraries. See Admin → General.

Wrapped

Overseerr Compatibility Shim

The /api/v1/ endpoint exposes an Overseerr-compatible API for external tools (Agregarr, DUMB/Riven, Homarr). Authenticate with the Overseerr Compat Key from Admin → General using the header: X-Api-Key: your-compat-key. The shim maps Diskovarr's data model to Overseerr API format automatically.