Documentation

Everything you need to automate browsers in the cloud. Get from zero to running in under a minute.

Quickstart

pip install browserfabric

export BROWSERFABRIC_API_KEY=bf_your_key_here

import browserfabric
import asyncio

async def main():
    async with browserfabric.browser() as session:
        await session.navigate("https://example.com")
        page = await session.snapshot()
        print(page)

asyncio.run(main())

# Create a session
curl -X POST https://api.browserfabric.com/api/v1/services/browseruse/call \
  -H "Authorization: Bearer bf_your_key" \
  -H "Content-Type: application/json" \
  -d '{"tool_name": "create_session", "arguments": {"headless": true}}'

Authentication

All API requests require an API key passed as a Bearer token in the Authorization header. Create keys from your dashboard.

Authorization: Bearer bf_your_api_key_here

{
  "name": "My Production Key",
  "permissions": {
    "browseruse": true,
    "web_search": true,
    "web_crawler": true
  }
}

{
  "api_key": "bf_abc123...",
  "key_prefix": "bf_abc123x",
  "name": "My Production Key",
  "permissions": {...}
}

Sessions

A session is a cloud browser instance. Each session runs a full Chromium browser and exposes a CDP WebSocket for direct connection.

{
  "tool_name": "create_session",
  "arguments": {
    "headless": true,
    "timeout": 30,
    "context_id": "optional-context-uuid",
    "persist": true
  }
}

{
  "success": true,
  "result": {
    "session_id": "uuid",
    "ws_url": "ws://host:port",
    "cdp_port": 12345,
    "context_restored": false
  }
}

{
  "tool_name": "close_session",
  "arguments": {},
  "session_id": "your-session-id"
}

{
  "tool_name": "get_session_info",
  "arguments": {},
  "session_id": "your-session-id"
}

Navigation & Actions

All browser actions are called through the same endpoint with different tool_name values. Pass session_id for all tool calls after session creation.

{
  "tool_name": "navigate",
  "arguments": {"url": "https://example.com"},
  "session_id": "your-session-id"
}

{
  "tool_name": "click_element",
  "arguments": {"selector": "#submit-btn", "by": "css"},
  "session_id": "your-session-id"
}

{
  "tool_name": "take_screenshot",
  "arguments": {"full_page": false},
  "session_id": "your-session-id"
}

{
  "tool_name": "wait_for",
  "arguments": {
    "selector": ".loading-spinner",
    "state": "hidden",
    "timeout": 10
  },
  "session_id": "your-session-id"
}

{
  "tool_name": "scroll",
  "arguments": {"direction": "down", "amount": 500},
  "session_id": "your-session-id"
}

Batch Operations

Execute multiple tool calls in a single HTTP request to reduce round-trips.

{
  "session_id": "your-session-id",
  "operations": [
    {"tool_name": "navigate", "arguments": {"url": "https://example.com"}},
    {"tool_name": "wait_for", "arguments": {"selector": "h1"}},
    {"tool_name": "take_screenshot", "arguments": {}}
  ],
  "stop_on_error": true
}

{
  "success": true,
  "results": [
    {"index": 0, "tool_name": "navigate", "success": true, "result": {...}},
    {"index": 1, "tool_name": "wait_for", "success": true, "result": {...}},
    {"index": 2, "tool_name": "take_screenshot", "success": true, "result": {...}}
  ],
  "total": 3,
  "duration_ms": 450
}

Persistent Contexts

Contexts save cookies and localStorage so you can resume sessions later without re-authenticating. There are two ways to persist:

{
  "contexts": [
    {
      "id": "uuid",
      "name": "twitter-login",
      "domain": "https://twitter.com/",
      "cookies_count": 12,
      "created_at": "2026-03-16T..."
    }
  ],
  "total": 1
}

CDP WebSocket

Every session exposes a Chrome DevTools Protocol WebSocket URL. Connect to it with Playwright, Puppeteer, or any CDP client for full browser control.

from playwright.async_api import async_playwright

# 1. Create session via BrowserFabric API
# response.result.ws_url = "ws://api.browserfabric.com:PORT"

# 2. Connect with Playwright
pw = await async_playwright().start()
browser = await pw.chromium.connect_over_cdp(ws_url)
page = browser.contexts[0].pages[0]

