Create Session

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, including session creation. 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 configuration for your new session. All parameters are optional. If you send an empty JSON object {}, the session is created with default settings: passive mode, medium sensibility, auto-generated fingerprint, no proxy, and a 120-second timeout. The following table describes every parameter accepted by this endpoint, including the data type, default value, validation rules, and detailed usage information. Understanding these parameters is critical for configuring sessions that match your specific use case, whether that is simple cookie persistence for API interactions or full browser automation for complex web workflows.

Session Lifecycle

Understanding the session lifecycle is essential for building reliable integrations with the BBRE session system. A session goes through a well-defined sequence of states from creation to termination, and knowing how these transitions work helps you design workflows that handle every scenario gracefully.

1. Creation

When you call POST /session/create, the BBRE engine allocates a new browser context with the specified mode, sensibility, fingerprint, and proxy configuration. The session is assigned a unique session ID and its status is set to active. The expiration timestamp is calculated as the current time plus the timeout value in seconds. If session pricing is configured, the session creation cost is deducted from your account balance at this point. The response includes the session ID, status, and expiration timestamp, which you need to store for subsequent requests.

2. Active Usage

While the session is active, you can send requests through it using the POST /session/request endpoint. Each request within the session shares the same browser context, which means cookies set by one request are automatically included in subsequent requests. If the session is in adaptive mode, you can also perform browser actions like navigate, click, fill, and screenshot through the POST /browser/action endpoint. The session tracks the number of requests made and the total amount charged. Cookies received from target websites are automatically merged into the session's cookie jar after each request. If the BBRE engine generates a browser profile during processing, it is stored in the session and returned with subsequent request results.

3. Expiration

Every session has an expiration timestamp set at creation time. When the current time exceeds the expiresAt timestamp, the session is considered expired. Any attempt to use an expired session returns a 400 SESSION_EXPIRED error. The session status is updated to expired when the expiration is detected. Expired sessions cannot be reactivated or extended. You must create a new session to continue your workflow. To avoid unexpected expirations, monitor the expiresAt value returned at creation time and plan your workflow to complete within the timeout window.

4. Explicit Close

You can explicitly close a session at any time using the POST /session/close endpoint. Closing a session immediately releases the browser context and frees up one of your 10 active session slots. The session status changes to closed and no further requests can be made through it. It is a best practice to always close sessions when you are done with them, rather than waiting for them to expire naturally. This ensures you do not hit the active session limit unnecessarily and frees up server resources for other users.

Session State Diagram

The following diagram summarizes the possible session states and transitions:

Session Limits

Each account is limited to a maximum of 10 active sessions at any given time. This limit exists to ensure fair resource allocation across all users, since each active session consumes server-side resources including memory for the browser context, cookie storage, and in adaptive mode, a dedicated browser instance. The limit applies only to sessions with active status that have not yet expired. Sessions that have been explicitly closed or that have expired do not count toward this limit.

When you attempt to create a session and you already have 10 active sessions, the API returns a 429 error with the SESSION_LIMIT_REACHED error code. The error response includes the current number of active sessions (activeCount) and the maximum allowed (maxAllowed: 10). To resolve this, close one or more existing sessions using the POST /session/close endpoint before creating a new one. You can also check your active sessions using the Account Sessions endpoint to see which sessions are still active and decide which ones to close.

Request Examples

The following examples demonstrate how to create BBRE sessions in different programming languages and for different use cases. 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.

Basic Session Creation

The simplest way to create a session. This uses all default settings: passive mode, medium sensibility, auto-generated fingerprint, no proxy, and a 120-second timeout. This is suitable for basic cookie persistence and simple multi-step workflows on sites without aggressive bot detection.

const axios = require("axios");

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

async function createBasicSession() {
  const response = await axios.post(
    API_BASE + "/session/create",
    {},
    {
      headers: {
        "Content-Type": "application/json",
        "x-api-key": API_KEY
      }
    }
  );

  const session = response.data.session;
  console.log("Session ID:", session.id);
  console.log("Status:", session.status);
  console.log("Expires At:", new Date(session.expiresAt).toISOString());

  return session;
}

createBasicSession();

import requests
from datetime import datetime

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

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

response = requests.post(
    API_BASE + "/session/create",
    headers=headers,
    json={}
)

data = response.json()
session = data["session"]
print("Session ID:", session["id"])
print("Status:", session["status"])
expires = datetime.fromtimestamp(session["expiresAt"] / 1000)
print("Expires At:", expires.isoformat())

