Browser Action

Endpoint

Authentication

All requests to the BBRE API require authentication via an API key. You must include your API key in the HTTP headers of every request. The API accepts the key through either the x-api-key header or the apikey header. Both header names are supported and functionally identical. If no API key is provided, the API returns a 401 error with the API_KEY_REQUIRED error code. If the provided key is invalid or belongs to a suspended or inactive account, the API returns a 403 error with the appropriate error code (INVALID_API_KEY, ACCOUNT_SUSPENDED, or ACCOUNT_INACTIVE).

Request Body Parameters

The request body must be a JSON object containing the session identifier, the action to execute, and optionally an object of action-specific parameters. The sessionId identifies which adaptive session the action should run in, the action string specifies which browser action to perform, and the params object provides the inputs that the action needs. Different actions accept different parameters, which are documented in detail in the action-specific sections below. If you omit the params field, it defaults to an empty object {}, which is valid for actions that do not require any parameters like back, forward, getTitle, getUrl, and html.

Available Actions Overview

The BBRE browser engine supports a comprehensive set of actions organized into functional categories. The following table provides a quick reference of every available action, its category, and a brief description. Detailed documentation for each action including parameters, defaults, and examples is provided in the category-specific sections that follow.

Navigation Actions

Navigation actions control where the browser goes. These actions let you load new pages, reload the current page, and move through the browser history. Navigation is typically the first action you perform after creating an adaptive session, since the browser starts with a blank page and needs to be directed to your target URL before you can interact with any page elements.

navigate / goto

Navigates the browser to the specified URL and waits for the page to load. The goto action is an alias for navigate and behaves identically. The waitUntil parameter controls when the navigation is considered complete. The default value "load" waits for the full page load event, which includes all resources like images, stylesheets, and scripts. The timeout parameter sets the maximum time in seconds to wait for the page to load before the action fails.

reload

Reloads the current page. This is equivalent to pressing F5 or clicking the refresh button in a browser. The reload action accepts the same waitUntil and timeout parameters as the navigate action to control when the reload is considered complete.

back

Navigates back in the browser history, equivalent to clicking the browser's back button. This action does not accept any parameters. If there is no previous page in the history, the action completes without error but the browser stays on the current page.

forward

Navigates forward in the browser history, equivalent to clicking the browser's forward button. This action does not accept any parameters. If there is no forward page in the history, the action completes without error but the browser stays on the current page.

Interaction Actions

Interaction actions let you interact with page elements the same way a human user would. You can click buttons and links, fill input fields, type text with realistic keystroke timing, select options from dropdowns, check checkboxes, fill entire forms at once, and clear input fields. These actions are the building blocks for automating any web workflow that involves user input.

click

Clicks an element identified by a CSS selector. The BBRE engine locates the element on the page, scrolls it into view if necessary, and performs a mouse click on it. The optional delay parameter adds a pause before the click, which can help with websites that detect instantaneous clicks as bot behavior.

fill

Fills an input field with the specified text, replacing any existing content in the field. This action first clears the field and then sets the value directly. It is faster than type because it does not simulate individual keystrokes. Use fill when speed is more important than realism, and use type when you need to simulate realistic typing behavior for bot detection evasion.

type

Types text into an input field character by character with a configurable delay between keystrokes. Unlike fill, which sets the value instantly, type simulates realistic keyboard input by dispatching individual key events for each character. This is important for websites that monitor typing patterns, validate input on each keystroke, or use JavaScript event listeners on keydown/keyup events. The delay parameter controls the time between each keystroke in seconds.

select / selectDropdown

Selects an option from a <select> dropdown element by its value attribute. The selectDropdown action is an alias for select and behaves identically. The selector parameter identifies the dropdown element, and the value parameter specifies which option to select.

clickCheckboxByText

Clicks a checkbox identified by its associated label text. This is useful when checkboxes do not have predictable IDs or CSS selectors, but their labels contain identifiable text. The exact parameter controls whether the text match must be exact or can be a partial match.

fillForm

Fills multiple form fields at once using a key-value mapping of CSS selectors to values. This is a convenience action that eliminates the need to send separate fill actions for each field. The optional submit parameter automatically submits the form after all fields are filled, which saves an additional click action on the submit button.

clear

Clears the content of an input field identified by a CSS selector. This removes all text from the field, leaving it empty. Use this before fill or type if you need to ensure the field is empty before entering new content.

Query Actions

Query actions let you extract information from the current page without modifying it. You can retrieve the full page HTML, get the text content of specific elements, read the page title and URL, and find elements by CSS selector or text content. These actions are essential for verifying that your navigation and interaction actions produced the expected results, and for extracting data from pages after you have navigated to them.

html

Returns the full HTML content of the current page. This action does not accept any parameters. The returned HTML includes the complete DOM as rendered by the browser, including any content generated by JavaScript. This is useful for parsing page content, extracting data, or debugging what the browser is currently displaying.

getText

Returns the text content of an element identified by a CSS selector. This extracts only the visible text, stripping all HTML tags. Use this to read the content of specific page elements like headings, paragraphs, table cells, or status messages.

getTitle

