BBRE Engine Overview

What is BBRE?

BBRE stands for Browser-Backed Request Engine. It is a distributed system that accepts HTTP request instructions from your application and executes them inside real browser instances. Unlike conventional request libraries that construct raw HTTP packets, BBRE leverages actual Chromium rendering engines to generate requests. This means every outgoing request carries authentic browser signatures including valid TLS/JA3 fingerprints, proper header ordering, real cookie handling, and genuine JavaScript execution capabilities.

The engine was designed from the ground up to handle the increasing sophistication of bot detection systems. Modern websites deploy multiple layers of protection including TLS fingerprinting, HTTP/2 header analysis, JavaScript challenges, and behavioral analysis. BBRE addresses all of these by operating at the browser level rather than the network level.

At its core, BBRE provides two distinct operation modes. Passive mode handles simple HTTP requests where you just need a response body, headers, or status code. Adaptive mode provides full browser automation where you can navigate pages, click buttons, fill forms, take screenshots, and execute arbitrary JavaScript. Both modes benefit from the same browser-backed infrastructure, ensuring your requests always appear legitimate.

How It Works

When you send a request to the BBRE API, the following sequence occurs:

1. Your application sends a request to the BBRE Public API on port 3010 with your API key
2. The Public API validates your credentials, checks your balance, and creates a task
3. The task is routed to the Internal API which communicates with the Python-based processor
4. The processor launches a real Chromium browser instance with a unique fingerprint profile
5. Your request is executed inside the browser environment with all anti-detection measures active
6. The response (or browser state) is captured and returned to your application

This architecture ensures that even the most aggressive bot detection systems cannot distinguish BBRE traffic from genuine human browsing. The processor generates unique browser fingerprints for each session, including realistic user agents, screen resolutions, timezone settings, WebGL parameters, and canvas fingerprints.

Architecture Overview

The BBRE system consists of four main components that work together to deliver browser-backed requests. Understanding this architecture helps you make better decisions about which mode to use, how to structure your workflows, and how to troubleshoot issues when they arise.

Public API (Port 3010)

The Public API is your entry point to the BBRE system. It is a Node.js/Express server that handles authentication, request validation, balance checking, and task management. Every request you make goes through this layer first. The Public API supports two authentication methods: the x-api-key header and the apikey query parameter. It exposes endpoints for creating requests, managing sessions, executing browser actions, and querying account information.

Internal API

The Internal API acts as a bridge between the Public API and the processor. It handles task routing, queue management, and result caching. When the Public API creates a task, the Internal API ensures it reaches the appropriate processor instance. This layer also handles retry logic and failover scenarios, making the system resilient to temporary processor unavailability.

Python Processor

The processor is the heart of BBRE. Written in Python, it manages real Chromium browser instances using Playwright. When a task arrives, the processor selects or creates a browser context with the appropriate fingerprint profile, executes the requested operation (whether a simple HTTP fetch or a complex browser automation sequence), and returns the result. The processor handles fingerprint generation, proxy routing, cookie management, and all browser-level operations.

Node.js SDK

The mydisctsolver-bbre npm package provides a high-level interface to the BBRE API. It includes three main classes: BBREClient for direct API interactions, BBRESession for session-based workflows, and BrowserAPI for browser automation commands. The SDK handles authentication, polling, error handling, and session management automatically, letting you focus on your application logic.

npm install mydisctsolver-bbre

Request Modes

BBRE operates in two distinct modes, each optimized for different use cases. Choosing the right mode is one of the most important decisions you will make when integrating BBRE, as it directly affects performance, cost, and capability.

Passive Mode

Passive mode is designed for straightforward HTTP requests where you need a response but do not require browser interaction. When you send a request in passive mode, BBRE uses a real browser environment to make the HTTP call, but it does not render the page or execute client-side JavaScript. This makes passive mode significantly faster and more cost-effective than adaptive mode.

Use passive mode when you need to:

• Fetch API responses from endpoints that check TLS fingerprints
• Download page content from sites with basic bot protection
• Make authenticated requests that require browser-like headers
• Perform high-volume data collection where speed matters
• Access REST APIs that reject requests from standard HTTP libraries

