Request Media On Overseerr

---
name: request-media-on-overseerr
description: "Request a movie or TV show using the user's Overseerr instance. Overseerr forwards the request to Sonarr/Radarr."
category: "Community"
author: community
version: "1.0.0"
icon: puzzle
---

# 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=<urlencoded title>

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": <tmdbId>
}

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

TV JSON (specific seasons):
{
  "mediaType": "tv",
  "mediaId": <tmdbId>,
  "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