BBRE Quick Start Guide

Step 1: Get Your API Key

Every request to the BBRE API requires authentication via an API key. Your API key is a unique string that identifies your account and authorizes your requests. The key must be included in every API call as an HTTP header.

1. Log in to your MyDisct Solver dashboard at solver.mydisct.com
2. Navigate to the API Keys section in your account settings
3. Click Generate New Key to create a new BBRE API key
4. Copy the generated key and store it securely

The BBRE API accepts your key through the x-api-key HTTP header. You can also use the apikey header name as an alternative. Both are accepted by the API and function identically.

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

Step 2: Install the SDK (Optional)

While you can interact with the BBRE API directly using HTTP requests from any language, the official Node.js SDK simplifies common tasks like polling for results, managing sessions, and handling errors. If you are working in a Node.js environment, installing the SDK is strongly recommended.

npm install mydisctsolver-bbre

After installation, you can import the SDK and create a client instance with your API key. The client handles authentication headers automatically for all subsequent requests.

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

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

For Python and other languages, you will use direct HTTP requests to the BBRE API endpoints. The examples throughout this guide show both the SDK approach and the raw HTTP approach so you can choose whichever fits your stack.

Step 3: Send Your First Request (Synchronous)

The fastest way to get started is with a synchronous request using the /request/execute endpoint. This endpoint accepts your request parameters, processes them through a real browser environment, and returns the result in a single HTTP response. No polling required.

The following examples send a simple GET request to https://httpbin.org/get in passive mode with medium sensibility. This is the most common configuration and works well for the majority of websites.

JavaScript (Node.js SDK)

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

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

async function main() {
  const result = await client.get("https://httpbin.org/get", {
    mode: "passive",
    sensibility: "medium"
  });

  console.log("Status Code:", result.statusCode);
  console.log("Response Body:", result.body);
}

main();

JavaScript (Direct HTTP)

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://httpbin.org/get",
    method: "GET",
    mode: "passive",
    sensibility: "medium"
  })
});

const data = await response.json();
console.log("Success:", data.success);
console.log("Status Code:", data.task.result.statusCode);
console.log("Response Body:", data.task.result.body);

Python

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://httpbin.org/get",
        "method": "GET",
        "mode": "passive",
        "sensibility": "medium"
    }
)

data = response.json()
print("Success:", data["success"])
print("Status Code:", data["task"]["result"]["statusCode"])
print("Response Body:", data["task"]["result"]["body"])

cURL

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://httpbin.org/get",
    "method": "GET",
    "mode": "passive",
    "sensibility": "medium"
  }'

Expected Response

A successful synchronous request returns a JSON object with the task status set to completed and the full response data nested inside task.result.

{
  "success": true,
  "service": "MyDisct Solver BBRE",
  "task": {
    "id": "task_abc123def456",
    "status": "completed",
    "result": {
      "statusCode": 200,
      "headers": {
        "content-type": "application/json",
        "access-control-allow-origin": "*"
      },
      "body": "{"origin": "203.0.113.42", "url": "https://httpbin.org/get"}",
      "cookies": {},
      "profile": null
    }
  },
  "processingTime": 2847
}

Step 4: Asynchronous Pattern (Create + Poll)

For longer-running requests or when you want to fire multiple requests in parallel, use the asynchronous pattern. This involves two steps: first, create a task using /request/create to get a taskId, then poll /request/result with that taskId until the task completes.

The asynchronous pattern is particularly useful when you need to process multiple URLs concurrently. You can create dozens of tasks simultaneously and then poll for their results as they complete, rather than waiting for each one sequentially.

JavaScript (Node.js SDK)

The SDK's request() method with sync: false returns a task object. You can then use the task ID to poll for results manually, or let the SDK handle polling automatically by using the default synchronous behavior.

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

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

async function main() {
  const task = await client.request({
    url: "https://httpbin.org/get",
    mode: "passive",
    sensibility: "medium",
    sync: false
  });

  console.log("Task ID:", task.id);
  console.log("Status:", task.status);
}

