Core API

Launch a profile

POST to launch a profile and receive a ready CDP endpoint plus driver recipes. An optional body sets per launch overrides that apply only to that launch.

Request

Send POST /api/profiles/{id}/launch. The body is optional. Any fields you pass are per launch overrides: they are applied to this launch only and are never written back to the saved profile.

POST /api/profiles/de-store-01/launch HTTP/1.1
Host: 127.0.0.1:8378
Authorization: Bearer <token>
Content-Type: application/json
 
{
  "stealth": "balanced",
  "headless": false,
  "proxy": "socks5://user:pass@gateway.example.com:1080",
  "args": ["--lang=de-DE"],
  "window": { "w": 1280, "h": 800 }
}

Launch options

All options are optional. Anything you omit falls back to the saved profile.

Field	Type	Description
stealth	"off" \| "balanced" \| "max"	Fingerprint strategy. off is clean Chromium with no fingerprint injection. balanced uses native fingerprints. max applies the strongest noise.
headless	boolean	Run without a visible window.
proxy	string	Overrides the profile proxy for this launch only.
args	string[]	Extra Chrome flags appended to the launch command line.
window	{ w, h }	Window size in pixels for this launch.
automation	"cdp" \| "playwright" \| "selenium" \| "none"	Which driver you intend to attach. Advisory today: the same CDP endpoint serves every driver.
ephemeral	boolean	Do not persist the user data dir for this launch. Advisory today.

stealth "off" is Chrome only. Firefox engine profiles always spoof their fingerprint.

Response

The response returns a ready CDP endpoint plus copy paste recipe strings for common drivers, so you do not have to assemble the connection arguments yourself. The ws_endpoint and cdp_http are proxied through the agent, so the dynamic CDP port stays hidden and any host that can reach the agent can attach.

{
  "profile_id": "de-store-01",
  "status": "running",
  "cdp_url": "/api/profiles/de-store-01/cdp",
  "ws_endpoint": "ws://127.0.0.1:8765/api/profiles/de-store-01/cdp",
  "cdp_http": "http://127.0.0.1:8765/api/profiles/de-store-01/cdp",
  "debugger_address": "127.0.0.1:9222",
  "debugger_address_is_local": true,
  "playwright": "browser = playwright.chromium.connect_over_cdp('http://127.0.0.1:8765/api/profiles/de-store-01/cdp')",
  "puppeteer": "const browser = await puppeteer.connect({ browserWSEndpoint: 'ws://127.0.0.1:8765/api/profiles/de-store-01/cdp' });",
  "selenium": "options.add_experimental_option('debuggerAddress', '127.0.0.1:9222')"
}

Field	Description
profile_id	The id of the launched profile.
status	Launch state, for example running.
cdp_url	Relative path of the proxied CDP endpoint on this agent.
ws_endpoint	Proxied WebSocket CDP endpoint for Playwright and Puppeteer. Reachable from any host that can reach the agent.
cdp_http	Proxied HTTP CDP base, useful for the /json endpoints and Playwright connectOverCDP.
debugger_address	Raw loopback host:port for the Selenium debugger_address. Only attaches when the script runs on the same machine as Oculr.
debugger_address_is_local	True when debugger_address is the real loopback port, so it only works same machine.
playwright	Ready Playwright connect recipe string.
selenium	Ready Selenium debugger_address recipe string.
puppeteer	Ready Puppeteer connect recipe string.

Try Oculr Quickstart