const response = await fetch("https://bbre-solver-api.mydisct.com/request/execute", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "x-api-key": "YOUR_API_KEY"
  },
  body: JSON.stringify({
    url: "https://example.com/api/data",
    method: "GET",
    mode: "passive",
    sensibility: "medium"
  })
});

const data = await response.json();
console.log(data.result.status);
console.log(data.result.body);

Adaptive Mode

Adaptive mode provides full browser automation capabilities. When you create a session in adaptive mode, BBRE launches a complete Chromium browser instance that you can control through the API. You can navigate to pages, wait for elements to load, click buttons, fill out forms, take screenshots, and execute arbitrary JavaScript. The browser maintains state across multiple actions, including cookies, local storage, and session data.

Use adaptive mode when you need to:

• Interact with JavaScript-heavy single-page applications
• Fill out and submit multi-step forms
• Handle sites that require JavaScript execution to render content
• Perform click-through workflows that span multiple pages
• Take screenshots of rendered pages for verification or monitoring
• Execute custom JavaScript in the page context

const BBREClient = require("mydisctsolver-bbre");

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

const session = await client.createSession();
await session.start();

const browser = session.browser();
await browser.navigate("https://example.com/login");
await browser.fill("#email", "[email protected]");
await browser.fill("#password", "securePassword123");
await browser.click("#login-button");
await browser.waitForSelector(".dashboard");

const pageTitle = await browser.getTitle();
console.log("Logged in, page title:", pageTitle);

await session.close();

Mode Comparison

Sensibility Levels

Sensibility controls how aggressively BBRE applies anti-detection measures to your requests. Higher sensibility means more stealth but slower execution. The sensibility level affects timing patterns, header randomization, fingerprint complexity, and behavioral simulation. Choosing the right level is a balance between speed and the likelihood of being detected.

Low Sensibility

Low sensibility provides the fastest execution with minimal anti-detection overhead. The processor sends requests with standard browser headers and a basic fingerprint profile but does not add artificial delays or advanced behavioral patterns. This level is appropriate for targets with minimal or no bot detection, internal APIs, development and testing environments, and high-volume tasks where speed is the priority.

const response = await fetch("https://bbre-solver-api.mydisct.com/request/execute", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "x-api-key": "YOUR_API_KEY"
  },
  body: JSON.stringify({
    url: "https://example.com/api/products",
    method: "GET",
    mode: "passive",
    sensibility: "low"
  })
});

const data = await response.json();
console.log(data.result.body);

Medium Sensibility

Medium sensibility is the default setting and provides a good balance between speed and stealth. The processor applies moderate anti-detection measures including randomized timing between actions, realistic header ordering, and a more detailed fingerprint profile. This level works well for most commercial websites, e-commerce platforms, social media sites, and any target with standard bot protection. If you are unsure which level to use, start with medium.

import requests

response = requests.post(
    "https://bbre-solver-api.mydisct.com/request/execute",
    headers={
        "Content-Type": "application/json",
        "x-api-key": "YOUR_API_KEY"
    },
    json={
        "url": "https://example.com/search?q=laptops",
        "method": "GET",
        "mode": "passive",
        "sensibility": "medium"
    }
)

data = response.json()
print(data["result"]["status"])
print(data["result"]["body"])

High Sensibility

High sensibility applies maximum stealth measures at the cost of slower execution. The processor introduces human-like delays between actions, simulates realistic mouse movements and scroll patterns, uses the most detailed fingerprint profiles with WebGL and canvas fingerprint spoofing, and applies advanced timing randomization. Use this level for targets with aggressive bot detection such as major financial institutions, ticketing platforms, and sites using advanced anti-bot solutions like Cloudflare Bot Management, PerimeterX, or DataDome.

Sensibility Comparison

Core Concepts

Before diving into the API endpoints, it is important to understand the fundamental concepts that BBRE is built around. These concepts appear throughout the documentation and understanding them will help you design better integrations.

Tasks

Every request you send to BBRE creates a task. A task represents a single unit of work and is identified by a unique taskId. When you create a task asynchronously using the /request/create endpoint, you receive a taskId immediately and then poll the /request/result endpoint to get the result once processing is complete. Alternatively, you can use the /request/execute endpoint which creates the task and waits for the result in a single synchronous call.

