Filters and sorting

Every parameter is on both transports

A filter here is a query parameter on GET /search and an argument to the web_search MCP tool, with the same name and the same meaning. That is enforced by a test that fails the API’s build if the two ever disagree, so you can read either reference and use the other.

IN-list filters take a comma-separated string on REST (a URL query string cannot carry an array) and either a string or a JSON array over MCP.

Narrowing

Filter	Narrows to
vertical	One vertical. Omit and the router picks.
lang / langs	One language, or an IN-list.
site / exclude_site	An exact host, or hosts to keep out. docs.rs does not match blog.docs.rs.
from / to	When we crawled it, unix seconds.
published_from / published_to	When the content claims it was published. Absent on pages that declare no date, which then drop out.
min_words / max_words	Passage length.
content_type	IN-list: article, news, docs, reference, qa, forum, academic, product, code, how-to, opinion, video, document.
authority	Publisher-authority class, IN-list.
tld	Top-level domains, IN-list — gov,edu.
topic	Topic tags, IN-list.
source	cc (bulk crawl) or delta (freshly crawled).
term	The exact-needle filter — see below.
min_host_rank	Host trust floor, 0 to 1.
min_quality	Quality floor.
safe	true (default) drops explicit content; false allows everything.
min_centrality	Graph signal: how central to the corpus.
min_independent_sources	Graph signal: distinct hosts asserting the story.
community	Graph signal: restrict to graph communities, IN-list.

These are hard filters. Nothing below a floor comes back, and a filter that matches nothing returns nothing — which is a real answer, not a malfunction.

GET /describe reports the live list for this deployment, including which content types, authorities and topics actually have data behind them. Read it at startup rather than hard-coding this table.

term — the filter worth knowing about

--data-urlencode 'q=kernel' -d term=CVE-2024-3094

term matches a salient term exactly. It exists because embedders are blind to strings that carry no meaning to average over: CVE numbers, error codes, part numbers, ticket ids. Semantic search will find you documents about vulnerabilities; term finds the documents that name that one.

It composes with everything else, so you can ask for one identifier, in one vertical, since one date.

The two that only bias

prefer_recent=true
prefer_authority=true

These are soft rerank nudges, not filters. Nothing is excluded; the ordering shifts. Use them when you would rather see older or lower-authority results ranked down than removed — which, for most questions, is what you actually want. Use from or min_host_rank when you mean it strictly.

Sorting

sort takes relevance (default), recency, host_rank, quality, published, words or centrality.

sort=centrality is the interesting one: it orders by position in the corpus graph rather than by match to your query, which is how you find the central documents in a field you do not know yet. See authorities for the same idea as a first-class call.

Collapsing

collapse takes none (default), host, page or story.

--data-urlencode 'q=central bank rate decision' -d collapse=story

collapse=story folds each near-duplicate cluster to one row, with group_size reporting how many were folded in. Wire copy, syndication and scraped mirrors become one result instead of eleven. For any query touching news, this is close to mandatory.

collapse=host is one result per site; collapse=page is one per source page, when several passages from the same document would otherwise match.

Shaping the response

Parameter	Effect
limit	Maximum hits, default 10. limit=0 returns the count only.
facets	Adds host / vertical / source / content-type counts and a publish-year histogram.
fields	Projects each hit down to the named fields.

limit=0 with facets=true is a cheap reconnaissance call: it tells you how much the corpus holds on a topic and where it comes from, for the price of one request, before you spend context on results.

fields matters more than it looks. A search that only feeds a citation list does not need topics, community_id and in_degree in your context window on every hit.

Next

• Reading a result — the fields these filter on.
• The Coverage Graph — where the graph signals come from.
• Search recipes — these, combined.