| name | overseerr |
| description | This skill should be used when the user wants to request movies or TV shows via Overseerr, monitor or manage media requests, or check request status. Triggers include: "request a movie", "request a TV show", "add to Overseerr", "check request status", "pending requests", "is my request done", "Overseerr status", "approve a request", "decline a request", "delete a request", or any mention of Overseerr media requesting. |
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). The plugin setup script writes them to ~/.config/lab-overseerr/config.json, which the scripts parse 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:
- Open Overseerr web UI
- Go to Settings → General
- Scroll to "API Key" section
- 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:
node scripts/search.mjs "Dune" --type movie
node scripts/request.mjs "Dune" --type movie --mediaId 438631
node scripts/search.mjs "Bluey" --type tv
node scripts/request.mjs "Bluey" --type tv --mediaId 82728 --seasons all
node scripts/request.mjs "Severance" --type tv --mediaId 95396 --seasons 1,2
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>
node scripts/decline-request.mjs <requestId>
node scripts/delete-request.mjs <requestId>
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)
monitor.mjs runs an infinite loop — it never exits on its own. Running it
directly in a foreground tool call will hang that turn indefinitely waiting
for output that never naturally completes. Background it with a timeout, or
prefer a single requests.mjs call polled manually instead:
timeout 120 node scripts/monitor.mjs --interval 30 --filter pending
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:
- "Request Dune" → Search for "Dune", confirm with user, then request
- "Add Bluey to my library" → Search, request as TV with all seasons
- "What's pending?" → Run
requests.mjs --filter pending
- "Is my Oppenheimer request done?" → Search requests or use request ID
- "Request seasons 1-3 of Severance" → Request with
--seasons 1,2,3
Request Flow
- Search for the media
- Present results with TMDB/TVDB links
- User confirms selection
- Submit request with the confirmed
--mediaId (optionally with 4K flag)
- 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:
node scripts/search.mjs "query"
OVERSEERR_URL="http://server2:5055" OVERSEERR_API_KEY="key2" node scripts/search.mjs "query"
Reference
Local References
references/quick-reference.md — curl examples for all common operationsreferences/troubleshooting.md — error diagnosis and common failure modesreferences/api-endpoints.md — full API endpoint catalogreferences/overseerr-api.yml — raw OpenAPI source snapshot