main();

JavaScript (Direct HTTP with Polling)

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

async function createTask() {
  const response = await fetch(API_BASE + "/request/create", {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "x-api-key": API_KEY
    },
    body: JSON.stringify({
      url: "https://httpbin.org/get",
      method: "GET",
      mode: "passive",
      sensibility: "medium"
    })
  });

  return await response.json();
}

async function pollResult(taskId) {
  while (true) {
    const response = await fetch(API_BASE + "/request/result", {
      method: "POST",
      headers: {
        "Content-Type": "application/json",
        "x-api-key": API_KEY
      },
      body: JSON.stringify({ taskId })
    });

    const data = await response.json();

    if (data.task.status === "completed") {
      return data;
    }

    if (data.task.status === "failed") {
      throw new Error("Task failed: " + JSON.stringify(data));
    }

    await new Promise(resolve => setTimeout(resolve, 2000));
  }
}

async function main() {
  const createData = await createTask();
  console.log("Task created:", createData.task.id);

  const result = await pollResult(createData.task.id);
  console.log("Status Code:", result.task.result.statusCode);
  console.log("Response Body:", result.task.result.body);
}

main();

Python

import requests
import time

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

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

create_response = requests.post(
    API_BASE + "/request/create",
    headers=headers,
    json={
        "url": "https://httpbin.org/get",
        "method": "GET",
        "mode": "passive",
        "sensibility": "medium"
    }
)

task_data = create_response.json()
task_id = task_data["task"]["id"]
print("Task created:", task_id)

while True:
    result_response = requests.post(
        API_BASE + "/request/result",
        headers=headers,
        json={"taskId": task_id}
    )

    result_data = result_response.json()

    if result_data["task"]["status"] == "completed":
        print("Status Code:", result_data["task"]["result"]["statusCode"])
        print("Response Body:", result_data["task"]["result"]["body"])
        break

    if result_data["task"]["status"] == "failed":
        print("Task failed:", result_data)
        break

    time.sleep(2)

cURL

With cURL, you perform the create and poll steps as separate commands. First create the task, then use the returned taskId to poll for the result.

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

The create endpoint returns a task object with the taskId. Use that ID to poll for the result:

curl -X POST https://bbre-solver-api.mydisct.com/request/result   -H "Content-Type: application/json"   -H "x-api-key: YOUR_API_KEY"   -d '{"taskId": "task_abc123def456"}'

Step 5: Sending a POST Request

BBRE supports all standard HTTP methods. Here is an example of sending a POST request with a JSON body and custom headers. This pattern is common when interacting with REST APIs that require browser-level TLS fingerprints.

JavaScript (Node.js SDK)

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

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

async function main() {
  const result = await client.post("https://httpbin.org/post", {
    mode: "passive",
    sensibility: "medium",
    headers: {
      "Accept": "application/json"
    },
    body: {
      username: "testuser",
      action: "login"
    }
  });

  console.log("Status Code:", result.statusCode);
  console.log("Response:", result.body);
}

main();

Python

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://httpbin.org/post",
        "method": "POST",
        "mode": "passive",
        "sensibility": "medium",
        "headers": {
            "Accept": "application/json"
        },
        "body": {
            "username": "testuser",
            "action": "login"
        }
    }
)

data = response.json()
print("Status Code:", data["task"]["result"]["statusCode"])
print("Response:", data["task"]["result"]["body"])

cURL

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://httpbin.org/post",
    "method": "POST",
    "mode": "passive",
    "sensibility": "medium",
    "headers": {
      "Accept": "application/json"
    },
    "body": {
      "username": "testuser",
      "action": "login"
    }
  }'

Understanding the Response

Every BBRE API response follows a consistent structure. Understanding this structure is essential for building robust integrations. Here is a breakdown of the key fields you will encounter.

Error Response

When a request fails, the API returns an error object instead of a task result. The error includes a machine-readable code and a human-readable message to help you diagnose the issue.