curl -X POST https://bbre-solver-api.mydisct.com/session/create \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{}'

Adaptive Session with Custom Fingerprint

This example creates an adaptive mode session with high sensibility and a custom browser fingerprint. Adaptive sessions are required when you need to perform browser actions like clicking buttons, filling forms, or taking screenshots. The custom fingerprint ensures the session presents a consistent and realistic browser identity to the target website, which is critical for bypassing advanced bot detection systems that track fingerprint consistency across page loads.

const axios = require("axios");

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

async function createAdaptiveSession() {
  const response = await axios.post(
    API_BASE + "/session/create",
    {
      mode: "adaptive",
      sensibility: "high",
      timeout: 300,
      fingerprint: {
        platform: "Win32",
        timezone: "America/New_York",
        language: "en-US",
        screen: { width: 1920, height: 1080 }
      }
    },
    {
      headers: {
        "Content-Type": "application/json",
        "x-api-key": API_KEY
      }
    }
  );

  const session = response.data.session;
  console.log("Session ID:", session.id);
  console.log("Status:", session.status);
  console.log("Expires At:", new Date(session.expiresAt).toISOString());

  return session;
}

createAdaptiveSession();

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
}

response = requests.post(
    API_BASE + "/session/create",
    headers=headers,
    json={
        "mode": "adaptive",
        "sensibility": "high",
        "timeout": 300,
        "fingerprint": {
            "platform": "Win32",
            "timezone": "America/New_York",
            "language": "en-US",
            "screen": {"width": 1920, "height": 1080}
        }
    }
)

data = response.json()
session = data["session"]
print("Session ID:", session["id"])
print("Status:", session["status"])

curl -X POST https://bbre-solver-api.mydisct.com/session/create \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{
    "mode": "adaptive",
    "sensibility": "high",
    "timeout": 300,
    "fingerprint": {
      "platform": "Win32",
      "timezone": "America/New_York",
      "language": "en-US",
      "screen": {"width": 1920, "height": 1080}
    }
  }'

Session with Proxy Configuration

This example creates a session with a dedicated proxy server. Using a proxy with sessions is highly recommended for production use cases because it ensures all requests within the session originate from the same IP address. Anti-bot systems commonly flag sessions where the IP address changes between requests, so maintaining IP consistency through a proxy significantly improves success rates on protected websites.

const axios = require("axios");

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

async function createProxySession() {
  const response = await axios.post(
    API_BASE + "/session/create",
    {
      mode: "passive",
      sensibility: "medium",
      timeout: 300,
      proxy: {
        host: "us-residential.proxy.com",
        port: 8080,
        username: "proxyuser",
        password: "proxypass"
      },
      fingerprint: {
        timezone: "America/Chicago",
        language: "en-US"
      }
    },
    {
      headers: {
        "Content-Type": "application/json",
        "x-api-key": API_KEY
      }
    }
  );

  const session = response.data.session;
  console.log("Session ID:", session.id);
  console.log("Expires At:", new Date(session.expiresAt).toISOString());

  return session;
}

createProxySession();

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
}

response = requests.post(
    API_BASE + "/session/create",
    headers=headers,
    json={
        "mode": "passive",
        "sensibility": "medium",
        "timeout": 300,
        "proxy": {
            "host": "us-residential.proxy.com",
            "port": 8080,
            "username": "proxyuser",
            "password": "proxypass"
        },
        "fingerprint": {
            "timezone": "America/Chicago",
            "language": "en-US"
        }
    }
)

data = response.json()
session = data["session"]
print("Session ID:", session["id"])
print("Expires At:", session["expiresAt"])

curl -X POST https://bbre-solver-api.mydisct.com/session/create \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{
    "mode": "passive",
    "sensibility": "medium",
    "timeout": 300,
    "proxy": {
      "host": "us-residential.proxy.com",
      "port": 8080,
      "username": "proxyuser",
      "password": "proxypass"
    },
    "fingerprint": {
      "timezone": "America/Chicago",
      "language": "en-US"
    }
  }'

Response Format

The session creation endpoint returns a JSON response indicating whether the session was created successfully. On success, the response includes the session ID, status, and expiration timestamp. On failure, the response includes an error code, a human-readable message, and additional details where applicable.

Success Response (200)

A successful session creation returns the following structure. The session.id is the unique identifier you will use for all subsequent operations on this session. The expiresAt value is a Unix timestamp in milliseconds representing when the session will automatically expire. The profile field is null at creation time and gets populated after the first request is processed through the session.

