BrowserWing Executor API

---

name: browserwing

homepage: https://github.com/browserwing/browserwing

description: Control browser automation through HTTP API. Supports page navigation, element interaction (click, type, select), data extraction, accessibility snapshot analysis, screenshot, JavaScript execution, and batch operations.

metadata: {"moltbot":{"emoji":"🌐","requires":{"bins":"env":["BROWSERWING_EXECUTOR_URL"]},"primaryEnv":"BROWSERWING_EXECUTOR_URL"}}

---

# BrowserWing Executor API

Overview

BrowserWing Executor provides comprehensive browser automation capabilities through HTTP APIs. You can control browser navigation, interact with page elements, extract data, and analyze page structure.

Configuration

**API Base URL:** The BrowserWing Executor API address is configurable via environment variable.

**Base URL Format:** `${BROWSERWING_EXECUTOR_URL}/api/v1/executor` or `http://127.0.0.1:8080/api/v1/executor` (if env var not set)

**Authentication:** Use `X-BrowserWing-Key: <api-key>` header or `Authorization: Bearer <token>` if required.

**Important:** Always construct the API URL by reading the environment variable first. In shell commands, use: `${BROWSERWING_EXECUTOR_URL:-http://127.0.0.1:8080}`

Core Capabilities

API Endpoints

1. Discover Available Commands

**IMPORTANT:** Always call this endpoint first to see all available commands and their parameters.

EXECUTOR_URL="${BROWSERWING_EXECUTOR_URL:-http://127.0.0.1:8080}"
curl -X GET "${EXECUTOR_URL}/api/v1/executor/help"

**Response:** Returns complete list of all commands with parameters, examples, and usage guidelines.

**Query specific command:**

EXECUTOR_URL="${BROWSERWING_EXECUTOR_URL:-http://127.0.0.1:8080}"
curl -X GET "${EXECUTOR_URL}/api/v1/executor/help?command=extract"

2. Get Accessibility Snapshot

**CRITICAL:** Always call this after navigation to understand page structure and get element RefIDs.

EXECUTOR_URL="${BROWSERWING_EXECUTOR_URL:-http://127.0.0.1:8080}"
curl -X GET "${EXECUTOR_URL}/api/v1/executor/snapshot"

**Response Example:**

{
  "success": true,
  "snapshot_text": "Clickable Elements:\n  @e1 Login (role: button)\n  @e2 Sign Up (role: link)\n\nInput Elements:\n  @e3 Email (role: textbox) [placeholder: your@email.com]\n  @e4 Password (role: textbox)"
}

**Use Cases:**

3. Common Operations

**Note:** All examples below use `EXECUTOR_URL="${BROWSERWING_EXECUTOR_URL:-http://127.0.0.1:8080}"` to read the API address from environment variable, with `http://127.0.0.1:8080` as fallback default.

#### Navigate to URL

EXECUTOR_URL="${BROWSERWING_EXECUTOR_URL:-http://127.0.0.1:8080}"
curl -X POST "${EXECUTOR_URL}/api/v1/executor/navigate" \
  -H 'Content-Type: application/json' \
  -d '{"url": "https://example.com"}'

#### Click Element

EXECUTOR_URL="${BROWSERWING_EXECUTOR_URL:-http://127.0.0.1:8080}"
curl -X POST "${EXECUTOR_URL}/api/v1/executor/click" \
  -H 'Content-Type: application/json' \
  -d '{"identifier": "@e1"}'

**Identifier formats:**

#### Type Text

EXECUTOR_URL="${BROWSERWING_EXECUTOR_URL:-http://127.0.0.1:8080}"
curl -X POST "${EXECUTOR_URL}/api/v1/executor/type" \
  -H 'Content-Type: application/json' \
  -d '{"identifier": "@e3", "text": "user@example.com"}'

#### Extract Data

EXECUTOR_URL="${BROWSERWING_EXECUTOR_URL:-http://127.0.0.1:8080}"
curl -X POST "${EXECUTOR_URL}/api/v1/executor/extract" \
  -H 'Content-Type: application/json' \
  -d '{
    "selector": ".product-item",
    "fields": ["text", "href"],
    "multiple": true
  }'

#### Wait for Element

EXECUTOR_URL="${BROWSERWING_EXECUTOR_URL:-http://127.0.0.1:8080}"
curl -X POST "${EXECUTOR_URL}/api/v1/executor/wait" \
  -H 'Content-Type: application/json' \
  -d '{"identifier": ".loading", "state": "hidden", "timeout": 10}'

#### Batch Operations

