Auto routing.

Send a query without a mode and the server picks one, tells you why, and puts the most relevant results first. Send a mode and it does exactly what you asked.

Auto mode

mode defaults to auto. Before anything is reserved or sent to an engine, auto resolves to one real mode, and your reservation and charge are those of that mode. The decision is in every response as routing.auto:

part of a search response

"routing": {
  "auto": {
    "mode": "news",
    "source": "jev",
    "reason": "Asked about recent events (p 0.97); used news with freshness week.",
    "probabilities": { "general": 0.02, "news": 0.97, "academic": 0, … },
    "filters_applied": { "freshness": "week" },
    "model": "jev-1.13.0",
    "latency_ms": 240
  },
  "reranked": true,
  …
}

Three steps, in order. Fixed rules decide the clear cases. If none fires, a small judgement model, TypeSafe's Jev, reads the query and picks a mode when it is confident. Otherwise the search runs as general, with source: "fallback".

The rules

Checked in this order, ignoring case except for "on X"; the first match decides.

#	when the query	mode
1	is a single http(s) URL	extract
2	mentions tweets, Twitter or "on X" (capital X, and not an x-axis), contains `x.com/`, or has a lone `@handle`. Code does not count: an email address, an npm scope such as `@types/node`, a decorator or at-rule such as `@property` or `@media`, or Twitter cards and Bootstrap	social
3	is "similar to", "sites like", "alternatives to", "competitors of" or "more like" followed by a URL (the URL becomes the query)	similar
4	mentions patents or prior art (not patent leather), or a patent number such as `US 10123456` or `EP1234567`	patents
5	asks for images, photos, pictures, logos or wallpapers "of" or "for" something, except system images such as Docker, container or VM images	images

Words such as "near me", "cited by", "paper", "who is" or "latest" are only hints: "news aggregator API" is not a news search and "who is hiring" is not a person search. Jev decides those from what the query asks for.

Freshness comes from explicit words only: "today" or "yesterday" sets day; "this week", "latest" or "breaking" sets week; "this month" and "this year" set month and year. It applies only when the search runs in news or social(in a general question "today" or "latest" is usually part of a name or a version), never overrides a freshness you sent, and is reported in filters_applied.

What Jev decides, and what it never does

Jev chooses among general, news, academic, scholar, people, images, places and patents. It sees the query and nothing else, answers in about a quarter of a second, and is given at most 1.5 seconds; if it is slow or down, the rules' answer or general stands. It never chooses deep or social, which cost several times a general search: ask for those by name. It never sets filters, and it never overrides a mode or engines you sent.

Relevance rerank

In general, news, academic, scholar, people and deep, when there are at least three results and the request is not pinned to one engine, Jev judges how well each result answers the query from its title, snippet and host. The new order weighs that judgement against the engines' own ranking, so a close call keeps the engines' order. Each result then carries extra.relevance (0 to 1) and routing.reranked is true. If the judgement fails, you get the original order and reranked: false. Rerank is free; send rerank: false to turn it off.

Page checks in extract

A fetched page that passes the built-in checks but is short gets one more look: is this the page's content, or a login wall, paywall, cookie notice, CAPTCHA, error page or empty shell? If it is clearly not content, the next engine in the chain is tried, and a page that was not returned is not charged. This check can only send a page onward; it can never accept a page the built-in checks refused.

Hints

When you send a mode and the query plainly belongs to another (for example academicfor "coffee near me"), the response may carry routing.hints with the suggested mode, its probability and a one-line message. Hints are worked out alongside the search and never change what ran.

Endpoints

Two endpoints expose the same decisions, so a client that searches on its own (search-cli does) can route and order results the way the server would. Both take your bearer key and are free. Each account gets 300 judgements a minute on each server instance: a route call is one, a rerank is one per result. Past that the answer is 429 rate_limited, and a missing or unknown key is 401 invalid_api_key.

which mode, and which engines

POST https://metasearch.sh/api/v1/route
Authorization: Bearer ms_live_…

{ "query": "latest news on the Fed rate decision" }

→ { "auto": { "mode": "news", "source": "jev", "reason": "…" },
    "providers": ["serper", "brave", "linkup", …] }

mode is optional; send one and it comes back unchanged, with source: "explicit" and that mode's engines. providers is the order the server would try right now: an engine that is switched off or has no key is left out, and one failing its health check moves back.

order results you already have

POST https://metasearch.sh/api/v1/rerank
Authorization: Bearer ms_live_…

{ "query": "postgres advisory lock with pgbouncer",
  "results": [ { "id": "a", "title": "…", "snippet": "…", "url": "https://…" }, … ] }

→ { "order": ["c", "a", "b"], "relevance": { "a": 0.91, "b": 0.12, "c": 0.97 },
    "model": "jev-1.13.0", "latency_ms": 260 }

1 to 30 results, each with a unique id of up to 64 characters and a url of up to 2,048 characters; the query has the search limit of 2,000 characters. If the judgement is unavailable the response is still a 200, with your order, an empty relevance and model: null, so a client never breaks on it.

Opting out

Send mode: "general" (or any mode) to skip auto routing, and rerank: false to keep the engines' order. The Search API lists every field.

next: Providers & modes →