{
  "success": false,
  "service": "MyDisct Solver BBRE",
  "error": {
    "code": "INSUFFICIENT_BALANCE",
    "message": "Your account balance is insufficient to process this request"
  }
}

Request Parameters Reference

The following table lists all available parameters you can include when creating a request. Only the url parameter is required. All other parameters have sensible defaults that work well for most use cases.

Best Practices

• Start with the synchronous endpoint for prototyping. The /request/execute endpoint is the simplest way to test your integration. It returns the result in a single call, which makes debugging straightforward. Once your integration is working, switch to the async pattern for production workloads that require concurrency.
• Use passive mode and medium sensibility as your default. This combination handles the vast majority of websites effectively. Only switch to adaptive mode when you need browser automation (clicking, form filling, JavaScript execution), and only increase sensibility to high when medium is getting blocked by the target site.
• Store your API key in environment variables. Never hardcode your API key directly in source files. Use process.env.BBRE_API_KEY in Node.js or os.environ["BBRE_API_KEY"] in Python to read the key from your environment. This prevents accidental exposure in version control systems.
• Implement proper error handling from the start. Always check the success field in the response before accessing task.result. Handle common error codes like INSUFFICIENT_BALANCE, URL_REQUIRED, and SERVICE_TIMEOUT gracefully in your application logic.
• Set explicit timeouts for synchronous requests. The default sync timeout is 120 seconds, which may be too long for your use case. Set a timeout value that matches your expectations. For fast APIs, 30 seconds is usually sufficient. For complex pages with heavy JavaScript, consider 60 to 90 seconds.

Common Issues

API_KEY_REQUIRED or INVALID_API_KEY Error

This error means the API did not receive a valid API key with your request. Make sure you are sending the key in the x-api-key header (or the apikey header as an alternative). Double-check that the header name is spelled correctly and that the key value does not contain extra whitespace or newline characters. If you recently regenerated your key, make sure you are using the new one.

INSUFFICIENT_BALANCE Error

Your account does not have enough balance to process the request. Each BBRE request has an associated cost that is deducted from your balance before processing begins. Check your current balance using the /account/balance endpoint and add funds through the MyDisct Solver dashboard. If a request fails after the balance deduction, the amount is automatically refunded.

SERVICE_TIMEOUT on Synchronous Requests

Synchronous requests have a maximum timeout of 300 seconds. If the target website takes longer than your configured timeout to respond, you will receive a SERVICE_TIMEOUT error. Try increasing the timeout parameter, or switch to the asynchronous pattern where you can poll for results without HTTP connection timeout constraints.

Empty Response Body

If you receive a successful response but the body is empty, the target website may be returning content that requires JavaScript rendering. In passive mode, BBRE does not execute client-side JavaScript. Switch to adaptive mode with a session to get the fully rendered page content. You can also try increasing the sensibility level, as some sites serve different content based on detected bot signals.

Next Steps

Now that you have successfully sent your first BBRE request, here are some directions to explore depending on your use case:

• Need browser automation? Learn how to create sessions and control a real browser instance in the Session Create and Browser Action documentation.
• Building complex workflows? The Hybrid Workflow Guide shows you how to combine passive and adaptive modes for multi-step processes like login flows and data extraction pipelines.
• Using Node.js? The Node.js SDK provides a much cleaner interface than raw HTTP calls, with built-in polling, session management, and error handling.

Related Documentation

• BBRE Engine Overview - Comprehensive overview of the BBRE architecture, modes, and core concepts
• Create Task API - Full documentation for the asynchronous task creation endpoint with all parameters
• Execute Sync API - Full documentation for the synchronous execution endpoint
• Fetch Result API - Documentation for polling task results in the async pattern
• Node.js SDK Overview - Get started with the mydisctsolver-bbre npm package
• Session Create API - Learn how to create persistent browser sessions for stateful workflows
• Hybrid Workflow Guide - Combine passive and adaptive modes for advanced use cases
• Fingerprint and Profile Guide - Deep dive into browser fingerprinting and identity management