Search API - APIs | Desearch Docs

Use AI Search, the Desearch AI search API, when a natural-language prompt should pull evidence from sources you choose (web and twitter, with optional domain filters on web), with an optional summary. Supported tools: web, twitter. Other values are unsupported and may be rejected (for example, youtube returns 422). This page gets Humans and Agents to a successful 200 without leaving for the first call.

Full schemas: AI Search API reference. Typed clients: Python SDK · JavaScript SDK.

Who this page is for

Humans

Create a Console account, mint an API key, copy one of the tabs below, and confirm a 200.

Agents / tool authors

Same endpoint, auth, and minimal JSON. Treat search[] (and optional completion) as the tool result. Read billing headers on every response.

Before you call

Create an account in Desearch Console.
Create an API key under API Keys. Details: Auth and API keys.
Store the key as DESEARCH_API_KEY (server-side only).

Auth (preferred): Authorization: $DESEARCH_API_KEY (raw key).
Prefer no Bearer prefix in examples. The API also accepts a Bearer-prefixed value; examples stay raw for Console copy-paste.

Base URL: https://api.desearch.ai
Endpoint: POST /desearch/ai/search

First successful call

Minimal REST body: prompt, tools, and streaming: false. Optional: count, date_filter.
SDK tabs use the same prompt / tools / count / date_filter. Do not pass streaming into Python or JavaScript SDK methods (not in current signatures).

Install if needed: pip install desearch-py · npm install desearch-js (Node.js 20.18.1 or later).

bash

curl --request POST 'https://api.desearch.ai/desearch/ai/search' \
  --header "Authorization: $DESEARCH_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
    "prompt": "latest research on AI search benchmarks",
    "tools": ["web", "twitter"],
    "streaming": false,
    "count": 10
  }'

What success looks like

A typical 200 JSON object includes:

search: array of citeable result objects (web-family tools)
tweets: array of X post objects when twitter is in tools (can appear together with search)
completion: optional summary when you request the summary path (see Annotated response)
warnings: optional list when a requested tool returns no results (for example code: tool_no_results)

When tools includes both web and twitter, a successful non-streaming call can return both search and tweets in the same JSON body. An empty search or tweets array (or a tool_no_results warning) means that tool finished with no hits; it does not mean the other tool failed.

Annotated response

To also return a summary in completion, set result_type to LINKS_WITH_FINAL_SUMMARY on the REST body.

json

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

Field	Role
`search[].link`	Citeable URL
`search[].title` / `snippet` / `highlights`	Evidence text (`highlights` is a list)
`completion`	Model summary on the summary path

Do not document published_date on AI Search items (absent on live 200).

Web + X in one call

REST short enum: tools: ["web", "twitter"] (with streaming: false). A live check returned both search and tweets in one JSON object (each length matched count on that run). Truncated shape (placeholders, not live URLs):

json

{
  "search": [
    {
      "title": "Example result",
      "link": "https://example.com/result",
      "snippet": "Short source text.",
      "highlights": ["Short source text."]
    }
  ],
  "tweets": [
    {
      "id": "0000000000000000000",
      "text": "Example post text.",
      "url": "https://x.com/example/status/0000000000000000000"
    }
  ],
  "completion": "Short summary of the sources."
}

Do not promise that LINKS_WITH_FINAL_SUMMARY always fills both arrays. Hosted checks have returned tweets with hits while search was empty and warnings included tool_no_results for web. Treat empty arrays and warnings as valid outcomes.

For sources without a completion, as one JSON object, use POST /desearch/ai/search/links/web (search_results) or POST /desearch/ai/search/links/twitter (miner_tweets).

result_type: ONLY_LINKS on POST /desearch/ai/search is not a cost-only JSON object. The 2026-10-01 live check returned text/event-stream: events with "type": "search" and a content array of link objects (title, link, snippet, highlights). It is not the first-call example on this page. Hosted MCP ai-search with ONLY_LINKS returns JSON search instead of that stream. See MCP.

Billing metadata

Header	Meaning
`X-Desearch-Cost-Usd`	Request cost in USD
`X-Desearch-Usage-Count`	Billable usage units
`X-Desearch-Service`	Pricing service key for the request
`X-Desearch-Currency`	Currency code

JSON object bodies may also include cost_usd, usage_count, service, and currency. JSON arrays, plain text, and streaming responses expose billing only via headers. Always read headers when you stream or when the body is not a JSON object.

This page does not list public dollar rates. Check Console for the rates on your account.

Useful parameters (first call)

Field	Required	Notes
`prompt`	yes	Natural-language question
`tools`	yes	Supported tools: web, twitter. Other values are unsupported and may be rejected (for example, youtube returns 422). To search Reddit, call GET /web and put site:reddit.com in the query
`streaming`	REST only	Set `false` on curl for a single JSON body. Not an SDK `ai_search` / `aiSearch` argument
`count`	no	Integer results per source. Min 10, max 200, default 10. Send a JSON number (`"count": 10`), not a string.
`date_filter`	no	Optional enum (e.g. `PAST_24_HOURS`, `PAST_WEEK`, `PAST_MONTH`, `PAST_YEAR`). On AI Search, date filtering applies to X results. When omitted, no date window is sent. Do not treat `start_date` / `end_date` as a web date filter on this page; for X absolute dates use the X API
`result_type`	REST optional	Use `LINKS_WITH_FINAL_SUMMARY` when you want `completion`. `ONLY_LINKS` on this REST endpoint returns SSE `search` events (link objects, no completion). For one JSON object of links, use the links endpoints

count is an integer. For AI Search and AI Search links, send a JSON number from 10 to 200 (default 10). It is results per source. A numeric string such as "10" can be coerced; a non-numeric string returns 422. Send a JSON number.

Next steps

Streaming AI Search when you need REST streaming: true
Which endpoint should I use? for AI Search vs links vs plain Search vs SERP vs Extract vs X/social
Extract API guide when you already have a URL and need the page body
AI Search API reference
Python SDK · JavaScript SDK