> Documentation index: https://unbrowse.ai/llms.txt. Fetch it to find every page.

# 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.

```bash
curl "https://unbrowse.ai/api/v1/sites?q=hacker+news"
```

```json
{
  "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.

```bash
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](/app/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

```bash
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": "/"}'
```

```json
{
  "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.

```bash
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](/docs/errors).

## 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.

```bash
claude mcp add --transport http unbrowse https://unbrowse.ai/mcp \
  --header "Authorization: Bearer $UNBROWSE_API_KEY"
```

```json
{
  "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](/app/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

- [Errors & statuses](/docs/errors): every error code and what to do about it.
- [Reference](/docs): REST endpoints, MCP tools, logins, orgs.
- [Agent skill](/skill/SKILL.md): drop-in instructions for coding agents.