const createResponse = await fetch("https://bbre-solver-api.mydisct.com/request/create", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "x-api-key": "YOUR_API_KEY"
  },
  body: JSON.stringify({
    url: "https://example.com",
    mode: "passive"
  })
});

const { taskId } = await createResponse.json();

let result;
while (true) {
  const resultResponse = await fetch("https://bbre-solver-api.mydisct.com/request/result", {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "x-api-key": "YOUR_API_KEY"
    },
    body: JSON.stringify({ taskId })
  });

  result = await resultResponse.json();
  if (result.status === "completed" || result.status === "failed") break;
  await new Promise(r => setTimeout(r, 2000));
}

console.log(result);

Sessions

A session represents a persistent browser instance that maintains state across multiple requests. When you create a session, BBRE allocates a dedicated browser context with its own cookies, local storage, and fingerprint profile. All requests made within a session share this state, which is essential for workflows that require login persistence, multi-step form submissions, or any scenario where you need to maintain continuity between requests.

Each account can have a maximum of 10 active sessions at any time. Sessions have a configurable timeout and will be automatically closed if they remain inactive beyond the timeout period. You should always close sessions explicitly when you are done with them to free up resources and avoid hitting the session limit.

Fingerprints

A fingerprint is a collection of browser identity attributes that make each browser instance unique and realistic. The BBRE processor generates fingerprints that include:

• userAgent - Browser user agent string matching real browser versions
• platform - Operating system identifier (Windows, macOS, Linux)
• screen - Screen resolution and color depth
• timezone - Geographic timezone setting
• language - Browser language preferences
• webGL - WebGL renderer and vendor information
• canvas - Canvas fingerprint characteristics

You can let BBRE generate fingerprints automatically, or you can provide custom fingerprint parameters to match specific browser profiles. Custom fingerprints are useful when you need to appear as a specific browser type or when you want consistent identity across multiple sessions.

Profiles

A profile is the complete browser identity information generated by the processor for a session. While a fingerprint is the input configuration, a profile is the full output that includes the generated fingerprint values plus additional browser-specific data. You can retrieve a session's profile using the SDK's getProfile() method or the session status endpoint. Profiles are useful for debugging, logging, and verifying that your sessions are using the expected browser identity.

Async vs Sync Execution

BBRE supports two execution patterns for requests:

Asynchronous (Create + Poll): You create a task using /request/create and receive a taskId immediately. You then poll /request/result with that taskId until the task completes. This pattern is ideal for long-running requests, batch processing, and scenarios where you want to fire multiple requests in parallel without blocking.

Synchronous (Execute): You send a request to /request/execute and the API blocks until the result is ready, returning everything in a single response. This pattern is simpler to implement and works well for quick requests where you need the result immediately. Keep in mind that synchronous requests are subject to HTTP timeout limits.

API Endpoints Overview

The BBRE API is organized into four endpoint groups. Each group handles a specific aspect of the system. Below is a complete reference of all available endpoints with their HTTP methods and descriptions.

Request API

The Request API handles creating, executing, and retrieving results for HTTP requests. These are the endpoints you will use most frequently.

Session API

The Session API manages persistent browser sessions. Use sessions when you need to maintain state across multiple requests, such as login workflows or multi-step form submissions.

Browser API

The Browser API provides direct browser automation commands for adaptive mode sessions. These endpoints let you control the browser instance programmatically.

Account API

The Account API provides endpoints for managing your account, checking your balance, and reviewing usage history.

Authentication

All BBRE API requests require authentication using your API key. You can provide your API key in two ways:

Header Authentication (Recommended)

Include your API key in the x-api-key request header. This is the recommended approach as it keeps your key out of URLs and server logs.

curl -X POST https://bbre-solver-api.mydisct.com/request/execute   -H "Content-Type: application/json"   -H "x-api-key: YOUR_API_KEY"   -d '{"url": "https://example.com", "mode": "passive"}'

Alternative Header Name

You can also use the apikey header name instead of x-api-key. Both header names are accepted by the API. Choose whichever fits your existing codebase better.

