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 plugin settings (userConfig). A SessionStart hook writes them to ~/.config/lab-overseerr/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/search.mjs "Dune" --type movie
node scripts/request.mjs "Dune" --type movie --mediaId 438631

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

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

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

Parameters:

• --type movie|tv: Media type (required)
• --mediaId N: Confirmed TMDB media id from search results (required unless --yes is used)
• --yes: Explicitly accept the first search result after user confirmation
• --seasons all|1,2,3: Season selection for TV (default: all)
• --is4k: Request 4K version
• --serverId N / --profileId N / --rootFolder PATH / --languageProfileId N: override the Sonarr/Radarr server, quality profile, root folder, or language profile
• --userId N: request on behalf of another Overseerr user
• --tvdbId N: pin the TVDB id for a TV request

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 all|approved|available|pending|processing|unavailable|failed|deleted|completed: Filter by status (default: all)
• --limit N: Maximum results
• --skip N: Offset for pagination
• --sort added|modified: Sort order
• --requestedBy USER_ID: Only requests made by a given user

Manage Requests (approve / decline / delete)

node scripts/approve-request.mjs <requestId>   # approve a pending request
node scripts/decline-request.mjs <requestId>   # decline a pending request
node scripts/delete-request.mjs <requestId>    # DESTRUCTIVE: delete the request record

Parameters:

• <requestId>: numeric request id (from requests.mjs / request-by-id.mjs)

delete-request.mjs is destructive — it removes the request record entirely. Always confirm with the user (and which request id) before running it. approve and decline are reversible state changes but still mutate; confirm intent first.

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 with the confirmed --mediaId (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
• references/overseerr-api.yml — raw OpenAPI source snapshot

---