desearch-ai Web Search API

openapi: 3.2.0
info:
  title: Desearch Web 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: Web Search
paths:
  /web:
    get:
      tags:
      - Web Search
      summary: SERP Web Search API
      description: 'This API allows users to search for any information over the web. This replicates a typical search engine experience, where users can search for any information they need. Each request returns up to 20 results. Paginate with `start`, the number of results to skip: any offset works, so `start=10` returns results beginning at the 11th. A search with no results, including a `start` past the last result, returns 503 and is not charged. So does a search provider failure or timeout. An empty or whitespace-only `query` returns 422 and is not charged. A blocked query returns 200 with no results and is not charged.


        Billing metadata: successful billable responses include the `X-Desearch-Cost-Usd`, `X-Desearch-Usage-Count`, `X-Desearch-Service`, and `X-Desearch-Currency` headers. JSON object responses also include optional `cost_usd`, `usage_count`, `service`, and `currency` fields. Current prices are at https://desearch.ai/pricing. JSON arrays, text, and streaming responses keep their body shape and expose billing metadata only through headers.'
      operationId: web_search_web_get
      parameters:
      - name: query
        in: query
        required: true
        schema:
          type: string
          pattern: \S
          description: The search query string, e.g., 'latest news on AI'. An empty or whitespace-only query returns 422 and is not charged.
          title: Query
        description: The search query string, e.g., 'latest news on AI'. An empty or whitespace-only query returns 422 and is not charged.
        example: latest news on AI
      - name: start
        in: query
        required: false
        schema:
          type: integer
          maximum: 100
          minimum: 0
          description: 'How many results to skip, for pagination. Any offset works, with no rounding: 0 (default) returns results from the 1st, 10 from the 11th, 20 from the 21st, and so on. Each request returns up to 20 results. Must be between 0 and 100. A value outside that range returns 422 and is not charged.'
          default: 0
          title: Start
        description: 'How many results to skip, for pagination. Any offset works, with no rounding: 0 (default) returns results from the 1st, 10 from the 11th, 20 from the 21st, and so on. Each request returns up to 20 results. Must be between 0 and 100. A value outside that range returns 422 and is not charged.'
        example: 20
      responses:
        '200':
          description: 'A JSON object mapping Web Search to its search results. Charged once per request. A blocked query is a 200 with `data: []` and is not charged.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WebSearchResultsResponse'
          headers:
            X-Desearch-Cost-Usd:
              description: Billable request cost in US dollars. Current prices are at https://desearch.ai/pricing.
              schema:
                type: number
                format: float
            X-Desearch-Usage-Count:
              description: Billable usage units applied to this request.
              schema:
                type: integer
                example: 10
            X-Desearch-Service:
              description: Priced service name used to calculate the request cost, as listed at https://desearch.ai/pricing (for example "Web Search" or "X Search").
              schema:
                type: string
                example: Web Search
            X-Desearch-Currency:
              description: Currency for cost metadata. Currently always USD.
              schema:
                type: string
                example: USD
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnauthorizedResponse'
        '422':
          description: Validation Error, for example `query` is missing, empty or only whitespace, or `start` is negative or above 100. The search provider is not called and the request is not charged.
          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: 'The search returned no results, for example `start` is past the last result (`error_code: upstream_empty`), or the search provider failed (`error_code: upstream_failed`) or timed out (`error_code: upstream_timeout`). The request is not charged (`X-Desearch-Cost-Usd: 0`, `X-Desearch-Usage-Count: 0`).'
        '301':
          description: Moved Permanently
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MovedPermanentlyResponse'
        '304':
          description: Not Modified
  /web/extract:
    get:
      tags:
      - Web Search
      summary: Extract API
      description: 'Fetch a public URL and return its content as text, markdown or HTML. `format=text` returns `text/plain; charset=utf-8`, `format=markdown` returns `text/markdown; charset=utf-8` and `format=html` returns `text/html; charset=utf-8`. `format=markdown` keeps headings, lists, tables and code: the main content of articles and docs, and the whole page without its navigation otherwise. By default `format=text` returns the page''s main content (the article or main block, the way reader views do), which can leave out other sections such as tables, notices and sidebars; set `full_page=true` to get all visible text of the page instead, one block per line, with table cells separated by ` | `. Pages that cannot be served answer with an `error_code` and are not charged.


        Billing metadata: successful billable responses include the `X-Desearch-Cost-Usd`, `X-Desearch-Usage-Count`, `X-Desearch-Service`, and `X-Desearch-Currency` headers. JSON object responses also include optional `cost_usd`, `usage_count`, `service`, and `currency` fields. Current prices are at https://desearch.ai/pricing. JSON arrays, text, and streaming responses keep their body shape and expose billing metadata only through headers.'
      operationId: desearch_crawl_web_extract_get
      parameters:
      - name: url
        in: query
        required: true
        schema:
          type: string
          description: URL to extract content from
          title: Url
        description: URL to extract content from
        example: https://en.wikipedia.org/wiki/Artificial_intelligence
      - name: format
        in: query
        required: false
        schema:
          enum:
          - html
          - text
          - markdown
          type: string
          description: 'Format of the content to be returned: ''text'', ''markdown'' or ''html''. Default is ''text''. ''text'' is sent as text/plain, ''markdown'' as text/markdown and ''html'' as text/html.'
          default: text
          title: Format
        description: 'Format of the content to be returned: ''text'', ''markdown'' or ''html''. Default is ''text''. ''text'' is sent as text/plain, ''markdown'' as text/markdown and ''html'' as text/html.'
        example: markdown
      - name: js
        in: query
        required: false
        schema:
          enum:
          - 'true'
          - 'false'
          type: string
          description: Render the page with a headless browser before extracting content. Use for SPAs or pages whose body is populated by JavaScript. Must be exactly `true` or `false` (case-sensitive); enables a separate billing tier when set to `true`.
          default: 'false'
          title: Js
        description: Render the page with a headless browser before extracting content. Use for SPAs or pages whose body is populated by JavaScript. Must be exactly `true` or `false` (case-sensitive); enables a separate billing tier when set to `true`.
      - name: wait
        in: query
        required: false
        schema:
          anyOf:
          - type: integer
            maximum: 30000
            minimum: 0
          - type: 'null'
          description: Optional extra wait in milliseconds after the page loads. Only applied when ``js=true``.
          title: Wait
        description: Optional extra wait in milliseconds after the page loads. Only applied when ``js=true``.
      - name: full_page
        in: query
        required: false
        schema:
          enum:
          - 'true'
          - 'false'
          type: string
          description: With `format=text`, return all visible text of the page instead of its main content. Must be exactly `true` or `false`. Applies only to `format=text`; `markdown` picks the main content or the whole page itself.
          default: 'false'
          title: Full Page
        description: With `format=text`, return all visible text of the page instead of its main content. Must be exactly `true` or `false`. Applies only to `format=text`; `markdown` picks the main content or the whole page itself.
      responses:
        '200':
          description: Extracted content of the web link
          content:
            text/plain:
              schema:
                type: string
            text/html:
              schema:
                type: string
            text/markdown:
              schema:
                type: string
          headers:
            X-Desearch-Cost-Usd:
              description: Billable request cost in US dollars. Current prices are at https://desearch.ai/pricing.
              schema:
                type: number
                format: float
            X-Desearch-Usage-Count:
              description: Billable usage units applied to this request.
              schema:
                type: integer
                example: 10
            X-Desearch-Service:
              description: Priced service name used to calculate the request cost, as listed at https://desearch.ai/pricing (for example "Web Search" or "X Search").
              schema:
                type: string
            X-Desearch-Currency:
              description: Currency for cost metadata. Currently always USD.
              schema:
                type: string
                example: USD
        '401':
          description: Unauthorized
          content:
            text/plain:
              schema:
                $ref: '#/components/schemas/UnauthorizedResponse'
        '404':
          description: Not charged. `error_code` is `page_not_found` when the site answered 404 or 410, or `no_content` when the page has no text.
        '422':
          description: 'Not charged. Either a validation error, or `error_code` `js_required`: the page only shows its content after JavaScript runs (an app shell, or a page that asks to enable JavaScript). Retry with `js=true`.'
          content:
            text/plain:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
        '429':
          description: Too Many Requests
          content:
            text/plain:
              schema:
                $ref: '#/components/schemas/TooManyRequestsResponse'
        '500':
          description: Internal Server Error
          content:
            text/plain:
              schema:
                $ref: '#/components/schemas/InternalServerErrorResponse'
        '503':
          description: Not charged. `error_code` is `blocked` when the site refused the request or answered with a bot check (a CAPTCHA or "verifying your request" page) instead of the page, `upstream_timeout` when the page took too long, and `upstream_failed` for any other crawler failure.
        '301':
          description: Moved Permanently
          content:
            text/plain:
              schema:
                $ref: '#/components/schemas/MovedPermanentlyResponse'
        '304':
          description: Not Modified
  /web/crawl:
    get:
      tags:
      - Web Search
      summary: Extract API (Legacy)
      description: 'Deprecated compatibility alias for `GET /web/extract`. Existing clients can continue using this route during the migration. `format=text` returns `text/plain; charset=utf-8` and `format=html` returns `text/html; charset=utf-8`.


        Billing metadata: successful billable responses include the `X-Desearch-Cost-Usd`, `X-Desearch-Usage-Count`, `X-Desearch-Service`, and `X-Desearch-Currency` headers. JSON object responses also include optional `cost_usd`, `usage_count`, `service`, and `currency` fields. Current prices are at https://desearch.ai/pricing. JSON arrays, text, and streaming responses keep their body shape and expose billing metadata only through headers.'
      operationId: desearch_crawl_web_crawl_get
      deprecated: true
      parameters:
      - name: url
        in: query
        required: true
        schema:
          type: string
          description: URL to extract content from
          title: Url
        description: URL to extract content from
        example: https://en.wikipedia.org/wiki/Artificial_intelligence
      - name: format
        in: query
        required: false
        schema:
          enum:
          - html
          - text
          - markdown
          type: string
          description: 'Format of the content to be returned: ''text'', ''markdown'' or ''html''. Default is ''text''. ''text'' is sent as text/plain, ''markdown'' as text/markdown and ''html'' as text/html.'
          default: text
          title: Format
        description: 'Format of the content to be returned: ''text'', ''markdown'' or ''html''. Default is ''text''. ''text'' is sent as text/plain, ''markdown'' as text/markdown and ''html'' as text/html.'
        example: markdown
      - name: js
        in: query
        required: false
        schema:
          enum:
          - 'true'
          - 'false'
          type: string
          description: Render the page with a headless browser before extracting content. Use for SPAs or pages whose body is populated by JavaScript. Must be exactly `true` or `false` (case-sensitive); enables a separate billing tier when set to `true`.
          default: 'false'
          title: Js
        description: Render the page with a headless browser before extracting content. Use for SPAs or pages whose body is populated by JavaScript. Must be exactly `true` or `false` (case-sensitive); enables a separate billing tier when set to `true`.
      - name: wait
        in: query
        required: false
        schema:
          anyOf:
          - type: integer
            maximum: 30000
            minimum: 0
          - type: 'null'
          description: Optional extra wait in milliseconds after the page loads. Only applied when ``js=true``.
          title: Wait
        description: Optional extra wait in milliseconds after the page loads. Only applied when ``js=true``.
      - name: full_page
        in: query
        required: false
        schema:
          enum:
          - 'true'
          - 'false'
          type: string
          description: With `format=text`, return all visible text of the page instead of its main content. Must be exactly `true` or `false`. Applies only to `format=text`; `markdown` picks the main content or the whole page itself.
          default: 'false'
          title: Full Page
        description: With `format=text`, return all visible text of the page instead of its main content. Must be exactly `true` or `false`. Applies only to `format=text`; `markdown` picks the main content or the whole page itself.
      responses:
        '200':
          description: Content of the web link
          content:
            text/plain:
              schema:
                type: string
            text/html:
              schema:
                type: string
            text/markdown:
              schema:
                type: string
          headers:
            X-Desearch-Cost-Usd:
              description: Billable request cost in US dollars. Current prices are at https://desearch.ai/pricing.
              schema:
                type: number
                format: float
            X-Desearch-Usage-Count:
              description: Billable usage units applied to this request.
              schema:
                type: integer
                example: 10
            X-Desearch-Service:
              description: Priced service name used to calculate the request cost, as listed at https://desearch.ai/pricing (for example "Web Search" or "X Search").
              schema:
                type: string
                example: Extract API
            X-Desearch-Currency:
              description: Currency for cost metadata. Currently always USD.
              schema:
                type: string
                example: USD
        '401':
          description: Unauthorized
          content:
            text/plain:
              schema:
                $ref: '#/components/schemas/UnauthorizedResponse'
        '404':
          description: Not charged. `error_code` is `page_not_found` when the site answered 404 or 410, or `no_content` when the page has no text.
        '422':
          description: 'Not charged. Either a validation error, or `error_code` `js_required`: the page only shows its content after JavaScript runs (an app shell, or a page that asks to enable JavaScript). Retry with `js=true`.'
          content:
            text/plain:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
        '429':
          description: Too Many Requests
          content:
            text/plain:
              schema:
                $ref: '#/components/schemas/TooManyRequestsResponse'
        '500':
          description: Internal Server Error
          content:
            text/plain:
              schema:
                $ref: '#/components/schemas/InternalServerErrorResponse'
        '503':
          description: Not charged. `error_code` is `blocked` when the site refused the request or answered with a bot check (a CAPTCHA or "verifying your request" page) instead of the page, `upstream_timeout` when the page took too long, and `upstream_failed` for any other crawler failure.
        '301':
          description: Moved Permanently
          content:
            text/plain:
              schema:
                $ref: '#/components/schemas/MovedPermanentlyResponse'
        '304':
          description: Not Modified
