overseerr/overseerr-api.yml

openapi: '3.0.2'
info:
  title: 'Overseerr API'
  version: '1.0.0'
servers:
  - url: /api/v1

components:
  schemas:
    User:
      type: object
      properties:
        id:
          type: integer
          example: 1
          readOnly: true
        email:
          type: string
          example: 'hey@itsme.com'
        plexToken:
          type: string
          readOnly: true
        permissions:
          type: number
          example: 0
        avatar:
          type: string
        createdAt:
          type: string
          example: '2020-09-02T05:02:23.000Z'
          readOnly: true
        updatedAt:
          type: string
          example: '2020-09-02T05:02:23.000Z'
          readOnly: true
        requests:
          type: array
          items:
            $ref: '#/components/schemas/MediaRequest'
      required:
        - id
        - email
        - permissions
        - createdAt
        - updatedAt
    MainSettings:
      type: object
      properties:
        apiKey:
          type: string
          example: 'anapikey'
      required:
        - apiKey
    PlexLibrary:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
          example: Movies
        enabled:
          type: boolean
          example: false
      required:
        - id
        - name
        - enabled
    PlexSettings:
      type: object
      properties:
        name:
          type: string
          example: 'Main Server'
          readOnly: true
        machineId:
          type: string
          example: '1234123412341234'
          readOnly: true
        ip:
          type: string
          example: '127.0.0.1'
        port:
          type: number
          example: 32400
        libraries:
          type: array
          readOnly: true
          items:
            $ref: '#/components/schemas/PlexLibrary'
      required:
        - name
        - machineId
        - ip
        - port
    RadarrSettings:
      type: object
      properties:
        id:
          type: number
          example: 0
          readOnly: true
        name:
          type: string
          example: 'Radarr Main'
        hostname:
          type: string
          example: '127.0.0.1'
        port:
          type: number
          example: 7878
        apiKey:
          type: string
          example: 'exampleapikey'
        useSsl:
          type: boolean
          example: false
        baseUrl:
          type: string
        activeProfileId:
          type: number
          example: 1
        activeProfileName:
          type: string
          example: 720p/1080p
        activeDirectory:
          type: string
          example: '/movies'
        is4k:
          type: boolean
          example: false
        minimumAvailability:
          type: string
          example: 'In Cinema'
        isDefault:
          type: boolean
          example: false
      required:
        - name
        - hostname
        - port
        - apiKey
        - useSsl
        - activeProfileId
        - activeProfileName
        - activeDirectory
        - is4k
        - minimumAvailability
        - isDefault
    SonarrSettings:
      type: object
      properties:
        id:
          type: number
          example: 0
          readOnly: true
        name:
          type: string
          example: 'Sonarr Main'
        hostname:
          type: string
          example: '127.0.0.1'
        port:
          type: number
          example: 8989
        apiKey:
          type: string
          example: 'exampleapikey'
        useSsl:
          type: boolean
          example: false
        baseUrl:
          type: string
        activeProfileId:
          type: number
          example: 1
        activeProfileName:
          type: string
          example: 720p/1080p
        activeDirectory:
          type: string
          example: '/tv/'
        activeAnimeProfileId:
          type: number
          nullable: true
        activeAnimeProfileName:
          type: string
          example: 720p/1080p
        activeAnimeDirectory:
          type: string
          nullable: true
        is4k:
          type: boolean
          example: false
        enableSeasonFolders:
          type: boolean
          example: false
        isDefault:
          type: boolean
          example: false
      required:
        - name
        - hostname
        - port
        - apiKey
        - useSsl
        - activeProfileId
        - activeProfileName
        - activeDirectory
        - is4k
        - enableSeasonFolders
        - isDefault
    PublicSettings:
      type: object
      properties:
        initialized:
          type: boolean
          example: false
    AllSettings:
      type: object
      properties:
        main:
          $ref: '#/components/schemas/MainSettings'
        plex:
          $ref: '#/components/schemas/PlexSettings'
        radarr:
          type: array
          items:
            $ref: '#/components/schemas/RadarrSettings'
        sonarr:
          type: array
          items:
            $ref: '#/components/schemas/SonarrSettings'
        public:
          $ref: '#/components/schemas/PublicSettings'
      required:
        - main
        - plex
        - radarr
        - sonarr
        - public
    MovieResult:
      type: object
      required:
        - id
        - mediaType
        - title
      properties:
        id:
          type: number
          example: 1234
        mediaType:
          type: string
        popularity:
          type: number
          example: 10
        posterPath:
          type: string
        backdropPath:
          type: string
        voteCount:
          type: number
        voteAverage:
          type: number
        genreIds:
          type: array
          items:
            type: number
        overview:
          type: string
          example: 'Overview of the movie'
        originalLanguage:
          type: string
          example: 'en'
        title:
          type: string
          example: Movie Title
        originalTitle:
          type: string
          example: Original Movie Title
        releaseDate:
          type: string
        adult:
          type: boolean
          example: false
        video:
          type: boolean
          example: false
        mediaInfo:
          $ref: '#/components/schemas/MediaInfo'
    TvResult:
      type: object
      properties:
        id:
          type: number
          example: 1234
        mediaType:
          type: string
        popularity:
          type: number
          example: 10
        posterPath:
          type: string
        backdropPath:
          type: string
        voteCount:
          type: number
        voteAverage:
          type: number
        genreIds:
          type: array
          items:
            type: number
        overview:
          type: string
          example: 'Overview of the movie'
        originalLanguage:
          type: string
          example: 'en'
        name:
          type: string
          example: TV Show Name
        originalName:
          type: string
          example: Original TV Show Name
        originCountry:
          type: array
          items:
            type: string
        firstAirDate:
          type: string
        mediaInfo:
          $ref: '#/components/schemas/MediaInfo'
    PersonResult:
      type: object
      properties:
        id:
          type: number
          example: 12345
        profilePath:
          type: string
        adult:
          type: boolean
          example: false
        mediaType:
          type: string
          default: 'person'
        knownFor:
          type: array
          items:
            oneOf:
              - $ref: '#/components/schemas/MovieResult'
              - $ref: '#/components/schemas/TvResult'
    Genre:
      type: object
      properties:
        id:
          type: number
          example: 1
        name:
          type: string
          example: Adventure
    ProductionCompany:
      type: object
      properties:
        id:
          type: number
          example: 1
        logoPath:
          type: string
        originCountry:
          type: string
        name:
          type: string
    MovieDetails:
      type: object
      properties:
        id:
          type: number
          example: 123
          readOnly: true
        imdbId:
          type: string
          example: 123
        adult:
          type: boolean
        backdropPath:
          type: string
        posterPath:
          type: string
        budget:
          type: number
          example: 1000000
        genres:
          type: array
          items:
            $ref: '#/components/schemas/Genre'
        homepage:
          type: string
        originalLanguage:
          type: string
        originalTitle:
          type: string
        overview:
          type: string
        popularity:
          type: number
        productionCompanies:
          type: array
          items:
            $ref: '#/components/schemas/ProductionCompany'
        productionCountries:
          type: array
          items:
            type: object
            properties:
              iso_3166_1:
                type: string
              name:
                type: string
        releaseDate:
          type: string
        revenue:
          type: string
        runtime:
          type: number
        spokenLanguages:
          type: array
          items:
            type: object
            properties:
              iso_639_1:
                type: string
              name:
                type: string
        status:
          type: string
        tagline:
          type: string
        title:
          type: string
        video:
          type: boolean
        voteAverage:
          type: number
        voteCount:
          type: number
        credits:
          type: object
          properties:
            cast:
              type: array
              items:
                $ref: '#/components/schemas/Cast'
            crew:
              type: array
              items:
                $ref: '#/components/schemas/Crew'
        externalIds:
          $ref: '#/components/schemas/ExternalIds'
        mediaInfo:
          $ref: '#/components/schemas/MediaInfo'
    Episode:
      type: object
      properties:
        id:
          type: number
        name:
          type: string
        airDate:
          type: string
        episodeNumber:
          type: number
        overview:
          type: string
        productionCode:
          type: string
        seasonNumber:
          type: string
        showId:
          type: number
        stillPath:
          type: string
        voteAverage:
          type: number
        voteCount:
          type: number
    Season:
      type: object
      properties:
        id:
          type: number
        airDate:
          type: string
        episodeCount:
          type: number
        name:
          type: string
        overview:
          type: string
        posterPath:
          type: string
        seasonNumber:
          type: number
        episodes:
          type: array
          items:
            $ref: '#/components/schemas/Episode'
    TvDetails:
      type: object
      properties:
        id:
          type: number
          example: 123
        backdropPath:
          type: string
        posterPath:
          type: string
        createdBy:
          type: array
          items:
            type: object
            properties:
              id:
                type: number
              name:
                type: string
              gender:
                type: number
              profilePath:
                type: string
        episodeRunTime:
          type: array
          items:
            type: number
        firstAirDate:
          type: string
        genres:
          type: array
          items:
            $ref: '#/components/schemas/Genre'
        homepage:
          type: string
        inProduction:
          type: boolean
        languages:
          type: array
          items:
            type: string
        lastAirDate:
          type: string
        lastEpisodeToAir:
          $ref: '#/components/schemas/Episode'
        name:
          type: string
        nextEpisodeToAir:
          $ref: '#/components/schemas/Episode'
        networks:
          type: array
          items:
            $ref: '#/components/schemas/ProductionCompany'
        numberOfEpisodes:
          type: number
        numberOfSeason:
          type: number
        originCountry:
          type: array
          items:
            type: string
        originalLanguage:
          type: string
        originalName:
          type: string
        overview:
          type: string
        popularity:
          type: number
        productionCompanies:
          type: array
          items:
            $ref: '#/components/schemas/ProductionCompany'
        seasons:
          type: array
          items:
            $ref: '#/components/schemas/Season'
        status:
          type: string
        type:
          type: string
        voteAverage:
          type: number
        voteCount:
          type: number
        credits:
          type: object
          properties:
            cast:
              type: array
              items:
                $ref: '#/components/schemas/Cast'
            crew:
              type: array
              items:
                $ref: '#/components/schemas/Crew'
        externalIds:
          $ref: '#/components/schemas/ExternalIds'
        mediaInfo:
          $ref: '#/components/schemas/MediaInfo'
    MediaRequest:
      type: object
      properties:
        id:
          type: number
          example: 123
          readOnly: true
        status:
          type: number
          example: 0
          description: Status of the request. 1 = PENDING APPROVAL, 2 = APPROVED, 3 = DECLINED, 4 = AVAILABLE
          readOnly: true
        media:
          $ref: '#/components/schemas/MediaInfo'
        createdAt:
          type: string
          example: '2020-09-12T10:00:27.000Z'
          readOnly: true
        updatedAt:
          type: string
          example: '2020-09-12T10:00:27.000Z'
          readOnly: true
        requestedBy:
          $ref: '#/components/schemas/User'
          readOnly: true
        modifiedBy:
          anyOf:
            - $ref: '#/components/schemas/User'
            - type: string
              nullable: true
      required:
        - id
        - status
    MediaInfo:
      type: object
      properties:
        id:
          type: number
          readOnly: true
        tmdbId:
          type: number
          readOnly: true
        tvdbId:
          type: number
          readOnly: true
        status:
          type: number
        requests:
          type: array
          readOnly: true
          items:
            $ref: '#/components/schemas/MediaRequest'
        createdAt:
          type: string
          example: '2020-09-12T10:00:27.000Z'
          readOnly: true
        updatedAt:
          type: string
          example: '2020-09-12T10:00:27.000Z'
          readOnly: true
    Cast:
      type: object
      properties:
        id:
          type: number
          example: 123
        castId:
          type: number
          example: 1
        character:
          type: string
          example: Some Character Name
        creditId:
          type: string
        gender:
          type: number
        name:
          type: string
          example: Some Persons Name
        order:
          type: number
        profilePath:
          type: string
    Crew:
      type: object
      properties:
        id:
          type: number
          example: 123
        creditId:
          type: string
        gender:
          type: number
        name:
          type: string
          example: Some Persons Name
        job:
          type: string
        department:
          type: string
        profilePath:
          type: string
    ExternalIds:
      type: object
      properties:
        facebookId:
          type: string
        freebaseId:
          type: string
        freebaseMid:
          type: string
        imdbId:
          type: string
        instagramId:
          type: string
        tvdbId:
          type: string
        tvrageId:
          type: string
        twitterId:
          type: string
    ServiceProfile:
      type: object
      properties:
        id:
          type: number
          example: 1
        name:
          type: string
          example: 720p/1080p

  securitySchemes:
    cookieAuth:
      type: apiKey
      name: connect.sid
      in: cookie

