POST /Browser/Open returns the WebSocket address of a fresh, isolated Chrome. Connect with Puppeteer or Playwright and automate it like a local browser — with stealth, proxies, saved sessions and a live remote desktop built in.
Request POST
/api/v1/Browser/Open
Authorization: Bearer ••••••••
Content-Type: application/json
{
"label": "price-check",
"keepOpen": 300,
"saveSession": true
}Response 200
{
"status": 200,
"address": "wss://browser.cloudbrowser.ai
/…/devtools/browser/…"
}Isolated Chrome · stealth on · premium proxy
Then connect:puppeteer.connect({ browserWSEndpoint: address })orchromium.connect_over_cdp(address)
How it works
The API manages browsers; the Chrome DevTools Protocol drives them. Any library that speaks CDP works — no proprietary scripting language to learn.
Ask for a browser with the options you need — a label, a proxy, a saved session.
POST /Browser/Open
Point Puppeteer or Playwright at the address in the response.
puppeteer.connect({ browserWSEndpoint })Navigate, click, type, extract and screenshot. Watch live on the remote desktop.
page.goto(url)
Close the browser when you’re done — or let keepOpen close it once nothing is connected.
POST /Browser/Close
Quickstart
Grab your API token from the dashboard, set it as CLOUDBROWSER_API_TOKEN and run any of these.
puppeteer-core; no SDK required.requests plus Playwright over CDP.import puppeteer from 'puppeteer-core';
const API = 'https://production.cloudbrowser.ai/api/v1';
const headers = {
Authorization: `Bearer ${process.env.CLOUDBROWSER_API_TOKEN}`,
'Content-Type': 'application/json',
};
// 1. Open a stealth Chrome in the cloud
const { status, address } = await fetch(`${API}/Browser/Open`, {
method: 'POST',
headers,
body: JSON.stringify({ label: 'price-check', keepOpen: 300 }),
}).then(res => res.json());
if (status !== 200) throw new Error(`CloudBrowser status ${status}`);
// 2. Drive it with Puppeteer over CDP
const browser = await puppeteer.connect({ browserWSEndpoint: address });
const [page] = await browser.pages();
await page.goto('https://example.com');
console.log(await page.title());
// 3. Close it so usage stops
await browser.close();Endpoints
Seven endpoints cover the whole browser lifecycle, plus eight optional AI helpers. Everything else happens over CDP, in the library you already use.
Base URLhttps://production.cloudbrowser.ai/api/v1AuthAuthorization: Bearer <API token>
Open, list and close isolated Chrome instances.
/Browser/OpenOpen a browser and get its CDP WebSocket address./Browser/GetList running browsers with their labels, start times and addresses./Browser/CloseClose a browser by its address.Watch a browser live and take over when a human is needed.
/Browser/StartRemoteDesktopStart a live view of a browser and receive its password./Browser/StopRemoteDesktopStop the live view.Keep cookies and localStorage under a label and bring them back later.
/Session/ListList saved sessions with their creation and update times./Session/RemoveDelete a saved session by label.Turn page HTML into answers and structured data with your own OpenAI key.
/AI/QueryAsk a question about a page’s HTML./AI/SummarizeSummarize a page in the language you choose./AI/ToJSON · ToCSV · ToMarkdownConvert HTML into JSON, CSV or Markdown./AI/Translate · Optimize · DescribeTranslate or rewrite text, or describe an image.Open options
Send these fields in the JSON body of POST /Browser/Open. All of them are optional.
| Field | Type | Default | What it does |
|---|---|---|---|
label | string | — | Names the browser so you can find it in the dashboard and the API, and keys its saved session. Must be unique among open browsers. |
keepOpen | number | 300 | Seconds the browser stays open with nothing connected. 0 keeps it open until you close it. |
browser | number | 0 | 0 = Chrome, 2 = Chromium, 3 = Chrome Headless Shell. Chrome gives the best stealth. |
headless | boolean | false | Run the browser without a window. |
stealth | boolean | true | Human-like fingerprints that keep bot-detection flags down. |
proxy | object | auto | { host, port, username, password } to use your own proxy. Omit it to use the automatically assigned premium proxy. |
saveSession | boolean | false | Save cookies and localStorage under the label — periodically and when the browser closes. Tabs are not saved. |
recoverSession | boolean | false | Restore the saved session for this label when the browser starts. |
args | string[] | — | Extra Chrome command-line flags. |
ignoredDefaultArgs | string[] | — | Default Chrome flags to leave out. |
Responses
Every response is JSON. A successful open returns the browser’s WebSocket address; anything else tells you exactly what to fix.
{
"status": 200,
"address": "wss://browser.cloudbrowser.ai/…/devtools/browser/…"
}CloudBrowser reports errors in the JSON body — status on Open and the AI endpoints, success and error elsewhere — so check the body, not only the HTTP code.
| Status | Meaning | What to do |
|---|---|---|
200 | Success | Use the returned address or result. |
401 | Missing or invalid API token | Check the Authorization: Bearer header. |
402 | No active subscription | Start the free trial or choose a plan. |
403 | No usage units left | Upgrade your plan or wait for next month’s units. |
404 | Concurrent browser limit reached | Close a browser, or upgrade to run more at once. |
405 | AI provider error | Check the OpenAI key and model you sent to an AI endpoint. |
406 | Label already in use | Pick another label, or close the browser that uses it. |
Built in
Fingerprints match real devices — timezone, locale, WebGL and screen — so JavaScript-heavy sites behave the way they do for people.
Every browser gets an automatically assigned premium proxy on every plan. Pass your own when you need a specific network.
saveSession and recoverSession keep logins alive between runs under a label — cookies and localStorage, not tabs.
Watch any browser live from the dashboard or the API, and take over for logins, one-time codes or CAPTCHAs.
Chrome by default, plus Chromium and Chrome Headless Shell — each in its own isolated container.
keepOpen shuts a browser down when nothing is connected, so a crashed script doesn’t keep using your units.
AI helpers
Send the HTML you collected and get Markdown, JSON, CSV, a summary or an answer back. The AI endpoints use your own OpenAI API key, so there is no AI markup from us.
curl -X POST https://production.cloudbrowser.ai/api/v1/AI/ToMarkdown \
-H "Authorization: Bearer $CLOUDBROWSER_API_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"html": "<html>…the page you collected…</html>",
"openAIConfiguration": {
"apiKey": "<your OpenAI API key>",
"model": "<OpenAI model>"
}
}'
# → { "status": 200, "response": "# Page title\n\n…" }Why a cloud browser
Running headless Chrome yourself works on a laptop. In production, CloudBrowser takes care of the parts that break.
| Topic | Run Chrome yourself | CloudBrowser |
|---|---|---|
| Setup | Install Chrome, fonts and drivers, then keep them patched | One HTTP call — nothing to install |
| Scale | Provision servers, queues and autoscaling | Up to 25 browsers at once, more on Custom plans |
| Bot detection | Tune flags and fingerprints yourself | Stealth fingerprints on by default |
| Proxies | Buy, rotate and wire up separately | Premium proxy included, or bring your own |
| Logins | Script cookie storage yourself | Saved sessions by label |
| Debugging | Logs and screenshots after the fact | Live remote desktop on every plan |
| AI assistants | Build your own tool layer | Hosted MCP server and ChatGPT plugin |
Limits & usage
Plans include a monthly allowance of usage units. One unit is 30 seconds of browser time per tab.
Concurrent browsers on Basic and Premium, with up to 3 tabs each. Custom plans go higher.
The default keepOpen: a browser closes after five minutes with nothing connected. Change it per call.
Browser time included on Basic ($25/mo, 7-day free trial) and Premium ($90/mo).
An API that starts real web browsers on remote servers for you. With CloudBrowser, POST /Browser/Open returns the WebSocket address of an isolated Chrome instance that you drive over the Chrome DevTools Protocol with Puppeteer, Playwright or any other CDP client.
Yes. Pass the address returned by /Browser/Open to Playwright’s connectOverCDP in Node.js or connect_over_cdp in Python. Disconnecting Playwright does not close the cloud browser, so call /Browser/Close when you finish.
Send your API token in the Authorization header as Bearer <token>. You find the token in the CloudBrowser dashboard. Keep it on the server — never ship it in browser or mobile code.
Until you close it, or until keepOpen seconds pass with nothing connected — 300 by default. Set keepOpen to 0 to keep the browser open until you call /Browser/Close.
10 concurrent browsers on Basic and 25 on Premium, each with up to 3 tabs. Custom plans go higher. Opening one more than your plan allows returns status 404 (browser limit).
Yes. Pass proxy with host, port, username and password. Without it, every browser uses an automatically assigned premium proxy.
Open the browser with a label and saveSession: true, then sign in once — yourself on the remote desktop or with your script. Next time, open with the same label and recoverSession: true: cookies and localStorage come back. Open tabs do not.
Yes. Call /Browser/StartRemoteDesktop to start a live view and receive its password, or open the browser from your dashboard. Stop the view with /Browser/StopRemoteDesktop.
No — they are optional helpers. They work on HTML you send and use your own OpenAI API key, so AI usage is billed by OpenAI, not CloudBrowser.
Yes. There are official SDKs for .NET and Node.js, and drop-in MCP toolkits for agent frameworks such as the OpenAI Agents SDK and the Claude Agent SDK. See the SDK page for install commands and examples.
Browser time is counted in usage units: one unit is 30 seconds of browser time per tab. Each plan includes a monthly allowance, and Basic starts with a 7-day free trial.
Start a 7-day free trial, copy your API token from the dashboard and run the quickstart.
