unlob Docs
Console
Browse documentation

Quickstart: get a key and ground your first objective

A key, one ground call, and evidence you can hold a claim to.

Get a key

Create one in the console. It looks like ulb_ followed by 48 hex characters, and it is shown once — the API stores only a hash, so a key you did not copy has to be rotated rather than recovered.

Give each key a label. The label and the last four characters are all you will have to tell two keys apart later.

export UNLOB_API_KEY=ulb_...

A key you just created can answer 401 for up to about a minute while it propagates to the serving fleet. That is expected — see Authentication.

Ground

The call to start with. An objective in; evidence with provenance, and a receipt saying whether it is enough, out.

curl -sG -H "x-api-key: $UNLOB_API_KEY" https://api.unlob.com/ground \
  --data-urlencode 'objective=how does tokio schedule tasks' -d token_budget=2000
{
  "status": "sufficient",
  "evidence": [
    {
      "hit": { "id": "3be72f8af6378060:0", "url": "https://docs.rs/tokio", "host": "docs.rs", "snippet": "Tokio is an asynchronous runtime for Rust…" },
      "reason": "original · 1 origin in this story · primary source · owner: docs.rs",
      "source_role": "primary",
      "origin_type": "original",
      "owner": "docs.rs",
      "independence_score": 1.0
    }
  ],
  "coverage": { "complete": true, "independent_origins": 2, "source_roles_missing": ["official"], "known_gaps": ["no official source in the evidence set"] },
  "budget": { "token_budget": 2000, "context_tokens": 640, "credits_billed": 5 },
  "next_actions": []
}

Read status first: sufficient, insufficient, stale, partial or empty. Then the evidence — each item says what kind of source it is and whether it is independent of the others — and coverage, which says what was and was not searched. The whole contract is on Grounding.

When the question is “find me the page that says Y” rather than “what should I know”, search is the cheaper call:

curl -sG -H "x-api-key: $UNLOB_API_KEY" https://api.unlob.com/search \
  --data-urlencode 'q=how does tokio schedule tasks'
{
  "vertical": "code",
  "routed": true,
  "mode": "hybrid",
  "total": 12,
  "results": [
    {
      "id": "3be72f8af6378060:0",
      "url": "https://docs.rs/tokio",
      "host": "docs.rs",
      "title": "Tokio",
      "snippet": "Tokio is an asynchronous runtime for Rust providing building blocks…",
      "host_rank": 1.0,
      "quality": 92,
      "score": 0.71,
      "independent_sources": 4,
      "centrality": 0.63
    }
  ]
}

Three things to notice, because they are what makes this different from a search API you have used before:

  • snippet is the passage text, not a teaser. Most questions end here. There is a get_document call, but you usually will not need it.
  • routed: true means you did not name a vertical and the router picked code from your query. Name one yourself when you know it — it is cheaper and more precise.
  • independent_sources is how many distinct hosts carry this story. It is on every hit, for free, and it is the cheapest filter against a widely echoed rumour — though hosts are not independent sources; ground counts origins for that.

Read a passage in full

curl -s -H "x-api-key: $UNLOB_API_KEY" \
  https://api.unlob.com/doc/3be72f8af6378060:0

Connect an MCP client

If your agent speaks MCP, you do not need any of the above. Point it at the endpoint. The grounding profile lists ground and get_document, which is the right surface for most tasks; leave the profile off and it lists every tool:

https://api.unlob.com/mcp?profile=grounding

Claude Code, for example:

claude mcp add --transport http unlob "https://api.unlob.com/mcp?profile=grounding" \
  --header "x-api-key: $UNLOB_API_KEY"

Every other client is on Connect a client. A coding agent can also install the Agent Skill and use the API without reading this page.

Ask the API what it can do

Before hard-coding a filter list, read the one this deployment actually has. It needs no key:

curl -s https://api.unlob.com/describe

It reports every filter with its meaning, the sort and collapse values, the search modes, the verticals, content types and topics this deployment currently holds, the ground contract and its vocabulary, and what the deployment can and cannot do — which is not necessarily what the docs said last month.

Where to go next

  • Grounding — the full ground contract, and when to use it over search.
  • Search modes — when to use keyword, semantic or hybrid, and the query grammar that works in all three.
  • Filters and sorting — narrowing, and the two parameters that bias rather than filter.
  • Search recipes — worked examples for the questions people actually ask.
  • The Coverage Graph — the six calls that replace a retrieval loop.