{
  "success": true,
  "service": "MyDisct Solver BBRE",
  "session": {
    "id": "session_abc123def456",
    "status": "active",
    "expiresAt": 1706789012345
  },
  "profile": null
}

Error Response Examples

When session creation fails, the API returns an error response with the appropriate HTTP status code, error code, and a descriptive message. Some error responses include additional details to help you diagnose and resolve the issue.

429 - Session Limit Reached

{
  "success": false,
  "service": "MyDisct Solver BBRE",
  "error": {
    "code": "SESSION_LIMIT_REACHED",
    "message": "Maximum active sessions limit reached. Please close an existing session before creating a new one.",
    "details": {
      "activeCount": 10,
      "maxAllowed": 10
    }
  }
}

402 - Insufficient Balance

{
  "success": false,
  "service": "MyDisct Solver BBRE",
  "error": {
    "code": "INSUFFICIENT_BALANCE",
    "message": "Insufficient balance. Please add funds to your account.",
    "details": {
      "required": 0.05,
      "current_balance": 0.02
    }
  }
}

400 - Invalid Mode

{
  "success": false,
  "service": "MyDisct Solver BBRE",
  "error": {
    "code": "INVALID_MODE",
    "message": "Invalid mode. Valid modes: passive, adaptive.",
    "details": {
      "details": "Invalid mode: aggressive",
      "allowedModes": ["passive", "adaptive"],
      "hint": "Use \\"passive\\" for simple HTTP requests or \\"adaptive\\" for browser automation",
      "warning": "Browser actions (navigate, click, etc.) only work with \\"adaptive\\" mode"
    }
  }
}

Error Codes

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

Complete Session Workflow Example

The following example demonstrates a complete session workflow: creating a session, making multiple requests within the session to maintain state, checking the session status, and closing the session when finished. This pattern is the foundation for any multi-step interaction with a website through the BBRE API.

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 completeSessionWorkflow() {
  const createResponse = await axios.post(
    API_BASE + "/session/create",
    {
      mode: "passive",
      sensibility: "medium",
      timeout: 300
    },
    { headers: authHeaders }
  );

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

  const loginResponse = await axios.post(
    API_BASE + "/session/request",
    {
      sessionId: sessionId,
      url: "https://example.com/api/login",
      method: "POST",
      body: {
        username: "myuser",
        password: "mypassword"
      }
    },
    { headers: authHeaders }
  );
  console.log("Login status:", loginResponse.data.data.task.result.statusCode);

  const dashboardResponse = await axios.post(
    API_BASE + "/session/request",
    {
      sessionId: sessionId,
      url: "https://example.com/dashboard",
      method: "GET"
    },
    { headers: authHeaders }
  );
  console.log("Dashboard status:", dashboardResponse.data.data.task.result.statusCode);

  const statusResponse = await axios.post(
    API_BASE + "/session/status",
    { sessionId: sessionId },
    { headers: authHeaders }
  );
  console.log("Request count:", statusResponse.data.session.requestCount);

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

completeSessionWorkflow();

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
}

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

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

login_response = requests.post(
    API_BASE + "/session/request",
    headers=headers,
    json={
        "sessionId": session_id,
        "url": "https://example.com/api/login",
        "method": "POST",
        "body": {
            "username": "myuser",
            "password": "mypassword"
        }
    }
)
print("Login status:", login_response.json()["data"]["task"]["result"]["statusCode"])

dashboard_response = requests.post(
    API_BASE + "/session/request",
    headers=headers,
    json={
        "sessionId": session_id,
        "url": "https://example.com/dashboard",
        "method": "GET"
    }
)
print("Dashboard status:", dashboard_response.json()["data"]["task"]["result"]["statusCode"])

status_response = requests.post(
    API_BASE + "/session/status",
    headers=headers,
    json={"sessionId": session_id}
)
print("Request count:", status_response.json()["session"]["requestCount"])

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

Node.js SDK Usage

The mydisctsolver-bbre Node.js SDK provides a convenient createSession() method on the BBREClient class that wraps the POST /session/create endpoint. The SDK handles authentication headers, request formatting, and response parsing automatically. It also merges your default fingerprint and proxy settings with the session-specific options, so you do not need to repeat common configuration for every session.

Basic SDK Session Creation

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

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

async function createSessionWithSDK() {
  const result = await client.createSession({
    timeout: 300
  });

  console.log("Session ID:", result.sessionId);
  console.log("Expires At:", new Date(result.expiresAt).toISOString());
  console.log("Profile:", result.profile);

  return result;
}

createSessionWithSDK();