Returns the title of the current page as defined by the <title> tag. This action does not accept any parameters. The page title is useful for verifying that navigation landed on the expected page.

getUrl

Returns the current URL of the browser. This action does not accept any parameters. The URL reflects the actual location of the browser after all navigations and redirects. Use this to verify that the browser is on the expected page, especially after form submissions or login attempts that may redirect to different URLs.

find

Finds an element by CSS selector and returns information about it. This is useful for checking whether an element exists on the page before attempting to interact with it.

findByText

Finds an element by its text content. This searches the page for elements containing the specified text and returns information about the first match. This is particularly useful when elements do not have predictable CSS selectors but contain identifiable text.

Wait Actions

Wait actions pause execution until a condition is met or a specified time has elapsed. These are critical for handling dynamic web pages where content loads asynchronously after the initial page load. Without proper waiting, your subsequent actions might fail because the target elements have not appeared yet. The BBRE engine provides both simple time-based waiting and intelligent element-based waiting with configurable polling intervals.

wait

Pauses execution for a specified number of seconds. This is a simple time-based wait that is useful when you know approximately how long to wait for a page transition, animation, or asynchronous operation to complete. For more precise waiting, use waitForElement instead, which waits for a specific condition rather than a fixed time.

waitForElement

Waits for an element to appear on the page. You can identify the target element by text content, CSS selector, or both. The engine polls the page at regular intervals checking for the element's presence. This is the recommended way to handle dynamic content because it waits only as long as necessary rather than using a fixed delay. The throwOnTimeout parameter controls whether the action fails or succeeds silently when the element does not appear within the timeout period.

Scroll Actions

Scroll actions control the scroll position of the page. Scrolling is important for interacting with elements that are not currently visible in the viewport, triggering lazy-loaded content, and simulating realistic user behavior. Many websites load additional content as the user scrolls down (infinite scroll), and some anti-bot systems track scroll behavior as a signal of human interaction. The BBRE engine provides both directional scrolling with configurable pixel amounts and absolute scrolling to the top or bottom of the page.

scroll

Performs a custom scroll operation with the specified options. This is the most flexible scroll action, allowing you to control the exact scroll behavior through the options parameter.

scrollDown

Scrolls the page down by a specified number of pixels. This is the most commonly used scroll action for loading lazy content and bringing lower page elements into view.

scrollUp

Scrolls the page up by a specified number of pixels. Use this to return to previously viewed content or to bring upper page elements back into view.

scrollToTop

Scrolls to the very top of the page. This action does not accept any parameters. It is equivalent to pressing the Home key in a browser.

scrollToBottom

Scrolls to the very bottom of the page. This action does not accept any parameters. It is useful for triggering lazy-loaded content at the bottom of the page or for reaching footer elements.

Cookie Actions

Cookie actions let you read, set, and delete cookies in the browser context. Cookies are automatically managed by the session, meaning cookies set by websites during navigation persist across all actions within the session. However, there are scenarios where you need to manually manage cookies: pre-setting authentication cookies to skip login flows, reading cookies to extract session tokens or CSRF tokens, or clearing cookies to reset the browser state within a session.

getCookies

Returns all cookies from the current browser context. This action does not accept any parameters. The result includes every cookie stored in the browser, including cookies set by the website during navigation and any cookies you have set manually using setCookie. Each cookie object includes properties like name, value, domain, path, expires, httpOnly, and secure.

setCookie

Sets a cookie in the browser context. You must provide at least the cookie name and value. Additional options like domain, path, expires, httpOnly, and secure can be specified to control the cookie's scope and behavior.

deleteCookies

Deletes all cookies from the browser context. This action does not accept any parameters. After calling this action, the browser has no cookies, which effectively resets the authentication state. Use this when you need to start fresh within the same session without creating a new one.

JavaScript Execution

JavaScript execution actions let you run arbitrary JavaScript code in the context of the current page. This is the most powerful and flexible action type because it gives you direct access to the page's DOM, JavaScript variables, and browser APIs. You can use it to extract complex data structures, modify page behavior, trigger custom events, interact with JavaScript frameworks, or perform any operation that is possible through the browser's developer console. The evaluate action is an alias for execute and behaves identically.

execute / evaluate

Executes JavaScript code in the page context and returns the result. The script is wrapped and executed within the page, meaning it has access to the page's document, window, and all JavaScript variables and functions defined by the page. The return value of your script is serialized and included in the action result. If your script throws an error, the action fails with the error message.

Screenshot

The screenshot action captures a visual snapshot of the current page and returns it as base64-encoded image data. Screenshots are invaluable for debugging automation workflows, verifying that the browser is displaying the expected content, monitoring visual changes on pages, and creating visual records of completed workflows. The screenshot captures the full visible viewport as rendered by the browser, including all CSS styling, images, and dynamically generated content.

screenshot

Batch Actions

The batch action lets you execute multiple browser actions in sequence within a single API call. Instead of making separate HTTP requests for each action, you can bundle them into one batch request. This reduces network overhead and latency, especially when you need to perform a series of related actions like navigating to a page, filling a form, and clicking submit. Each action in the batch is executed in order, and the results of all actions are returned together. The optional stopOnError parameter controls whether the batch stops at the first failure or continues executing remaining actions.

