openapi: 3.0.3
info:
  title: The Open Movie Database Movies Search 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: Search
  description: Search for movies and series by title.
paths:
  /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:
  responses:
    Unauthorized:
      description: Unauthorized — invalid or missing API key.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
  schemas:
    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.
    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.
    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'
  securitySchemes:
    apiKey:
      type: apiKey
      name: apikey
      in: query