The Open Movie Database Movies API

openapi: 3.0.3
info:
  title: The Open Movie Database Movies 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: []
tags:
- name: Movies
  description: Retrieve movie, series, and episode details by ID or title.
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'
components:
  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).
    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.
    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.
    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.
    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
  responses:
    Unauthorized:
      description: Unauthorized — invalid or missing API key.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
  securitySchemes:
    apiKey:
      type: apiKey
      name: apikey
      in: query