vaaya / docs / reference

OneSearch

vaaya/onesearch (flat 5¢) is the retrieval routing engine as a single executable action. Hand it an intent; it plans a multi-source retrieval, races independent indexes, chains full-content extraction when fidelity matters, and returns normalized evidence where every item cites its transaction id. The internal source calls are included in the flat price. You pay 5¢, not the sum of the rungs.

The simplest call: just a query

Price

flat 5¢, internal source calls included

Facets

12 search facets + scrape + social

Output

normalized evidence, each item cites its transaction id

With only a query, an intent classifier authors the routing frame for you: which facets to search, whether to race indexes, whether to pull full content.

curl -X POST https://vaaya.ai/api/run/vaaya/onesearch \
  -H "Authorization: Bearer $VAAYA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "what changed in the WebTransport spec this year"}'

Route it yourself: facets

Adding any frame field skips the classifier. facets (one or more, default ["web"]) picks the source ladders; each facet fires its own ladder concurrently and the evidence is merged.

Frame modifiers

• timeCritical: true races two independent indexes (Exa + Brave for web, Brave News + Tavily for news) for breaking / “latest” queries.
• fidelityRequired: true fetches the full page content (chains search → extraction), not just snippets.
• recencyDays restricts to recent results.
• domains / excludeDomains include or exclude sites.
• maxResults caps the merged evidence list.
• urls: [...] skips search and extracts these pages directly.
• asOf: "YYYYMMDD" fetches the archived copy via the Wayback Machine.

Scrape facets: fetch these URLs

Pass urls with a scrape facet to use OneSearch as a laddered, managed extractor. Both are fetch-only (they require urls) and are never chosen by the classifier. Route to them explicitly.

• facets: ["scrape"] runs a cheapest-first ladder that escalates each URL on a miss: bulk no-JS extraction → JS rendering → anti-bot scraping → residential proxies. Use for “get the clean content of these pages” when a plain fetch might be blocked.
• facets: ["scrape-hard"] goes straight to residential proxies + headless Chrome for anti-bot / geo-walled pages. One page per call; it’s the priciest rung.

curl -X POST https://vaaya.ai/api/run/vaaya/onesearch \
  -H "Authorization: Bearer $VAAYA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "facets": ["scrape"],
    "urls": ["https://example.com/pricing", "https://example.com/changelog"]
  }'

For direct control over the individual rungs (vendor choice, formats, structured extraction, crawls), see Web scraping.

Social facet: search one platform

facets: ["social"] + platform (one of tiktok, instagram, youtube, twitter, weibo, reddit) + query (the keyword) returns raw posts for the platform. This facet is caller-driven: pick the platform explicitly; the classifier never chooses it. Defaults to twitter. For profile/comment/follower endpoints beyond keyword search, see Social data.

OneSearch vs. a raw search vendor

Pick OneSearch when the value is in the bundling: one call that searches, corroborates across indexes, optionally pulls full page content, and hands back cited evidence, without you orchestrating an exa/search → scrape chain. It’s the best default for:

• “Search + read the pages” in one shot (fidelityRequired).
• Documentation lookups that must keep full code and markdown (facets: ["docs"]).
• Time-critical questions where a second independent index matters (timeCritical).

Pick a raw vendor from Web search when a single 1¢ call is enough, or when you need something OneSearch doesn’t do:

• A specific vendor feature: exa/search category: "people" for GTM people-discovery, Tavily’s include_answer, linkup/deep-search (5¢) or parallel/task (10–30¢) for deep async research, firecrawl/search for content-with-hits.
• A plain one-off 1¢ search where the 5¢ bundle isn’t worth it.
• A facet OneSearch doesn’t cover yet. It routes web, docs, news, academic, code, public-filings, funding, financials, legal, nonprofits, regulatory, and compliance (search), scrape / scrape-hard (fetch), and social (per-platform) today. For people and contacts use OneFind, for pages use OneScrape: Search answers questions, Find returns people, Scrape returns pages. For on-chain and other facets, call the specific vendor directly.

OneSearch vs. consult

vaaya/consult is the router. It tells you which call(s) to run. OneSearch is a call you actually run. They compose: for a search or research intent, consult can simply recommend vaaya/onesearch with a plain-English query and let the engine plan the rest. Reach past OneSearch to name specific vendors only when the intent needs a capability it doesn’t cover.