batch

Response Format

The browser action endpoint returns a JSON response indicating whether the action was executed successfully. On success, the response includes the action-specific result and optionally a browser profile object. On failure, the response includes an error code and a descriptive message. The response structure varies slightly depending on whether the action succeeded, failed with a partial result, or failed completely.

Success Response (200)

A successful browser action returns the following structure. The result field contains the output of the action, which varies by action type. For example, a getTitle action returns the page title string, a screenshot action returns base64 image data, and a navigate action returns navigation status information. The profile field contains the browser profile data if the BBRE engine generated or updated a profile during the action.

{
  "success": true,
  "service": "MyDisct Solver BBRE",
  "result": {
    "title": "Example Domain"
  },
  "profile": {
    "userAgent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36",
    "platform": "Win32",
    "language": "en-US",
    "timezone": "America/New_York"
  }
}

Failure Response with Partial Result (200)

When the BBRE engine reports a failure but includes a partial result object, the API returns a 200 status code with "success": false. This can happen when an action partially completes before encountering an error. The partial result may contain useful information about what happened before the failure.

{
  "success": false,
  "result": {
    "error": "Element not found: #nonexistent-button"
  },
  "profile": {
    "userAgent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36",
    "platform": "Win32"
  }
}

Error Response Examples

400 - Session ID Required

{
  "success": false,
  "service": "MyDisct Solver BBRE",
  "error": {
    "code": "SESSION_ID_REQUIRED",
    "message": "Session ID is required."
  }
}

400 - Action Required

{
  "success": false,
  "service": "MyDisct Solver BBRE",
  "error": {
    "code": "INVALID_REQUEST",
    "message": "Browser action is required."
  }
}

404 - Session Not Found

{
  "success": false,
  "service": "MyDisct Solver BBRE",
  "error": {
    "code": "SESSION_NOT_FOUND",
    "message": "Session not found."
  }
}

500 - Browser Action Failed

{
  "success": false,
  "service": "MyDisct Solver BBRE",
  "error": {
    "code": "BROWSER_ACTION_FAILED",
    "message": "Browser action failed."
  }
}

Request Examples

The following examples demonstrate how to execute browser actions using the BBRE API in different programming languages. All examples show complete, working code that you can copy and run directly. Remember to replace YOUR_API_KEY with your actual BBRE API key and YOUR_SESSION_ID with a valid adaptive mode session ID.

Navigate to a URL

The most fundamental browser action. This navigates the browser to a specified URL and waits for the page to fully load. You should always start your browser automation workflow by navigating to the target page.

const axios = require("axios");

const API_BASE = "https://bbre-solver-api.mydisct.com";
const API_KEY = "YOUR_API_KEY";
const SESSION_ID = "YOUR_SESSION_ID";

async function navigateToPage() {
  const response = await axios.post(
    API_BASE + "/browser/action",
    {
      sessionId: SESSION_ID,
      action: "navigate",
      params: {
        url: "https://example.com/login",
        waitUntil: "load",
        timeout: 30
      }
    },
    {
      headers: {
        "Content-Type": "application/json",
        "x-api-key": API_KEY
      }
    }
  );

  console.log("Success:", response.data.success);
  console.log("Result:", response.data.result);
  return response.data;
}

navigateToPage();

import requests

API_BASE = "https://bbre-solver-api.mydisct.com"
API_KEY = "YOUR_API_KEY"
SESSION_ID = "YOUR_SESSION_ID"

headers = {
    "Content-Type": "application/json",
    "x-api-key": API_KEY
}

response = requests.post(
    API_BASE + "/browser/action",
    headers=headers,
    json={
        "sessionId": SESSION_ID,
        "action": "navigate",
        "params": {
            "url": "https://example.com/login",
            "waitUntil": "load",
            "timeout": 30
        }
    }
)

data = response.json()
print("Success:", data["success"])
print("Result:", data["result"])

curl -X POST https://bbre-solver-api.mydisct.com/browser/action \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{
    "sessionId": "YOUR_SESSION_ID",
    "action": "navigate",
    "params": {
      "url": "https://example.com/login",
      "waitUntil": "load",
      "timeout": 30
    }
  }'

Fill a Form and Click Submit

This example demonstrates filling input fields and clicking a submit button. This is one of the most common browser automation patterns, used for login forms, search forms, registration forms, and any other form-based interaction.

const axios = require("axios");

const API_BASE = "https://bbre-solver-api.mydisct.com";
const API_KEY = "YOUR_API_KEY";
const SESSION_ID = "YOUR_SESSION_ID";
const authHeaders = {
  "Content-Type": "application/json",
  "x-api-key": API_KEY
};

async function fillAndSubmitForm() {
  await axios.post(
    API_BASE + "/browser/action",
    {
      sessionId: SESSION_ID,
      action: "fill",
      params: { selector: "#username", text: "myuser" }
    },
    { headers: authHeaders }
  );

  await axios.post(
    API_BASE + "/browser/action",
    {
      sessionId: SESSION_ID,
      action: "fill",
      params: { selector: "#password", text: "mypassword" }
    },
    { headers: authHeaders }
  );

  const clickResponse = await axios.post(
    API_BASE + "/browser/action",
    {
      sessionId: SESSION_ID,
      action: "click",
      params: { selector: "#login-button" }
    },
    { headers: authHeaders }
  );

  console.log("Click result:", clickResponse.data.result);
  return clickResponse.data;
}