EXECUTOR_URL="${BROWSERWING_EXECUTOR_URL:-http://127.0.0.1:8080}"
curl -X POST "${EXECUTOR_URL}/api/v1/executor/batch" \
  -H 'Content-Type: application/json' \
  -d '{
    "operations": [
      {"type": "navigate", "params": {"url": "https://example.com"}, "stop_on_error": true},
      {"type": "click", "params": {"identifier": "@e1"}, "stop_on_error": true},
      {"type": "type", "params": {"identifier": "@e3", "text": "query"}, "stop_on_error": true}
    ]
  }'

Instructions

**Step-by-step workflow:**

0. **Get API URL:** First, read the API base URL from environment variable `$BROWSERWING_EXECUTOR_URL`. If not set, use default `http://127.0.0.1:8080`. In shell commands, use: `EXECUTOR_URL="${BROWSERWING_EXECUTOR_URL:-http://127.0.0.1:8080}"`

1. **Discover commands:** Call `GET /help` to see all available operations and their parameters (do this first if unsure).

2. **Navigate:** Use `POST /navigate` to open the target webpage.

3. **Analyze page:** Call `GET /snapshot` to understand page structure and get element RefIDs.

4. **Interact:** Use element RefIDs (like `@e1`, `@e2`) or CSS selectors to:

- Click elements: `POST /click`

- Input text: `POST /type`

- Select options: `POST /select`

- Wait for elements: `POST /wait`

5. **Extract data:** Use `POST /extract` to get information from the page.

6. **Present results:** Format and show extracted data to the user.

Complete Example

**User Request:** "Search for 'laptop' on example.com and get the first 5 results"

**Your Actions:**

1. Navigate to search page:

curl -X POST 'http://127.0.0.1:18085/api/v1/executor/navigate' \
  -H 'Content-Type: application/json' \
  -d '{"url": "https://example.com/search"}'

2. Get page structure to find search input:

curl -X GET 'http://127.0.0.1:18085/api/v1/executor/snapshot'

Response shows: `@e3 Search (role: textbox) [placeholder: Search...]`

3. Type search query:

curl -X POST 'http://127.0.0.1:18085/api/v1/executor/type' \
  -H 'Content-Type: application/json' \
  -d '{"identifier": "@e3", "text": "laptop"}'

4. Press Enter to submit:

curl -X POST 'http://127.0.0.1:18085/api/v1/executor/press-key' \
  -H 'Content-Type: application/json' \
  -d '{"key": "Enter"}'

5. Wait for results to load:

curl -X POST 'http://127.0.0.1:18085/api/v1/executor/wait' \
  -H 'Content-Type: application/json' \
  -d '{"identifier": ".search-results", "state": "visible", "timeout": 10}'

6. Extract search results:

curl -X POST 'http://127.0.0.1:18085/api/v1/executor/extract' \
  -H 'Content-Type: application/json' \
  -d '{
    "selector": ".result-item",
    "fields": ["text", "href"],
    "multiple": true
  }'

7. Present the extracted data:

