The Coverage Graph

Two ways to use it

There is a graph over the corpus — passages linked to hosts, to near-duplicate stories, to topics and to entities. You can use it two ways, and the cheap way covers most of what you need.

The cheap way: signals on every hit. centrality, independent_sources, community_id and in_degree come back on every search result, and /search filters and sorts on them:

# corroborated results only, most central first
curl -sG -H "x-api-key: $UNLOB_API_KEY" https://api.unlob.com/search \
  --data-urlencode 'q=merger terms' -d min_independent_sources=3 -d sort=centrality

No extra call, no extra cost. For most questions this is enough.

The structural way: six calls. When you need the shape of the connections rather than a ranking derived from it.

The six

Call	Returns	The loop it replaces
corroborate	Distinct hosts carrying a story, grouped and ranked by authority	Cross-searching by hand to check whether a claim is independently reported
dossier	An entity’s mentions, top sources, and co-mentioned entities	About ten searches and a manual merge
authorities	Top passages on a topic by centrality, not by query match	Reading junk into context before you know the vocabulary
related	The connected neighbourhood of a passage	A search per hop
path	The shortest edge chain between two passages	Guessing at what connects two things
assemble_context	A deduplicated, trust-ranked, budget-packed reading set	The entire retrieval loop

corroborate is the one to build a habit around

curl -sG -H "x-api-key: $UNLOB_API_KEY" https://api.unlob.com/corroborate \
  -d 'id=https://example.com/article:0'

{
  "story_id": "…",
  "independent_sources": 4,
  "merged_duplicates": 37,
  "sources": [
    { "host": "reuters.com", "host_rank": 0.97, "passages": [ … ] },
    { "host": "ft.com", "host_rank": 0.95, "passages": [ … ] }
  ]
}

Forty rows in a result list and independent_sources: 1 describe the same corpus. The first looks like consensus; the second is one source and thirty-nine reprints.

One detail in your favour: when a near-duplicate copy is dropped at ingest, the host that published it is still recorded against the passage that survived. So independent_sources counts every host that asserted the story, not only the ones whose copy was kept.

dossier gives you the leads

curl -sG -H "x-api-key: $UNLOB_API_KEY" https://api.unlob.com/dossier \
  --data-urlencode 'entity=Acme Corporation'

Mentions, top source hosts, and related_entities as [entity, count] pairs. That third list is what earns the call: it is the people, products and organisations you did not know to search for. Feed the interesting ones back in and you have walked a network in three calls.

assemble_context is the whole loop

curl -sG -H "x-api-key: $UNLOB_API_KEY" https://api.unlob.com/assemble_context \
  --data-urlencode 'q=what happened with the Acme acquisition' -d budget=4000

Search, deduplicate, corroborate, rank, pack — done on the server, returned as a context pack where each item carries the reason it was included. budget is a token ceiling; estimated_tokens reports what was actually packed.

Use it when the question is “what should I know about X”. Use search when the question is “find me the page that says Y”.

Node keys

path returns a chain of namespaced nodes, so the chain reads as an explanation rather than a route:

Prefix	Node
p:	Passage
h:	Host
s:	Story (near-duplicate cluster)
t:	Topic
e:	Entity

Two documents linked through a shared entity and two linked only through a shared topic are very different findings. found: false is also an answer: within everything the index holds, these two things are not connected.

A research loop, six calls

1. authorities on the topic — acquire the vocabulary.
2. search with min_independent_sources — corroborated hits, in that vocabulary.
3. corroborate the one you intend to rely on.
4. dossier on the entity it names — find the leads.
5. path between two leads that look connected — find out whether they are.
6. assemble_context on the refined question — hand yourself the reading.

Each call bills one request. See Graph recipes for the worked version.

Next

• Graph recipes
• MCP tools — every tool’s arguments and return schema
• Coverage transparency