fillAndSubmitForm();

import requests

API_BASE = "https://bbre-solver-api.mydisct.com"
API_KEY = "YOUR_API_KEY"
SESSION_ID = "YOUR_SESSION_ID"

headers = {
    "Content-Type": "application/json",
    "x-api-key": API_KEY
}

requests.post(
    API_BASE + "/browser/action",
    headers=headers,
    json={
        "sessionId": SESSION_ID,
        "action": "fill",
        "params": {"selector": "#username", "text": "myuser"}
    }
)

requests.post(
    API_BASE + "/browser/action",
    headers=headers,
    json={
        "sessionId": SESSION_ID,
        "action": "fill",
        "params": {"selector": "#password", "text": "mypassword"}
    }
)

click_response = requests.post(
    API_BASE + "/browser/action",
    headers=headers,
    json={
        "sessionId": SESSION_ID,
        "action": "click",
        "params": {"selector": "#login-button"}
    }
)

data = click_response.json()
print("Click result:", data["result"])

curl -X POST https://bbre-solver-api.mydisct.com/browser/action \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{
    "sessionId": "YOUR_SESSION_ID",
    "action": "fill",
    "params": {"selector": "#username", "text": "myuser"}
  }'

curl -X POST https://bbre-solver-api.mydisct.com/browser/action \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{
    "sessionId": "YOUR_SESSION_ID",
    "action": "fill",
    "params": {"selector": "#password", "text": "mypassword"}
  }'

curl -X POST https://bbre-solver-api.mydisct.com/browser/action \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{
    "sessionId": "YOUR_SESSION_ID",
    "action": "click",
    "params": {"selector": "#login-button"}
  }'

Take a Screenshot

This example captures a screenshot of the current page. The screenshot is returned as base64-encoded image data that you can decode and save to a file. Screenshots are useful for debugging, visual verification, and creating records of automation results.

const axios = require("axios");
const fs = require("fs");

const API_BASE = "https://bbre-solver-api.mydisct.com";
const API_KEY = "YOUR_API_KEY";
const SESSION_ID = "YOUR_SESSION_ID";

async function takeScreenshot() {
  const response = await axios.post(
    API_BASE + "/browser/action",
    {
      sessionId: SESSION_ID,
      action: "screenshot",
      params: {}
    },
    {
      headers: {
        "Content-Type": "application/json",
        "x-api-key": API_KEY
      }
    }
  );

  const base64Data = response.data.result.screenshot;
  const buffer = Buffer.from(base64Data, "base64");
  fs.writeFileSync("screenshot.png", buffer);
  console.log("Screenshot saved to screenshot.png");

  return response.data;
}

takeScreenshot();

import requests
import base64

API_BASE = "https://bbre-solver-api.mydisct.com"
API_KEY = "YOUR_API_KEY"
SESSION_ID = "YOUR_SESSION_ID"

headers = {
    "Content-Type": "application/json",
    "x-api-key": API_KEY
}

response = requests.post(
    API_BASE + "/browser/action",
    headers=headers,
    json={
        "sessionId": SESSION_ID,
        "action": "screenshot",
        "params": {}
    }
)

data = response.json()
base64_data = data["result"]["screenshot"]
image_bytes = base64.b64decode(base64_data)

with open("screenshot.png", "wb") as f:
    f.write(image_bytes)

print("Screenshot saved to screenshot.png")

Execute JavaScript

This example executes JavaScript in the page context to extract data that is not easily accessible through other actions. JavaScript execution gives you full access to the page DOM and any JavaScript variables or functions defined by the page.

const axios = require("axios");

const API_BASE = "https://bbre-solver-api.mydisct.com";
const API_KEY = "YOUR_API_KEY";
const SESSION_ID = "YOUR_SESSION_ID";

async function executeJavaScript() {
  const response = await axios.post(
    API_BASE + "/browser/action",
    {
      sessionId: SESSION_ID,
      action: "execute",
      params: {
        script: "return document.querySelectorAll('.product-card').length"
      }
    },
    {
      headers: {
        "Content-Type": "application/json",
        "x-api-key": API_KEY
      }
    }
  );

  console.log("Product count:", response.data.result);
  return response.data;
}

executeJavaScript();

import requests

API_BASE = "https://bbre-solver-api.mydisct.com"
API_KEY = "YOUR_API_KEY"
SESSION_ID = "YOUR_SESSION_ID"

headers = {
    "Content-Type": "application/json",
    "x-api-key": API_KEY
}

response = requests.post(
    API_BASE + "/browser/action",
    headers=headers,
    json={
        "sessionId": SESSION_ID,
        "action": "execute",
        "params": {
            "script": "return document.querySelectorAll('.product-card').length"
        }
    }
)

data = response.json()
print("Product count:", data["result"])

Wait for Element and Extract Text

This example waits for a specific element to appear on the page and then extracts its text content. This pattern is essential for handling dynamic pages where content loads asynchronously after the initial page load.

