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.