openapi: 3.0.0
info:
  title: Yandex Videos API
  description: Search Yandex Videos with source exclusions, safe-search,
    and pagination parameters. Results include direct video links, channel information,
    view counts, and thumbnails. Use the Yandex Search API for web results.
  version: 1.0.0
servers:
- url: https://www.searchapi.io/api/v1
paths:
  "/search":
    get:
      summary: Yandex Videos Search
      security:
      - ApiKeyAuth: []
      - ApiKeyQuery: []
      parameters:
      - name: engine
        in: query
        required: true
        description: Search engine to use.
        schema:
          type: string
          enum: ["yandex_videos"]
      - name: q
        in: query
        required: true
        description: Video search query.
        schema:
          type: string
      - name: yandex_domain
        in: query
        required: false
        description: Yandex domain to search.
        schema:
          type: string
          enum: ["yandex.com","yandex.ru","ya.ru","yandex.by","yandex.kz","yandex.uz","yandex.com.tr","yandex.fr","yandex.az","yandex.com.ge","yandex.com.am","yandex.co.il","yandex.lv","yandex.lt","yandex.ee","yandex.md","yandex.tm","yandex.tj","yandex.eu"]
          default: "yandex.com"
      - name: exclude_source
        in: query
        required: false
        description: Exclude one video source.
        schema:
          type: string
          enum: ["youtube","vk_video","kinopoisk","mail_ru","ok","rutube","dzen","vimeo"]
      - name: safe_search
        in: query
        required: false
        description: Adult-content filtering level. moderate still returns adult videos for adult queries, and strict removes them.
        schema:
          type: string
          enum: ["off","moderate","strict"]
          default: "moderate"
      - name: page
        in: query
        required: false
        description: Page number from 1 to 50. Most queries run out of results before page 50, and a page past the last results returns the no-results error.
        schema:
          type: integer
          minimum: 1
          maximum: 50
          default: 1
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/SearchResponse"
        '400':
          description: Validation Error. There is an issue with query parameters,
            such as missing required parameters or invalid values.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
        '401':
          description: Authentication Error. The API key is missing or invalid.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
        '429':
          description: Rate Limit Exceeded. The number of allowed requests has been
            exceeded. Consider upgrading your plan or waiting for the limit to reset.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
        '500':
          description: Server Error. Internal server error.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
        '503':
          description: Timeout. We could not retrieve results in 90 seconds.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
components:
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: Authorization
      description: 'Use Bearer authentication. Format: "Bearer YOUR_API_KEY"'
    ApiKeyQuery:
      type: apiKey
      in: query
      name: api_key
      description: Pass API key as query parameter
  schemas:
    SearchResponse:
      type: object
      required:
      - search_metadata
      - search_parameters
      properties:
        search_metadata:
          "$ref": "#/components/schemas/SearchMetadata"
        search_parameters:
          "$ref": "#/components/schemas/SearchParameters"
        search_information:
          "$ref": "#/components/schemas/SearchInformation"
        videos:
          type: array
          description: Video search results.
          items:
            "$ref": "#/components/schemas/Video"
        pagination:
          "$ref": "#/components/schemas/Pagination"
        error:
          type: string
          description: Message describing an empty result set.
    SearchMetadata:
      type: object
      required:
      - id
      - status
      - created_at
      properties:
        id:
          type: string
          description: Unique identifier for the search request
        status:
          type: string
          description: Status of the search request
        created_at:
          type: string
          format: date-time
          description: Timestamp when the search was created
        request_time_taken:
          type: number
          description: Time taken to make the request in seconds
        parsing_time_taken:
          type: number
          description: Time taken to parse the results in seconds
        total_time_taken:
          type: number
          description: Total time taken for the search in seconds
        request_url:
          type: string
          description: Yandex Videos URL for this search.
        html_url:
          type: string
          description: URL to view HTML results
        json_url:
          type: string
          description: URL to view JSON results
    SearchParameters:
      type: object
      required:
      - engine
      - q
      - yandex_domain
      properties:
        engine:
          type: string
          description: Search engine to use.
          enum: ["yandex_videos"]
        q:
          type: string
          description: Video search query.
        yandex_domain:
          type: string
          description: Yandex domain to search.
          enum: ["yandex.com","yandex.ru","ya.ru","yandex.by","yandex.kz","yandex.uz","yandex.com.tr","yandex.fr","yandex.az","yandex.com.ge","yandex.com.am","yandex.co.il","yandex.lv","yandex.lt","yandex.ee","yandex.md","yandex.tm","yandex.tj","yandex.eu"]
        exclude_source:
          type: string
          description: Exclude one video source.
          enum: ["youtube","vk_video","kinopoisk","mail_ru","ok","rutube","dzen","vimeo"]
        safe_search:
          type: string
          description: Adult-content filtering level.
          enum: ["off","moderate","strict"]
        page:
          type: string
          description: Requested page number.
    SearchInformation:
      type: object
      required:
      - query_displayed
      properties:
        query_displayed:
          type: string
          description: Original search query before any automatic correction.
        did_you_mean:
          type: string
          description: Suggested spelling correction.
        showing_results_for:
          type: string
          description: Corrected query used by Yandex.
    Video:
      type: object
      required:
      - position
      - title
      - link
      - yandex_link
      - source
      - thumbnail
      properties:
        position:
          type: integer
          description: Position in the returned results.
          minimum: 1
        title:
          type: string
          description: Video title.
        link:
          type: string
          description: Direct URL of the displayed video.
          format: uri
        yandex_link:
          type: string
          description: Yandex preview URL for the video.
          format: uri
        snippet:
          type: string
          description: Video description.
        length:
          type: string
          description: Formatted video duration.
        length_seconds:
          type: integer
          description: Video duration in seconds.
          minimum: 0
        source:
          type: string
          description: Video source domain.
        channel:
          type: string
          description: Channel name.
        channel_link:
          type: string
          description: Channel URL.
          format: uri
        views:
          type: integer
          description: View count reported by Yandex.
          minimum: 0
        iso_date:
          type: string
          description: Video publication timestamp in UTC.
          format: date-time
        thumbnail:
          type: string
          description: Video thumbnail URL.
          format: uri
    Pagination:
      type: object
      required:
      - current
      properties:
        current:
          type: integer
          description: Current page number.
          minimum: 1
        previous:
          type: string
          description: Yandex URL for the previous page.
          format: uri
        next:
          type: string
          description: Yandex URL for the next page.
          format: uri
    ErrorResponse:
      type: object
      required:
      - error
      properties:
        error:
          type: string
          description: Error message describing what went wrong