Venom Search
Turn on Venom Search, your org's own metasearch over official APIs and open data, and call it from the API, MCP or the CLI's web_search.
Venom Search asks several search engines at once, merges what they find and ranks it. It follows the design of SearXNG, the open-source metasearch engine, but it is Venom's own code: see ADR 0079.
It is off until you turn it on. Until an owner or admin turns it on in Settings → Search, no search leaves
Venom and POST /v1/search answers 404 search_disabled. It is a 404 because the route answered 404 before it
existed, so a venom CLI whose provider is Venom Cloud moves on to its own search backends.
Engines
Every engine uses an official API or open data. None of them reads a search results page meant for people.
| Engine | Categories | What it returns | Needs |
|---|---|---|---|
| Brave Search | general, news, images | Web, news and image results from Brave's own index | a Brave Search API key: yours, or Venom's (below) |
| Wikipedia | general, people | Article titles and the passage that matched | nothing |
| Wikidata | general, people | Entities: label, short description, Q-id | nothing |
| OpenAlex | science, people | Papers (title, year, venue, authors, abstract); for people, researchers and their institution | nothing |
| ORCID | people, science | Researchers by name: ORCID iD and institutions | nothing |
| GitHub | code, people | Repositories (description, stars, language); for people, accounts | nothing |
| Hacker News | news, code | Stories with points and comments (Algolia's HN API) | nothing |
| Stack Overflow | code | Questions with score, answered state and tags (Stack Exchange API) | nothing |
| arXiv | science | Preprints: title, authors, abstract, date | nothing |
| Gravatar | people | For an email address only: the public profile (name, job, company, verified accounts). Only the address's SHA-256 hash is sent | nothing |
| Your SearxNG | general, news, images, science, code | Results from a SearxNG instance you run, with the engines it used | its URL |
A request picks categories (general, people, code, science, news, images; default general) and
every enabled engine of those categories is asked. It can name engines instead.
Turn it on
In Settings → Search (/settings/search; owners and admins; everyone with providers:read can look):
- Switch on Use Venom Search.
- Turn engines on or off. Each row shows its health: average response time, the share of the last 20 calls that failed, and whether it is suspended.
- Optional: paste your Brave Search API key. It is sealed in the vault and never shown again; only its last
four characters are. Without one, Venom's own Brave key (
BRAVE_SEARCH_API_KEYon the deployment) answers if this deployment has one and your org's Use Venom's keys switch (Providers) is on. Your key always comes first. - Optional: the URL of your SearxNG. Its JSON API must be allowed (
format: jsonin its settings). Private and loopback addresses are refused. - Optional: Keep search queries. Off by default.
Agents with a member's key can do the same with admin_search_get and admin_search_set, and scripts with the admin
API: GET /api/admin/v1/settings/search reads the settings, the engines with their health and the recent queries;
PUT /api/admin/v1/settings/search takes {enabled, engines, brave_key, searxng_url, log_queries}, any of them.
Search from the API
curl -s "$VENOM_CLOUD_URL/v1/search" \
-H "Authorization: Bearer $VENOM_CLOUD_KEY" -H "content-type: application/json" \
-d '{"query": "tokio runtime", "categories": ["code"], "limit": 5}'| Field | ||
|---|---|---|
query |
required | up to 500 characters |
categories |
optional | list of categories, default ["general"] |
engines |
optional | ask only these engines |
limit |
optional | 1 to 50, default 10 |
freshness |
optional | day, week, month or year, for engines that can filter by date |
country |
optional | two-letter code, for engines that take one (Brave) |
The body of the venom orchestrator's POST /v1/search works too, which is what the CLI's web_search sends to its
provider: count for limit, time_range for freshness, allowed_domains (keep only results from these domains
and their subdomains) and blocked_domains (drop them), at most 20 each. language, answer and model are accepted
and ignored: Venom Search gives results, not a written answer.
{
"object": "search.result",
"backend": "venom-search",
"id": "req_…",
"query": "tokio runtime",
"results": [
{ "url": "https://github.com/tokio-rs/tokio", "title": "tokio-rs/tokio", "snippet": "A runtime for writing reliable asynchronous applications with Rust.",
"category": "code", "engines": ["github", "hackernews"], "score": 1.35, "published_at": "2026-11-01T10:00:00.000Z", "thumbnail": null, "extra": { "stars": 29000 } }
],
"engines": [
{ "name": "github", "status": "ok", "results": 5, "ms": 312, "error": null },
{ "name": "stackexchange", "status": "timeout", "results": 0, "ms": 4000, "error": "timeout" }
],
"cached": false,
"cost_usd": 0
}Each result lists every engine that found it. An engine that is slow, fails, is suspended or has nothing to ask
(Gravatar without an email address) is listed in engines with its status; it never fails the search.
Errors: 400 invalid_request names the field (param), 404 search_disabled when search is off, 429 for the
key's rate limit or the org's spend cap.
From MCP and REST
On the workspace MCP server the tool is workspace_web_search (also callable as
search_web), with the same arguments and format: "json" for the full answer. Its REST twin is
POST /api/v1/web/search. An OAuth app's searches are booked to the org without a key.
Studio research runs
A Studio research run searches through Venom Search and, under the same switch, also reads the
pages its results point to (public https addresses only, SSRF-guarded, 8 seconds and 1.5 MB each, no cookie or referrer)
and the World Bank's open data API (api.worldbank.org, no key). With search off, a run reaches nothing outside Venom: it
uses the model's own knowledge and marks every figure unverified. Its searches are booked with source studio-research.
Provider search
Provider search for research runs (off by default) lets Studio research runs also search through the web search the model
providers run themselves: OpenAI, Anthropic, Model Studio and Z.ai, with the org's own key (or Venom's, as "Use Venom's keys"
allows). It is separate from Venom Search: either one makes a run researched. It sends the research queries to that provider,
so an owner or admin turns it on here (provider_search on the admin API and admin_search_set); the page lists the providers
that could serve it and whose key each uses. Calls are booked under the model provider-search. Details: Research
runs.
From the CLI
The venom CLI's web_search tool uses Venom Search once you are signed in to Venom Cloud (venom cloud login, or
VENOM_CLOUD_URL and VENOM_CLOUD_KEY) and your org has turned search on. It sends POST /v1/search with your cloud
key, after your own SearxNG (VENOM_SEARCH_URL) when you have one and before Brave, Tavily and DuckDuckGo. When the
CLI's provider is the cloud itself, its first search already reaches Venom Search, so the cloud is not asked twice.
While search is off the cloud answers 404 and the CLI stops asking it for the rest of the session. Any other error (a spend cap, a rate limit) hands the search to the next backend. A gear that allows only self-hosted search never uses it. See The agent's tools.
How results are ranked
An engine's results are ranked 1, 2, 3, … and each one earns the engine's weight divided by its rank. A page that
several engines found adds up their scores, so it ranks above a page only one engine found at the same place.
Addresses are normalised before they are compared: no scheme, no www., no default port, no trailing slash, no
fragment, tracking parameters (utm_*, fbclid, gclid, …) removed and the rest sorted.
Health and suspension
After three errors in a row an engine is suspended for a minute, then two, four and so on up to an hour. A rate limit (429) or a refused key (401, 403) suspends it at once. After the suspension the next search tries it again, and one success clears it.
Cache
The same search by the same org within five minutes is answered from memory ("cached": true), without asking
the engines again and at no cost.
Privacy and cost
- Engines get the query and nothing about who asked: no IP address, no key, no org name. The User-Agent names Venom Search only.
request_logkeeps metadata only (when, which key, which engines answered, the cost). The query text is kept only while Keep search queries is on, for 30 days, and turning it off deletes it.- Every search is in Requests and Usage under the model
venom-search. Open engines cost nothing. A Brave call is booked at $0.005, with your key or Venom's.
Why our own code
SearXNG is licensed under the AGPL-3.0. Venom Search contains none of its code or engine files: it was written from SearXNG's public descriptions of its design (engines as adapters, a fan-out with timeouts, merged and scored results, categories, engine suspension, a short cache) and the engines' own API documentation. ADR 0079 in the repository records the decision and the sources.