overseerr

Overseerr Media Request Skill

Request movies and TV shows via the Overseerr API. Search, request, and monitor media request status.

Purpose

This skill enables media request management through Overseerr:

• Search for movies and TV shows
• Request new media (movies, TV series, specific seasons)
• Check request status (pending, processing, available)
• Monitor request progress
• Support for 4K requests

Note: This skill targets Overseerr (the stable project), not the newer "Seerr" rewrite that is in beta.

Setup

Credentials are configured in the arrs plugin settings (userConfig). A SessionStart hook writes them to ~/.config/lab-arrs/config.env, which the scripts load automatically — no manual file editing. Variables used:

OVERSEERR_URL="http://localhost:5055"
OVERSEERR_API_KEY="your-api-key"

• OVERSEERR_URL: Your Overseerr server URL (no trailing slash)
• OVERSEERR_API_KEY: API key from Overseerr (Settings → General → API Key)

Get your API key:

1. Open Overseerr web UI
2. Go to Settings → General
3. Scroll to "API Key" section
4. Copy your API key

Commands

All commands use Node.js scripts and return JSON output.

Search

Find movies or TV shows:

node scripts/search.mjs "the matrix"
node scripts/search.mjs "bluey" --type tv
node scripts/search.mjs "dune" --limit 5

Parameters:

• --type movie|tv: Filter by media type
• --limit N: Maximum results to return

Request Media

Request movies or TV shows:

# Request a movie
node scripts/request.mjs "Dune" --type movie

# Request TV show (all seasons by default)
node scripts/request.mjs "Bluey" --type tv --seasons all

# Request specific seasons
node scripts/request.mjs "Severance" --type tv --seasons 1,2

# Request in 4K
node scripts/request.mjs "Oppenheimer" --type movie --is4k

Parameters:

• --type movie|tv: Media type (required)
• --seasons all|1,2,3: Season selection for TV (default: all)
• --is4k: Request 4K version

Check Request Status

View pending and processing requests:

node scripts/requests.mjs --filter pending
node scripts/requests.mjs --filter processing --limit 20
node scripts/request-by-id.mjs 123

Parameters:

• --filter pending|processing|available|all: Filter by status
• --limit N: Maximum results

Get Enriched Request Details

View detailed request information with media metadata:

node scripts/requests-enriched.mjs --filter pending

Monitor Requests (Polling)

Continuously watch request status:

node scripts/monitor.mjs --interval 30 --filter pending

Parameters:

• --interval N: Polling interval in seconds (default: 30)
• --filter: Status filter

Workflow

When the user asks about media requests:

1. "Request Dune" → Search for "Dune", confirm with user, then request
2. "Add Bluey to my library" → Search, request as TV with all seasons
3. "What's pending?" → Run requests.mjs --filter pending
4. "Is my Oppenheimer request done?" → Search requests or use request ID
5. "Request seasons 1-3 of Severance" → Request with --seasons 1,2,3

Request Flow

1. Search for the media
2. Present results with TMDB/TVDB links
3. User confirms selection
4. Submit request (optionally with 4K flag)
5. Check status periodically or wait for notification

Request Statuses

• pending: Awaiting approval
• processing: Approved, being fetched by Sonarr/Radarr
• available: Downloaded and ready in Plex

Notes

• Requires network access to your Overseerr server
• Uses X-Api-Key header authentication
• Overseerr coordinates with Sonarr/Radarr for actual downloads
• 4K requests require 4K quality profiles configured in Overseerr
• Webhooks can push status updates; polling is the baseline approach

Multiple Servers

To use multiple Overseerr instances, override environment variables:

# Use default server (from plugin settings)
node scripts/search.mjs "query"

# Use alternative server (override with environment variables)
OVERSEERR_URL="http://server2:5055" OVERSEERR_API_KEY="key2" node scripts/search.mjs "query"

Reference

• Overseerr API Documentation
• Overseerr GitHub

Local References

• references/quick-reference.md — curl examples for all common operations
• references/troubleshooting.md — error diagnosis and common failure modes
• references/api-endpoints.md — full API endpoint catalog

---