Search modes

Three modes

mode takes keyword, semantic or hybrid. hybrid is the default, and it is usually right.

Mode	Matches on	Reach for it when
hybrid	Words and meaning, fused	You are asking a question. This is the default for a reason.
semantic	Meaning only	The wording is yours, not the document’s — a paraphrase, or a description of a concept whose name you do not know.
keyword	Words only	You know the exact string. Fastest, and it will not drift toward something adjacent.

The trade is straightforward. semantic finds the right document when you asked for it in the wrong words, and occasionally finds a plausible-sounding wrong one. keyword never drifts and never rescues a badly worded query. hybrid fuses both rankings, which is why it is the default.

For an exact identifier — a CVE number, an error code, a part number — do not reach for keyword. Use the term filter, which matches the identifier exactly and composes with everything else.

Query grammar

Boolean syntax works in all three modes:

Syntax	Meaning
rust AND async	Both
rust OR go	Either
-python	Exclude
"exact phrase"	The phrase, in that order

curl -sG -H "x-api-key: $UNLOB_API_KEY" https://api.unlob.com/search \
  --data-urlencode 'q=rust AND async -python "work stealing"'

Structured filters do the same job more reliably than syntax where both would work. site=docs.rs is better than trying to express a host restriction in the query string, and exclude_site=reddit.com is better than -reddit, which excludes the word.

Verticals and routing

The index is partitioned into verticals — code, science, cooking, and whatever else this deployment holds. Ask GET /describe for the live list.

Name one and you get zero-cost disambiguation:

--data-urlencode 'q=python' -d vertical=code

Omit it and the router picks one from the query. The response tells you which way it went:

{ "vertical": "code", "routed": true }

routed: true means the router chose. If it chose wrong — and “python” between code and science is exactly where that happens — name the vertical yourself. It is cheaper as well as more precise, because the router does not have to decide.

The typo case

A query with no special syntax that returns nothing is worth re-checking before you conclude the index is empty on the topic. A query you wrote deliberately — with operators, quotes or filters — is run exactly as written, because guessing at a deliberate query is worse than returning nothing.

Choosing a mode in practice

Most agents should send hybrid and forget the parameter exists. Reach for the others when you have a specific reason:

• Feeding the API a user’s natural-language question, verbatim → hybrid.
• Searching by a description you generated yourself (“articles about the economics of container shipping”) → semantic.
• Looking for a literal string you already have → keyword, or better, term.

Next

• Filters and sorting — the twenty-odd ways to narrow.
• Reading a result — what comes back.
• Search recipes — worked examples.