# unlob

> An agent-first web search API. The index is admission-controlled rather than
> exhaustive, so a search returns a short high-signal set of passages instead of a page
> of links to triage. Every hit carries trust and graph signals you can filter and sort
> on directly.

## Two ways in

- REST: `GET https://api.unlob.com/search?q=...` with `x-api-key: ulb_...` (or `Authorization: Bearer`).
- MCP: Streamable HTTP at `https://api.unlob.com/mcp`, same key, tools: web_search, get_document, similar, why_not, browse, related, corroborate, authorities, dossier, path, assemble_context.

Both surfaces accept the same filters and return the same shapes. Pick MCP if your client
speaks it; pick REST if you want one HTTP call.

## Machine-readable

- [OpenAPI](https://api.unlob.com/openapi.json)
- [MCP tools](https://api.unlob.com/mcp/tools.json)
- [Capability catalog](https://api.unlob.com/describe) — the live filter/sort/vertical list for THIS
  deployment, including which verticals actually hold data
- [Search recipes](https://api.unlob.com/guides/search-recipes)
- [Graph recipes](https://api.unlob.com/guides/graph-recipes)

## Things worth knowing before your first call

- **Hits are passages, not pages.** The snippet IS the passage text, so most questions
  need no follow-up fetch. `get_document` / `GET /doc/:id` is there for when you want the
  whole document.
- **`partial: true` means the answer is incomplete** because part of the corpus was
  unreachable — not that this is all there is. Never treat it as a complete result.
- **A small result set is normal.** The index holds what was judged worth keeping. Use
  `why_not` to tell 'we dropped that URL, here is why' apart from 'we never had it'.
- **`corroborate` before you assert.** An echoed rumour and an independently reported fact
  look identical in a result list. `independent_sources` counts the distinct hosts.
- **A new key is not live immediately.** Keys propagate to the serving fleet on a refresh
  cycle; a key you just minted can 401 for up to about a minute. Retry rather than
  assuming it is wrong.

## Cost

Every search or graph call bills one request against your plan's monthly quota. Reading
the descriptions above is free and needs no key.