POST/desearch/ai/search

AI Contextual Search

The Desearch API allows you to perform AI-powered web searches, gathering relevant information from multiple sources, including web pages, research papers, and social media discussions. 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. For example, `usage_count=10` at `$0.015 / 1,000` resolves to `cost_usd=0.00015`. JSON arrays, text, and streaming responses keep their body shape and expose billing metadata only through headers.

Base URL

https://api.desearch.ai

Implementation guidance

Use AI Contextual Search when your application needs search-grounded AI resultswithout maintaining its own crawler, social-data pipeline, or retrieval infrastructure. The endpoint returns structured data that can be consumed by agents, research tools, dashboards, and retrieval-augmented generation workflows. Keep the request focused on the minimum fields your workflow needs so responses remain fast and easy to validate.

Send requests to POST /desearch/ai/search with your Desearch API key in the authorization header. Treat the key as a server-side secret, validate all required parameters before sending the request, and handle non-2xx responses explicitly. Production integrations should use sensible timeouts, retry only transient failures with backoff, and record the response status and request identifier for troubleshooting.

Test the example request below before integrating it into a larger workflow. Confirm that the returned fields, links, and timestamps meet your freshness requirements, then add schema validation at the application boundary. For agentic systems, preserve source URLs with the generated answer so users can inspect evidence and your application can avoid presenting unsupported claims.

Body Parameters

promptstringrequired

Search query prompt

toolsarrayrequired

A list of tools to be used for the search

start_datestring

The start date for the search query. Format: YYYY-MM-DDTHH:MM:SSZ (UTC)

end_datestring

The end date for the search query. Format: YYYY-MM-DDTHH:MM:SSZ (UTC)

date_filterstring

Deprecated relative window. When set (and no start_date/end_date), it is translated to start_date/end_date. Prefer start_date/end_date.

streamingboolean

Whether to stream results

Default: false

result_typestring

The result type to be used for the search

Default: LINKS_WITH_FINAL_SUMMARY

modestring

Speed/quality mode for the search (fast, balanced, deep). fast is web-only: X (Twitter) search supports balanced and deep.

system_messagestring

The system message to be used for the search

Default:

scoring_system_messagestring

System message for scoring the response

countstring

The number of results to return per source. Min 10. Max 200.

Default: 10

include_domainsarray of strings

Restrict Web Search results to these domains.

One item per line, or a JSON array. Sent as an array.

exclude_domainsarray of strings

Drop Web Search results from these domains.

One item per line, or a JSON array. Sent as an array.

highlightsboolean

Include highlights (token-efficient key excerpts from each page) on Web Search results.

Default: true

page_textboolean

Include the full page text on each Web Search result. Responses get significantly larger.

Default: false

Responses

200A JSON object mapping tool names to their search results.

301Moved Permanently

304Not Modified

400Invalid JSON body

401Unauthorized

422Validation Error

429Too Many Requests

500Internal Server Error

503Search unavailable

Annotated 200 (non-stream)

A typical JSON object includes search[] (title, link, snippet, highlights as a list) and optional completion when result_type is LINKS_WITH_FINAL_SUMMARY. Do not document published_date on these items.

{
  "search": [
    {
      "title": "What is Bittensor?",
      "link": "https://www.thebigwhale.io/tokens/bittensor",
      "snippet": "Bittensor (TAO) is a decentralized machine learning network.",
      "highlights": ["Bittensor transforms machine intelligence into a tradable commodity."]
    }
  ],
  "completion": "Bittensor is a decentralized, open-source machine learning network."
}

Billing headers on every response: X-Desearch-Cost-Usd, X-Desearch-Usage-Count, X-Desearch-Service, X-Desearch-Currency. JSON object bodies may also include cost_usd, usage_count, service, and currency. Streaming responses expose billing through headers only.

For sources without a completion, use POST /desearch/ai/search/links/web or POST /desearch/ai/search/links/twitter. See the Search API guide.

Authorization

Your API key is sent in the Authorization header.

Request

curl -X POST "https://api.desearch.ai/desearch/ai/search" \
  -H "Authorization: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "prompt": "Bittensor",
  "tools": [
    "web",
    "twitter"
  ],
  "streaming": false
}'

ResponseSchema

{
  "search": [
    {
      "title": "Overview of the topic",
      "link": "https://example.com/articles/topic-overview",
      "snippet": "A short excerpt from a public web page that matches the query.",
      "highlights": [
        "The page summarizes the topic and points to the original source."
      ]
    }
  ],
  "tweets": [
    {
      "id": "1000000000000000001",
      "text": "A short public post about the same topic.",
      "url": "https://example.com/posts/1000000000000000001",
      "created_at": "2026-01-15T12:00:00.000Z",
      "like_count": 4,
      "retweet_count": 1,
      "reply_count": 2,
      "user": {
        "username": "example_user",
        "name": "Example User"
      }
    }
  ],
  "completion": "A short summary of the matching web pages and posts. The linked sources contain the full text."
}

Possible status codes:

200401422429500