# looot

One gateway to discover, inspect, run and pay for provider operations (email verification,
SEO/SERP data, enrichment, social and more) with one account, one pricing model and one
run/idempotency contract instead of an SDK per provider.

## MCP

Streamable HTTP transport at https://api.looot.ai/mcp. Sign in with the browser (OAuth, no token):

```
claude mcp add looot https://api.looot.ai/mcp --transport http
```

then /mcp, looot, Authenticate (Codex, Cursor, Gemini CLI too). Headless fallback: add
`--header "Authorization: Bearer $LOOOT_TOKEN"` to that command.

16 tools: balance, capability_request, catalog_overview, discover, discover_smart, inspect, media_link, my_tools, run, runs_cancel, runs_evidence, runs_get, runs_list, search, search_catalog, top_up.
register_endpoint, verify_endpoint: platform operators (provider-registry:write) only.
Full descriptions and schemas: /llms-full.txt.

## Token (REST and headless clients)

1. Go to https://looot.ai/auth/sign-up and create an account with email and password (or
   https://looot.ai/auth/sign-in if you already have one). This creates your organization.
2. Open Settings, the "Agent tokens" tab, and "Create agent token". Tick the scopes it
   needs -- `catalog.read`, `runs.read`, `runs.execute` cover discover/inspect/run/runs_get;
   add `usage.read` for balance, `connections.read` for connections, `workflows.read`/
   `workflows.execute` for workflows -- and submit.
3. Copy the `cs_ms_...` secret (it is shown once) and set it as LOOOT_TOKEN in your
   environment. Never hardcode or commit it.
4. Top up before your first paid run: a new workspace starts at $0 and runs get 402
   insufficient_balance until you do. Minimum: topUpLink.minimumUsd from GET /v1/balance.
   Pay at https://looot.ai/usage, POST /v1/top-ups or the top_up tool. Browsing is free.

