AgentSkillsCN

Overseerr Request Media

Overseerr请求媒体

SKILL.md

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:

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