# 3. Full Playwright API available
await page.goto("https://example.com")
await page.screenshot(path="screenshot.png")
await page.fill("#email", "user@example.com")
await page.click("button[type=submit]")

Agent Skill

BrowserFabric is available as an agent skill that can be installed with one command. Skills inject browser automation capabilities into Claude Code, Cursor, Cline, and other skill-compatible agents — no configuration needed beyond your API key.

Install the skill

npx skills add https://www.browserfabric.com

This installs the BrowserFabric skill into your agent. The skill teaches the agent when and how to use cloud browsers — it automatically activates when you ask the agent to browse a website, fill a form, take a screenshot, or manage a logged-in session.

What the agent learns

The skill teaches your agent to:

• Call BrowserFabric's REST API via curl with your API key
• Create persistent or temporary browser sessions
• Navigate, click, type, scroll, and take screenshots
• Save login state and resume authenticated sessions later
• Hand off browser tabs to humans for CAPTCHA/2FA
• Use observe to understand page structure before acting

Try it now — copy-paste commands for popular agents

After installing the skill and setting your API key, run one of these commands in your agent:

# Install skill + set API key
npx skills add https://www.browserfabric.com
export BROWSERFABRIC_API_KEY=bf_your_key_here

# Try it (one-liner)
claude --dangerously-skip-permissions -p "use browserfabric to list the top 5 news on hackernews"

# Or in an interactive session
claude
> use browserfabric to take a screenshot of example.com

# Install skill + set API key
npx skills add https://www.browserfabric.com
export BROWSERFABRIC_API_KEY=bf_your_key_here

# Try it
codex "use browserfabric to check what's on the front page of hackernews"

# Install skill
npx skills add https://www.browserfabric.com

# Set BROWSERFABRIC_API_KEY in Cursor Settings → Environment Variables
# Then in Cursor chat:
> use browserfabric to open example.com and tell me the page title

# Install skill + set API key
npx skills add https://www.browserfabric.com
export BROWSERFABRIC_API_KEY=bf_your_key_here

# Then ask your agent:
> use browserfabric to fill out the contact form on example.com

# No skill install needed — just curl directly
export BROWSERFABRIC_API_KEY=bf_your_key_here

SID=$(curl -s -X POST https://api.browserfabric.com/api/v1/services/browseruse/call \
  -H "Authorization: Bearer $BROWSERFABRIC_API_KEY" -H "Content-Type: application/json" \
  -d '{"tool_name":"create_session","arguments":{"headless":true}}' | jq -r .session_id)

curl -s -X POST https://api.browserfabric.com/api/v1/services/browseruse/call \
  -H "Authorization: Bearer $BROWSERFABRIC_API_KEY" -H "Content-Type: application/json" \
  -d "{\"tool_name\":\"navigate\",\"arguments\":{\"url\":\"https://example.com\"},\"session_id\":\"$SID\"}"

curl -s -X POST https://api.browserfabric.com/api/v1/services/browseruse/call \
  -H "Authorization: Bearer $BROWSERFABRIC_API_KEY" -H "Content-Type: application/json" \
  -d "{\"tool_name\":\"observe\",\"arguments\":{},\"session_id\":\"$SID\"}"

curl -s -X POST https://api.browserfabric.com/api/v1/services/browseruse/call \
  -H "Authorization: Bearer $BROWSERFABRIC_API_KEY" -H "Content-Type: application/json" \
  -d "{\"tool_name\":\"close_session\",\"arguments\":{},\"session_id\":\"$SID\"}"

Three ways to use BrowserFabric

MCP Integration

BrowserFabric is a hosted Model Context Protocol server. Point any MCP-speaking agent — Claude Desktop, Cursor, Cline, the Anthropic Agent SDK, your own app — at https://www.browserfabric.com/mcp with your API key and you get all 28 browser tools (create_session, navigate, click_element, type_text, take_screenshot, evaluate_js, save_context, list_contexts, and more).

Claude Desktop

Edit ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "browserfabric": {
      "url": "https://www.browserfabric.com/mcp",
      "headers": {
        "Authorization": "Bearer bf_your_api_key_here"
      }
    }
  }
}

Quit and relaunch Claude Desktop. The tools appear under the 🔌 icon in the composer.

Cursor

