openapi: 3.0.3
info:
  title: OMDb ID Parameter Search Parameter API
  description: 'Open Movie Database REST API providing movie and TV show metadata, ratings, poster images, and episode data from a community-maintained database. Supports lookup by IMDb ID or title, full-text search, and a dedicated Poster API for high-resolution cover art available to patrons. This API requires authorization — get a free key at https://www.omdbapi.com/apikey.aspx

    '
  version: '1.0'
  contact:
    email: bfritz@fadingsignal.com
  license:
    name: CC BY-NC 4.0
    url: https://creativecommons.org/licenses/by-nc/4.0/
  termsOfService: https://omdbapi.com/legal.htm
servers:
- url: https://www.omdbapi.com
  description: OMDb API
security:
- APIKeyQueryParam: []
tags:
- name: Search Parameter
paths:
  /?s:
    get:
      summary: Title search — returns an array of results for a given title string
      description: 'Returns a paginated list of titles matching the search string. Results include basic metadata (title, year, type, poster, IMDb ID).

        '
      operationId: searchByTitle
      tags:
      - Search Parameter
      parameters:
      - name: s
        in: query
        description: Title of movie or series to search for
        required: true
        schema:
          type: string
        example: Batman
      - name: y
        in: query
        description: Year of release
        required: false
        schema:
          type: integer
      - name: type
        in: query
        description: Return movie or series results
        required: false
        schema:
          type: string
          enum:
          - movie
          - series
      - name: r
        in: query
        description: The response type to return
        required: false
        schema:
          type: string
          enum:
          - json
          - xml
        default: json
      - name: page
        in: query
        description: Page number to return (results come in sets of 10)
        required: false
        schema:
          type: integer
          minimum: 1
          maximum: 100
        default: 1
      - name: callback
        in: query
        description: JSONP callback name
        required: false
        schema:
          type: string
      - name: apikey
        in: query
        description: API key (may also be supplied via security scheme)
        required: false
        schema:
          type: string
      responses:
        '200':
          description: Successful operation — paginated search results
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SearchResult'
              example:
                Search:
                - Title: Batman Begins
                  Year: '2005'
                  imdbID: tt0372784
                  Type: movie
                  Poster: https://m.media-amazon.com/images/M/MV5BZDM4OGU1OWEtYjQ4OC00MDQ2LThjOWQtNmM2ODBlZWJjN2I3XkEyXkFqcGdeQXVyMTMxODk2OTU@._V1_SX300.jpg
                - Title: The Dark Knight
                  Year: '2008'
                  imdbID: tt0468569
                  Type: movie
                  Poster: https://m.media-amazon.com/images/M/MV5BMTMxNTMwODM0NF5BMl5BanBnXkFtZTcwODAyMTk2Mw@@._V1_SX300.jpg
                totalResults: '521'
                Response: 'True'
        '401':
          description: Not authenticated — invalid or missing API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResult'
components:
  schemas:
    ErrorResult:
      type: object
      description: Error response returned for authentication failures
      properties:
        Response:
          type: string
          description: Always "False" for errors
          enum:
          - 'False'
          example: 'False'
        Error:
          type: string
          description: Human-readable error message
          example: No API key provided.
    SearchResultItem:
      type: object
      description: Condensed record returned in search results
      properties:
        Title:
          type: string
          description: Title of the movie or series
          example: Batman Begins
        Year:
          type: string
          description: Year of release
          example: '2005'
        imdbID:
          type: string
          description: IMDb unique identifier
          pattern: ^tt\d{7,8}$
          example: tt0372784
        Type:
          type: string
          description: Type of title
          enum:
          - movie
          - series
          - episode
          example: movie
        Poster:
          type: string
          format: uri
          description: URL of the poster image (or "N/A")
    SearchResult:
      type: object
      description: Paginated search results container
      properties:
        Search:
          type: array
          description: Array of matching titles (up to 10 per page)
          items:
            $ref: '#/components/schemas/SearchResultItem'
        totalResults:
          type: string
          description: Total number of results across all pages
          example: '521'
        Response:
          type: string
          description: Whether the query succeeded
          enum:
          - 'True'
          - 'False'
          example: 'True'
        Error:
          type: string
          description: Error message (present when Response is False)
  securitySchemes:
    APIKeyQueryParam:
      type: apiKey
      name: apikey
      in: query
      description: API key obtained from https://www.omdbapi.com/apikey.aspx
externalDocs:
  description: OMDb API Documentation
  url: https://www.omdbapi.com/