Request media on Overseerr

Request movies or TV shows on Overseerr by title and optional season, checking availability before forwarding the request to Sonarr or Radarr.

Overseerr Request Media Skill

Purpose

Request a movie or TV show using the user's Overseerr instance. Overseerr forwards the request to Sonarr/Radarr.

Requirements

Environment variables:

• OVERSEERR_URL (example: https://overseerr.yourdomain.com)
• OVERSEERR_API_KEY

Authentication header:

• X-Api-Key: $OVERSEERR_API_KEY

Overseerr can detect if media is already available or already requested based on your configured Plex + Sonarr/Radarr connections.

What this skill handles

User examples:

• "Request Interstellar"
• "Add Interstellar to overseerr"
• "Request Reacher season 2"
• "Request The Office seasons 2-4"

Workflow (ALWAYS FOLLOW)

1) Parse the user's request

Extract:

• Title
• Optional type hint: movie or tv
• Optional season request:
  • "season 2"
  • "seasons 1-3"
  • "season 1 and 4"

2) Search Overseerr

GET: $OVERSEERR_URL/api/v1/search?query=

Example: curl -s -H "X-Api-Key: $OVERSEERR_API_KEY"
"$OVERSEERR_URL/api/v1/search?query=interstellar"

3) Clarify if the result is ambiguous (movie vs show with same name)

If the search results include BOTH:

• a movie match AND
• a tv match with the same (or extremely similar) title,

THEN ask the user to choose before requesting.

Show 2-4 options max, like:

• Movie: Title (Year)
• TV: Title (Year)

If the user provided an obvious hint like "movie", "show", "tv", "season 2", then pick the matching type automatically.

4) Pick the best match

Rules:

• Prefer exact title match
• Prefer the highest popularity match when multiple results exist
• Respect the user's type hint if provided (movie vs tv)

5) Check if it already exists (available or already requested)

Before creating a request:

• Inspect the selected result for availability/request status info returned by Overseerr (library/availability/request indicators).
• If it indicates the media is already available in the library:
  • Do NOT request it
  • Reply: "Already available ✅"
• If it indicates the media is already requested (pending/processing/approved/requested):
  • Do NOT request it again
  • Reply: "Already requested ✅"

If the API response does NOT clearly indicate status:

• Proceed with creating the request
• If the POST fails due to duplicate/existing request, reply "Already requested ✅"

6) Create the request

POST: $OVERSEERR_URL/api/v1/request

Movie JSON: { "mediaType": "movie", "mediaId": }

TV JSON (full series): { "mediaType": "tv", "mediaId": }

TV JSON (specific seasons): { "mediaType": "tv", "mediaId": , "seasons": [2,3] }

Examples:

Movie: curl -s -X POST
-H "X-Api-Key: $OVERSEERR_API_KEY"
-H "Content-Type: application/json"
"$OVERSEERR_URL/api/v1/request"
-d '{"mediaType":"movie","mediaId":157336}'

TV (full): curl -s -X POST
-H "X-Api-Key: $OVERSEERR_API_KEY"
-H "Content-Type: application/json"
"$OVERSEERR_URL/api/v1/request"
-d '{"mediaType":"tv","mediaId":71912}'

TV (season 2): curl -s -X POST
-H "X-Api-Key: $OVERSEERR_API_KEY"
-H "Content-Type: application/json"
"$OVERSEERR_URL/api/v1/request"
"$OVERSEERR_URL/api/v1/request"
-d '{"mediaType":"tv","mediaId":71912,"seasons":[2]}'

7) Respond cleanly

• Confirm what was requested
• If TV request was partial, list seasons
• If already requested/available, say so
• If no results, ask for alternate spelling or more context

Output style

Short confirmations:

• "✅ Requested: Interstellar (2014)"
• "✅ Requested: Reacher (Season 2)"
• "Already requested ✅"
• "Already available ✅"

Error handling

• If search returns 0 results:
  • Ask for alternate title or year
• If multiple equally good matches remain:
  • Ask the user to pick from 2-4 options