overseerr/server/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
      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'
        machineId:
          type: string
          example: '1234-1234-1234-1234'
        ip:
          type: string
          example: '127.0.0.1'
        port:
          type: number
          example: 32400
        libraries:
          type: array
          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
        activeProfile:
          type: string
          example: '1080p'
        activeDirectory:
          type: string
          example: '/movies'
        is4k:
          type: boolean
          example: false
        minimumAvailability:
          type: string
          example: 'In Cinema'
      required:
        - name
        - hostname
        - port
        - apiKey
        - useSsl
        - activeProfile
        - activeDirectory
        - is4k
        - minimumAvailability
    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
        activeProfile:
          type: string
          example: '1080p'
        activeDirectory:
          type: string
          example: '/movies'
        activeAnimeProfile:
          type: string
          nullable: true
        activeAnimeDirectory:
          type: string
          nullable: true
        is4k:
          type: boolean
          example: false
        enableSeasonFolders:
          type: boolean
          example: false
      required:
        - name
        - hostname
        - port
        - apiKey
        - useSsl
        - activeProfile
        - activeDirectory
        - is4k
        - enableSeasonFolders
    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
        request:
          $ref: '#/components/schemas/MediaRequest'
    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
        request:
          $ref: '#/components/schemas/MediaRequest'
    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'
    MediaRequest:
      type: object
      properties:
        id:
          type: number
          example: 123
          readOnly: true
        mediaId:
          type: number
          example: 123
          description: TMDB Movie ID
        mediaType:
          type: string
          enum: [movie, tv]
        status:
          type: number
          example: 0
          description: Status of the request. 0 = PENDING APPROVAL, 1 = APPROVED, 2 = DECLINED, 3 = AVAILABLE
          readOnly: 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
        requestedBy:
          $ref: '#/components/schemas/User'
          readOnly: true
        modifiedBy:
          anyOf:
            - $ref: '#/components/schemas/User'
            - type: string
              nullable: true
      required:
        - id
        - mediaId
        - mediaType
        - status

  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/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/{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/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/{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'
  /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
      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
      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
      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
      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:
        '200':
          description: Succesfully removed request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MediaRequest'
  /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'

security:
  - cookieAuth: []