Open Cursor Settings → Features → MCP Servers → Add, then paste:

{
  "name": "browserfabric",
  "type": "http",
  "url": "https://www.browserfabric.com/mcp",
  "headers": {
    "Authorization": "Bearer bf_your_api_key_here"
  }
}

Cline / Continue / any MCP-compatible client

Any client that speaks the MCP streamable-http transport can use the same URL. Most accept a headers map next to the URL — put your bearer token there.

Python (Claude Agent SDK, MCP library)

import asyncio
from mcp import ClientSession
from mcp.client.streamable_http import streamablehttp_client

async def main():
    async with streamablehttp_client(
        "https://www.browserfabric.com/mcp",
        headers={"Authorization": "Bearer bf_your_api_key_here"},
    ) as (read, write, _):
        async with ClientSession(read, write) as session:
            await session.initialize()

            tools = await session.list_tools()
            print([t.name for t in tools.tools])

            r = await session.call_tool("create_session", {"headless": True})
            session_data = r.content[0].text  # JSON string

asyncio.run(main())

TypeScript (Anthropic Agent SDK)

import Anthropic from "@anthropic-ai/sdk";

const client = new Anthropic();

const stream = client.beta.messages.stream({
  model: "claude-opus-4-6",
  max_tokens: 4096,
  mcp_servers: [
    {
      type: "url",
      url: "https://www.browserfabric.com/mcp",
      name: "browserfabric",
      authorization_token: "bf_your_api_key_here",
    },
  ],
  messages: [
    { role: "user", content: "Open example.com and summarise the page." },
  ],
});

for await (const event of stream) {
  // MCP tool calls happen automatically via the SDK's MCP connector
}

A note on persistence

Sessions you create over MCP are the same sessions you see in your dashboard Sessions tab, and contexts saved with save_context are reusable across MCP, REST, and the SDKs — that's the whole point of a hosted cloud browser. An agent can hand a running tab off to a human (and vice versa) just by sharing the session_id.

Usage Tracking

Every API call is tracked with timing data. Query your usage from the API or view it on your dashboard.

{
  "total_calls": 142,
  "period_days": 30,
  "by_service": {
    "browseruse": 128,
    "web_search": 14
  }
}

REST API

All 28 browser tools are available via a single REST endpoint. No SDK needed — just HTTP calls from any language.

{
  "tool_name": "navigate",
  "arguments": { "url": "https://example.com" },
  "session_id": "SESSION_ID"
}

{
  "success": true,
  "result": { "url": "https://example.com/", "title": "Example Domain", "status": 200 },
  "session_id": "SESSION_ID"
}

# Create a session
curl -X POST https://api.browserfabric.com/api/v1/services/browseruse/call \
  -H "Authorization: Bearer bf_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"tool_name":"create_session","arguments":{"headless":true,"persist":true}}'
# Returns: {"session_id":"abc-123-...", "status":"created"}

# Navigate
curl -X POST https://api.browserfabric.com/api/v1/services/browseruse/call \
  -H "Authorization: Bearer bf_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"tool_name":"navigate","arguments":{"url":"https://example.com"},"session_id":"abc-123-..."}'

# Close (auto-saves context if persist=true)
curl -X POST https://api.browserfabric.com/api/v1/services/browseruse/call \
  -H "Authorization: Bearer bf_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"tool_name":"close_session","arguments":{},"session_id":"abc-123-..."}'

SDKs

Python

pip install browserfabric

from browserfabric import SyncBrowserFabric

bf = SyncBrowserFabric(api_key="bf_YOUR_KEY")

# Create a persistent session
session = bf.create_session(headless=True)
session.navigate("https://example.com")
info = session.page_info()
print(info["title"])  # "Example Domain"
shot = session.screenshot()
session.close()  # auto-saves if persist=True

TypeScript / JavaScript

npm install browserfabric

import { BrowserFabric } from "browserfabric";

const bf = new BrowserFabric({ apiKey: "bf_YOUR_KEY" });

const session = await bf.createSession({ headless: true });
await session.navigate("https://example.com");
const info = await session.pageInfo();
console.log(info.title); // "Example Domain"
await session.close();

Error Handling

{
  "success": true | false,
  "result": { ... },
  "session_id": "uuid or null",
  "error": "error message or null"
}