paths:
  /settings/main:
    get:
      summary: Returns main settings
      description: Retreives all main settings in JSON format
      tags:
        - settings
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MainSettings'
    post:
      summary: Update main settings
      description: Update current main settings with provided values
      tags:
        - settings
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MainSettings'
      responses:
        '200':
          description: 'Values were sucessfully updated'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MainSettings'
  /settings/plex:
    get:
      summary: Returns plex settings
      description: Retrieves current Plex settings
      tags:
        - settings
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PlexSettings'
    post:
      summary: Update plex settings
      description: Update the current plex settings with provided values
      tags:
        - settings
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PlexSettings'
      responses:
        '200':
          description: 'Values were successfully updated'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PlexSettings'
  /settings/plex/library:
    get:
      summary: Get a list of current plex libraries
      description: Returns a list of plex libraries in a JSON array
      tags:
        - settings
      parameters:
        - in: query
          name: sync
          description: Syncs the current libraries with the current plex server
          schema:
            type: string
            nullable: true
        - in: query
          name: enable
          explode: false
          allowReserved: true
          description: Comma separated list of libraries to enable. Any libraries not passed will be disabled!
          schema:
            type: string
            nullable: true
      responses:
        '200':
          description: 'Plex libraries returned'
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/PlexLibrary'
  /settings/plex/sync:
    get:
      summary: Start a full Plex Library sync
      description: Runs a full plex library sync and returns the progress in a JSON array
      tags:
        - settings
      parameters:
        - in: query
          name: cancel
          schema:
            type: boolean
            example: false
        - in: query
          name: start
          schema:
            type: boolean
            example: false
      responses:
        '200':
          description: Status of Plex Sync
          content:
            application/json:
              schema:
                type: object
                properties:
                  running:
                    type: boolean
                    example: false
                  progress:
                    type: number
                    example: 0
                  total:
                    type: number
                    example: 100
                  currentLibrary:
                    $ref: '#/components/schemas/PlexLibrary'
                  libraries:
                    type: array
                    items:
                      $ref: '#/components/schemas/PlexLibrary'
  /settings/radarr:
    get:
      summary: Get all radarr settings
      description: Returns all radarr settings in a JSON array
      tags:
        - settings
      responses:
        '200':
          description: 'Values were returned'
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/RadarrSettings'
    post:
      summary: Create new radarr instance
      description: Creates a new radarr instance from the request body
      tags:
        - settings
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RadarrSettings'
      responses:
        '201':
          description: 'New Radarr instance created'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RadarrSettings'
  /settings/radarr/test:
    post:
      summary: Test radarr configuration
      description: Test if the provided Radarr congifuration values are valid. Returns profiles and root folders on success
      tags:
        - settings
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                hostname:
                  type: string
                  example: '127.0.0.1'
                port:
                  type: number
                  example: 7878
                apiKey:
                  type: string
                  example: yourapikey
                useSsl:
                  type: boolean
                  example: false
                baseUrl:
                  type: string
              required:
                - hostname
                - port
                - apiKey
                - useSsl
      responses:
        '200':
          description: Succesfully connected to Radarr instance
          content:
            application/json:
              schema:
                type: object
                properties:
                  profiles:
                    type: array
                    items:
                      $ref: '#/components/schemas/ServiceProfile'
  /settings/radarr/{radarrId}:
    put:
      summary: Update existing radarr instance
      description: Updates an existing radarr instance with values from request body
      tags:
        - settings
      parameters:
        - in: path
          name: radarrId
          required: true
          schema:
            type: integer
          description: Radarr instance ID
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RadarrSettings'
      responses:
        '200':
          description: 'Radarr instance updated'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RadarrSettings'
    delete:
      summary: Delete existing radarr instance
      description: Deletes an existing radarr instance based on id parameter
      tags:
        - settings
      parameters:
        - in: path
          name: radarrId
          required: true
          schema:
            type: integer
          description: Radarr Instance ID
      responses:
        '200':
          description: 'Radarr instance updated'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RadarrSettings'
  /settings/radarr/{radarrId}/profiles:
    get:
      summary: Retrieve available profiles for the Radarr instance
      description: Returns an array of profile available on the Radarr server instance in JSON format
      tags:
        - settings
      parameters:
        - in: path
          name: radarrId
          required: true
          schema:
            type: integer
          description: Radarr Instance ID
      responses:
        '200':
          description: Returned list of profiles
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ServiceProfile'
  /settings/sonarr:
    get:
      summary: Get all sonarr settings
      description: Returns all sonarr settings in a JSON array
      tags:
        - settings
      responses:
        '200':
          description: 'Values were returned'
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/SonarrSettings'
    post:
      summary: Create new Sonarr instance
      description: Creates a new Sonarr instance from the request body
      tags:
        - settings
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SonarrSettings'
      responses:
        '201':
          description: 'New Sonarr instance created'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SonarrSettings'
  /settings/sonarr/test:
    post:
      summary: Test Sonarr configuration
      description: Test if the provided Sonarr congifuration values are valid. Returns profiles and root folders on success
      tags:
        - settings
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                hostname:
                  type: string
                  example: '127.0.0.1'
                port:
                  type: number
                  example: 8989
                apiKey:
                  type: string
                  example: yourapikey
                useSsl:
                  type: boolean
                  example: false
                baseUrl:
                  type: string
              required:
                - hostname
                - port
                - apiKey
                - useSsl
      responses:
        '200':
          description: Succesfully connected to Sonarr instance
          content:
            application/json:
              schema:
                type: object
                properties:
                  profiles:
                    type: array
                    items:
                      $ref: '#/components/schemas/ServiceProfile'
  /settings/sonarr/{sonarrId}:
    put:
      summary: Update existing sonarr instance
      description: Updates an existing sonarr instance with values from request body
      tags:
        - settings
      parameters:
        - in: path
          name: sonarrId
          required: true
          schema:
            type: integer
          description: Sonarr instance ID
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SonarrSettings'
      responses:
        '200':
          description: 'Sonarr instance updated'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SonarrSettings'
    delete:
      summary: Delete existing sonarr instance
      description: Deletes an existing sonarr instance based on id parameter
      tags:
        - settings
      parameters:
        - in: path
          name: sonarrId
          required: true
          schema:
            type: integer
          description: Sonarr Instance ID
      responses:
        '200':
          description: 'Sonarr instance updated'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SonarrSettings'
  /settings/public:
    get:
      summary: Returns public settings
      description: Returns settings that are not protected or sensitive. Mainly used to determine if the app has been configured for the first time.
      tags:
        - settings
      responses:
        '200':
          description: Public Settings returned
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicSettings'
  /settings/jobs:
    get:
      summary: Returns list of scheduled jobs
      description: Returns list of all scheduled jobs and details about their next execution time
      tags:
        - settings
      responses:
        '200':
          description: Scheduled jobs returned
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    name:
                      type: string
                      example: A Job Name
                    nextExecutionTime:
                      type: string
                      example: '2020-09-02T05:02:23.000Z'

  /auth/me:
    get:
      summary: Returns the currently logged in user
      description: Returns the currently logged in user
      tags:
        - auth
        - users
      responses:
        '200':
          description: Object containing the logged in user in JSON
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
  /auth/login:
    post:
      summary: Login using a plex auth token
      description: Takes an `authToken` (plex token) to log the user in. Generates a session cookie for use in further requests. If the user does not exist, and there are no other users, then a user will be created with full admin privileges. If a user logs in with access to the main plex server, they will also have an account created, but without any permissions.
      security: []
      tags:
        - auth
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                authToken:
                  type: string
              required:
                - authToken
  /auth/logout:
    get:
      summary: Logout and clear session cookie
      description: This endpoint will completely clear the session cookie and associated values, logging out the user
      tags:
        - auth
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    example: 'ok'
  /user:
    get:
      summary: Returns a list of all users
      description: Requests all users and returns them in a large array
      tags:
        - users
      responses:
        '200':
          description: A JSON array of all users
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/User'
    post:
      summary: Create a new user
      description: |
        Creates a new user. Should under normal circumstances never be called as you will not have a valid authToken to provide for the user.

        In the future when Plex auth is not required, this will be used to create accounts.

        Requires the `MANAGE_USERS` permission.
      tags:
        - users
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/User'
      responses:
        '201':
          description: The created user in JSON
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
  /user/{userId}:
    get:
      summary: Retrieve a user by ID
      description: |
        Retrieve user details in JSON format. Requires the `MANAGE_USERS` permission.
      tags:
        - users
      parameters:
        - in: path
          name: userId
          required: true
          schema:
            type: number
      responses:
        '200':
          description: Users details in JSON
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
    put:
      summary: Update a user by user ID
      description: |
        Update a user with provided values in request body. You cannot update a users plex token through this request.

        Requires the `MANAGE_USERS` permission.
      tags:
        - users
      parameters:
        - in: path
          name: userId
          required: true
          schema:
            type: number
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/User'
      responses:
        '200':
          description: Successfully updated user details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
    delete:
      summary: Delete a user by user ID
      description: Deletes a user by provided user ID. Requires the `MANAGE_USERS` permission.
      tags:
        - users
      parameters:
        - in: path
          name: userId
          required: true
          schema:
            type: number
      responses:
        '200':
          description: User successfully deleted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
  /search:
    get:
      summary: Search for movies/tv shows/people
      description: Returns a list of movies/tv shows/people in JSON format
      tags:
        - search
      parameters:
        - in: query
          name: query
          required: true
          schema:
            type: string
            example: 'Mulan'
        - in: query
          name: page
          schema:
            type: number
            example: 1
            default: 1
        - in: query
          name: language
          schema:
            type: string
            example: en
      responses:
        '200':
          description: Results
          content:
            application/json:
              schema:
                type: object
                properties:
                  page:
                    type: number
                    example: 1
                  totalPages:
                    type: number
                    example: 20
                  totalResults:
                    type: number
                    example: 200
                  results:
                    type: array
                    items:
                      anyOf:
                        - $ref: '#/components/schemas/MovieResult'
                        - $ref: '#/components/schemas/TvResult'
                        - $ref: '#/components/schemas/PersonResult'
  /discover/movies:
    get:
      summary: Discover movies
      description: Returns a list of movies in JSON format
      tags:
        - search
      parameters:
        - in: query
          name: page
          schema:
            type: number
            example: 1
            default: 1
        - in: query
          name: language
          schema:
            type: string
            example: en
      responses:
        '200':
          description: Results
          content:
            application/json:
              schema:
                type: object
                properties:
                  page:
                    type: number
                    example: 1
                  totalPages:
                    type: number
                    example: 20
                  totalResults:
                    type: number
                    example: 200
                  results:
                    type: array
                    items:
                      $ref: '#/components/schemas/MovieResult'
  /discover/tv:
    get:
      summary: Discover TV shows
      description: Returns a list of tv shows in JSON format
      tags:
        - search
      parameters:
        - in: query
          name: page
          schema:
            type: number
            example: 1
            default: 1
        - in: query
          name: language
          schema:
            type: string
            example: en
      responses:
        '200':
          description: Results
          content:
            application/json:
              schema:
                type: object
                properties:
                  page:
                    type: number
                    example: 1
                  totalPages:
                    type: number
                    example: 20
                  totalResults:
                    type: number
                    example: 200
                  results:
                    type: array
                    items:
                      $ref: '#/components/schemas/TvResult'
  /request:
    get:
      summary: Get all requests
      description: |
        Returns all requests if the user has the `ADMIN` or `MANAGE_REQUESTS` permissions. Otherwise, only the logged in users requests are returned.
      tags:
        - request
      responses:
        '200':
          description: Requests returned
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/MediaRequest'
    post:
      summary: Create a new request
      description: |
        Creates a new request with the provided media id and type. The `REQUEST` permission is required.

        If the user has the `ADMIN` or `AUTO_APPROVE` permissions, their request will be auomatically approved.
      tags:
        - request
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                mediaType:
                  type: string
                  enum: [movie, tv]
                  example: movie
                mediaId:
                  type: number
                  example: 123
                tvdbId:
                  type: number
                  example: 123
                seasons:
                  type: array
                  items:
                    type: number
              required:
                - mediaType
                - mediaId
      responses:
        '201':
          description: Succesfully created the request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MediaRequest'
  /request/{requestId}:
    get:
      summary: Requests a specific MediaRequest
      description: Returns a MediaRequest in JSON format
      tags:
        - request
      parameters:
        - in: path
          name: requestId
          description: Request ID
          required: true
          example: 1
          schema:
            type: string
      responses:
        '200':
          description: Succesfully returns request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MediaRequest'
    delete:
      summary: Delete a request
      description: Removes a request. If the user has the `MANAGE_REQUESTS` permission, then any request can be removed. Otherwise, only pending requests can be removed.
      tags:
        - request
      parameters:
        - in: path
          name: requestId
          description: Request ID
          required: true
          example: 1
          schema:
            type: string
      responses:
        '204':
          description: Succesfully removed request
  /request/{requestId}/{status}:
    get:
      summary: Update a requests status
      description: |
        Updates a requests status to approved or declined. Also returns the request in JSON format

        Requires the `MANAGE_REQUESTS` permission or `ADMIN`
      tags:
        - request
      parameters:
        - in: path
          name: requestId
          description: Request ID
          required: true
          schema:
            type: string
            example: 1
        - in: path
          name: status
          description: New status
          required: true
          schema:
            type: string
            enum: [pending, approve, decline, available]
      responses:
        '200':
          description: Request status changed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MediaRequest'
  /movie/{movieId}:
    get:
      summary: Request movie details
      description: Returns back full movie details in JSON format
      tags:
        - movies
      parameters:
        - in: path
          name: movieId
          required: true
          schema:
            type: number
            example: 337401
        - in: query
          name: language
          schema:
            type: string
            example: en
      responses:
        '200':
          description: Movie details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MovieDetails'
  /movie/{movieId}/recommendations:
    get:
      summary: Request recommended movies
      description: Returns list of recommended movies based on provided movie ID in JSON format
      tags:
        - movies
      parameters:
        - in: path
          name: movieId
          required: true
          schema:
            type: number
            example: 337401
        - in: query
          name: page
          schema:
            type: number
            example: 1
            default: 1
        - in: query
          name: language
          schema:
            type: string
            example: en
      responses:
        '200':
          description: List of movies
          content:
            application/json:
              schema:
                type: object
                properties:
                  page:
                    type: number
                    example: 1
                  totalPages:
                    type: number
                    example: 20
                  totalResults:
                    type: number
                    example: 200
                  results:
                    type: array
                    items:
                      $ref: '#/components/schemas/MovieResult'
  /movie/{movieId}/similar:
    get:
      summary: Request similar movies
      description: Returns list of similar movies based on provided movie ID in JSON format
      tags:
        - movies
      parameters:
        - in: path
          name: movieId
          required: true
          schema:
            type: number
            example: 337401
        - in: query
          name: page
          schema:
            type: number
            example: 1
            default: 1
        - in: query
          name: language
          schema:
            type: string
            example: en
      responses:
        '200':
          description: List of movies
          content:
            application/json:
              schema:
                type: object
                properties:
                  page:
                    type: number
                    example: 1
                  totalPages:
                    type: number
                    example: 20
                  totalResults:
                    type: number
                    example: 200
                  results:
                    type: array
                    items:
                      $ref: '#/components/schemas/MovieResult'
  /tv/{tvId}:
    get:
      summary: Request tv details
      description: Returns back full tv details in JSON format
      tags:
        - tv
      parameters:
        - in: path
          name: tvId
          required: true
          schema:
            type: number
            example: 76479
        - in: query
          name: language
          schema:
            type: string
            example: en
      responses:
        '200':
          description: TV details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TvDetails'
  /tv/{tvId}/season/{seasonId}:
    get:
      summary: Return season details with episode list
      description: Returns back season details with a list of episodes
      tags:
        - tv
      parameters:
        - in: path
          name: tvId
          required: true
          schema:
            type: number
            example: 76479
        - in: path
          name: seasonId
          required: true
          schema:
            type: number
            example: 1
        - in: query
          name: language
          schema:
            type: string
            example: en-US
      responses:
        '200':
          description: TV details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Season'
  /tv/{tvId}/recommendations:
    get:
      summary: Request recommended tv series
      description: Returns list of recommended tv series based on provided tv ID in JSON format
      tags:
        - tv
      parameters:
        - in: path
          name: tvId
          required: true
          schema:
            type: number
            example: 76479
        - in: query
          name: page
          schema:
            type: number
            example: 1
            default: 1
        - in: query
          name: language
          schema:
            type: string
            example: en
      responses:
        '200':
          description: List of tv series
          content:
            application/json:
              schema:
                type: object
                properties:
                  page:
                    type: number
                    example: 1
                  totalPages:
                    type: number
                    example: 20
                  totalResults:
                    type: number
                    example: 200
                  results:
                    type: array
                    items:
                      $ref: '#/components/schemas/TvResult'
  /tv/{tvId}/similar:
    get:
      summary: Request similar tv series
      description: Returns list of similar tv series based on provided movie ID in JSON format
      tags:
        - tv
      parameters:
        - in: path
          name: tvId
          required: true
          schema:
            type: number
            example: 76479
        - in: query
          name: page
          schema:
            type: number
            example: 1
            default: 1
        - in: query
          name: language
          schema:
            type: string
            example: en
      responses:
        '200':
          description: List of tv series
          content:
            application/json:
              schema:
                type: object
                properties:
                  page:
                    type: number
                    example: 1
                  totalPages:
                    type: number
                    example: 20
                  totalResults:
                    type: number
                    example: 200
                  results:
                    type: array
                    items:
                      $ref: '#/components/schemas/TvResult'

security:
  - cookieAuth: []