feat: Add media removal request system with approval workflow, per-season support, and granular permissions

seerr-api.yml

@@ -1274,6 +1274,53 @@ components:
       required:
         - id
         - status
+    MediaRemovalRequest:
+      type: object
+      properties:
+        id:
+          type: number
+          example: 1
+          readOnly: true
+        status:
+          type: number
+          description: >-
+            Status of the removal request. 1 = PENDING, 2 = APPROVED,
+            3 = DECLINED, 4 = FAILED, 5 = PARTIALLY_REMOVED
+          example: 1
+          readOnly: true
+        is4k:
+          type: boolean
+          example: false
+        seasons:
+          type: array
+          nullable: true
+          description: Season numbers targeted by the removal request (TV only).
+          items:
+            type: number
+        reason:
+          type: string
+          nullable: true
+        media:
+          $ref: '#/components/schemas/MediaInfo'
+        requestedBy:
+          $ref: '#/components/schemas/User'
+        modifiedBy:
+          anyOf:
+            - $ref: '#/components/schemas/User'
+            - type: string
+              nullable: true
+        createdAt:
+          type: string
+          example: '2020-09-12T10:00:27.000Z'
+          readOnly: true
+        updatedAt:
+          type: string
+          example: '2020-09-12T10:00:27.000Z'
+          readOnly: true
+      required:
+        - id
+        - status
+        - is4k
     MediaInfo:
       type: object
       properties:
@@ -6282,6 +6329,193 @@ paths:
                           type: string
                         title:
                           type: string
+  /removal-request:
+    get:
+      summary: Get all removal requests
+      description: |
+        Returns all removal requests if the user has the `ADMIN`, `MANAGE_REQUESTS`, or `REQUEST_VIEW` permissions. Otherwise, only the logged-in user's removal requests are returned.
+      tags:
+        - removal-request
+      parameters:
+        - in: query
+          name: take
+          schema:
+            type: number
+            nullable: true
+            maximum: 100
+            example: 20
+        - in: query
+          name: skip
+          schema:
+            type: number
+            nullable: true
+            example: 0
+        - in: query
+          name: filter
+          schema:
+            type: string
+            enum: [all, pending, approved, declined, failed, partially-removed]
+            nullable: true
+        - in: query
+          name: requestedBy
+          description: Filter removal requests by the ID of the user who created them. Only available for users with `MANAGE_REQUESTS` or `REQUEST_VIEW` permissions.
+          schema:
+            type: number
+            nullable: true
+      responses:
+        '200':
+          description: Removal requests returned
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  pageInfo:
+                    $ref: '#/components/schemas/PageInfo'
+                  results:
+                    type: array
+                    items:
+                      $ref: '#/components/schemas/MediaRemovalRequest'
+    post:
+      summary: Create a removal request
+      description: |
+        Creates a new removal request. Requires the `REQUEST_REMOVAL` permission.
+      tags:
+        - removal-request
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              required:
+                - mediaId
+              properties:
+                mediaId:
+                  type: number
+                  example: 1
+                is4k:
+                  type: boolean
+                  default: false
+                reason:
+                  type: string
+                  nullable: true
+                seasons:
+                  type: array
+                  description: Season numbers to request removal for. Only valid for TV media. Must be positive integers.
+                  items:
+                    type: number
+                    minimum: 1
+                  nullable: true
+      responses:
+        '201':
+          description: Removal request created
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/MediaRemovalRequest'
+        '400':
+          description: Invalid input (e.g. seasons provided for a movie, invalid season numbers, or reason too long)
+        '401':
+          description: Not authenticated
+        '403':
+          description: User may only request removal of media they originally requested
+        '404':
+          description: Media not found
+        '409':
+          description: The user already has an active removal request for this media
+  /removal-request/{requestId}/approve:
+    post:
+      summary: Approve a removal request
+      description: |
+        Approves a removal request and executes the media removal. Requires the `MANAGE_REQUESTS` permission.
+      tags:
+        - removal-request
+      parameters:
+        - in: path
+          name: requestId
+          required: true
+          schema:
+            type: number
+      responses:
+        '200':
+          description: Removal request approved
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/MediaRemovalRequest'
+        '400':
+          description: The request is not pending
+        '404':
+          description: Removal request not found
+  /removal-request/{requestId}/decline:
+    post:
+      summary: Decline a removal request
+      description: |
+        Declines a removal request. Requires the `MANAGE_REQUESTS` permission.
+      tags:
+        - removal-request
+      parameters:
+        - in: path
+          name: requestId
+          required: true
+          schema:
+            type: number
+      responses:
+        '200':
+          description: Removal request declined
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/MediaRemovalRequest'
+        '400':
+          description: The request is not pending
+        '404':
+          description: Removal request not found
+  /removal-request/{requestId}/retry:
+    post:
+      summary: Retry a failed removal request
+      description: |
+        Retries a previously failed removal request. Requires the `MANAGE_REQUESTS` permission.
+      tags:
+        - removal-request
+      parameters:
+        - in: path
+          name: requestId
+          required: true
+          schema:
+            type: number
+      responses:
+        '200':
+          description: Removal request retried
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/MediaRemovalRequest'
+        '400':
+          description: Only failed requests can be retried
+        '404':
+          description: Removal request not found
+  /removal-request/{requestId}:
+    delete:
+      summary: Delete a removal request
+      description: |
+        Deletes a removal request. The requester or a user with `MANAGE_REQUESTS` permission can delete.
+      tags:
+        - removal-request
+      parameters:
+        - in: path
+          name: requestId
+          required: true
+          schema:
+            type: number
+      responses:
+        '204':
+          description: Removal request deleted
+        '403':
+          description: User does not have permission to delete this removal request
+        '404':
+          description: Removal request not found
   /request:
     get:
       summary: Get all requests