Adaptive Session with SDK

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

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

async function createAdaptiveSessionSDK() {
  const result = await client.createSession({
    mode: "adaptive",
    sensibility: "high",
    timeout: 300,
    fingerprint: {
      platform: "Win32",
      timezone: "America/New_York",
      language: "en-US",
      screen: { width: 1920, height: 1080 }
    },
    proxy: {
      host: "us-proxy.example.com",
      port: 8080,
      username: "proxyuser",
      password: "proxypass"
    }
  });

  console.log("Session ID:", result.sessionId);
  console.log("Expires At:", new Date(result.expiresAt).toISOString());

  return result;
}

createAdaptiveSessionSDK();

SDK Session with Default Settings

When you configure default fingerprint and proxy settings on the BBREClient instance, those defaults are automatically merged into every session you create. This eliminates the need to repeat common configuration and ensures consistency across all your sessions.

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

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

client.setDefaultFingerprint({
  platform: "Win32",
  timezone: "America/New_York",
  language: "en-US"
});

client.setDefaultProxy({
  host: "us-proxy.example.com",
  port: 8080,
  username: "proxyuser",
  password: "proxypass"
});

async function createSessionWithDefaults() {
  const result = await client.createSession({
    timeout: 300
  });

  console.log("Session ID:", result.sessionId);
  return result;
}

createSessionWithDefaults();

The SDK createSession() method returns an object with success, sessionId, expiresAt, and profile fields. If the session creation fails, the method throws an error with the error message from the API response. For more details on the SDK, see the Node.js SDK Overview and the Session Management documentation.

Pricing and Balance

Session creation has an associated cost that is determined by the BBRE_SESSION pricing tier configured in the system. When you create a session, the system checks the current price for the BBRE_SESSION captcha type and verifies that your account balance is sufficient to cover the cost. If pricing is configured and your balance is insufficient, the API returns a 402 INSUFFICIENT_BALANCE error that includes the required amount and your current balance. The balance deduction happens after the session is successfully created in the BBRE engine. Note that the session creation cost is separate from the per-request cost that may be charged for individual requests made within the session. You can check your current balance at any time using the Account Balance endpoint.

Best Practices

Common Issues

Issue 1: SESSION_LIMIT_REACHED When Creating Sessions

Solution: This happens when you have 10 sessions that are still in active status and have not yet expired. The most common cause is forgetting to close sessions after your workflow completes. Sessions remain active until they either expire naturally or are explicitly closed. First, use the POST /account/sessions endpoint to list your active sessions and identify which ones can be closed. Then close unnecessary sessions using POST /session/close. To prevent this issue in the future, always implement session cleanup in your code using try/finally blocks, and avoid creating sessions with unnecessarily long timeouts.

Issue 2: Session Expires Before Workflow Completes

Solution: Increase the timeout parameter when creating the session. Calculate the total expected duration of your workflow including all requests, processing time, and network latency, then add a 50-100% buffer. For example, if your workflow takes approximately 90 seconds, set the timeout to 180-240 seconds. The maximum allowed timeout through the validator is 3600 seconds (1 hour), though the controller clamps the effective value to a maximum of 300 seconds. For workflows that genuinely need more than 300 seconds, consider breaking them into multiple shorter sessions where each session handles a portion of the workflow.

Issue 3: Timeout Validation Error When Sending Values Below 60

Solution: The session creation endpoint has a minimum timeout of 60 seconds enforced by the request validator. Unlike the request endpoints where timeouts can be as low as 1 second, sessions require a minimum of 60 seconds because they are designed for multi-step workflows that inherently take longer. If you need a very short-lived interaction, consider using the stateless POST /request/execute endpoint instead of creating a session. Sessions are most effective when your workflow involves multiple sequential requests that need to share state.

Related Documentation

• Close Session - Learn how to explicitly close sessions to free up active session slots and release server resources
• Session Status - Check the current status, request count, total charged amount, and expiration time of an active session
• Session Request - Send HTTP requests within an active session to maintain cookies, fingerprint, and browser state across multiple interactions
• Browser Action - Perform browser automation actions (navigate, click, fill, screenshot) within adaptive mode sessions
• BBRE Engine Overview - Understand the BBRE architecture, passive and adaptive modes, sensibility levels, and core concepts
• Fingerprint and Profile Guide - Deep dive into browser fingerprint customization and profile management for sessions
• Account Sessions - List all your sessions with filtering options to manage your active session inventory
• Account Balance - Check your account balance before creating sessions to avoid insufficient balance errors