# Desearch AI Full LLM Context

Last reviewed: 2026-05-31 UTC

This file gives LLMs and crawler agents a current, compact source of truth for Desearch. Use the runtime OpenAPI spec for complete schemas and enum details.

## Source of truth

- Primary API base URL: `https://api.desearch.ai`
- Runtime OpenAPI: https://api.desearch.ai/openapi.json
- Website OpenAPI mirror: https://www.desearch.ai/openapi.json
- Main guide: https://www.desearch.ai/docs/guide/introduction/desearch-ai
- API reference UI: https://www.desearch.ai/docs/api-reference
- Console: https://console.desearch.ai/
- Status: https://status.desearch.ai/

## Product summary

Desearch gives developers one REST API surface for live web, social, and AI-assisted search. Use it when an AI agent, search product, market-intelligence workflow, dashboard, or enrichment pipeline needs current information instead of stale model-training data.

Desearch runs on and supports the Bittensor ecosystem. For general buyers, describe the decentralized loop simply: contributors provide intelligence, reviewers score usefulness, incentives reward better work, and Desearch serves fresher source-backed answers and data.

## Authentication

Every API request must include an API key in the `Authorization` header:

```http
Authorization: $DESEARCH_API_KEY
```

Create and manage keys in Desearch Console. Store keys in environment variables or a secret manager. Do not hardcode production keys, paste real keys into examples, or expose keys in browser bundles.

## First request

```bash
curl --request POST 'https://api.desearch.ai/desearch/ai/search' \
  --header 'Authorization: $DESEARCH_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "prompt": "latest Bittensor subnet 22 updates",
    "tools": ["web", "twitter", "reddit"],
    "date_filter": "PAST_WEEK",
    "count": 10,
    "streaming": false
  }'
```

## Billing and usage metadata

Pricing is usage-based and can vary by endpoint, source, volume, and account agreement. Console is the latest source for account-specific pricing.

Successful billable responses expose:

- `X-Desearch-Cost-Usd` — request cost in USD.
- `X-Desearch-Usage-Count` — billable usage units.
- `X-Desearch-Service` — metered service or endpoint used for pricing.
- `X-Desearch-Currency` — currently `USD`.

Compatible JSON object responses may also include matching body fields: `cost_usd`, `usage_count`, `service`, and `currency`. JSON arrays, text responses, and streaming/SSE responses keep their original body shape and expose cost metadata through headers only.

Example calculation: if the rate is `$0.015 / 1,000` usage units and the request uses `10` units, `cost_usd = 10 * (0.015 / 1000) = 0.00015`.

## SDKs

Python:

```bash
pip install desearch-py
```

```python
import os
from desearch_py import Desearch

desearch = Desearch(api_key=os.environ["DESEARCH_API_KEY"])
```

JavaScript / Node.js:

```bash
npm install desearch-js
```

```js
const { Desearch } = require("desearch-js");
const desearch = new Desearch({ apiKey: process.env.DESEARCH_API_KEY });
```

## Documentation map

