openapi.yml

openapi: 3.1.0
info:
  title: Search API
  version: 1.0.0
servers:
  - url: https://na-us-1.presearch.com
paths:
  /v1/search:
    get:
      summary: Search for default results
      description: Returns a list of search results
      parameters:
        - $ref: '#/components/parameters/SearchQuery'
        - $ref: '#/components/parameters/UserIP'
        - $ref: '#/components/parameters/LangParameter'
        - $ref: '#/components/parameters/TimeParameter'
        - $ref: '#/components/parameters/SearchResultsLocation'
        - $ref: '#/components/parameters/PageParameter'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SearchResponse'
        '401':
          description: Unauthorized
        '402':
          description: Payment Required
        '422':
          description: Unprocessable Entity
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnprocessableEntity'
      security:
        - BearerAuth: []

components:
  parameters:
    SearchQuery:
      name: q
      in: query
      required: true
      schema:
        type: string
      description: The search query.

    UserIP:
      name: ip
      in: query
      required: false
      schema:
        type: string
      description: The IP address of the user.

    LangParameter:
      name: lang
      in: query
      required: false
      schema:
        type: string
      description: The language for search results (BCP 47 language code format).
      example: 'en-US'

    TimeParameter:
      name: time
      in: query
      required: false
      schema:
        type: string
        enum:
          - any
          - day
          - week
          - month
          - year
      description: >
        The desired timeframe for the search results (optional).
        Valid values:
        - 'any': Any time
        - 'day': Last day
        - 'week': Last week
        - 'month': Last month
        - 'year': Last year

    SearchResultsLocation:
      name: search_results_location
      in: query
      required: false
      schema:
        type: string
      description: The location where search results should be localized or filtered (optional).

    PageParameter:
      name: page
      in: query
      required: false
      schema:
        type: string
      description: The page number for paginating search results (optional).

  schemas:
    SearchResponse:
      type: object
      properties:
        data:
          type: object
          properties:
            standardResults:
              type: array
              items:
                $ref: '#/components/schemas/StandardResult'
            infoSection:
              type: object
              properties:
                title:
                  type: string
                subtitle:
                  type: string
                description:
                  type: string
                image:
                  type: string
                about:
                  type: array
                  items:
                    type: string
            specialSections:
              type: object
              properties:
                topStories:
                  type: array
                  items:
                    $ref: '#/components/schemas/TopStory'
                videos:
                  type: array
                  items:
                    $ref: '#/components/schemas/Video'
        links:
          type: object
          properties:
            first:
              type: string
            last:
              type: string
            prev:
              type: string|null
            next:
              type: string|null
        meta:
          type: object
          properties:
            current_page:
              type: number
            from:
              type: number
            last_page:
              type: number
            path:
              type: string
            pages:
              type: number

    StandardResult:
      type: object
      properties:
        title:
          type: string
        link:
          type: string
        description:
          type: string

    TopStory:
      type: object
      properties:
        title:
          type: string
        link:
          type: string
        image:
          type: string
        source:
          type: string

    Video:
      type: object
      properties:
        title:
          type: string
        link:
          type: string
        source:
          type: string

    UnprocessableEntity:
      type: object
      properties:
        error:
          type: string

  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT