desearch-ai Search API

openapi: 3.2.0
info:
  title: Desearch Search API
  description: The Desearch API is a powerful suite of AI-driven tools designed to integrate natural language processing, AI-powered search, image generation, and data extraction into your applications. Whether you’re building intelligent search engines, automating content creation, analyzing text data, or generating AI-based media, Desearch provides a robust and scalable solution.
  version: 1.0.0
servers:
- url: https://api.desearch.ai
security:
- ApiKeyAuth: []
tags:
- name: Search
paths:
  /search:
    post:
      tags:
      - Search
      summary: Search API
      description: 'Search the web and return ranked pages, each with the passage that best matches the query.


        Billing metadata: responses include `cost_usd`, `usage_count`, `service`, and `currency` fields in the JSON body.'
      operationId: search_api_search_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SearchRequest'
        required: true
      responses:
        '200':
          description: Ranked results and the cost of the request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SearchResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnauthorizedResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
        '429':
          description: Too Many Requests
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TooManyRequestsResponse'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InternalServerErrorResponse'
        '503':
          description: Search unavailable
        '400':
          description: Invalid JSON body
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BadRequestResponse'
components:
  schemas:
    SearchResult:
      properties:
        url:
          type: string
          title: Url
        title:
          type: string
          title: Title
        published_date:
          anyOf:
          - type: string
          - type: 'null'
          title: Published Date
          description: Publication date (YYYY-MM-DD) when known.
        highlights:
          anyOf:
          - items:
              type: string
            type: array
          - type: 'null'
          title: Highlights
          description: 'Returned unless the request sets `highlights: false`.'
        page_text:
          anyOf:
          - type: string
          - type: 'null'
          title: Page Text
          description: 'Returned only when the request sets `page_text: true`.'
      type: object
      required:
      - url
      - title
      title: SearchResult
    TooManyRequestsResponse:
      properties:
        detail:
          additionalProperties:
            anyOf:
            - type: string
            - type: integer
          type: object
          title: Detail
          example:
            error_code: 429
            message: Too Many Requests
            retry_after: 60 seconds
      type: object
      required:
      - detail
      title: TooManyRequestsResponse
    InternalServerErrorResponse:
      properties:
        detail:
          additionalProperties:
            anyOf:
            - type: string
            - type: integer
          type: object
          title: Detail
          example:
            description: An unexpected error occurred on the server.
            error_code: 500
            message: Internal Server Error
      type: object
      required:
      - detail
      title: InternalServerErrorResponse
    SearchResponse:
      properties:
        results:
          items:
            $ref: '#/components/schemas/SearchResult'
          type: array
          title: Results
        cost_usd:
          type: number
          title: Cost Usd
          description: Cost charged for this request in USD.
        usage_count:
          type: integer
          title: Usage Count
          description: Billable usage units for this request.
        service:
          type: string
          title: Service
          description: Pricing service used for the charge.
        currency:
          type: string
          title: Currency
          description: Currency of `cost_usd`.
      type: object
      required:
      - results
      - cost_usd
      - usage_count
      - service
      - currency
      title: SearchResponse
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
            - type: string
            - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
      type: object
      required:
      - loc
      - msg
      - type
      title: ValidationError
    SearchRequest:
      properties:
        query:
          type: string
          maxLength: 2000
          minLength: 1
          title: Query
          description: Search query.
          examples:
          - Who won the 2024 Nobel Prize in Physics?
        mode:
          type: string
          enum:
          - fast
          - balanced
          title: Mode
          description: '`fast` returns results sooner. `balanced` favors relevance.'
          default: balanced
        count:
          type: integer
          multipleOf: 5.0
          maximum: 20.0
          minimum: 10.0
          title: Count
          description: 'Number of results to return: 10, 15 or 20.'
          default: 10
        start_date:
          anyOf:
          - type: string
            format: date
          - type: 'null'
          title: Start Date
          description: Only return pages published on or after this date (YYYY-MM-DD).
          examples:
          - '2026-01-01'
        end_date:
          anyOf:
          - type: string
            format: date
          - type: 'null'
          title: End Date
          description: Only return pages published on or before this date (YYYY-MM-DD).
          examples:
          - '2026-09-17'
        highlights:
          type: boolean
          title: Highlights
          description: Include the passage that best matches the query.
          default: true
        page_text:
          type: boolean
          title: Page Text
          description: Include the full page text.
          default: false
      type: object
      required:
      - query
      title: SearchRequest
    BadRequestResponse:
      title: BadRequestResponse
      type: object
      properties:
        detail:
          type: string
          title: Detail
          example: Invalid JSON body
      required:
      - detail
    UnauthorizedResponse:
      properties:
        detail:
          type: string
          title: Detail
          example: Invalid API key
      type: object
      required:
      - detail
      title: UnauthorizedResponse
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: Authorization