You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
overseerr/server/overseerr-api.yml

1587 lines
40 KiB

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'
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
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
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
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
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
- 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:
'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'
/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}/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: []