Search recipes

Worked examples, end to end. Every one works on both transports: the REST form is shown because it is the shortest thing to paste into a terminal, and the MCP argument is always the same name with the same meaning.

Set your key once:

export UNLOB_API_KEY=ulb_...
alias unlob='curl -sG -H "x-api-key: $UNLOB_API_KEY" https://api.unlob.com'

Ask a plain question

unlob /search --data-urlencode 'q=how does tokio schedule tasks'

No vertical, no filters. The router picks a vertical from the query, and mode defaults to hybrid, so this matches on meaning and on words at once. The response says which vertical it chose (vertical) and whether it chose it (routed: true) or you did.

The snippet in each hit is the passage text. Most questions end here.

Name the vertical when you already know it

unlob /search --data-urlencode 'q=async runtime' -d vertical=code

Cheaper and more precise than letting the router guess — "python" means something different in code and in science. GET /describe lists the verticals this deployment actually holds.

Find an exact identifier

unlob /search -d q=kernel -d term=CVE-2024-3094

term is an exact-needle filter over salient terms. Use it for CVEs, error codes, part numbers, ticket ids — the strings an embedder is blind to because they carry no meaning to average over. It composes with everything else, so you can ask for one identifier within one vertical since one date.

Restrict to a source, or exclude one

unlob /search -d q=lifetimes -d site=doc.rust-lang.org
unlob /search -d q=lifetimes -d 'exclude_site=reddit.com,quora.com'

site is an exact host match, not a domain suffix — docs.rs does not match blog.docs.rs. exclude_site takes a list.

Ask only trustworthy sources

unlob /search -d q='vitamin d dosage' -d min_host_rank=0.6 -d 'tld=gov,edu'

min_host_rank is a trust floor from 0 to 1. authority and tld narrow by publisher class and domain. All three are filters, not nudges: nothing below the floor comes back.

If you would rather bias than exclude, use the soft form:

unlob /search -d q='vitamin d dosage' -d prefer_authority=true

Stop reading the same story five times

unlob /search -d q='central bank rate decision' -d collapse=story

collapse=story returns one passage per near-duplicate cluster, with group_size saying how many were folded in. Wire copy, syndication and scraped mirrors collapse to one row. collapse=host and collapse=page do the same thing one level coarser and one level finer.

Ask what is recent

unlob /search -d q='rust release notes' -d sort=recency
unlob /search -d q='rust release notes' -d from=1735689600

Two different questions. sort=recency reorders what matched. from/to filter by when we crawled it. published_from/published_to filter by when the content itself claims to have been published — which is what you usually mean, and which is missing on pages that do not declare one.

Ask what is corroborated

unlob /search -d q='company X acquisition' -d min_independent_sources=3

Only stories at least three distinct hosts assert. This is the cheapest anti-hallucination filter available: it costs nothing extra and removes the single-source claims before you ever read them. Follow up with corroborate on a hit to see who those sources are.

Get a lay of the land before searching

unlob /search -d q=transformers -d facets=true -d limit=0

limit=0 returns the match count and nothing else; facets=true adds host, vertical, source, content-type and authority counts plus a publish-year histogram. One call tells you whether the corpus has ten documents on this or ten thousand, and where they come from — then you spend your context budget knowingly.

Keep the response small

unlob /search -d q=tokio -d 'fields=id,url,title,snippet' -d limit=5

fields projects the hit down. A search that only feeds a citation list does not need topics, community_id and in_degree in your context window.

Choose a mode deliberately

mode	Use it when
hybrid (default)	You are asking a question. Matches meaning and words together.
semantic	The wording is yours, not the document's — paraphrases, descriptions of a concept.
keyword	You know the exact string. Fastest, and it will not "helpfully" drift.

Boolean syntax works in all three: AND, OR, -term to exclude, "exact phrase" to require a phrase.

When the answer is empty

An empty result is information. The index is admission-controlled, so it holds what was judged worth keeping rather than everything that exists — a topic with nothing in it usually has nothing worth having.

Before concluding that, check two things:

unlob /why_not --data-urlencode 'url=https://example.com/the-page-you-expected'

present means it is there and your query missed it — loosen the filters. removed names why it went. unknown means we never had it.

And check partial on the search response. If it is true, part of the corpus was unreachable for that request, and the short answer is a symptom, not a finding. Retry.

What things cost

Every call above bills one request against your monthly quota, whatever it returns. limit=0 costs the same as limit=100, so ask for the count when the count is what you want — and ask once, with facets, rather than five times to explore.

GET /describe, /openapi.json, /mcp/tools.json, /llms.txt and these guides are free and need no key.