PBX Local API v1

A loopback HTTP/JSON API for creating, editing, validating, launching, stopping, and automating PBX virtual browser profiles from local software.

Download the Python SDK

Quick SDK usage

from pbx_local_api import PBXLocalAPI, PBXAPIError

# Best option when your script runs on the same Windows installation:
pbx = PBXLocalAPI.from_installed_pbx()

print(pbx.health())
print(pbx.capabilities())
print(pbx.list_environments())

draft = pbx.generate_draft({"os": "win64"})
print(draft)

# API start is automation-only:
pbx.start_selenium("env_001")
pbx.wait_until_running("env_001")

print(pbx.status("env_001"))
print(pbx.automation("env_001"))

pbx.stop("env_001")
pbx.wait_until_stopped("env_001")

Important API rules

• GET /v1/health is public.
• Every other Local API route requires authentication.
• API profile start is asynchronous and must explicitly select cdp or selenium.
• Manual browser launch remains a UI-only action.
• Selenium publishes its WebDriver endpoint. PBX's internal Chromium CDP attachment endpoint is not a public Local API endpoint.
• Profile creation/run requests can be rejected by PBX policy and may return HTTP 403 or 429.

Authentication

Protected routes accept either authentication header:

Authorization: Bearer <PBX_API_KEY>

or:

X-PBX-API-Key: <PBX_API_KEY>

Installed-PBX discovery for Python

PBXLocalAPI.from_installed_pbx() reads the Local API configuration from the current Windows PBX installation. The SDK uses the installed API key and the configured Local API port, including the PBX_LOCAL_API_PORT override when present.

Use the API from different languages

Every PBX route is normal HTTP + JSON, so any language with an HTTP client can use it. These reusable helpers let you call all methods in the endpoint table below.

from pbx_local_api import PBXLocalAPI, PBXAPIError

# Best option when your script runs on the same Windows installation:
pbx = PBXLocalAPI.from_installed_pbx()

print(pbx.health())
print(pbx.capabilities())
print(pbx.list_environments())

draft = pbx.generate_draft({"os": "win64"})
print(draft)

# API start is automation-only:
pbx.start_selenium("env_001")
pbx.wait_until_running("env_001")

print(pbx.status("env_001"))
print(pbx.automation("env_001"))

pbx.stop("env_001")
pbx.wait_until_stopped("env_001")

$Base = "http://127.0.0.1:8787"
$Key  = "YOUR_PBX_API_KEY"
$Headers = @{ Authorization = "Bearer $Key" }

function Invoke-PBX {
    param(
        [string]$Method,
        [string]$Path,
        $Body = $null,
        [switch]$Public
    )

    $args = @{
        Method = $Method
        Uri    = "$Base$Path"
    }

    if (-not $Public) { $args.Headers = $Headers }

    if ($null -ne $Body) {
        $args.ContentType = "application/json"
        $args.Body = ($Body | ConvertTo-Json -Depth 20)
    }

    Invoke-RestMethod @args
}

Invoke-PBX GET "/v1/health" -Public
Invoke-PBX GET "/v1/environments"

$draft = Invoke-PBX POST "/v1/environments/draft" @{ os = "win64" }

Invoke-PBX POST "/v1/environments/env_001/start" @{
    automation = "selenium"
}

Invoke-PBX GET "/v1/environments/env_001/status"
Invoke-PBX POST "/v1/environments/env_001/stop" @{}

# Public health
curl http://127.0.0.1:8787/v1/health

# Authenticated request
curl -H "Authorization: Bearer YOUR_PBX_API_KEY" \
  http://127.0.0.1:8787/v1/environments

# Draft
curl -X POST \
  -H "Authorization: Bearer YOUR_PBX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"os":"win64"}' \
  http://127.0.0.1:8787/v1/environments/draft

# Start with Selenium
curl -X POST \
  -H "Authorization: Bearer YOUR_PBX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"automation":"selenium"}' \
  http://127.0.0.1:8787/v1/environments/env_001/start

const BASE = "http://127.0.0.1:8787";
const API_KEY = "YOUR_PBX_API_KEY";

async function pbx(method, path, body = undefined, auth = true) {
  const headers = { "Accept": "application/json" };
  if (auth) headers["Authorization"] = `Bearer ${API_KEY}`;
  if (body !== undefined) headers["Content-Type"] = "application/json";

  const res = await fetch(BASE + path, {
    method,
    headers,
    body: body === undefined ? undefined : JSON.stringify(body)
  });

  const data = await res.json();
  if (!res.ok) throw new Error(JSON.stringify(data));
  return data;
}