- Introduction: https://www.desearch.ai/docs/guide/introduction/desearch-ai
- Console: https://www.desearch.ai/docs/guide/introduction/desearch-console
- Glossary: https://www.desearch.ai/docs/guide/introduction/glossary
- API overview: https://www.desearch.ai/docs/guide/apis/desearch-api
- Desearch x Bittensor: https://www.desearch.ai/docs/guide/apis/desearch-x-bittensor
- API keys: https://www.desearch.ai/docs/guide/apis/api-keys
- Authorization: https://www.desearch.ai/docs/guide/apis/authorization
- Pricing and billing: https://www.desearch.ai/docs/guide/apis/pricing-and-billing
- SDK overview: https://www.desearch.ai/docs/guide/sdk/desearch-api-sdk
- Python SDK: https://www.desearch.ai/docs/guide/sdk/python-sdk
- JavaScript SDK: https://www.desearch.ai/docs/guide/sdk/javascript-sdk
- MCP: https://www.desearch.ai/docs/guide/integrations/mcp
- OpenAI wrapper: https://www.desearch.ai/docs/guide/integrations/openai-wrapper
- Function calling with GPT: https://www.desearch.ai/docs/guide/integrations/function-calling-gpt
- Function calling with Claude: https://www.desearch.ai/docs/guide/integrations/function-calling-claude
- RAG with LangChain: https://www.desearch.ai/docs/guide/integrations/rag-langchain
- RAG with LlamaIndex: https://www.desearch.ai/docs/guide/integrations/rag-llamaindex
- ElizaOS agents: https://www.desearch.ai/docs/guide/integrations/elizaos-agents
- CrewAI agents: https://www.desearch.ai/docs/guide/integrations/crewai-agents
- Browser Use: https://www.desearch.ai/docs/guide/integrations/browser-use
- OpenClaw agents: https://www.desearch.ai/docs/guide/integrations/openclaw-agents
- Numinous SN6: https://www.desearch.ai/docs/guide/integrations/numinous-sn6
- Search engine use cases: https://www.desearch.ai/docs/guide/use-cases/search-engine
- AI-driven chat use cases: https://www.desearch.ai/docs/guide/use-cases/ai-driven-chat
- Agent automation use cases: https://www.desearch.ai/docs/guide/use-cases/agent-automation
- X queries capability: https://www.desearch.ai/docs/guide/capabilities/x-queries
- API reference: https://www.desearch.ai/docs/api-reference

## Complete current endpoint inventory

