unbrowseBeta
Connect

Docs

Quickstart

Call a website as an API in about two minutes: find the site, read its tools, then call one with your key. Steps 1 and 2 need no key.

1. Find the site

Every site Unbrowse has compiled is listed in the public registry. Search it by name or by what you want to do.

curl "https://unbrowse.ai/api/v1/sites?q=hacker+news"
{
  "total": 7879,
  "sites": [
    {
      "host": "news.ycombinator.com",
      "tools": 2,
      "mcp": "/api/v1/sites/news.ycombinator.com/mcp",
      "openapi": "/api/v1/sites/news.ycombinator.com/openapi.json"
    }
  ]
}

2. Read its tools

Each site is an OpenAPI 3.1 document with one operation per tool. Every tool has a typed input and an output schema learned from verified responses.

curl "https://unbrowse.ai/api/v1/sites/news.ycombinator.com/openapi.json"

The operation for reading a page is POST /api/v1/sites/news.ycombinator.com/call/news_ycombinator_com__read_page. It takes { "path": "/" }.

When Unbrowse knows an input a tool works with, the tool carries it as a ready-to-send example: in its request body in the OpenAPI document, in examples on its MCP input schema, and in unbrowse.discover results. For public tools that is the input Unbrowse verified the tool with. Send it as-is for a first call that works.

3. Get a key

Sign in, open MCP & keys and mint a key. Keys start with ub_live_. Send the key as a bearer token:

Authorization: Bearer ub_live_…

4. Call the tool

curl -X POST "https://unbrowse.ai/api/v1/sites/news.ycombinator.com/call/news_ycombinator_com__read_page" \
  -H "Authorization: Bearer $UNBROWSE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"path": "/"}'
{
  "runId": "lrun_12meih1",
  "status": "succeeded",
  "capabilityId": "public.news_ycombinator_com.read_page",
  "result": {
    "title": "Hacker News",
    "text": "1. OpenAI Feared \"Optics\" of what might appear on Hacker News …",
    "links": [{ "text": "new", "href": "https://news.ycombinator.com/newest" }]
  },
  "error": null,
  "via": "http",
  "verified": true,
  "cost": { "calls": 1, "browserMs": 0, "inference": 0 }
}

succeeded means the result was checked, not just that the site answered 200. Only verified successes bill. via: "http" means Unbrowse made one first-party request and opened no browser. An argument the tool does not take returns 422 unknown_argument with the list of arguments it does take.

5. A site with no tools yet

Give Unbrowse a task instead of a tool. The first run browses the site in Unbrowse's cloud browser, answers the task, and compiles the requests it saw into a tool. Later calls replay that tool over HTTP.

curl -X POST "https://unbrowse.ai/api/v1/runs" \
  -H "Authorization: Bearer $UNBROWSE_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: first-run-1" \
  -d '{"task": "list this week'\''s events", "targetUrl": "https://example.com/events"}'

A run still in progress returns 202 with status accepted or working. Poll GET /api/v1/runs/<runId> until it reaches succeeded, input_required, failed, outcome_unknown or cancelled. To cover a whole site ahead of time, start an index job: POST /api/v1/index.

6. Sites behind a sign-in

When a site needs a login you have not saved, the run ends failed with error session_or_permission and carries signIn.url, a one-time link. Open the link in the person's browser and save the login there. It is sealed in your workspace's password manager. Then run the call again. From then on Unbrowse signs in by itself and keeps the session. The agent never receives the password. See Errors & statuses.

7. Connect an agent (MCP)

The same tools are available over remote MCP at https://unbrowse.ai/mcp (Streamable HTTP). Clients with OAuth (Claude, Cursor) can leave out the header and sign in when prompted.

claude mcp add --transport http unbrowse https://unbrowse.ai/mcp \
  --header "Authorization: Bearer $UNBROWSE_API_KEY"
{
  "mcpServers": {
    "unbrowse": {
      "url": "https://unbrowse.ai/mcp",
      "headers": { "Authorization": "Bearer ub_live_…" }
    }
  }
}

One site on its own is also an MCP server: https://unbrowse.ai/api/v1/sites/<host>/mcp.

To give an agent only some apps, make a tool scope in Apps & tools (or POST /api/v1/scopes with {"slug": "research", "apps": ["github.com", "news.ycombinator.com"], "core": "run_only"}) and connect to https://unbrowse.ai/mcp/research. That connection lists, discovers and routes only to those apps' tools; core picks which Unbrowse tools it keeps (all, run_only, or a list). Clients that only take the plain URL can use https://unbrowse.ai/mcp?scope=research, and ?apps=github.com,news.ycombinator.com scopes a connection ad hoc. A tool switched off in Apps & tools is hidden from every connection; a tool you learned and published can be unpublished (and republished) there too.

Next