components:
  schemas:
    WebSearchResultItem:
      properties:
        title:
          type: string
          title: Title
          description: EXCLUSIVE Major coffee buyers face losses as Colombia ...
        snippet:
          type: string
          title: Snippet
          description: Coffee farmers in Colombia, the world's No. 2 arabica producer, have failed to deliver up to 1 million bags of beans this year or nearly 10% ...
        link:
          type: string
          maxLength: 2083
          minLength: 1
          format: uri
          title: Link
          description: https://www.reuters.com/world/americas/exclusive-major-coffee-buyers-face-losses-colombia-farmers-fail-deliver-2021-10-11/
        highlights:
          anyOf:
          - items:
              type: string
            type: array
          - type: 'null'
          title: Highlights
          description: 'Key excerpts from the page. Returned unless the request sets `highlights: false`.'
        text:
          anyOf:
          - type: string
          - type: 'null'
          title: Text
          description: 'Full page text. Returned only when the request sets `page_text: true`.'
      type: object
      required:
      - title
      - snippet
      - link
      title: WebSearchResultItem
      example:
        link: https://www.reuters.com/world/americas/exclusive-major-coffee-buyers-face-losses-colombia-farmers-fail-deliver-2021-10-11/
        snippet: Coffee farmers in Colombia, the world's No. 2 arabica producer, have failed to deliver up to 1 million bags of beans this year or nearly 10% ...
        title: EXCLUSIVE Major coffee buyers face losses as Colombia ...
    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
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    MovedPermanentlyResponse:
      properties:
        detail:
          additionalProperties:
            anyOf:
            - type: string
            - type: integer
          type: object
          title: Detail
          example:
            error_code: 301
            location: https://new-url.com
            message: Moved Permanently
      type: object
      required:
      - detail
      title: MovedPermanentlyResponse
    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
    WebSearchResultsResponse:
      properties:
        data:
          items:
            $ref: '#/components/schemas/WebSearchResultItem'
          type: array
          title: Data
      type: object
      required:
      - data
      title: WebSearchResultsResponse
    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