openapi: 3.0.3
info:
title: The Open Movie Database API
description: >-
The OMDb API is a RESTful web service to obtain movie, series, and episode
information. All content and images on the site are contributed and maintained
by users. Access movie and TV metadata including title, year, genre, director,
cast, plot, ratings, and IMDb data. Search by title or look up by IMDb ID.
Requires a free API key obtained at omdbapi.com/apikey.aspx.
version: 1.0.0
contact:
url: https://www.omdbapi.com/
termsOfService: https://www.omdbapi.com/legal.htm
servers:
- url: https://www.omdbapi.com
description: Main OMDb API server
- url: https://img.omdbapi.com
description: OMDb Poster API server
security:
- apiKey: []
paths:
/:
get:
operationId: getMovie
summary: Get Movie By Title Or IMDb ID
description: >-
Retrieve detailed information about a single movie, TV series, or episode
by IMDb ID or title. At least one of the 'i' (IMDb ID) or 't' (title)
parameters is required.
tags:
- Movies
parameters:
- name: apikey
in: query
required: true
description: Your OMDb API key.
schema:
type: string
- name: i
in: query
required: false
description: >-
A valid IMDb ID (e.g., tt1285016). Required if 't' is not provided.
schema:
type: string
pattern: "^tt\\d{7,8}$"
- name: t
in: query
required: false
description: >-
Movie or series title to retrieve. Required if 'i' is not provided.
schema:
type: string
- name: type
in: query
required: false
description: "Type of result to return: movie, series, or episode."
schema:
type: string
enum:
- movie
- series
- episode
- name: y
in: query
required: false
description: Year of release.
schema:
type: integer
- name: plot
in: query
required: false
description: "Return short or full plot. Values: short (default), full."
schema:
type: string
enum:
- short
- full
default: short
- name: r
in: query
required: false
description: "Response format. Values: json (default), xml."
schema:
type: string
enum:
- json
- xml
default: json
- name: callback
in: query
required: false
description: JSONP callback function name.
schema:
type: string
- name: v
in: query
required: false
description: API version (default 1).
schema:
type: integer
default: 1
- name: Season
in: query
required: false
description: "Season number (integer). Used to retrieve a specific TV season."
schema:
type: integer
- name: Episode
in: query
required: false
description: "Episode number (integer). Used with Season to retrieve a specific episode."
schema:
type: integer
responses:
"200":
description: Movie, series, or episode details.
content:
application/json:
schema:
oneOf:
- $ref: "#/components/schemas/Movie"
- $ref: "#/components/schemas/Season"
- $ref: "#/components/schemas/ErrorResponse"
"401":
$ref: "#/components/responses/Unauthorized"
/search:
get:
operationId: searchMovies
summary: Search Movies By Title
description: >-
Search for movies, series, or episodes by title. Returns a paginated list
of matching results. Note: The search endpoint uses the same base URL
(https://www.omdbapi.com/) with the 's' parameter instead of 't'.
tags:
- Search
parameters:
- name: apikey
in: query
required: true
description: Your OMDb API key.
schema:
type: string
- name: s
in: query
required: true
description: Search term — movie title or partial title to search for.
schema:
type: string
- name: type
in: query
required: false
description: "Filter by type: movie, series, or episode."
schema:
type: string
enum:
- movie
- series
- episode
- name: y
in: query
required: false
description: Year of release filter.
schema:
type: integer
- name: page
in: query
required: false
description: Page number for pagination (1-100, default 1). Each page contains up to 10 results.
schema:
type: integer
minimum: 1
maximum: 100
default: 1
- name: r
in: query
required: false
description: "Response format: json (default) or xml."
schema:
type: string
enum:
- json
- xml
default: json
- name: callback
in: query
required: false
description: JSONP callback function name.
schema:
type: string
responses:
"200":
description: Search results with matching movies/series.
content:
application/json:
schema:
oneOf:
- $ref: "#/components/schemas/SearchResponse"
- $ref: "#/components/schemas/ErrorResponse"
"401":
$ref: "#/components/responses/Unauthorized"
components:
securitySchemes:
apiKey:
type: apiKey
name: apikey
in: query
schemas:
Rating:
type: object
description: A rating from a specific source.
properties:
Source:
type: string
description: "Rating source name (e.g., Internet Movie Database, Rotten Tomatoes, Metacritic)."
Value:
type: string
description: "Rating value (e.g., 8.5/10, 92%, 75/100)."
Movie:
type: object
description: Detailed information about a movie, TV series, or episode.
properties:
Title:
type: string
description: "Title of the movie or series."
Year:
type: string
description: "Release year or year range for series (e.g., 2010 or 2010-2014)."
Rated:
type: string
description: "MPAA content rating (e.g., PG-13, R, TV-MA, N/A)."
Released:
type: string
description: "Theatrical or air release date (e.g., 20 Oct 2010)."
Runtime:
type: string
description: "Runtime in minutes (e.g., 148 min)."
Genre:
type: string
description: "Comma-separated list of genres (e.g., Drama, Thriller)."
Director:
type: string
description: "Director name(s)."
Writer:
type: string
description: "Writer name(s)."
Actors:
type: string
description: "Comma-separated list of main cast members."
Plot:
type: string
description: "Short or full plot summary depending on the plot parameter."
Language:
type: string
description: "Language(s) of the film."
Country:
type: string
description: "Country or countries of production."
Awards:
type: string
description: "Awards won or nominated for (e.g., Won 6 Oscars. Another 56 wins & 34 nominations.)."
Poster:
type: string
description: "URL to the movie poster image."
Ratings:
type: array
items:
$ref: "#/components/schemas/Rating"
description: "Array of ratings from multiple sources."
Metascore:
type: string
description: "Metacritic score (0-100) or N/A."
imdbRating:
type: string
description: "IMDb user rating (0-10) or N/A."
imdbVotes:
type: string
description: "Number of IMDb user votes."
imdbID:
type: string
description: "IMDb identifier (e.g., tt1285016)."
Type:
type: string
description: "Content type: movie, series, or episode."
DVD:
type: string
description: "DVD release date."
BoxOffice:
type: string
description: "Box office earnings (US) (e.g., $421,791,123)."
Production:
type: string
description: "Production company name."
Website:
type: string
description: "Official website URL or N/A."
totalSeasons:
type: string
description: "Total number of seasons (series only)."
seriesID:
type: string
description: "IMDb ID of the parent series (episode only)."
Season:
type: string
description: "Season number (episode only)."
Episode:
type: string
description: "Episode number within the season (episode only)."
Response:
type: string
description: "API response status: True or False."
enum:
- "True"
- "False"
required: ["Title", "imdbID", "Response"]
SearchResult:
type: object
description: A search result item (abbreviated movie/series data).
properties:
Title:
type: string
description: "Title of the movie or series."
Year:
type: string
description: "Release year."
imdbID:
type: string
description: "IMDb identifier."
Type:
type: string
description: "Content type: movie, series, or episode."
Poster:
type: string
description: "URL to the poster image or N/A."
SearchResponse:
type: object
description: Paginated search results.
properties:
Search:
type: array
items:
$ref: "#/components/schemas/SearchResult"
description: "Array of matching results (up to 10 per page)."
totalResults:
type: string
description: "Total number of matching results."
Response:
type: string
description: "API response status: True or False."
enum:
- "True"
- "False"
EpisodeRef:
type: object
description: Episode reference in a season listing.
properties:
Title:
type: string
description: "Episode title."
Released:
type: string
description: "Episode air date."
Episode:
type: string
description: "Episode number within the season."
imdbRating:
type: string
description: "IMDb rating."
imdbID:
type: string
description: "Episode IMDb ID."
Season:
type: object
description: Season listing for a TV series.
properties:
Title:
type: string
description: "Series title."
Season:
type: string
description: "Season number."
totalSeasons:
type: string
description: "Total seasons in the series."
Episodes:
type: array
items:
$ref: "#/components/schemas/EpisodeRef"
description: "List of episodes in the season."
Response:
type: string
description: "Response status."
ErrorResponse:
type: object
description: Error response when the request fails.
properties:
Response:
type: string
description: "Always False for errors."
enum:
- "False"
Error:
type: string
description: "Error message describing what went wrong."
responses:
Unauthorized:
description: "Unauthorized — invalid or missing API key."
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorResponse"
tags:
- name: Movies
description: Retrieve movie, series, and episode details by ID or title.
- name: Search
description: Search for movies and series by title.