fix(api): correct watchlist POST request schema in OpenAPI spec

[Arul1998]

Description

The OpenAPI spec for POST /api/v1/watchlist used the Watchlist response schema as its request body. That schema is missing the required mediaType field and carries response-only fields (id, type, media, createdAt, updatedAt, requestedBy), so it does not describe what the endpoint actually accepts.

As reported in #3298, this causes SDK-generated clients to send requests the backend rejects with:

Invalid option: expected one of "movie"|"tv" (path: mediaType)

This change adds a dedicated WatchlistRequest schema that mirrors the watchlistCreate zod validator (server/interfaces/api/watchlistCreate.ts):

• required: tmdbId (number), mediaType (movie | tv)
• optional: ratingKey (string), title (string)

It also corrects the documented success response from 200 → 201, matching the handler in server/routes/watchlist.ts, which returns res.status(201).

No runtime code is changed this is a spec/documentation correction only.

• Fixes Outdated Openapi Yaml file ? #3298

AI assistance disclosure: This change was prepared with the assistance of an AI coding tool (Claude). I reviewed the root cause against the backend watchlistCreate validator and verified the corrected schema myself.

How Has This Been Tested?

• Compared the spec against the backend validator (watchlistCreate zod schema) and the POST /watchlist handler to confirm the required fields (tmdbId, mediaType) and the 201 response code match the real API.
• Validated that seerr-api.yml still parses as valid YAML after the change.
• No behavioural/runtime code was touched, so no functional regression is expected.

Screenshots / Logs (if applicable)

N/A — OpenAPI spec change only.

Checklist:

• I have read and followed the contribution guidelines.
• Disclosed any use of AI (see our policy)
• I have updated the documentation accordingly.
• All new and existing tests passed.
• Successful build pnpm build
• Translation keys pnpm i18n:extract (N/A — no translation strings changed)
• Database migration (if required) (N/A)

Summary by CodeRabbit

• API Improvements
  • Updated watchlist creation to accept the required media ID and media type.
  • Added optional rating and title fields when creating a watchlist item.
  • Watchlist creation now returns a 201 Created response to clearly indicate successful creation.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: ec3520f4-8a27-4ddb-908c-839fe10e091a

📥 Commits

Reviewing files that changed from the base of the PR and between 059008c and 0bbd263.

📒 Files selected for processing (1)

• seerr-api.yml

Included review availability: Your plan provides up to 10 included reviews per hour; 9 remain after this review.

---

📝 Walkthrough

Walkthrough

The OpenAPI definition adds a WatchlistRequest schema for watchlist creation. The POST /watchlist endpoint now uses this schema and documents HTTP 201 for successful creation.

Changes

Watchlist API contract

Layer / File(s)	Summary
Watchlist creation request contract seerr-api.yml	Adds required tmdbId and mediaType fields, restricts mediaType to movie or tv, and allows optional ratingKey and title. Updates POST /watchlist to use WatchlistRequest and return 201.

Estimated code review effort: 2 (Simple) | ~10 minutes

Merge Risk: ⚪ Minimal · up to 0bbd2

This localized documentation change corrects the watchlist request schema and documented success status without changing runtime behavior; no actionable merge-blocking risk remains after normal checks and review.

Suggested reviewers: 0xsysr3ll, fallenbagel

Poem

I’m a rabbit with a watchlist bright,
movie or tv now fits just right.
IDs are required, fields are neat,
Creation returns 201—a treat!
Hop through the schema, swift and light.

🚥 Pre-merge checks | ✅ 4

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly identifies the correction to the watchlist POST request schema, which is the main change.
Linked Issues check	✅ Passed	The changes address issue #3298 by documenting required tmdbId and mediaType fields for POST /watchlist.
Out of Scope Changes check	✅ Passed	All changes update the OpenAPI definition for the watchlist endpoint and remain within issue #3298 scope.

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}