console.log(await pbx("GET", "/v1/health", undefined, false));
console.log(await pbx("GET", "/v1/environments"));

const draft = await pbx("POST", "/v1/environments/draft", { os: "win64" });

await pbx("POST", "/v1/environments/env_001/start", {
  automation: "cdp"
});

console.log(await pbx("GET", "/v1/environments/env_001/status"));

using System.Net.Http.Headers;
using System.Text;
using System.Text.Json;

var baseUrl = "http://127.0.0.1:8787";
var apiKey = "YOUR_PBX_API_KEY";
using var http = new HttpClient();

async Task PBX(
    HttpMethod method,
    string path,
    object? body = null,
    bool auth = true)
{
    using var req = new HttpRequestMessage(method, baseUrl + path);

    if (auth)
        req.Headers.Authorization =
            new AuthenticationHeaderValue("Bearer", apiKey);

    if (body is not null)
        req.Content = new StringContent(
            JsonSerializer.Serialize(body),
            Encoding.UTF8,
            "application/json");

    using var res = await http.SendAsync(req);
    var text = await res.Content.ReadAsStringAsync();
    res.EnsureSuccessStatusCode();
    return text;
}

Console.WriteLine(await PBX(HttpMethod.Get, "/v1/health", auth:false));
Console.WriteLine(await PBX(HttpMethod.Get, "/v1/environments"));

Console.WriteLine(await PBX(
    HttpMethod.Post,
    "/v1/environments/draft",
    new { os = "win64" }));

await PBX(
    HttpMethod.Post,
    "/v1/environments/env_001/start",
    new { automation = "selenium" });

= 300)
        throw new Exception("PBX API HTTP " . $status . ": " . $result);

    return json_decode($result, true);
}

print_r(pbx("GET", "/v1/health", null, false));
print_r(pbx("GET", "/v1/environments"));
print_r(pbx("POST", "/v1/environments/draft", ["os" => "win64"]));

pbx("POST", "/v1/environments/env_001/start", [
    "automation" => "cdp"
]);

Complete endpoint reference

The API retains the route name /v1/environments for compatibility. In the product documentation these objects are called PBX virtual profiles.

Complete Python SDK method reference

The downloadable module exposes the following public helpers:

Common request bodies

Generate a draft

POST /v1/environments/draft
{ "os": "win64" }

Create multiple profiles

POST /v1/environments/batch
{
  "count": 5,
  "template": { "os": "win64" },
  "name_prefix": "QA"
}

The Python SDK validates count between 1 and 100.

Start a profile

POST /v1/environments/env_001/start
{
  "automation": "selenium"
}

Use "cdp" or "selenium". API starts are automation launches; there is no Local API manual-start mode.

Update proxy

PATCH /v1/environments/env_001/proxy
{
  "proxy": {
    "enabled": true,
    "host": "proxy.example",
    "port": 1080
  }
}

Set direct network

PATCH /v1/environments/env_001/proxy
{
  "proxy": {
    "enabled": false
  }
}

Randomize selected supported fingerprint fields

POST /v1/environments/env_001/fingerprint/randomize
{
  "fields": ["language", "timezone"]
}

Batch update

PATCH /v1/environments/batch
{
  "environment_ids": ["env_001", "env_002"],
  "patch": {
    "name": "Updated"
  }
}

Batch start

POST /v1/environments/batch/start
{
  "environment_ids": ["env_001", "env_002"],
  "automation": "cdp"
}

Errors and lifecycle handling

The Python SDK raises PBXAPIError with status, code, message, and the parsed API response when available. Connection failures and timeouts use status 0.

from pbx_local_api import PBXLocalAPI, PBXAPIError

pbx = PBXLocalAPI.from_installed_pbx()

try:
    pbx.start_selenium("env_001")
    running = pbx.wait_until_running("env_001", timeout=60)
    print(running)
except PBXAPIError as exc:
    print("status :", exc.status)
    print("code   :", exc.code)
    print("message:", exc.message)

Async start

Do not assume the browser is already ready when the start request returns. Poll /status or use the Python SDK's wait_until_running(). For Selenium, read the published automation information from profile status instead of attempting to use PBX's internal Chromium attachment endpoint.

Security

• Keep the Local API on loopback/local access.
• Do not publish the API key in websites, public JavaScript, repositories, screenshots, or logs.
• Prefer the Python SDK's installed-PBX discovery when your integration runs locally on the same Windows user account.
• Handle HTTP 403, 409, 429, connection errors, and lifecycle failures explicitly.
• Query /v1/capabilities when building integrations that must work across PBX versions.

Download the PBX Local API Python SDK →