---
name: browserfabric
description: "Cloud browser automation via curl REST API. No MCP needed — just run curl commands with $BROWSERFABRIC_API_KEY."
metadata:
  version: "1.3.0"
  requires:
    env: ["BROWSERFABRIC_API_KEY"]
---

> The cloud browser for AI agents. Your tools, our browsers.


# BrowserFabric — Cloud Browser via curl

Use available BrowserFabric MCP tools, its SDK, or the REST calls below. Do not configure an MCP server or change agent settings as part of an ordinary browsing task.

The `$BROWSERFABRIC_API_KEY` environment variable must be set. If it is, you're ready — start with step 1 below.

## Preferred agent workflow

On servers exposing `observe_page` and `act`, use these tools for ordinary browsing. The examples below using selectors remain supported for older servers and advanced operations.

1. Create or resume a session. `browser_tabs` lists tabs; `operation: "select"` with `tab_id` selects the tab used by legacy `navigate` and the live view. New tabs start blank.
2. Navigate, then call `observe_page` with `tab_id`. Read its `observation_id`, element `ref`s, names, roles, and form states. Values of inputs are omitted; password fields are marked `sensitive`.
3. Call `act` with that `tab_id`, `observation_id`, and an `actions` array. Batch predictable steps, such as filling two fields and clicking submit. Use `check` with `checked: true` instead of toggling a checkbox. Add a `wait_for` condition for the outcome you need.
4. Inspect the returned status and observation. `completed` means actions executed; `verified` means the specified condition also matched. `condition_not_met` and `action_failed` include recovery state. `interrupted` means navigation, popup, or dialog stopped remaining steps; do not blindly replay the batch.

Example `arguments` for `act` (use refs actually returned by your observation):

```json
{
  "tab_id": "TAB_ID",
  "observation_id": "OBSERVATION_ID",
  "request_id": "UNIQUE_REQUEST_ID",
  "actions": [
    {"type": "fill", "ref": "FIELD_REF", "text": "example.com"},
    {"type": "click", "ref": "SEARCH_REF"}
  ],
  "wait_for": {"text": "Authority Score"},
  "timeout_ms": 10000
}
```

- `act` returns a diff relative to its input observation. Apply `added`, `changed`, and `removed`; omitted text is unchanged. Use the new `observation_id` next. Request `observe_page` without `since` when you need a full reset.
- A stale observation or replaced element is rejected. Inspect the new state and decide again; never substitute another element just because it has the same selector.
- Popups return `opened_tab_ids`; inspect the new tab explicitly. Selecting it also updates the live view. A tab does not become the target of subsequent `act` calls implicitly.
- For visual controls, call `browser_screenshot` with `tab_id`, then use `act` coordinate clicks or scrolling. MCP returns an image; REST returns base64 PNG. Observe again when the layout changes. Use existing `drag_slider` after explicitly selecting the desired tab for dragging.
- Reuse a `request_id` only for transport retries of the exact same request. Results are retained for the last 64 IDs in a live session, not across backend restarts. A replay contains the original observation, which may now be stale. `outcome_unknown` requires inspecting the page before deciding what to do next.
- Use `cancel_action` to interrupt a pending operation, then inspect the page; cancellation does not undo actions already taken. `close_session` also interrupts pending work. Legacy `wait_for.timeout` is in seconds; `act.timeout_ms` is in milliseconds.
- For specialized operations, query the tool catalogue; retain selectors and `evaluate_js` as fallbacks. Avoid reading entire page HTML when a scoped observation or screenshot answers the question.

## Quick example — browse a page in 4 curl calls

```bash
# 1. Create a browser session
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":false}}' | jq -r .session_id)
echo "Session: $SID"

# 2. Navigate to a page
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\"}"

# 3. Read the page content
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\"}"

# 4. Close the session
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\"}"
```

Run each curl command using the Bash tool. Parse the JSON response with jq.

## When to use this skill

- User asks you to open, visit, or check a website
- User needs a form filled out, a button clicked, or content read from a web page
- User wants to take a screenshot of a web page
- User needs to log into a site and keep the session for later
- User asks you to scrape, monitor, or automate a website
- User needs to solve a task that requires a real browser (not just HTTP requests)

## How to call the API

All browser tools are called through a single REST endpoint using curl in Bash:

```bash
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": "TOOL_NAME",
    "arguments": { ... },
    "session_id": "SESSION_ID"
  }'
```

- `tool_name`: the tool to call (see list below)
- `arguments`: tool-specific parameters
- `session_id`: required for all tools except `create_session`, `list_sessions`, `list_contexts`

The response is always JSON with `success`, `result`, `session_id`, and `error` fields.

## Core Workflow

Every interaction follows this pattern:

### 1. Create a session

```bash
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":false,"persist":true}}'
```

Returns `session_id` — save this and pass it to all subsequent calls.
Use `persist: true` to auto-save cookies on close. Use `persist: false` for throwaway tasks.

