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.

• - Environment Variable: INLINECODE0
• Default Value: INLINECODE1
• How to get the URL: Read from environment variable $BROWSERWING_EXECUTOR_URL, if not set, use default INLINECODE3

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: INLINECODE8

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.

CODEBLOCK0

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

Query specific command:
CODEBLOCK1

2. Get Accessibility Snapshot

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

CODEBLOCK2

Response Example:
CODEBLOCK3

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 LLMs
• RefIDs are stable references that work reliably across page changes

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

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"}'

• - RefID (Recommended): @e1, @e2 (from snapshot)
• CSS Selector: #button-id, INLINECODE14
• XPath: INLINECODE15
• Text: Login (text content)

Type Text

Extract Data

Wait for Element

Batch Operations

Instructions

Step-by-step workflow:

1. 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: INLINECODE19

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

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

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

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

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

1. 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. 1. Navigate to search page:

1. 2. Get page structure to find search input:

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

1. 3. Type search query:

1. 4. Press Enter to submit:

1. 5. Wait for results to load:

1. 6. Extract search results:

1. 7. Present the extracted data:

Key Commands Reference

Navigation

• - POST /navigate - Navigate to URL
• INLINECODE32 - Go back in history
• INLINECODE33 - Go forward in history
• INLINECODE34 - Reload current page

Element Interaction

• - POST /click - Click element (supports: RefID @e1, CSS selector, XPath, text content)
• INLINECODE37 - Type text into input (supports: RefID @e3, CSS selector, XPath)
• INLINECODE39 - Select dropdown option
• INLINECODE40 - Hover over element
• INLINECODE41 - Wait for element state (visible, hidden, enabled)
• INLINECODE42 - Press keyboard key (Enter, Tab, Ctrl+S, etc.)

Data Extraction

• - POST /extract - Extract data from elements (supports multiple elements, custom fields)
• INLINECODE44 - Get element text content
• INLINECODE45 - Get input element value
• INLINECODE46 - Get page URL and title
• INLINECODE47 - Get all page text
• INLINECODE48 - Get full HTML

Page Analysis

• - GET /snapshot - Get accessibility snapshot (⭐ ALWAYS call after navigation)
• INLINECODE50 - Get all clickable elements
• INLINECODE51 - Get all input elements

Advanced

• - POST /screenshot - Take page screenshot (base64 encoded)
• INLINECODE53 - Execute JavaScript code
• INLINECODE54 - Execute multiple operations in sequence
• INLINECODE55 - Scroll to page bottom
• INLINECODE56 - Resize browser window
• INLINECODE57 - Manage browser tabs (list, new, switch, close)
• INLINECODE58 - Intelligently fill multiple form fields at once

Debug & Monitoring

• - GET /console-messages - Get browser console messages (logs, warnings, errors)
• INLINECODE60 - Get network requests made by the page
• INLINECODE61 - Configure JavaScript dialog (alert, confirm, prompt) handling
• INLINECODE62 - Upload files to input elements
• INLINECODE63 - Drag and drop elements
• INLINECODE64 - Close the current page/tab

Element Identification

You can identify elements using:

1. 1. RefID (Recommended): @e1, @e2, INLINECODE67

1. 2. CSS Selector: #id, .class, INLINECODE72

1. 3. XPath: //button[@id='login'], INLINECODE75

1. 4. Text Content: Login, Sign Up, INLINECODE79

1. 5. ARIA Label: Elements with aria-label attribute

Guidelines

Before starting:

• - Get API URL first: Read from $BROWSERWING_EXECUTOR_URL environment variable, or use http://127.0.0.1:8080 as default
• Call GET /help if you're unsure about available commands or their parameters
• Ensure browser is started (if not, it will auto-start on first operation)

During automation:

• - Always call /snapshot after navigation to get page structure and RefIDs
• Prefer RefIDs (like @e1) over CSS selectors for reliability and stability
• Re-snapshot after page changes to get updated RefIDs
• Use /wait for dynamic content that loads asynchronously
• Check element states before interaction (visible, enabled)
• Use /batch for multiple sequential operations to improve efficiency

Error handling:

• - If operation fails, check element identifier and try different format
• For timeout errors, increase timeout value
• If element not found, call /snapshot again to refresh page structure
• Explain errors clearly to user with suggested solutions

Data extraction:

• - Use fields parameter to specify what to extract: INLINECODE91
• Set multiple: true to extract from multiple elements
• Format extracted data in a readable way for user

Complete Workflow Example

Scenario: User wants to login to a website

CODEBLOCK17

Your Actions:

Step 1: Navigate to login page
CODEBLOCK18

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"

Step 3: Enter username
CODEBLOCK21

Step 4: Enter password
CODEBLOCK22

Step 5: Click login button
CODEBLOCK23

Step 6: Wait for login success (optional)
CODEBLOCK24

Step 7: Inform user
CODEBLOCK25

Batch Operation Example

Scenario: Fill out a form with multiple fields

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

CODEBLOCK26

Best Practices

1. 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. 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. 1. Navigate to target page
2. Wait for content to load with INLINECODE102
3. Use /extract with CSS selector and INLINECODE104
4. Specify fields to extract: INLINECODE105

Search Operations

1. 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. 1. Navigate to login page
2. Get accessibility snapshot to find RefIDs
3. Type username: INLINECODE106
4. Type password: INLINECODE107
5. Click login button: INLINECODE108
6. Wait for success indicator

Important Notes

• - Browser must be running (it will auto-start on first operation if needed)
• Operations are executed on the currently active browser tab
• Accessibility snapshot updates after each navigation and click operation
• All timeouts are in seconds
• Use wait_visible: true (default) for reliable element interaction
• API address: Always read from $BROWSERWING_EXECUTOR_URL environment variable, fallback to http://127.0.0.1:8080 if not set
• Authentication required: use X-BrowserWing-Key header or JWT token if configured

Troubleshooting

Element not found:

• - Call /snapshot to see available elements
• Try different identifier format (accessibility index, CSS selector, text)
• Check if page has finished loading

Timeout errors:

• - Increase timeout value in request
• Check if element actually appears on page
• Use /wait with appropriate state before interaction

Extraction returns empty:

• - Verify CSS selector matches target elements
• Check if content has loaded (use /wait first)
• Try different extraction fields or type

Quick Reference

CODEBLOCK27

Response Format

All operations return:
CODEBLOCK28

Error response:
CODEBLOCK29