server/api/servarr/radarr.ts

@@ -270,6 +270,17 @@ class RadarrAPI extends ServarrBase<{ movieId: number }> {
   public removeMovie = async (movieId: number): Promise<void> => {
     try {
       const { id, title } = await this.getMovieByTmdbId(movieId);
+      if (!id) {
+        // Movie is not in the Radarr library (e.g. already removed). Treat the
+        // desired end-state as reached so retries remain idempotent.
+        logger.info(
+          '[Radarr] Movie not present in library; nothing to remove',
+          {
+            tmdbId: movieId,
+          }
+        );
+        return;
+      }
       await this.axios.delete(`/movie/${id}`, {
         params: {
           deleteFiles: true,
@@ -284,6 +295,26 @@ class RadarrAPI extends ServarrBase<{ movieId: number }> {
     }
   };
 
+  public removeTagFromMovie = async (
+    tmdbId: number,
+    tagId: number
+  ): Promise<void> => {
+    try {
+      const movie = await this.getMovieByTmdbId(tmdbId);
+      const updatedTags = movie.tags.filter((t) => t !== tagId);
+      await this.axios.put(`/movie`, {
+        ...movie,
+        tags: updatedTags,
+      });
+      logger.info(`[Radarr] Removed tag ${tagId} from movie ${movie.title}`);
+    } catch (e) {
+      throw new Error(
+        `[Radarr] Failed to remove tag from movie: ${e.message}`,
+        { cause: e }
+      );
+    }
+  };
+
   public clearCache = ({
     tmdbId,
     externalId,

server/api/servarr/sonarr.ts

@@ -413,6 +413,15 @@ class SonarrAPI extends ServarrBase<{
   public removeSeries = async (serieId: number): Promise<void> => {
     try {
       const { id, title } = await this.getSeriesByTvdbId(serieId);
+      if (!id) {
+        // Series is not in the Sonarr library (e.g. already removed). Treat the
+        // desired end-state as reached so retries remain idempotent.
+        logger.info(
+          '[Sonarr] Series not present in library; nothing to remove',
+          { tvdbId: serieId }
+        );
+        return;
+      }
       await this.axios.delete(`/series/${id}`, {
         params: {
           deleteFiles: true,
@@ -427,6 +436,84 @@ class SonarrAPI extends ServarrBase<{
     }
   };
 
+  public removeTagFromSeries = async (
+    tvdbId: number,
+    tagId: number
+  ): Promise<void> => {
+    try {
+      const series = await this.getSeriesByTvdbId(tvdbId);
+      if (!series.id) {
+        throw new Error('Series not found in Sonarr');
+      }
+      const updatedTags = series.tags.filter((t) => t !== tagId);
+      await this.axios.put(`/series/${series.id}`, {
+        ...series,
+        tags: updatedTags,
+      });
+      logger.info(`[Sonarr] Removed tag ${tagId} from series ${series.title}`);
+    } catch (e) {
+      throw new Error(
+        `[Sonarr] Failed to remove tag from series: ${e.message}`,
+        { cause: e }
+      );
+    }
+  };
+
+  public removeSeasonFiles = async (
+    tvdbId: number,
+    seasonNumbers: number[]
+  ): Promise<void> => {
+    try {
+      const series = await this.getSeriesByTvdbId(tvdbId);
+      if (!series.id) {
+        // Series is not in the Sonarr library (e.g. already removed). Treat the
+        // desired end-state as reached so retries remain idempotent.
+        logger.info(
+          '[Sonarr] Series not present in library; nothing to remove',
+          { tvdbId }
+        );
+        return;
+      }
+
+      const episodes = await this.getEpisodes(series.id);
+      const targetEpisodes = episodes.filter((ep) =>
+        seasonNumbers.includes(ep.seasonNumber)
+      );
+      const episodeFileIds = targetEpisodes
+        .filter((ep) => ep.hasFile && ep.episodeFileId > 0)
+        .map((ep) => ep.episodeFileId);
+
+      // Unmonitor the affected episodes before deleting files
+      const episodeIds = targetEpisodes.map((ep) => ep.id);
+      if (episodeIds.length > 0) {
+        await this.axios.put('/episode/monitor', {
+          episodeIds,
+          monitored: false,
+        });
+      }
+
+      // Delete episode files
+      for (const fileId of [...new Set(episodeFileIds)]) {
+        await this.axios.delete(`/episodefile/${fileId}`);
+      }
+
+      // Unmonitor the seasons
+      series.seasons = series.seasons.map((s) => ({
+        ...s,
+        monitored: seasonNumbers.includes(s.seasonNumber) ? false : s.monitored,
+      }));
+      await this.axios.put(`/series/${series.id}`, series);
+
+      logger.info(
+        `[Sonarr] Removed files for seasons ${seasonNumbers.join(', ')} of ${series.title}`
+      );
+    } catch (e) {
+      throw new Error(`[Sonarr] Failed to remove season files: ${e.message}`, {
+        cause: e,
+      });
+    }
+  };
+
   public clearCache = ({
     tvdbId,
     externalId,