### 2. Navigate

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

### 3. Understand the page

Use `observe` to get interactive elements (buttons, links, inputs) with their CSS selectors:

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

Or use `take_screenshot` for a visual PNG (base64-encoded):

```bash
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":"take_screenshot","arguments":{},"session_id":"SESSION_ID"}'
```

### 4. Interact

```bash
# Click an element
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":"click_element","arguments":{"selector":"button.submit","by":"css"},"session_id":"SESSION_ID"}'

# Type into an input
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":"type_text","arguments":{"selector":"input[name=email]","text":"user@example.com"},"session_id":"SESSION_ID"}'

# Scroll down
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":"scroll","arguments":{"direction":"down","amount":500},"session_id":"SESSION_ID"}'

# Press a key
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":"press_key","arguments":{"key":"Enter"},"session_id":"SESSION_ID"}'

# Run JavaScript
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":"evaluate_js","arguments":{"expression":"document.title"},"session_id":"SESSION_ID"}'
```

### 5. Close

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

If `persist=true` was set, cookies and localStorage are saved automatically.

## All Available Tools

### Session Management
- `create_session` — args: `headless` (deprecated compatibility flag; tabs always run headed), `persist` (bool), `context_id` (string, optional to restore saved login)
- `close_session` — no args (just session_id)
- `list_sessions` — no args, no session_id needed
- `get_session_info` — no args

### Navigation
- `navigate` — args: `url` (string)
- `go_back` — no args
- `go_forward` — no args

### Page Interaction
- `click_element` — args: `selector` (string), `by` (string, default "css", also "xpath", "id", "name")
- `type_text` — args: `selector` (string), `text` (string), `by` (string)
- `scroll` — args: `direction` ("up"/"down"/"left"/"right"), `amount` (int, pixels)
- `press_key` — args: `key` (string: "Enter", "Tab", "Escape", "ArrowDown", etc.)
- `select_option` — args: `selector` (string), `value` (string)
- `hover` — args: `selector` (string)

### Page Inspection
- `observe` — no args. Returns interactive elements with selectors. **Use this before clicking.**
- `take_screenshot` — args: `full_page` (bool). Returns base64 PNG.
- `get_page_info` — no args. Returns URL, title, source length.
- `page_summary` — no args. Returns element counts, text preview.
- `snapshot` — no args. Returns full accessibility tree.
- `find_elements` — args: `selector` (string), `by` (string)
- `evaluate_js` — args: `expression` (string). Run JavaScript and return result.
- `wait_for` — args: `selector` (string), `state` ("visible"/"hidden"), `timeout` (int ms)

### Persistent Contexts (Login Persistence)
- `save_context` — args: `context_name` (string), optional `ttl_hours` (int)
- `list_contexts` — no args, no session_id needed
- `delete_context` — args: `context_id` (string), no session_id needed

## Important Rules

1. **Always pass `session_id`** to every tool after `create_session`.
2. **Ground actions in page state.** Prefer `observe_page` refs and `act`. For legacy selector tools, inspect `observe` first rather than guessing selectors.
3. **Use `persist=true`** when the user might want to resume the session later.
4. **Idle tabs sleep after 15 minutes.** A `persist=true` tab keeps its login state and wakes automatically on your next call with the same `session_id` (expect a few seconds); a `persist=false` tab is closed. Your plan caps how many tabs can be awake at once (free: 5); sleeping tabs don't count and are unlimited.
5. **Screenshots are base64 PNG.** Decode and display when relevant.
6. **For human handoff** (CAPTCHA, 2FA), share the `share_url` from the `create_session` response. It looks like `https://www.browserfabric.com/live/{share_token}` — this URL does NOT expose the API key. The human opens it, sees the live browser, and can click/type to help.

## Common Patterns

### Browse and read a page
```bash
# Create session
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":false}}' | jq -r .session_id)

# Navigate
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\"}"

# Read the page
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\"}"

# Close
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\"}"
```

### Login once, reuse forever
```bash
# Create persistent session
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":false,"persist":true}}' | jq -r .session_id)

# Navigate to login, fill credentials, submit
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://app.example.com/login\"},\"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\":\"type_text\",\"arguments\":{\"selector\":\"input[name=email]\",\"text\":\"user@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\":\"click_element\",\"arguments\":{\"selector\":\"button[type=submit]\"},\"session_id\":\"$SID\"}"

# Save login — returns context_id for future use
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\":\"save_context\",\"arguments\":{\"context_name\":\"my-app-login\"},\"session_id\":\"$SID\"}"

# Close
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\"}"

# Days later — resume already logged in:
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":false,"persist":true,"context_id":"CONTEXT_ID"}}' | jq -r .session_id)
# No login needed — cookies were restored
```

## Reference

Full tool documentation: https://www.browserfabric.com/llms-full.txt
API docs: https://www.browserfabric.com/docs
Dashboard: https://www.browserfabric.com/dashboard