### AI Search
- `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. JSON body schema: `ScraperStreamingSynapseRequest`.
- `POST /desearch/ai/search/links/twitter` — AI X Posts Search. The X Posts Search API allows users to search for relevant links based on X search queries with leveraging AI-powered models. This API analyze links from X posts that match the given prompt. This API is useful for tracking trends, gathering insights, and retrieving real-time information from X. JSON body schema: `LinksSearchRequestTwitter`.
- `POST /desearch/ai/search/links/web` — AI Web Search. This API allows users to search for links related to a given query (prompt) using multiple tools, excluding X (Twitter) Search. The API returns a list of relevant sources from selected platforms such as web pages, YouTube, Wikipedia, and ArXiv. JSON body schema: `LinksSearchRequestWeb`.

### Web Search
- `GET /web` — SERP Web Search API. 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. Query/path params: query, start.
- `GET /web/crawl` — Crawl API. The Desearch API allows you to crawl web content Query/path params: url, format, js, wait.

### X Search
- `GET /twitter` — X Search API. The X Search API enables users to retrieve relevant links and tweets based on specified search queries without utilizing AI-driven models. It analyzes links from X posts that align with the provided search criteria. Query/path params: query, sort, user, start_date, end_date, lang, verified, blue_verified, is_quote, is_video, is_image, min_retweets, min_replies, min_likes, count.
- `GET /twitter/post` — Retrieve Post by ID. Retrieve comprehensive details of a post by specifying its unique ID. This endpoint provides metadata, content, and engagement metrics associated with the specified post. Query/path params: id.
- `GET /twitter/post/retweeters` — Get Retweeters of a Post. Retrieve the list of users who retweeted a specific post by its ID. Supports pagination via cursor. Query/path params: id, cursor.
- `GET /twitter/post/user` — Search X Posts by User. The X posts search by user API allows users to search for relevant links or tweets based on X search queries without leveraging AI-powered models. This API analyze links from X posts that match the given prompt. Query/path params: user, query, count.
- `GET /twitter/replies` — Fetch User's Tweets and Replies. The tweets and replies by user API allows users to search for relevant links or tweets based on X search queries without leveraging AI-powered models. This API analyze links from X posts that match the given prompt. Query/path params: user, count, query.
- `GET /twitter/replies/post` — Retrieve Replies for a Post. The Tweets and Replies by User API enables users to retrieve relevant tweets and replies based on specified search queries without relying on AI-powered models. It analyzes and extracts links from X posts that align with the provided search criteria. Query/path params: post_id, count, query.
- `GET /twitter/trends` — Get X Trends. Retrieve trending topics on X for a given location using its WOEID (Where On Earth ID). Query/path params: woeid, count.
- `GET /twitter/urls` — Fetch Posts by URLs. Retrieve detailed information for multiple posts by providing their respective URLs. This endpoint extracts metadata, content, and relevant engagement metrics associated with each specified URL. Query/path params: urls.
- `GET /twitter/user/posts` — Get X Posts by Username. Retrieve user's timeline posts by specifying their username. This endpoint fetches the latest tweets posted by the user associated with the provided username. Query/path params: username, cursor.

### TikTok Search
- `GET /desearch/tiktok/comments/{video_id}` — Retrieve TikTok Comments. Retrieve normalized public comments for a TikTok video/post. Query/path params: video_id, count, cursor.
- `GET /desearch/tiktok/hashtag/{tag}` — Retrieve TikTok Hashtag Posts. Retrieve normalized public TikTok posts for a hashtag. Query/path params: tag, count, cursor.
- `GET /desearch/tiktok/post/{id}` — Retrieve TikTok Post by ID. Retrieve normalized metadata for a public TikTok post by ID. This endpoint does not expose no-watermark/download-only media URLs. Query/path params: id.
- `GET /desearch/tiktok/profile/{username}` — Retrieve TikTok Profile. Retrieve normalized public TikTok profile metadata by username. Query/path params: username.
- `GET /desearch/tiktok/profile/{username}/posts` — Retrieve TikTok Profile Posts. Retrieve normalized public posts for a TikTok username. Query/path params: username, count, cursor.
- `POST /desearch/tiktok/search` — TikTok Search API. Search public TikTok posts by keyword using the public TikTok integration. Download/no-watermark media surfaces are intentionally not exposed. JSON body schema: `TikTokSearchRequest`.
- `GET /desearch/tiktok/trending` — Retrieve TikTok Trending Posts. Retrieve normalized trending TikTok posts for a region where supported by the public TikTok integration. Query/path params: region, count.

### Facebook Search
- `GET /desearch/facebook/comments/{post_id}` — Retrieve Facebook Comments. Retrieve normalized public comments for a Facebook post/media item. Query/path params: post_id, count, cursor.
- `GET /desearch/facebook/hashtag/{tag}` — Retrieve Facebook Hashtag Posts. Retrieve normalized public Meta Ad Library records for a keyword/hashtag. Organic Facebook hashtag search and Facebook trending are intentionally omitted until a reliable public surface exists. Query/path params: tag, count, cursor.
- `GET /desearch/facebook/post/{id}` — Retrieve Facebook Post by ID. Retrieve normalized metadata for a public Facebook post/media item by ID. Query/path params: id.
- `GET /desearch/facebook/profile/{profile_id}` — Retrieve Facebook Profile or Page. Retrieve normalized public Facebook profile/page metadata by username, vanity handle, or public ID. Query/path params: profile_id.
- `GET /desearch/facebook/profile/{profile_id}/posts` — Retrieve Facebook Profile/Page Posts. Retrieve normalized public posts for a Facebook profile/page. Query/path params: profile_id, count, cursor.
- `POST /desearch/facebook/search` — Facebook Search API. Search public Meta Ad Library records by keyword. Organic Facebook post keyword search, private/account-authenticated surfaces, messaging, and publishing are intentionally not exposed. JSON body schema: `FacebookSearchRequest`.

### Instagram Search
- `GET /desearch/instagram/comments/{media_id}` — Retrieve Instagram Comments. Retrieve normalized public comments for an Instagram media/post. Query/path params: media_id, count, cursor.
- `GET /desearch/instagram/hashtag/{tag}` — Retrieve Instagram Hashtag Media. Retrieve normalized public Instagram media for a hashtag. Instagram trending is not exposed until a stable unauthenticated public surface is selected. Query/path params: tag, count, cursor.
- `GET /desearch/instagram/media/{id}` — Retrieve Instagram Media by ID. Retrieve normalized metadata for a public Instagram media/post by shortcode, ID, or URL. Query/path params: id.
- `GET /desearch/instagram/profile/{username}` — Retrieve Instagram Profile. Retrieve normalized public Instagram profile metadata by username. Query/path params: username.
- `GET /desearch/instagram/profile/{username}/posts` — Retrieve Instagram Profile Posts. Retrieve normalized public posts for an Instagram username. Query/path params: username, count, cursor.
- `POST /desearch/instagram/search` — Instagram Search API. Search public Instagram profiles by keyword. Hashtag/media discovery remains available through /desearch/instagram/hashtag/{tag}. Private, login, posting, messaging, and download-only surfaces are intentionally not exposed. JSON body schema: `InstagramSearchRequest`.

### Numinous Forecasting
- `POST /numinous/forecasts` — Create Forecast Job. Submit a forecasting question to the Numinous AI superforecasting system powered by Bittensor Subnet 6. Returns a prediction job ID to poll for results. Supports two modes: **structured** (title + description + cutoff) for precise results, or **query** (natural language question) for quick exploration. JSON body schema: `NuminousForecastRequest`.
- `GET /numinous/forecasts/{prediction_id}` — Get Forecast Result. Poll the status of a prediction job created via POST /numinous/forecasts. Poll every 5 seconds — jobs typically complete within 30–120 seconds. The `prediction_id` UUID acts as an access token; no API key is required for polling. Query/path params: prediction_id.

## API family guidance

### AI Search
Use AI Search when the caller wants current context plus model-assisted synthesis or source selection. `POST /desearch/ai/search` is the main contextual search endpoint. Link-search endpoints split web/source discovery and X post discovery.

### Web Search
Use `GET /web` for SERP-style results and `GET /web/crawl` when the workflow needs crawled content from a specific URL. Crawl text responses may expose billing metadata through headers only.

### X/Twitter Search
Use `/twitter` for query search. Use the specialized `/twitter/*` endpoints when the workflow already knows a post ID, URL, username, or needs retweeters, replies, user posts, or trends.

### TikTok Search
Use TikTok endpoints for public TikTok search and normalized public post/profile/comment/hashtag/trending data. Do not claim support for download-only/no-watermark media surfaces.

### Facebook Search
Use Facebook endpoints for public Meta Ad Library and normalized public Facebook records. Do not claim support for private/account-authenticated Facebook surfaces, messaging, or publishing.

### Instagram Search
Use Instagram endpoints for public profile/media/search, profile posts, comments, and hashtag media. Do not claim support for login-only, posting, messaging, private, or download-only surfaces.

### Numinous Forecasting
Use `POST /numinous/forecasts` to create a forecast job. Use `GET /numinous/forecasts/{prediction_id}` to poll results. Treat `prediction_id` as access-bearing data.

## Common errors

- `401 Unauthorized` — missing, invalid, revoked, or wrong-environment API key.
- `422 Validation Error` — bad parameter name, enum, request body, or old endpoint shape.
- `429 Too Many Requests` — rate/account limit or usage spike; add retry/backoff and check Console.
- `500 Internal Server Error` — retry later; if persistent, capture request details and Console logs for support.

## Drift warnings for LLMs

Do not use legacy v1 search endpoint examples. Current production endpoints are under paths such as `/desearch/ai/search`, `/desearch/ai/search/links/web`, `/desearch/ai/search/links/twitter`, `/twitter`, `/web`, `/desearch/tiktok/*`, `/desearch/facebook/*`, `/desearch/instagram/*`, and `/numinous/forecasts`.

Do not describe Desearch as an image-generation or generic media-generation API. The current public contract is live AI, web, social search/retrieval, crawl, and forecasting.