openapi: 3.2.0
info:
  title: Mad AI API
  version: 0.0.0
servers:
- url: https://madapi.madkudu.com
  description: Production server
  variables: {}
- url: https://madapi.wisekudu.com
  description: Staging server
  variables: {}
security:
- ApiKeyAuth: []
tags:
- name: AI
paths:
  /ai/web-search:
    post:
      operationId: AI_webSearch
      summary: AI Web Search
      description: Performs a web search using advanced AI-powered search capabilities. This endpoint leverages the Tavily API to provide comprehensive search results with optional LLM-generated answers, image results, and content extraction.
      parameters: []
      responses:
        '200':
          description: The request has succeeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WebSearchResponse'
      tags:
      - AI
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WebSearchRequest'
components:
  schemas:
    WebSearchRequest:
      type: object
      required:
      - query
      properties:
        query:
          type: string
          description: The query to run a search on
        searchDepth:
          type: string
          enum:
          - basic
          - advanced
          description: The depth of the search. 'advanced' search is tailored to retrieve the most relevant sources and content snippets for your query, while 'basic' search provides generic content snippets from each source
        topic:
          type: string
          enum:
          - general
          - news
          description: The category of the search. Determines which agent will be used
        days:
          type: integer
          format: int32
          minimum: 1
          maximum: 365
          description: The number of days back from the current date to include in the results. Available only when using the 'news' topic
        timeRange:
          type: string
          enum:
          - day
          - week
          - month
          - year
          - d
          - w
          - m
          - y
          description: The time range back from the current date
        maxResults:
          type: integer
          format: int32
          minimum: 0
          maximum: 20
          description: The maximum number of search results to return
        chunksPerSource:
          type: integer
          format: int32
          minimum: 1
          maximum: 10
          description: Maximum number of relevant chunks returned per source. Available only when searchDepth is 'advanced'
        includeImages:
          type: boolean
          description: Include a list of query-related images in the response
        includeImageDescriptions:
          type: boolean
          description: Include a list of query-related images and their descriptions in the response
        includeAnswer:
          anyOf:
          - type: boolean
          - type: string
            enum:
            - basic
            - advanced
          description: Include an answer to the query generated by an LLM based on search results. A 'basic' (or true) answer is quick but less detailed; an 'advanced' answer is more detailed
        includeRawContent:
          anyOf:
          - type: boolean
          - type: string
            enum:
            - markdown
            - text
          description: Include the cleaned and parsed HTML content of each search result. 'markdown' or True returns search result content in markdown format. 'text' returns the plain text from the results and may increase latency
        includeDomains:
          type: array
          items:
            type: string
          description: A list of domains to specifically include in the search results
        excludeDomains:
          type: array
          items:
            type: string
          description: A list of domains to specifically exclude from the search results
        country:
          type: string
          description: Boost search results from a specific country. This will prioritize content from the selected country in the search results. Available only if topic is general
        timeout:
          type: integer
          format: int32
          minimum: 1
          maximum: 300
          description: A timeout to be used in requests to the Tavily API
    WebSearchResult:
      type: object
      required:
      - title
      - url
      - content
      - score
      properties:
        title:
          type: string
          description: The title of the search result
        url:
          type: string
          description: The URL of the search result
        content:
          type: string
          description: The most query-related content from the scraped URL
        score:
          type: number
          format: double
          description: The relevance score of the search result
        raw_content:
          type: string
          description: The parsed and cleaned HTML content of the site. This is only available if includeRawContent is set to true
        publishedDate:
          type: string
          description: The publication date of the source. This is only available if the search topic is set to news
    WebSearchResponse:
      type: object
      required:
      - query
      - images
      - results
      - response_time
      properties:
        query:
          type: string
          description: Your search query
        follow_up_questions:
          type: string
          description: Follow-up questions related to the search
        answer:
          type: string
          description: The answer to your search query, generated by an LLM based on Tavily's search results. This is only available if includeAnswer is set to true
        images:
          type: array
          items:
            $ref: '#/components/schemas/WebSearchImageResult'
          description: A list of query-related image URLs or ImageResult objects. This is only available if includeImages is set to true
        results:
          type: array
          items:
            $ref: '#/components/schemas/WebSearchResult'
          description: A list of sorted search results ranked by relevancy
        response_time:
          type: number
          format: double
          description: Your search result response time
    WebSearchImageResult:
      type: object
      required:
      - url
      properties:
        url:
          type: string
          description: The URL of the image
        description:
          type: string
          description: An LLM-generated description of the image. This is only available if includeImageDescriptions is set to true
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key