unlob Docs
Console
Browse documentation

curl

Everything the API does, from a terminal.

Setup

export UNLOB_API_KEY=ulb_...
alias unlob='curl -sG -H "x-api-key: $UNLOB_API_KEY" https://api.unlob.com'

-G puts the data as a query string, which is what lets --data-urlencode handle spaces and quotes in a query without you escaping anything.

unlob /search --data-urlencode 'q=how does tokio schedule tasks'
unlob /search --data-urlencode 'q=async runtime' -d vertical=code -d limit=5
unlob /search -d q=kernel -d term=CVE-2024-3094
unlob /search --data-urlencode 'q=bank rates' -d collapse=story -d facets=true

Pipe through jq to read it:

unlob /search --data-urlencode 'q=tokio' | jq -r '.results[] | "\(.title)\n\(.url)\n\(.snippet)\n"'

Check partial before trusting a short answer

unlob /search --data-urlencode 'q=obscure topic' \
  | jq 'if .partial then "INCOMPLETE — retry" else .total end'

The graph

unlob /corroborate -d 'id=<passage-id>'
unlob /dossier --data-urlencode 'entity=Acme Corporation'
unlob /authorities -d topic=cryptography
unlob /assemble_context --data-urlencode 'q=what should I know about X' -d budget=4000

What the API says about itself

No key needed:

curl -s https://api.unlob.com/describe | jq '.filters'
curl -s https://api.unlob.com/llms.txt
curl -s https://api.unlob.com/openapi.json | jq '.paths | keys'
curl -s https://api.unlob.com/mcp/tools.json | jq -r '.tools[].name'
curl -s https://api.unlob.com/guides/search-recipes

Watch the rate limit

curl -sD- -o /dev/null -H "x-api-key: $UNLOB_API_KEY" \
  'https://api.unlob.com/search?q=test' | grep -i ratelimit

Your account

unlob /account | jq

MCP by hand

Worth knowing when a client is failing silently — the status codes tell you which step broke. Note the accept header naming both types; a client that names only one is out of spec.

curl -sD- https://api.unlob.com/mcp \
  -H "x-api-key: $UNLOB_API_KEY" \
  -H 'content-type: application/json' \
  -H 'accept: application/json, text/event-stream' \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{
        "protocolVersion":"2025-06-18","capabilities":{},
        "clientInfo":{"name":"curl","version":"0"}}}'

Then a tool call:

curl -s https://api.unlob.com/mcp \
  -H "x-api-key: $UNLOB_API_KEY" \
  -H 'content-type: application/json' \
  -H 'accept: application/json, text/event-stream' \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{
        "name":"web_search","arguments":{"query":"tokio","limit":3}}}' \
  | jq -r '.result.content[0].text' | jq

A shell function that handles the two 429s

unlob_search() {
  local out status
  out=$(curl -sG -w '\n%{http_code}' -H "x-api-key: $UNLOB_API_KEY" \
        -D /tmp/unlob.h "https://api.unlob.com/search" --data-urlencode "q=$1")
  status=$(tail -n1 <<<"$out")
  if [ "$status" = 429 ]; then
    if grep -qi '^retry-after' /tmp/unlob.h; then
      sleep 1; unlob_search "$1"; return
    fi
    # No retry-after means a hard-capped monthly quota. Retrying will not help.
    echo "quota exhausted" >&2; return 1
  fi
  sed '$d' <<<"$out"
}

Next