Which endpoint

Humans

Need a natural-language answer with sources: AI Search (POST /desearch/ai/search).
Need ranked pages, no model summary: plain Search (POST /search). That path is not in the checked-in OpenAPI (public/openapi.json has no /search), and there is no public docs page yet. Do not treat a docs URL for it as live.
Need sources without a completion: links endpoints (POST /desearch/ai/search/links/web or POST /desearch/ai/search/links/twitter).
Need keyword SERP / pagination: GET /web.
Need page body from a URL you already have: Extract (GET /web/extract).
Need X operators / posts / replies / trends: X API.
Need TikTok / Facebook / Instagram: Social APIs.

Agents / tool authors

Route by contract: AI Search when the caller needs completion or multi-tool natural-language retrieval; POST /search for structured ranked hits without a model summary; GET /web for keyword SERP; Extract for URL to content; platform X and social tools when you need post, replies, or trends APIs (not only tools: ["twitter"] inside AI Search).

Decision matrix

Use this when…	Path	What you get	Cost cue (no dollar rates)
Natural-language question across sources, plus optional summary or streaming	`POST /desearch/ai/search`	`search[]` plus optional `completion`	Headers `X-Desearch-Cost-Usd`, `X-Desearch-Usage-Count`, `X-Desearch-Service`, `X-Desearch-Currency`; body cost fields on JSON objects
Sources only, no completion (web family)	`POST /desearch/ai/search/links/web`	Link lists per API reference	Links pricing in Console. No dollar figures here
Sources only on the X/Twitter links path	`POST /desearch/ai/search/links/twitter`	Twitter-oriented link results	Links pricing in Console. No dollar figures here
Ranked web pages; no model summary	`POST /search`	Not in the checked-in OpenAPI, so this page does not document a response shape	No public docs page yet. Dollar rates stay off this page
Keyword SERP-style hits plus pagination	`GET /web?query=…&start=…`	SERP-like hits (`query` and `start` only)	Web Search pricing in Console. No dollar figures here
Clean text or HTML for a known URL	`GET /web/extract`	Extracted content	Extract pricing. `js=true` may be a separate tier. No dollar figures here
Exact X keyword ops, post, user, replies, or trends	X guide and API reference (`GET /twitter…`)	Posts and metadata	X pricing in Console. No dollar figures here
TikTok, Facebook, or Instagram	`POST /desearch/tiktok/search`, `POST /desearch/facebook/search`, `POST /desearch/instagram/search`, plus GET helpers in API reference	Platform objects	Social pricing in Console. Guide: Social APIs

AI Search vs plain Search vs links vs SERP

AI Search: one prompt, optional tools, optional completion, optional streaming. Start with the Search API first call.
Links endpoints: sources without a completion. Prefer these over an ONLY_LINKS first-call mode. ONLY_LINKS docs stay on hold.
Plain POST /search: the name for ranked hits without a model summary. It is not in the checked-in OpenAPI, and the public docs page is not live. Do not invent a response shape or dollar rates here.
GET /web: keyword SERP with query and start pagination.

Page content you already have

Use Extract (GET /web/extract) when you already have a URL and need the page body. Legacy GET /web/crawl is a compatibility alias only.

Social and X

X: follow the X API guide. Inside AI Search, tools: ["twitter"] is not a substitute for operators, replies, or trends APIs.
TikTok, Facebook, and Instagram: Social APIs. Do not present a /docs/guide/apis/social-apis URL as live.

AI Search `tools[]` (short)

Goal	Prefer
General web evidence	`web`
Research papers	`arxiv`
Discussions	`reddit`, `hackernews`
Video or wiki	`youtube`, `wikipedia`
X posts inside AI Search	`twitter`. For operators, replies, or trends, use the X API

Do not invent tools beyond: web, twitter, reddit, wikipedia, youtube, hackernews, arxiv.

Search API first call and annotated response
Streaming AI Search
Auth and API keys
API Reference

Forecasting stays out of this chooser. Do not expand it here.