All articles

Local API and command line

The desktop app runs a REST API on your own computer so scripts can manage and launch profiles. Available on Pro and higher; in a team, your role needs Use the API.

Enabling

  1. Create an API key in Dashboard → API keys (shown once — store it safely). With two-factor sign-in on, creating a key asks for your code (Account security).
  2. In the desktop app, open API & Developers (or Settings → Local API), turn it on and paste the key. The default address is http://127.0.0.1:50380.

API & Developers in the app: the switch, the port, the key and copy-ready examples

The server only listens on 127.0.0.1 and refuses requests from web pages. Every request needs the key:

Authorization: Bearer lak_xxxxxxxxxxxxxxxxxxxxxxxx

Requests are rate-limited per plan (Pro 60/min, Business 300/min). Over the limit you get 429 with a Retry-After header. Errors look like {"error": "…"}; a bad request body is a 422 that says which field is wrong.

Endpoints

MethodPathDescription
GET/v1/statusApp version, headless or not, signed-in account and workspace, open profiles
GET/v1/profilesList profiles (?search=, ?group=, ?tag=)
POST/v1/profilesCreate a profile (name, engine or template_id, group_id, proxy_id, tags, notes)
GET/v1/profiles/{id}Get one profile
PATCH/v1/profiles/{id}Change name, notes, group, proxy, tags
DELETE/v1/profiles/{id}Move a profile to the trash
POST/v1/profiles/{id}/moveMove to a group: {"group_id": 12} (or null)
POST/v1/profiles/{id}/startStart and return connection info ({"headless": true} for no window)
POST/v1/profiles/{id}/stopStop a running profile
GET/v1/profiles/{id}/statusrunning, stopped or locked, and the automation endpoint
GET/v1/profiles/runningProfiles open on this computer
POST/v1/profiles/{id}/clear-cacheDelete a stopped profile's cache (cookies and logins stay)
GET/v1/profiles/{id}/cookiesThe profile's cookies
POST/v1/profiles/{id}/cookiesAdd cookies: {"cookies": [...]} or the text of a cookies file (JSON or Netscape)
POST/v1/profiles/{id}/new-fingerprintA new device for a stopped profile
GET/v1/profiles/{id}/user-agentThe User-Agent the profile's browser sends
POST/v1/profiles/stop-allClose every profile open on this computer
GET/v1/tagsList tags
POST/v1/tagsCreate a tag: {"name": "…", "color": "blue"}
PATCH/v1/tags/{id}Rename or recolor a tag
DELETE/v1/tags/{id}Delete a tag
GET/v1/groupsList profile groups
POST/v1/groupsCreate a group: {"name": "…", "color": "blue"}
PATCH/v1/groups/{id}Rename or recolor a group
GET/v1/proxiesSaved proxies (never their passwords)
POST/v1/proxiesSave a proxy (type: http, https, socks5 or ssh; host, port, username, password, name, rotate_url)
PATCH/v1/proxies/{id}Change a proxy
DELETE/v1/proxies/{id}Delete a proxy
POST/v1/proxies/{id}/checkCheck it from this computer: alive, exit IP, country, speed
GET/v1/flowsYour RPA flows
POST/v1/flows/{id}/runRun a flow: {"profile_ids": [...], "options": {"concurrency": 3, "headless": true}} → a task
GET/v1/tasksRecent runs on this computer
GET/v1/tasks/{id}A run: status per profile and the data it collected

Cookies need the role permission Export and import cookies in a team.

Starting a profile

POST /v1/profiles/01J.../start
{
  "id": "01J...",
  "status": "running",
  "engine": "chromium",
  "protocol": "cdp",
  "endpoint": "ws://127.0.0.1:53111/devtools/browser/…",
  "http_endpoint": "http://127.0.0.1:53111",
  "debug_port": 53111,
  "debugger_address": "127.0.0.1:53111"
}

protocol tells you how to attach:

protocolUse
cdpPuppeteer connect({ browserWSEndpoint }), Playwright chromium.connectOverCDP(...), Selenium debuggerAddress
bidiCamoufox (Firefox) profiles: Puppeteer connect({ browserWSEndpoint, protocol: "webDriverBiDi" }) or any WebDriver BiDi client

Selenium needs a ChromeDriver of the same Chrome version as the profile: give Selenium the browser version (the number after Chrome/ at http_endpoint + /json/version) and Selenium Manager downloads the right one.

Headless mode (servers)

On a server or VPS, start the app without a window, signed in with an API key:

owlxbrowser --headless --api-key=lak_xxxxxxxx --api-port=50380
  • The app signs this computer in with the key (it counts as one of your devices) and turns the Local API on with it. The key can also come from the OWLX_API_KEY environment variable.
  • Profiles started through the API run without windows unless a request says {"headless": false}.
  • It writes one line when it is ready (Local API on http://127.0.0.1:50380) and stops cleanly on Ctrl+C / SIGTERM, closing the browsers first.
  • Linux without a display: if the app doesn't start, run it as xvfb-run owlxbrowser --headless ….

Command line

For quick jobs and shell scripts there is a small command-line tool: download owlx-cli.mjs (one file, needs Node.js 18 or newer). It talks to the app on this computer through the Local API, so turn the API on first.

export OWLX_API_KEY=lak_xxxxxxxx        # Windows PowerShell: $env:OWLX_API_KEY = "lak_xxxxxxxx"
node owlx-cli.mjs profiles list
node owlx-cli.mjs start 42 --headless   # by No. or by ID; prints the automation endpoint
node owlx-cli.mjs run 3 42 43           # run flow 3 on profiles 42 and 43
node owlx-cli.mjs task <task id>        # follow the run
node owlx-cli.mjs stop-all

node owlx-cli.mjs --help lists every command. Add --json for the raw answer (handy with jq) and --port if you changed the API port.

Coming from another antidetect browser?

See Migration: import your accounts from a spreadsheet and keep existing automation scripts. Scripts written for AdsPower's Local API (v1 /api/v1/… and v2 /api/v2/browser-profile/…, /api/v2/browser-tags/…, /api/v2/proxy-list/…) and for Dolphin Anty (/v1.0/browser_profiles/{id}/start) work with the port changed and the API key added.

If the API page says the port can't be used, Windows has reserved it (Hyper-V, WSL and Docker reserve port ranges) or another program uses it: choose another port, for example 60380.

Examples

The repository's examples/ folder has complete scripts: Playwright (Node and Python), Puppeteer (Node), Selenium (Node and Python), and the MCP bridge for AI apps.

import { chromium } from "playwright-core";

const res = await fetch("http://127.0.0.1:50380/v1/profiles/PROFILE_ID/start", {
  method: "POST",
  headers: { Authorization: `Bearer ${process.env.LOCAL_API_KEY}` },
});
const { endpoint } = await res.json();
const browser = await chromium.connectOverCDP(endpoint);
const context = browser.contexts()[0];
const page = context.pages()[0] ?? (await context.newPage());
await page.goto("https://example.com");
import os, requests
from playwright.sync_api import sync_playwright

started = requests.post("http://127.0.0.1:50380/v1/profiles/PROFILE_ID/start",
    headers={"Authorization": f"Bearer {os.environ['LOCAL_API_KEY']}"}).json()
with sync_playwright() as p:
    browser = p.chromium.connect_over_cdp(started["endpoint"])
    page = browser.contexts[0].pages[0]
    page.goto("https://example.com")