curl -X POST https://bbre-solver-api.mydisct.com/request/execute   -H "Content-Type: application/json"   -H "apikey: YOUR_API_KEY"   -d '{"url": "https://example.com", "mode": "passive"}'

Quick Example

Here is a complete working example that demonstrates the most common BBRE workflow: making a simple request in passive mode and retrieving the result. This example uses the synchronous execute endpoint for simplicity.

const BBREClient = require("mydisctsolver-bbre");

const client = new BBREClient({
  apiKey: "YOUR_API_KEY"
});

async function fetchPage() {
  const result = await client.get("https://example.com", {
    mode: "passive",
    sensibility: "medium"
  });

  console.log("Status:", result.status);
  console.log("Headers:", result.headers);
  console.log("Body length:", result.body.length);
  return result;
}

fetchPage();

import requests

response = requests.post(
    "https://bbre-solver-api.mydisct.com/request/execute",
    headers={
        "Content-Type": "application/json",
        "x-api-key": "YOUR_API_KEY"
    },
    json={
        "url": "https://example.com",
        "method": "GET",
        "mode": "passive",
        "sensibility": "medium"
    }
)

data = response.json()
print("Status:", data["result"]["status"])
print("Body length:", len(data["result"]["body"]))

curl -X POST https://bbre-solver-api.mydisct.com/request/execute   -H "Content-Type: application/json"   -H "x-api-key: YOUR_API_KEY"   -d '{
    "url": "https://example.com",
    "method": "GET",
    "mode": "passive",
    "sensibility": "medium"
  }'

Best Practices

• Start with passive mode and medium sensibility. This combination works for the majority of websites and provides the best balance between speed and stealth. Only switch to adaptive mode when you need browser automation, and only increase sensibility when you encounter blocks.
• Always close sessions when you are done. Each account is limited to 10 active sessions. Leaving sessions open unnecessarily will prevent you from creating new ones. Use try/finally blocks or equivalent error handling to ensure sessions are closed even when errors occur.
• Use the Node.js SDK for complex workflows. The SDK handles polling, error recovery, session management, and response formatting automatically. Writing raw API calls is fine for simple requests, but the SDK significantly reduces boilerplate for multi-step workflows.
• Set appropriate timeouts. Request timeouts default to 30 seconds for async and 120 seconds for sync. If your target site is slow, increase the timeout rather than retrying immediately. For session timeouts, set them based on how long your workflow actually takes rather than using the maximum value.
• Monitor your balance proactively. Use the /account/balance endpoint or the SDK's getBalance() method to check your balance before starting batch operations. Running out of balance mid-workflow can leave sessions in an inconsistent state.

Common Issues

SESSION_LIMIT_REACHED Error

This error occurs when you try to create a new session but already have 10 active sessions. The solution is to close sessions you no longer need using the /session/close endpoint. If you believe sessions should have expired, check their status first. Sessions that exceed their timeout are automatically marked as expired, but they still count against your limit until they are explicitly closed.

INSUFFICIENT_BALANCE Error

This error means your account balance is too low to cover the cost of the request. Each request and session creation has an associated cost. Check your balance using /account/balance and add funds through the MyDisct Solver dashboard. Note that if a request fails after balance deduction, the amount is automatically refunded to your account.

Browser Actions Failing in Passive Mode

Browser automation commands (navigate, click, fill, type, screenshot, etc.) are only available in adaptive mode. If you try to execute browser actions on a session created with passive mode, you will receive an INVALID_MODE error. Create a new session with mode: "adaptive" to use browser automation features.

Related Documentation

• BBRE Quick Start Guide - Get up and running with your first BBRE request in minutes
• Create Task API - Detailed documentation for the asynchronous request creation endpoint
• Execute Sync API - Detailed documentation for the synchronous request execution endpoint
• Session Create API - Learn how to create and manage persistent browser sessions
• Hybrid Workflow Guide - Combine passive and adaptive modes for advanced use cases
• Fingerprint and Profile Guide - Deep dive into browser fingerprinting and profile management
• Node.js SDK Overview - Get started with the mydisctsolver-bbre npm package