Documentation
One base URL, one header, and a query surface an agent can discover for itself. Everything below is reachable on every plan, including the free one.
export UNLOB_API_KEY="ulb_..."
curl -H "x-api-key: $UNLOB_API_KEY" \
"https://api.unlob.com/search?q=climate+policy&collapse=story&limit=5"Guides
Getting started
Querying
Query syntax
The q parameter accepts boolean operators, negation with a leading minus, and quoted phrases for exact matching.
Search modes
Keyword runs BM25, semantic runs vector similarity, and hybrid fuses both by reciprocal rank. Hybrid is the default.
Filtering
Around thirty filters narrow a result set by scope, time, quality, shape and output — all evaluated against stored fields, so filtering is free at query time.
Sorting
Order results by relevance, recency, publication date, host rank, quality, length or graph centrality.
Deduplication
Collapse results by host, page or story cluster so one syndicated item cannot occupy an entire result set.
Facets
Return counts by host, vertical, source, content type, authority, publication year and community alongside your results.
Field projection
Use the fields parameter to return only the attributes you need, shrinking responses that go straight into a context window.
Operating
Rate limits and quotas
Each plan carries a monthly request quota and a per-minute rate limit, enforced per serving replica. The free plan hard-caps; paid plans continue with usage-based overage.
Errors
Standard HTTP status codes: 401 for authentication, 429 for rate limits, 408 on timeout, 503 when the index is not ready.
Capability discovery
The unauthenticated /describe endpoint returns the filter grammar and every controlled vocabulary, so an agent can discover the query surface instead of hardcoding it.
API reference
All endpoints →Search & retrieval
Find passages, widen a result set, and fetch the one document you actually decided to read.
/searchThe main query surface: returns metadata-only passage hits — url, host, title, snippet, score and world-model signals — but never the page body.
GET/similarMore-like-this: given a passage id, returns its semantic neighbours from the same embedding space the index was built in.
GET/browseQuery-free browsing: the most recent or highest-ranked passages, optionally within a single vertical.
GET/doc/:idFetches the full cleaned text of one passage by id — the only endpoint that returns page content.
Coverage graph
Traverse the relationships the index already computed: corroboration, authority, entity briefs, connecting paths and packed context.
/relatedCoverage graph traversal: the connected neighbourhood of a passage, up to k hops — the edges are what to read next.
GET/corroborateThe anti-hallucination check: how many distinct hosts independently carry a story, and which ones.
GET/authoritiesThe top passages on a topic ranked by graph centrality, so an agent can triage a field before reading into it.
GET/dossierA one-hop brief on an entity: where it is mentioned, which hosts cover it, and which entities co-occur with it.
GET/pathThe shortest chain of edges linking two passages — reasoning-path retrieval, or connect-the-dots.
GET/assemble_contextGraphRAG as a single call: a corroborated, story-deduplicated, trust-ranked context pack fitted to a token budget, with a reason attached to every passage.
Discovery & operations
Capability discovery, coverage transparency, account state and the probes your infrastructure expects.
/why_notCoverage transparency: explains whether a URL is present in the index, was removed and why, or was never admitted.
GET/describeA self-describing capability catalog: the filter grammar and every controlled vocabulary, so an agent can discover the query surface instead of guessing it.
GET/accountYour tenant’s current plan, usage against quota and remaining allowance for this billing period.
GET/healthzUnauthenticated liveness probe. Returns 200 while the process is up.
GET/readyzUnauthenticated readiness probe: 200 once the index is loaded and non-empty, 503 while it is not.
GET/metricsPrometheus metrics: per-status request counters, a latency histogram and an in-flight gauge.
MCP server
Setup and all tools →If your agent speaks the Model Context Protocol you do not need to write HTTP calls at all. All 11 tools are available over stdio JSON-RPC.
Machine-readable
We sell a search API, so this documentation is also available as structured data.
Get a key and start
One magic link creates your account and issues your first API key. 10,000 free requests a month, no card.