Found 15 results for 'laptop':
1. Gaming Laptop - $1299 (https://...)
2. Business Laptop - $899 (https://...)
...

Key Commands Reference

Navigation

Element Interaction

Data Extraction

Page Analysis

Advanced

Debug & Monitoring

Element Identification

You can identify elements using:

1. **RefID (Recommended):** `@e1`, `@e2`, `@e3`

- Most reliable method - stable across page changes

- Get RefIDs from `/snapshot` endpoint

- Valid for 5 minutes after snapshot

- Example: `"identifier": "@e1"`

- Works with multi-strategy fallback for robustness

2. **CSS Selector:** `#id`, `.class`, `button[type="submit"]`

- Standard CSS selectors

- Example: `"identifier": "#login-button"`

3. **XPath:** `//button[@id='login']`, `//a[contains(text(), 'Submit')]`

- XPath expressions for complex queries

- Example: `"identifier": "//button[@id='login']"`

4. **Text Content:** `Login`, `Sign Up`, `Submit`

- Searches buttons and links with matching text

- Example: `"identifier": "Login"`

5. **ARIA Label:** Elements with `aria-label` attribute

- Automatically searched

Guidelines

**Before starting:**

**During automation:**

**Error handling:**

**Data extraction:**

Complete Workflow Example

**Scenario:** User wants to login to a website

User: "Please log in to example.com with username 'john' and password 'secret123'"

**Your Actions:**

**Step 1:** Navigate to login page

EXECUTOR_URL="${BROWSERWING_EXECUTOR_URL:-http://127.0.0.1:8080}"
curl -X POST "${EXECUTOR_URL}/api/v1/executor/navigate" \
  -H 'Content-Type: application/json' \
  -d '{"url": "https://example.com/login"}'

**Step 2:** Get page structure

EXECUTOR_URL="${BROWSERWING_EXECUTOR_URL:-http://127.0.0.1:8080}"
curl -X GET "${EXECUTOR_URL}/api/v1/executor/snapshot"

Response:

Clickable Elements:
  @e1 Login (role: button)

Input Elements:
  @e2 Username (role: textbox)
  @e3 Password (role: textbox)

**Step 3:** Enter username

POST http://127.0.0.1:18085/api/v1/executor/type
{"identifier": "@e2", "text": "john"}

**Step 4:** Enter password

POST http://127.0.0.1:18085/api/v1/executor/type
{"identifier": "@e3", "text": "secret123"}

**Step 5:** Click login button

POST http://127.0.0.1:18085/api/v1/executor/click
{"identifier": "@e1"}

**Step 6:** Wait for login success (optional)

POST http://127.0.0.1:18085/api/v1/executor/wait
{"identifier": ".welcome-message", "state": "visible", "timeout": 10}

**Step 7:** Inform user

"Successfully logged in to example.com!"

Batch Operation Example

**Scenario:** Fill out a form with multiple fields

Instead of making 5 separate API calls, use one batch operation:

EXECUTOR_URL="${BROWSERWING_EXECUTOR_URL:-http://127.0.0.1:8080}"
curl -X POST "${EXECUTOR_URL}/api/v1/executor/batch" \
  -H 'Content-Type: application/json' \
  -d '{
    "operations": [
      {
        "type": "navigate",
        "params": {"url": "https://example.com/form"},
        "stop_on_error": true
      },
      {
        "type": "type",
        "params": {"identifier": "#name", "text": "John Doe"},
        "stop_on_error": true
      },
      {
        "type": "type",
        "params": {"identifier": "#email", "text": "john@example.com"},
        "stop_on_error": true
      },
      {
        "type": "select",
        "params": {"identifier": "#country", "value": "United States"},
        "stop_on_error": true
      },
      {
        "type": "click",
        "params": {"identifier": "#submit"},
        "stop_on_error": true
      }
    ]
  }'

Best Practices

1. **Discovery first:** If unsure, call `/help` or `/help?command=<name>` to learn about commands

2. **Structure first:** Always call `/snapshot` after navigation to understand the page

3. **Use accessibility indices:** They're more reliable than CSS selectors (elements might have dynamic classes)

4. **Wait for dynamic content:** Use `/wait` before interacting with elements that load asynchronously

5. **Batch when possible:** Use `/batch` for multiple sequential operations

6. **Handle errors gracefully:** Provide clear explanations and suggestions when operations fail

7. **Verify results:** After operations, check if desired outcome was achieved

Common Scenarios

Form Filling

1. Navigate to form page

2. Get accessibility snapshot to find input elements and their RefIDs

3. Use `/type` for each field: `@e1`, `@e2`, etc.

4. Use `/select` for dropdowns

5. Click submit button using its RefID

Data Scraping

1. Navigate to target page

2. Wait for content to load with `/wait`

3. Use `/extract` with CSS selector and `multiple: true`

4. Specify fields to extract: `["text", "href", "src"]`

Search Operations

1. Navigate to search page

2. Get accessibility snapshot to locate search input

3. Type search query into input

4. Press Enter or click search button

5. Wait for results

6. Extract results data

Login Automation

1. Navigate to login page

2. Get accessibility snapshot to find RefIDs

3. Type username: `@e2`

4. Type password: `@e3`

5. Click login button: `@e1`

6. Wait for success indicator

Important Notes

Troubleshooting

**Element not found:**

**Timeout errors:**

**Extraction returns empty:**

Quick Reference

EXECUTOR_URL="${BROWSERWING_EXECUTOR_URL:-http://127.0.0.1:8080}"

# Discover commands
curl -X GET "${EXECUTOR_URL}/api/v1/executor/help"

# Navigate
curl -X POST "${EXECUTOR_URL}/api/v1/executor/navigate" \
  -H 'Content-Type: application/json' \
  -d '{"url": "..."}'

# Get page structure
curl -X GET "${EXECUTOR_URL}/api/v1/executor/snapshot"

# Click element
curl -X POST "${EXECUTOR_URL}/api/v1/executor/click" \
  -H 'Content-Type: application/json' \
  -d '{"identifier": "@e1"}'

# Type text
curl -X POST "${EXECUTOR_URL}/api/v1/executor/type" \
  -H 'Content-Type: application/json' \
  -d '{"identifier": "@e3", "text": "..."}'

# Extract data
curl -X POST "${EXECUTOR_URL}/api/v1/executor/extract" \
  -H 'Content-Type: application/json' \
  -d '{"selector": "...", "fields": [...], "multiple": true}'

Response Format

All operations return:

{
  "success": true,
  "message": "Operation description",
  "timestamp": "2026-01-15T10:30:00Z",
  "data": {
    // Operation-specific data
  }
}

**Error response:**

{
  "error": "error.operationFailed",
  "detail": "Detailed error message"
}