const axios = require("axios");

const API_BASE = "https://bbre-solver-api.mydisct.com";
const API_KEY = "YOUR_API_KEY";
const SESSION_ID = "YOUR_SESSION_ID";
const authHeaders = {
  "Content-Type": "application/json",
  "x-api-key": API_KEY
};

async function waitAndExtract() {
  await axios.post(
    API_BASE + "/browser/action",
    {
      sessionId: SESSION_ID,
      action: "waitForElement",
      params: {
        selector: ".dashboard-welcome",
        timeout: 15,
        visible: true
      }
    },
    { headers: authHeaders }
  );

  const textResponse = await axios.post(
    API_BASE + "/browser/action",
    {
      sessionId: SESSION_ID,
      action: "getText",
      params: { selector: ".dashboard-welcome" }
    },
    { headers: authHeaders }
  );

  console.log("Welcome message:", textResponse.data.result);
  return textResponse.data;
}

waitAndExtract();

import requests

API_BASE = "https://bbre-solver-api.mydisct.com"
API_KEY = "YOUR_API_KEY"
SESSION_ID = "YOUR_SESSION_ID"

headers = {
    "Content-Type": "application/json",
    "x-api-key": API_KEY
}

requests.post(
    API_BASE + "/browser/action",
    headers=headers,
    json={
        "sessionId": SESSION_ID,
        "action": "waitForElement",
        "params": {
            "selector": ".dashboard-welcome",
            "timeout": 15,
            "visible": True
        }
    }
)

text_response = requests.post(
    API_BASE + "/browser/action",
    headers=headers,
    json={
        "sessionId": SESSION_ID,
        "action": "getText",
        "params": {"selector": ".dashboard-welcome"}
    }
)

data = text_response.json()
print("Welcome message:", data["result"])

Batch Action Example

This example uses the batch action to execute multiple actions in a single API call. The batch navigates to a page, fills a search field, and clicks the search button, all in one request. This reduces the number of HTTP round trips from three to one.

const axios = require("axios");

const API_BASE = "https://bbre-solver-api.mydisct.com";
const API_KEY = "YOUR_API_KEY";
const SESSION_ID = "YOUR_SESSION_ID";

async function executeBatch() {
  const response = await axios.post(
    API_BASE + "/browser/action",
    {
      sessionId: SESSION_ID,
      action: "batch",
      params: {
        actions: [
          {
            action: "navigate",
            params: { url: "https://example.com/search" }
          },
          {
            action: "fill",
            params: { selector: "#search-input", text: "BBRE automation" }
          },
          {
            action: "click",
            params: { selector: "#search-button" }
          },
          {
            action: "waitForElement",
            params: { selector: ".search-results", timeout: 10 }
          }
        ],
        stopOnError: true
      }
    },
    {
      headers: {
        "Content-Type": "application/json",
        "x-api-key": API_KEY
      }
    }
  );

  console.log("Batch result:", response.data.result);
  return response.data;
}

executeBatch();

import requests

API_BASE = "https://bbre-solver-api.mydisct.com"
API_KEY = "YOUR_API_KEY"
SESSION_ID = "YOUR_SESSION_ID"

headers = {
    "Content-Type": "application/json",
    "x-api-key": API_KEY
}

response = requests.post(
    API_BASE + "/browser/action",
    headers=headers,
    json={
        "sessionId": SESSION_ID,
        "action": "batch",
        "params": {
            "actions": [
                {
                    "action": "navigate",
                    "params": {"url": "https://example.com/search"}
                },
                {
                    "action": "fill",
                    "params": {"selector": "#search-input", "text": "BBRE automation"}
                },
                {
                    "action": "click",
                    "params": {"selector": "#search-button"}
                },
                {
                    "action": "waitForElement",
                    "params": {"selector": ".search-results", "timeout": 10}
                }
            ],
            "stopOnError": True
        }
    }
)

data = response.json()
print("Batch result:", data["result"])

curl -X POST https://bbre-solver-api.mydisct.com/browser/action \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{
    "sessionId": "YOUR_SESSION_ID",
    "action": "batch",
    "params": {
      "actions": [
        {"action": "navigate", "params": {"url": "https://example.com/search"}},
        {"action": "fill", "params": {"selector": "#search-input", "text": "BBRE automation"}},
        {"action": "click", "params": {"selector": "#search-button"}},
        {"action": "waitForElement", "params": {"selector": ".search-results", "timeout": 10}}
      ],
      "stopOnError": true
    }
  }'

Node.js SDK Usage

The mydisctsolver-bbre Node.js SDK provides the BrowserAPI class that wraps the POST /browser/action endpoint with convenient methods for each browser action. When you create a BBRESession instance in adaptive mode, the session.browser property gives you access to the BrowserAPI instance. Each method on the BrowserAPI class corresponds to a browser action and handles the session ID, request formatting, and response parsing automatically. This makes browser automation code significantly cleaner and more readable compared to making raw API calls.

Basic SDK Browser Automation

const { BBRESession } = require("mydisctsolver-bbre");

