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.

API Base URL: http://localhost:8080/api/v1/executor, host=localhost:8080

Core Capabilities

• Page Navigation: Navigate to URLs, go back/forward, reload
• Element Interaction: Click, type, select, hover on page elements
• Data Extraction: Extract text, attributes, values from elements
• Accessibility Analysis: Get accessibility snapshot to understand page structure
• Advanced Operations: Screenshot, JavaScript execution, keyboard input
• Batch Processing: Execute multiple operations in sequence

API Endpoints

1. Discover Available Commands

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

curl -X GET 'http://{host}/api/v1/executor/help'

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

Query specific command:

curl -X GET 'http://{host}/api/v1/executor/help?command=extract'

2. Get Accessibility Snapshot

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

curl -X GET 'http://{host}/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:

• Understand what interactive elements are on the page
• Get element RefIDs (@e1, @e2, etc.) for precise identification
• See element labels, roles, and attributes
• The accessibility tree is cleaner than raw DOM and better for understanding page structure
• RefIDs are stable references that work reliably across page changes

3. Common Operations

Navigate to URL

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

Click Element

curl -X POST 'http://{host}/api/v1/executor/click' \
  -H 'Content-Type: application/json' \
  -d '{"identifier": "@e1"}'

Identifier formats:

• RefID (Recommended): @e1, @e2 (from snapshot)
• CSS Selector: #button-id, .class-name
• XPath: //button[@type='submit']
• Text: Login (text content)

Type Text

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

Extract Data

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

Wait for Element

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

Batch Operations

curl -X POST 'http://{host}/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}
    ]
  }'

4. Tab Management (NEW)

List all tabs:

curl -X POST 'http://{host}/api/v1/mcp/message' \
  -H 'Content-Type: application/json' \
  -d '{
    "method": "tools/call",
    "params": {
      "name": "browser_tabs",
      "arguments": {"action": "list"}
    }
  }'

Create new tab:

curl -X POST 'http://{host}/api/v1/mcp/message' \
  -H 'Content-Type: application/json' \
  -d '{
    "method": "tools/call",
    "params": {
      "name": "browser_tabs",
      "arguments": {
        "action": "new",
        "url": "https://example.com"
      }
    }
  }'

Switch to tab (by index):

curl -X POST 'http://{host}/api/v1/mcp/message' \
  -H 'Content-Type: application/json' \
  -d '{
    "method": "tools/call",
    "params": {
      "name": "browser_tabs",
      "arguments": {
        "action": "switch",
        "index": 1
      }
    }
  }'

Close tab (by index):

curl -X POST 'http://{host}/api/v1/mcp/message' \
  -H 'Content-Type: application/json' \
  -d '{
    "method": "tools/call",
    "params": {
      "name": "browser_tabs",
      "arguments": {
        "action": "close",
        "index": 2
      }
    }
  }'

Note: Tab indices are 0-based (first tab is 0, second tab is 1, etc.)

Alternative: Direct HTTP API (without MCP):

# List tabs
curl -X POST 'http://{host}/api/v1/executor/tabs' \
  -H 'Content-T