REST, MCP and CLI all send it as `Authorization: Bearer ${LOOOT_TOKEN}`. Only this page,
/skill.md, /catalog/*.md, /install.sh and the OpenAPI document work with no token.

## CLI

Install: `npm install -g looot`.
Then `looot login` (or set LOOOT_TOKEN), and top up (`looot balance` shows the minimum)
before your first `looot run`:

```
looot run <endpoint-id> --input '{"..."}' [--idempotency-key <key>] [--wait] [--fallback]
looot inspect <endpoint-id>
looot search "<query>"
looot runs get|list|cancel|evidence <run-id>
looot balance
looot whoami
looot init
```

`looot init` wires the MCP server into Claude Code/Cursor/Codex and writes the SKILL.md served
at /skill.md. `looot help --all` lists every command and flag; every command accepts
`--format json|human|jsonl`.

## Customer REST routes

- `GET /v1/discover` -- Discover operations
  e.g. `GET /v1/discover?query=enrich+a+company+from+its+domain&mode=auto` -> `{"candidates":[{"endpointId":"parity-tomba-companies-enrich","provider":"tomba","access":"runs_now", ...}],"meta":{...}}`
- `GET /v1/catalog/search` -- Ranked full-text catalog search, with capability expansion and a stemmed-token fallback so a long natural-language query is never empty
  e.g. `GET /v1/catalog/search?q=verify+an+email&limit=5` -> `{"query":"verify an email","total":3,"endpoints":[{"endpointId":"hunter-email-verify","access":"coming_soon", ...}]}`
- `GET /v1/catalog/endpoints` -- Paged, filtered, faceted catalog listing
  e.g. `GET /v1/catalog/endpoints?capability=company.enrich&limit=20` -> `{"endpoints":[{"endpointId":"parity-tomba-companies-enrich","access":"runs_now", ...}],"nextCursor":null}`
- `GET /v1/operations/{endpointId}` -- Inspect an operation
  e.g. `GET /v1/operations/parity-tomba-companies-enrich` -> `{"endpoint":{"id":"parity-tomba-companies-enrich","price":{"estimateFormula":"$0.0089 / call"}},"usageHints":{...},"inputSchema":{...}}`
- `POST /v1/runs` -- Create a run -- idempotencyKey replay returns the existing run (any status) with replayed:true instead of creating a new one
  e.g. `POST /v1/runs?wait=20 {"endpointId":"icypeas-email-verify","input":{"email":"patrick@stripe.com"},"idempotencyKey":"<key>"}` -> `{"runId":"run_000028","status":"completed","result":{"raw":"..."},"actualCost":0.0019,"error":null}  -- or, past the wait window (or wait omitted): {"runId":"run_000028","status":"queued","estimatedCost":0.0019,"reservationId":"res_000025"}`
- `GET /v1/runs/{runId}` -- Get a run -- on a failed run, error carries { code, providerStatus, message, requestId, whoseError, retryable, retryHint }, never secrets or raw provider headers
  e.g. `GET /v1/runs/run_000028` -> `{"status":"completed","result":{"raw":"..."},"actualCost":0,"error":null}`
- `POST /v1/runs/{runId}/cancel` -- Cancel a run
  e.g. `POST /v1/runs/run_000028/cancel` -> `{"status":"stopped"}`
- `GET /v1/runs/{runId}/attempts` -- Inspect durable attempts and receipts
  e.g. `GET /v1/runs/run_000028/attempts` -> `{"attempts":[{"providerId":"hunter","status":"succeeded","costMicros":12250, ...}]}`
- `GET /v1/balance` -- Get workspace balance. topUpLink includes purchase minimum, dashboard and any pending checkout. Compare funds with each run estimate; the purchase minimum is not a wallet threshold. Reading balance never creates checkout
  e.g. `GET /v1/balance` -> `{"available":0,"reserved":0,"topUpLink":{"minimumUsd":<gateway minimum>, ...}}`
- `GET /v1/top-ups` -- List prepaid top-ups
  e.g. `GET /v1/top-ups` -> `{"topUps":[{"amountMicros":20000000,"status":"succeeded", ...}]}`

Full route list with examples: /llms-full.txt (alias /integrate.md). Contract: /openapi.json.
MCP descriptor: /.well-known/mcp.json. Agent cards: /catalog/{endpointId}.md. SKILL.md: /skill.md.
What exists, no token: GET /v1/catalog/overview (?topic=email ?category= ?depth=; MCP catalog_overview).

## Ranking

`prefer` on search and discover: balanced (default), cheapest, reliable, fastest, else a
validation_error. It orders providers inside a job. Full rows carry
`facts` (price, cost per success, success and sample, p50, async, inputs); discover `ranking` is an alias.

## What runs today

Every endpoint carries an `access` field: `runs_now` (callable now: keyless rows, `mock-*` and
`parity-*` fixtures, live providers), `needs_your_account` (acts on your own connected account,
e.g. Instantly/Gmail) or `coming_soon` (a real provider with no platform key yet; calling one
returns a `provider_error`, not a result). Check `access` before you pick an endpoint;
GET /v1/catalog/search and GET /v1/discover both report it.

## Errors

REST errors are `{error: {code, message, requestId}}` plus a status: 402 insufficient_balance,
403 forbidden/platform_operator_required, 404 not_found, 409 idempotency_conflict (same key, new
body; the same body replays). 429 too_many_inflight_runs (the body's `limit`) or
rate_limit_exceeded (x-ratelimit-*, retry-after). 503 catalog_loading/storage_busy/
runtime_bridge_timeout/billing_unavailable: transient, retry-after. A 201 can carry
status:"failed" (a pre-dispatch denial); check `status` and `error`. Full list: /llms-full.txt.

## Live providers

Real providers with an approved, priced platform key -- callable right now with no connection of your own:

- **Adyntel** -- 10 endpoints, cheapest priced runs_now: `adyntel-google` ($0.00642 all-in). Details: /catalog/providers/adyntel.md
- **AI Ark** -- 21 endpoints, cheapest priced runs_now: `ai-ark-companies` ($0.0012 all-in). Details: /catalog/providers/ai-ark.md
- **Akta** -- 14 endpoints, cheapest priced runs_now: `akta-news` ($0.0005 all-in). Details: /catalog/providers/akta.md
- **AnyAPI** -- 37 endpoints, cheapest priced runs_now: `anyapi-run-twitter-profile` ($0.00022 all-in). Details: /catalog/providers/anyapi.md
- **Anysite** -- 120 endpoints, cheapest priced runs_now: `anysite-api-minnesota-companies-search` ($0.000037 all-in). Details: /catalog/providers/anysite.md
- **Apify** -- 55 endpoints, cheapest priced runs_now: `apify-dataset-items` ($0.0001 all-in). Details: /catalog/providers/apify.md
- **Aviato** -- 42 endpoints, cheapest priced runs_now: `aviato-images-token` ($0.0020 all-in). Details: /catalog/providers/aviato.md
- **BounceBan** -- 12 endpoints, cheapest priced runs_now: `bounceban-verify` ($0.0040 all-in). Details: /catalog/providers/bounceban.md
- **Brave Search** -- 6 endpoints, cheapest priced runs_now: `brave-search-res-news-search` ($0.0050 all-in). Details: /catalog/providers/brave-search.md
- **Bright Data** -- 14 endpoints, cheapest priced runs_now: `brightdata-amazon-product` ($0.0015 all-in). Details: /catalog/providers/brightdata.md
- **Browser Use** -- 32 endpoints. Details: /catalog/providers/browser-use.md
- **BuiltWith** -- 12 endpoints, cheapest priced runs_now: `builtwith-api-json` ($0.0495 all-in). Details: /catalog/providers/builtwith.md
- **Cloro** -- 12 endpoints, cheapest priced runs_now: `cloro-monitor-google` ($0.0040 all-in). Details: /catalog/providers/cloro.md
- **CloudConvert** -- 15 endpoints, cheapest priced runs_now: `cloudconvert-archive` ($0.0080 all-in). Details: /catalog/providers/cloudconvert.md
- **CoinMarketCap** -- 18 endpoints, cheapest priced runs_now: `coinmarketcap-cryptocurrency-categories` ($0.000193 all-in). Details: /catalog/providers/coinmarketcap.md
- **CompanyEnrich** -- 47 endpoints, cheapest priced runs_now: `companyenrich-companies-enrich-bulk` ($0.0098 all-in). Details: /catalog/providers/companyenrich.md
- **Context.dev** -- 79 endpoints, cheapest priced runs_now: `context-dev-news-search` ($0.00025 all-in). Details: /catalog/providers/context-dev.md
- **Coresignal** -- 26 endpoints, cheapest priced runs_now: `coresignal-employee-post-collect` ($0.0196 all-in). Details: /catalog/providers/coresignal.md
- **DataForSEO** -- 329 endpoints, cheapest priced runs_now: `dataforseo-on-page-content-parsing-live-ai` ($0.000125 all-in). Details: /catalog/providers/dataforseo.md
- **Datagma** -- 15 endpoints, cheapest priced runs_now: `datagma-find-email` ($0.01633 all-in). Details: /catalog/providers/datagma.md
- **Deepgram** -- 50 endpoints, cheapest priced runs_now: `deepgram-speak` ($0.00003 all-in). Details: /catalog/providers/deepgram.md
- **Diffbot** -- 10 endpoints, cheapest priced runs_now: `diffbot-job` ($0.001196 all-in). Details: /catalog/providers/diffbot.md
- **Dropleads** -- 14 endpoints, cheapest priced runs_now: `dropleads-company-enrich` ($0.00145 all-in). Details: /catalog/providers/dropleads.md
- **ElevenLabs** -- 3 endpoints, cheapest priced runs_now: `elevenlabs-text-to-speech-audio` ($0.00008 all-in). Details: /catalog/providers/elevenlabs.md
- **Enrichlayer** -- 29 endpoints, cheapest priced runs_now: `enrichlayer-api-company-employees-count` ($0.0264 all-in). Details: /catalog/providers/enrichlayer.md
- **EODHD** -- 88 endpoints, cheapest priced runs_now: `eodhd-calendar-dividends` ($0.000033 all-in). Details: /catalog/providers/eodhd.md
- **Exa** -- 65 endpoints, cheapest priced runs_now: `exa-contents` ($0.0010 all-in). Details: /catalog/providers/exa.md
- **Fetchin** -- 11 endpoints, cheapest priced runs_now: `fetchin-company` ($0.0015 all-in). Details: /catalog/providers/fetchin.md
- **Findymail** -- 36 endpoints, cheapest priced runs_now: `findymail-api-search-company` ($0.0198 all-in). Details: /catalog/providers/findymail.md
- **Firecrawl** -- 18 endpoints, cheapest priced runs_now: `firecrawl-extract` ($0.000333 all-in). Details: /catalog/providers/firecrawl.md
- **FullEnrich** -- 10 endpoints, cheapest priced runs_now: `fullenrich-api-company-lookup` ($0.0160 all-in). Details: /catalog/providers/fullenrich.md
- **Fundable** -- 19 endpoints, cheapest priced runs_now: `fundable-company-search` ($0.0050 all-in). Details: /catalog/providers/fundable.md
- **HarvestAPI** -- 29 endpoints, cheapest priced runs_now: `harvestapi-geo-id-search` ($0.0010 all-in). Details: /catalog/providers/harvestapi.md
- **Hunter** -- 184 endpoints, cheapest priced runs_now: `hunter-domain-search-get` ($0.00245 all-in). Details: /catalog/providers/hunter.md
- **Hyperbrowser** -- 84 endpoints, cheapest priced runs_now: `hyperbrowser-api-scrape` ($0.0010 all-in). Details: /catalog/providers/hyperbrowser.md
- **Icypeas** -- 19 endpoints, cheapest priced runs_now: `icypeas-find-companies` ($0.00038 all-in). Details: /catalog/providers/icypeas.md
- **IPinfo** -- 48 endpoints, cheapest priced runs_now: `ipinfo-city-2` ($0.0005 all-in). Details: /catalog/providers/ipinfo.md
- **Jina Reader API** -- 5 endpoints, cheapest priced runs_now: `jina-classify` ($0.0002 all-in). Details: /catalog/providers/jina.md
- **Just One API** -- 58 endpoints, cheapest priced runs_now: `justoneapi-api-xiaohongshu-share-url-transfer` ($0.01476 all-in). Details: /catalog/providers/justoneapi.md
- **Keenable** -- 2 endpoints, cheapest priced runs_now: `keenable-fetch` ($0.0040 all-in). Details: /catalog/providers/keenable.md
- **Kitt AI** -- 4 endpoints, cheapest priced runs_now: `kittai-verify-email` ($0.0015 all-in). Details: /catalog/providers/kittai.md
- **LeadMagic** -- 8 endpoints, cheapest priced runs_now: `leadmagic-people-employee-finder` ($0.00099 all-in). Details: /catalog/providers/leadmagic.md
- **Limadata** -- 15 endpoints, cheapest priced runs_now: `limadata-api-database-search-companies` ($0.0020 all-in). Details: /catalog/providers/limadata.md
- **Linkup** -- 13 endpoints, cheapest priced runs_now: `linkup-fetch` ($0.0010 all-in). Details: /catalog/providers/linkup.md
- **Lusha** -- 7 endpoints, cheapest priced runs_now: `lusha-companies-prospecting` ($0.0050 all-in). Details: /catalog/providers/lusha.md
- **Marketstack** -- 46 endpoints, cheapest priced runs_now: `marketstack-commodities` ($0.000899 all-in). Details: /catalog/providers/marketstack.md
- **MillionVerifier** -- 2 endpoints, cheapest priced runs_now: `millionverifier-verify` ($0.00178 all-in). Details: /catalog/providers/millionverifier.md
- **NewsData.io API** -- 12 endpoints, cheapest priced runs_now: `newsdata-io-1-crypto` ($0.0100 all-in). Details: /catalog/providers/newsdata-io.md
- **Octen** -- 4 endpoints, cheapest priced runs_now: `octen-web-search` ($0.0060 all-in). Details: /catalog/providers/octen.md
- **Olostep** -- 43 endpoints, cheapest priced runs_now: `olostep-crawl-start` ($0.0018 all-in). Details: /catalog/providers/olostep.md
- **OpenCage** -- 4 endpoints, cheapest priced runs_now: `opencage-json` ($0.000167 all-in). Details: /catalog/providers/opencage.md
- **Openmart** -- 17 endpoints, cheapest priced runs_now: `openmart-search` ($0.00894 all-in). Details: /catalog/providers/openmart.md
- **OpenRouter** -- 2 endpoints, cheapest priced runs_now: `openrouter-chat` ($0.000006 all-in). Details: /catalog/providers/openrouter.md
- **Parallel** -- 35 endpoints, cheapest priced runs_now: `parallel-extract` ($0.0010 all-in). Details: /catalog/providers/parallel.md
- **People Data Labs** -- 22 endpoints, cheapest priced runs_now: `people-data-labs-company-enrich` ($0.2800 all-in). Details: /catalog/providers/people-data-labs.md
- **PredictLeads** -- 32 endpoints, cheapest priced runs_now: `predictleads-companies-connections` ($0.0100 all-in). Details: /catalog/providers/predictleads.md
- **Prospeo** -- 8 endpoints, cheapest priced runs_now: `prospeo-bulk-enrich-company` ($0.0390 all-in). Details: /catalog/providers/prospeo.md
- **QuickEnrich** -- 13 endpoints, cheapest priced runs_now: `quickenrich-api-companies-company-finder` ($0.00483 all-in). Details: /catalog/providers/quickenrich.md
- **Replicate HTTP API** -- 38 endpoints, cheapest priced runs_now: `replicate-models-predictions` ($0.0030 all-in). Details: /catalog/providers/replicate.md
- **ScrapeCreators** -- 189 endpoints, cheapest priced runs_now: `scrapecreators-google-advertisers-search` ($0.00188 all-in). Details: /catalog/providers/scrapecreators.md
- **ScrapeGraphAI** -- 14 endpoints, cheapest priced runs_now: `scrapegraphai-scrape` ($0.0020 all-in). Details: /catalog/providers/scrapegraphai.md
- **Scrubby** -- 5 endpoints, cheapest priced runs_now: `scrubby-validate` ($0.0078 all-in). Details: /catalog/providers/scrubby.md
- **SearchAPI.io** -- 138 endpoints, cheapest priced runs_now: `searchapi-io-linkedin-ad-library` ($0.0040 all-in). Details: /catalog/providers/searchapi-io.md
- **SerpApi** -- 32 endpoints, cheapest priced runs_now: `serpapi-amazon` ($0.0250 all-in). Details: /catalog/providers/serpapi.md
- **Serper** -- 13 endpoints, cheapest priced runs_now: `serper-images` ($0.0010 all-in). Details: /catalog/providers/serper.md
- **Signalbase** -- 17 endpoints, cheapest priced runs_now: `signalbase-companies` ($0.1080 all-in). Details: /catalog/providers/signalbase.md
- **Steel API** -- 45 endpoints, cheapest priced runs_now: `steel-pdf` ($0.0050 all-in). Details: /catalog/providers/steel.md
- **Sumble** -- 29 endpoints, cheapest priced runs_now: `sumble-jobs-title-lookup` ($0.0001 all-in). Details: /catalog/providers/sumble.md
- **Tavily Search and Extract API** -- 9 endpoints, cheapest priced runs_now: `tavily-map` ($0.0008 all-in). Details: /catalog/providers/tavily.md
- **The Companies API** -- 44 endpoints, cheapest priced runs_now: `thecompaniesapi-companies-ask` ($0.0019 all-in). Details: /catalog/providers/thecompaniesapi.md
- **TheirStack** -- 55 endpoints, cheapest priced runs_now: `theirstack-jobs-search` ($0.0327 all-in). Details: /catalog/providers/theirstack.md
- **TikHub** -- 1064 endpoints, cheapest priced runs_now: `tikhub-api-douyin-app-fetch-brand-hot-search-list` ($0.0010 all-in). Details: /catalog/providers/tikhub.md
- **TinyFish Search API** -- 33 endpoints, cheapest priced runs_now: `tinyfish-automation-run` ($0.0160 all-in). Details: /catalog/providers/tinyfish.md
- **Tomba** -- 157 endpoints, cheapest priced runs_now: `tomba-companies-find` ($0.0089 all-in). Details: /catalog/providers/tomba.md
- **Trestle** -- 9 endpoints, cheapest priced runs_now: `trestleiq-address-validation` ($0.0100 all-in). Details: /catalog/providers/trestleiq.md
- **TypeSafe (Jev)** -- 3 endpoints, cheapest priced runs_now: `typesafe-noul` ($0.00029 all-in). Details: /catalog/providers/typesafe.md
- **You.com** -- 9 endpoints, cheapest priced runs_now: `youcom-contents` ($0.0010 all-in). Details: /catalog/providers/youcom.md
- **ZeroBounce** -- 8 endpoints, cheapest priced runs_now: `zerobounce-guessformat` ($0.0100 all-in). Details: /catalog/providers/zerobounce.md
- **Zyte API** -- 5 endpoints, cheapest priced runs_now: `zyte-raw-html` ($0.00044 all-in). Details: /catalog/providers/zyte-api.md

## Pricing

Prepaid workspace balance. A run reserves its endpoint's estimated cost up front, then one
of three outcomes applies: refused before admission holds and charges nothing; a definitive
failure releases the hold and settles at $0 or the provider's evidenced cost; an uncertain
outcome parks as reconciliation_pending with the hold retained until an operator decision.
New workspaces start at $0; GET /v1/balance shows topUpLink.minimumUsd.
POST /v1/top-ups creates a Stripe Checkout session ($5-$500); out of credits, 402 carries
topUp.checkoutUrl (Stripe's hosted page) and topUp.message to show the customer.
Every endpoint's exact price formula is in its GET /v1/operations/{endpointId} response and
in its /catalog/{id}.md card.