const session = new BBRESession({
  apiKey: "YOUR_API_KEY",
  mode: "adaptive",
  sensibility: "medium"
});

async function basicBrowserAutomation() {
  await session.start();

  await session.browser.navigate("https://example.com");
  const title = await session.browser.getTitle();
  console.log("Page title:", title);

  const url = await session.browser.getUrl();
  console.log("Current URL:", url);

  const html = await session.browser.html();
  console.log("Page HTML length:", html.length);

  await session.close();
}

basicBrowserAutomation();

SDK Form Filling and Submission

const { BBRESession } = require("mydisctsolver-bbre");

const session = new BBRESession({
  apiKey: "YOUR_API_KEY",
  mode: "adaptive",
  sensibility: "high"
});

async function loginWithSDK() {
  await session.start();

  await session.browser.navigate("https://example.com/login");
  await session.browser.fill("#username", "myuser");
  await session.browser.fill("#password", "mypassword");
  await session.browser.click("#login-button");

  await session.browser.waitForElement({ text: "Dashboard", timeout: 10 });
  const title = await session.browser.getTitle();
  console.log("After login:", title);

  await session.close();
}

loginWithSDK();

SDK Scrolling and Data Extraction

const { BBRESession } = require("mydisctsolver-bbre");

const session = new BBRESession({
  apiKey: "YOUR_API_KEY",
  mode: "adaptive"
});

async function scrollAndExtract() {
  await session.start();

  await session.browser.navigate("https://example.com/products");

  await session.browser.scrollDown(1000);
  await session.browser.wait(2);

  await session.browser.scrollDown(1000);
  await session.browser.wait(2);

  const productCount = await session.browser.execute(
    "return document.querySelectorAll('.product-item').length"
  );
  console.log("Total products loaded:", productCount);

  await session.browser.scrollToTop();

  await session.close();
}

scrollAndExtract();

SDK Cookie Management

const { BBRESession } = require("mydisctsolver-bbre");

const session = new BBRESession({
  apiKey: "YOUR_API_KEY",
  mode: "adaptive"
});

async function manageCookies() {
  await session.start();

  await session.browser.navigate("https://example.com");

  await session.browser.setCookie({
    name: "session_token",
    value: "abc123def456",
    domain: "example.com",
    path: "/",
    secure: true
  });

  const cookies = await session.browser.getCookies();
  console.log("All cookies:", cookies);

  await session.browser.deleteCookies();
  console.log("All cookies cleared");

  await session.close();
}

manageCookies();

SDK Screenshot and Debugging

const { BBRESession } = require("mydisctsolver-bbre");
const fs = require("fs");

const session = new BBRESession({
  apiKey: "YOUR_API_KEY",
  mode: "adaptive"
});

async function screenshotWorkflow() {
  await session.start();

  await session.browser.navigate("https://example.com/dashboard");
  await session.browser.waitForElement({ selector: ".dashboard-content", timeout: 15 });

  const screenshotData = await session.browser.screenshot();
  const buffer = Buffer.from(screenshotData, "base64");
  fs.writeFileSync("dashboard.png", buffer);
  console.log("Dashboard screenshot saved");

  await session.close();
}

screenshotWorkflow();

Real-World Workflow Example

The following example demonstrates a complete real-world browser automation workflow that combines session creation, navigation, form interaction, waiting, data extraction, and session cleanup. This pattern represents a typical use case: navigating to a website, logging in, navigating to a data page, extracting information, and closing the session. The example includes proper error handling with a try/finally block to ensure the session is always closed.

const axios = require("axios");

const API_BASE = "https://bbre-solver-api.mydisct.com";
const API_KEY = "YOUR_API_KEY";
const authHeaders = {
  "Content-Type": "application/json",
  "x-api-key": API_KEY
};

async function browserAction(sessionId, action, params) {
  const response = await axios.post(
    API_BASE + "/browser/action",
    { sessionId, action, params },
    { headers: authHeaders }
  );
  return response.data;
}

async function completeWorkflow() {
  const createResponse = await axios.post(
    API_BASE + "/session/create",
    {
      mode: "adaptive",
      sensibility: "high",
      timeout: 300
    },
    { headers: authHeaders }
  );

  const sessionId = createResponse.data.session.id;
  console.log("Session created:", sessionId);

  try {
    await browserAction(sessionId, "navigate", {
      url: "https://example.com/login",
      timeout: 30
    });
    console.log("Navigated to login page");

    await browserAction(sessionId, "waitForElement", {
      selector: "#login-form",
      timeout: 10
    });

    await browserAction(sessionId, "fill", {
      selector: "#email",
      text: "[email protected]"
    });

    await browserAction(sessionId, "fill", {
      selector: "#password",
      text: "securepassword"
    });

    await browserAction(sessionId, "click", {
      selector: "button[type='submit']"
    });
    console.log("Login form submitted");

    await browserAction(sessionId, "waitForElement", {
      text: "Welcome back",
      timeout: 15
    });
    console.log("Login successful");

    await browserAction(sessionId, "navigate", {
      url: "https://example.com/account/orders"
    });

    await browserAction(sessionId, "waitForElement", {
      selector: ".order-list",
      timeout: 10
    });

    const result = await browserAction(sessionId, "execute", {
      script: "return Array.from(document.querySelectorAll('.order-row')).map(row => ({id: row.querySelector('.order-id').textContent, total: row.querySelector('.order-total').textContent, status: row.querySelector('.order-status').textContent}))"
    });

    console.log("Orders extracted:", result.result);

    const titleResult = await browserAction(sessionId, "getTitle", {});
    console.log("Page title:", titleResult.result);

  } finally {
    await axios.post(
      API_BASE + "/session/close",
      { sessionId },
      { headers: authHeaders }
    );
    console.log("Session closed");
  }
}

