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
- 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).
- 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.

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
| Method | Path | Description |
|---|---|---|
| GET | /v1/status | App version, headless or not, signed-in account and workspace, open profiles |
| GET | /v1/profiles | List profiles (?search=, ?group=, ?tag=) |
| POST | /v1/profiles | Create 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}/move | Move to a group: {"group_id": 12} (or null) |
| POST | /v1/profiles/{id}/start | Start and return connection info ({"headless": true} for no window) |
| POST | /v1/profiles/{id}/stop | Stop a running profile |
| GET | /v1/profiles/{id}/status | running, stopped or locked, and the automation endpoint |
| GET | /v1/profiles/running | Profiles open on this computer |
| POST | /v1/profiles/{id}/clear-cache | Delete a stopped profile's cache (cookies and logins stay) |
| GET | /v1/profiles/{id}/cookies | The profile's cookies |
| POST | /v1/profiles/{id}/cookies | Add cookies: {"cookies": [...]} or the text of a cookies file (JSON or Netscape) |
| POST | /v1/profiles/{id}/new-fingerprint | A new device for a stopped profile |
| GET | /v1/profiles/{id}/user-agent | The User-Agent the profile's browser sends |
| POST | /v1/profiles/stop-all | Close every profile open on this computer |
| GET | /v1/tags | List tags |
| POST | /v1/tags | Create a tag: {"name": "…", "color": "blue"} |
| PATCH | /v1/tags/{id} | Rename or recolor a tag |
| DELETE | /v1/tags/{id} | Delete a tag |
| GET | /v1/groups | List profile groups |
| POST | /v1/groups | Create a group: {"name": "…", "color": "blue"} |
| PATCH | /v1/groups/{id} | Rename or recolor a group |
| GET | /v1/proxies | Saved proxies (never their passwords) |
| POST | /v1/proxies | Save 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}/check | Check it from this computer: alive, exit IP, country, speed |
| GET | /v1/flows | Your RPA flows |
| POST | /v1/flows/{id}/run | Run a flow: {"profile_ids": [...], "options": {"concurrency": 3, "headless": true}} → a task |
| GET | /v1/tasks | Recent 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:
| protocol | Use |
|---|---|
cdp | Puppeteer connect({ browserWSEndpoint }), Playwright chromium.connectOverCDP(...), Selenium debuggerAddress |
bidi | Camoufox (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_KEYenvironment 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")