completeWorkflow();

import requests

API_BASE = "https://bbre-solver-api.mydisct.com"
API_KEY = "YOUR_API_KEY"

headers = {
    "Content-Type": "application/json",
    "x-api-key": API_KEY
}

def browser_action(session_id, action, params=None):
    response = requests.post(
        API_BASE + "/browser/action",
        headers=headers,
        json={
            "sessionId": session_id,
            "action": action,
            "params": params or {}
        }
    )
    return response.json()

create_response = requests.post(
    API_BASE + "/session/create",
    headers=headers,
    json={
        "mode": "adaptive",
        "sensibility": "high",
        "timeout": 300
    }
)

session_id = create_response.json()["session"]["id"]
print("Session created:", session_id)

try:
    browser_action(session_id, "navigate", {
        "url": "https://example.com/login",
        "timeout": 30
    })
    print("Navigated to login page")

    browser_action(session_id, "waitForElement", {
        "selector": "#login-form",
        "timeout": 10
    })

    browser_action(session_id, "fill", {
        "selector": "#email",
        "text": "[email protected]"
    })

    browser_action(session_id, "fill", {
        "selector": "#password",
        "text": "securepassword"
    })

    browser_action(session_id, "click", {
        "selector": "button[type='submit']"
    })
    print("Login form submitted")

    browser_action(session_id, "waitForElement", {
        "text": "Welcome back",
        "timeout": 15
    })
    print("Login successful")

    browser_action(session_id, "navigate", {
        "url": "https://example.com/account/orders"
    })

    browser_action(session_id, "waitForElement", {
        "selector": ".order-list",
        "timeout": 10
    })

    result = browser_action(session_id, "execute", {
        "script": "return Array.from(document.querySelectorAll('.order-row')).map(row => ({id: row.querySelector('.order-id').textContent, total: row.querySelector('.order-total').textContent}))"
    })
    print("Orders:", result["result"])

finally:
    requests.post(
        API_BASE + "/session/close",
        headers=headers,
        json={"sessionId": session_id}
    )
    print("Session closed")

Complete SDK Workflow

The following example shows the same real-world workflow using the Node.js SDK. Notice how much cleaner the code is compared to the raw API version. The SDK handles session management, request formatting, and response parsing, letting you focus on the automation logic itself.

const { BBRESession } = require("mydisctsolver-bbre");

const session = new BBRESession({
  apiKey: "YOUR_API_KEY",
  mode: "adaptive",
  sensibility: "high"
});

async function completeSDKWorkflow() {
  await session.start();

  try {
    await session.browser.navigate("https://example.com/login");

    await session.browser.waitForElement({ selector: "#login-form", timeout: 10 });

    await session.browser.fill("#email", "[email protected]");
    await session.browser.fill("#password", "securepassword");
    await session.browser.click("button[type='submit']");

    await session.browser.waitForElement({ text: "Welcome back", timeout: 15 });
    console.log("Login successful");

    await session.browser.navigate("https://example.com/account/orders");
    await session.browser.waitForElement({ selector: ".order-list", timeout: 10 });

    const orders = await session.browser.execute(
      "return Array.from(document.querySelectorAll('.order-row')).map(row => ({id: row.querySelector('.order-id').textContent, total: row.querySelector('.order-total').textContent, status: row.querySelector('.order-status').textContent}))"
    );
    console.log("Orders:", orders);

    const title = await session.browser.getTitle();
    console.log("Page:", title);

  } finally {
    await session.close();
    console.log("Session closed");
  }
}

completeSDKWorkflow();

Error Codes

The following table lists all error codes that can be returned by the browser action endpoint, along with their HTTP status codes, descriptions, and recommended solutions. Implementing proper error handling for each of these codes ensures your automation workflows can recover gracefully from any failure scenario.

Using fillForm for Multi-Field Forms

The fillForm action is a powerful convenience method that fills multiple form fields in a single action call. Instead of sending separate fill actions for each field, you provide a formData object that maps CSS selectors to values. This is particularly useful for registration forms, checkout forms, and any form with many fields. When combined with the submit: true option, the form is automatically submitted after all fields are filled, eliminating the need for a separate click action on the submit button.

const axios = require("axios");

const API_BASE = "https://bbre-solver-api.mydisct.com";
const API_KEY = "YOUR_API_KEY";
const SESSION_ID = "YOUR_SESSION_ID";

async function fillRegistrationForm() {
  const response = await axios.post(
    API_BASE + "/browser/action",
    {
      sessionId: SESSION_ID,
      action: "fillForm",
      params: {
        formData: {
          "#first-name": "John",
          "#last-name": "Doe",
          "#email": "[email protected]",
          "#phone": "+1-555-0123",
          "#address": "123 Main Street",
          "#city": "New York",
          "#zip": "10001"
        },
        submit: true
      }
    },
    {
      headers: {
        "Content-Type": "application/json",
        "x-api-key": API_KEY
      }
    }
  );

  console.log("Form submitted:", response.data.success);
  return response.data;
}

fillRegistrationForm();

import requests

API_BASE = "https://bbre-solver-api.mydisct.com"
API_KEY = "YOUR_API_KEY"
SESSION_ID = "YOUR_SESSION_ID"

headers = {
    "Content-Type": "application/json",
    "x-api-key": API_KEY
}

response = requests.post(
    API_BASE + "/browser/action",
    headers=headers,
    json={
        "sessionId": SESSION_ID,
        "action": "fillForm",
        "params": {
            "formData": {
                "#first-name": "John",
                "#last-name": "Doe",
                "#email": "[email protected]",
                "#phone": "+1-555-0123",
                "#address": "123 Main Street",
                "#city": "New York",
                "#zip": "10001"
            },
            "submit": True
        }
    }
)

data = response.json()
print("Form submitted:", data["success"])

Choosing Between type and fill

The fill and type actions both put text into input fields, but they work differently and are suited for different scenarios. Understanding when to use each one is important for building reliable automation workflows.

fill sets the input value directly and instantly. It clears the existing content and replaces it with the new text in a single operation. This is fast and reliable for most forms. Use fill when speed matters and the target website does not monitor individual keystrokes.

type simulates typing by dispatching individual key events (keydown, keypress, keyup) for each character with a configurable delay between them. This is slower but more realistic. Use type when the target website has JavaScript event listeners that respond to individual keystrokes (like autocomplete suggestions, real-time validation, or search-as-you-type features), or when the website monitors typing patterns as part of its bot detection system.

As a general rule, start with fill for all fields. If you encounter issues where the website does not recognize the input or triggers bot detection, switch to type for those specific fields. For websites with aggressive bot detection, using type with a delay of 0.03 to 0.08 seconds per character produces realistic typing patterns that are difficult to distinguish from human input.

Best Practices

Common Issues

Issue 1: BROWSER_ACTION_FAILED When Clicking Elements

Solution: This typically happens because the element has not loaded yet when the click action is executed. Web pages load content asynchronously, and the element may appear after the initial page load event. Add a waitForElement action before the click to ensure the element is present and visible. If the element is inside an iframe, it may not be directly accessible through CSS selectors on the main page. Also verify that your CSS selector is correct by testing it in the browser developer console using document.querySelector("your-selector"). If the element is dynamically generated with random class names (common in React and Angular applications), use a more stable selector like a data attribute or the element's text content with findByText.

Issue 2: Browser Actions Fail on Passive Mode Sessions

Solution: Browser actions are exclusively available in adaptive mode sessions. Passive mode sessions do not maintain a browser instance and therefore cannot execute browser actions. You must create a new session with "mode": "adaptive" to use the POST /browser/action endpoint. If you initially created a passive session because you did not anticipate needing browser actions, close the passive session and create a new adaptive one. The session mode cannot be changed after creation.

Issue 3: Navigation Timeout on Heavy Pages

Solution: Increase the timeout parameter in the navigate action params. For heavy pages, set the timeout to 60 seconds or more. If the page has many non-essential resources that slow down the load event, you can also try changing the waitUntil parameter to wait for a different load state. Additionally, some pages never fully "load" because they continuously fetch data or have long-running scripts. In these cases, use a shorter navigation timeout and then use waitForElement to wait for the specific content you need rather than waiting for the entire page to finish loading.

Issue 4: JavaScript Execution Returns Unexpected Results

Solution: Make sure your script includes a return statement to return the value you want. Without an explicit return, the result is undefined. Also ensure that the page has fully loaded and the JavaScript variables or DOM elements your script references actually exist at the time of execution. Use waitForElement before executing JavaScript that depends on specific DOM elements. If your script references page-specific JavaScript variables or functions, verify they exist by first executing a simple check like return typeof variableName !== 'undefined'. Complex objects like DOM nodes cannot be serialized directly; extract the specific properties you need instead of returning entire DOM elements.

Related Documentation

• Create Session - Create an adaptive mode session that is required for browser actions. Learn about session configuration including mode, sensibility, fingerprint, proxy, and timeout settings
• Close Session - Close your adaptive session when your browser automation workflow is complete to free up active session slots
• Session Status - Check the current status, request count, and expiration time of your adaptive session during long workflows
• Session Request - Send HTTP requests within the same session to combine browser actions with traditional HTTP interactions
• BBRE Engine Overview - Understand the BBRE architecture, the difference between passive and adaptive modes, and how browser actions fit into the overall system
• Fingerprint and Profile Guide - Learn about browser fingerprint customization and how profiles are generated and maintained across browser actions within a session
• Hybrid Workflow Guide - Combine passive mode HTTP requests with adaptive mode browser actions for efficient multi-stage automation workflows
• Quick Start Guide - Get started with the BBRE API including your first session creation and browser action