openapi: 3.0.0 info: title: Browserless Browser REST APIs Management REST APIs API version: 2.49.0 x-logo: altText: browserless logo url: ./docs/browserless-logo-inline.svg description: "# Browserless.io\n\nThis service extends the Browserless open-source image with many features and enhancements for teams automating at scale. Notable features include:\n\n- A Chrome-devtools-protocol based API for extending and enhancing libraries in a cross-language way.\n- A new hybrid-automation toolkit with live session interactivity.\n- Robust session management: connect, reconnect, kill and limit what a browser can do.\n- Bleeding features like multiplexing numerous clients into a single Chrome process in an isolated way.\n- The ability to upload and run custom extensions.\n- Run multiple tokens, with access controls on each.\n- Multi-browser with all the robust capabilities already in the open-source images.\n\nThere's a lot to cover here so let's get started!\n\n# Software Keys\n\nThe Enterprise image supports time-limited software keys that allow usage for a specific period without requiring any external connections or callbacks. These keys are cryptographically secure and cannot be reverse engineered. When a key expires, the container will exit with a semantic error code.\n\n## Using a Software Key\n\nTo use a software key, set the `KEY` environment variable when running the container:\n\n```bash\ndocker run -e KEY=your-generated-key browserless/enterprise\n```\n\n# Using the Browserless Proxy\n\n> The Residential proxy is only available for Enterprise and Cloud plans.\n\nBrowserless comes with a built-in mechanism to proxy to what's called \"residential\" IPs. These are IP addresses are sourced from real-users running a proxy server on their home networking machines. Residential proxying is especially useful for things like bypassing certain bot blockages and more.\n\nUsing a residential proxy is as straightforward as adding a few parameters to your library or API calls. Here's the required parameters and the values they support:\n\n- `?proxy=residential`: Specifies that you want to use the residential proxy for this request. Data-center coming soon.\n- `?proxyCountry=us`: Specifies a country you wish to use for the request. A two-digit ISO code.\n- `?proxySticky=true`: If you want to use the same IP address for the entirety of the session. Generally recommended for most cases.\n- `?proxyPreset=px_gov01`: Website-specific proxy configuration. Use `px_gov01` for government websites to ensure optimal proxy vendor selection.\n\nSimply append these to your connection call, REST API calls, or any library call:\n\n`wss://production-sfo.browserless.io/chromium?token=YOUR-API-TOKEN&proxy=residential&proxyCountry=us&proxySticky`\n\n`https://production-sfo.browserless.io/chromium/unblock?token=YOUR-API-TOKEN&proxy=residential&proxyCountry=us&proxySticky`\n\nPlease do note that using a proxy will increase the amount of units consumed. Every megabyte of data transferred consumes 6 units.\n\n# The Browserless CDP API\n\nIn order to enhance the experience with open source libraries like Puppeteer, we decided to take a new approach to extending these libraries in a language-agnostic way. We call it the Browserless CDP API. Here's a quick list of what it can do:\n\n- Generate and give back live URLs for hybrid automation.\n- Solve Captchas.\n- Return your page's unique identifier created by Chrome.\n- Way more coming!\n\nSince most libraries come with a way to issue \"raw\" CDP commands, it's an easy way to drop-in custom behaviors without having to write and maintain a library. Plus you can continue to enjoy using the same packages you've already come to know.\n\nGetting started with this API is pretty simple. For instance, if you want to use the live viewer for a particular page, simply do the following:\n\n```js\nimport puppeteer from 'puppeteer-core';\n\n(async () => {\n const browserWSEndpoint = 'wss://production-sfo.browserless.io/chromium';\n const browser = await puppeteer.connect({ browserWSEndpoint });\n const page = await browser.newPage();\n const cdp = await page.createCDPSession();\n await page.goto('https://example.com');\n const { liveURL } = await cdp.send('Browserless.liveURL');\n\n // liveURL = 'http://localhost:5555/live/?i=98e83bbfd396241a6963425b1feeba2f';\n})();\n```\n\nYou can then visit this URL in any browser to interact with the headless Chrome running someplace else.\n\nSee more below for a full list of the available APIs and features.\n\n## Browserless.liveURL\n\n> This API is available on all plans except the Free plan. [Contact us for more information here.](https://www.browserless.io/contact/)\n\nReturns a fully-qualified URL to load into a web-browser. This URL allows for clicking, typing and other interactions with the underlying page. This URL doesn't require an authorization token, so you're free to share it externally with your own users or employees. If security is a concern, you can set a `timeout` parameter to limit the amount of time this URL is valid for. By default no `timeout` is set and the URL is good as long as the underlying browser is open.\n\nProgrammatic control of the session is also available, so you can close the live session once your code has detected a selector, network call, or whatever else. See the below example for programmatic control.\n\n**Basic example**\n\n```js\nimport puppeteer from 'puppeteer-core';\n\n(async () => {\n const browserWSEndpoint =\n 'wss://production-sfo.browserless.io/chromium?token=YOUR-API-TOKEN';\n const browser = await puppeteer.connect({ browserWSEndpoint });\n const page = await browser.newPage();\n const cdp = await page.createCDPSession();\n await page.goto('https://example.com');\n const { liveURL } = await cdp.send('Browserless.liveURL');\n\n // liveURL = 'https://production-sfo.browserless.io/live/?i=98e83bbfd396241a6963425b1feeba2f';\n})();\n```\n\n**Timeout example**\n\n```js\nimport puppeteer from 'puppeteer-core';\n\n(async () => {\n const browserWSEndpoint =\n 'wss://production-sfo.browserless.io/chromium?token=YOUR-API-TOKEN';\n const browser = await puppeteer.connect({ browserWSEndpoint });\n const page = await browser.newPage();\n const cdp = await page.createCDPSession();\n await page.goto('https://example.com');\n const { liveURL } = await cdp.send('Browserless.liveURL', {\n timeout: 10000, // 10 seconds to connect!\n });\n\n // liveURL = 'https://production-sfo.browserless.io/live/?i=98e83bbfd396241a6963425b1feeba2f';\n})();\n```\n\n**Maintaining the width and height**\n\nBy default, Browserless will dynamically change the width and height of the browser to match an end-users screen. This isn't always ideal and can be disabled by setting a `resizable` value to `false`. When this is done, only your script can alter the width and height of the browser:\n\n```js\nimport puppeteer from 'puppeteer-core';\n\n(async () => {\n const browserWSEndpoint =\n 'wss://production-sfo.browserless.io/chromium?token=YOUR-API-TOKEN';\n const browser = await puppeteer.connect({ browserWSEndpoint });\n const page = await browser.newPage();\n\n // Width and height will always be 1920x1080\n // and the Live URL will maintain this aspect ratio\n await page.setViewport({ width: 1920, height: 1080 });\n const cdp = await page.createCDPSession();\n await page.goto('https://example.com');\n const { liveURL } = await cdp.send('Browserless.liveURL', {\n resizable: false,\n });\n\n // liveURL = 'https://production-sfo.browserless.io/live/?i=98e83bbfd396241a6963425b1feeba2f';\n})();\n```\n\n**Setting a Quality and Type**\n\nSetting a \"quality\" and \"type\" effects the streamed quality of the live URL's client-side resolution. By default, Browserless sets these to quality: 70 and type of \"jpeg\". You can experiment different settings to get an ideal resolutions while keep latency slow. The closer to 100 quality is, the potential for higher perceived latency.\n\n```js\nimport puppeteer from 'puppeteer-core';\n\n(async () => {\n const browserWSEndpoint =\n 'wss://production-sfo.browserless.io/chromium?token=YOUR-API-TOKEN';\n const browser = await puppeteer.connect({ browserWSEndpoint });\n const page = await browser.newPage();\n const cdp = await page.createCDPSession();\n await page.goto('https://example.com');\n const { liveURL } = await cdp.send('Browserless.liveURL', {\n quality: 70, // Can be 1 - 100. Default is 70\n type: 'jpeg', // Can be 'jpeg' or 'png'. Default is 'jpeg'\n compressed: true, // Whether to compress each frame of the streamed image data\n });\n\n // liveURL = 'https://production-sfo.browserless.io/live/?i=98e83bbfd396241a6963425b1feeba2f';\n})();\n```\n\nIt's also helpful to \"wait\" until the user is done doing what's needed. For that reason, Browserless will fire a custom event when the page is closed as well:\n\n**Wait for close**\n\n> Custom CDP Events are not supported in all libraries, including .NET Playwright.\n\n```js\nimport puppeteer from 'puppeteer-core';\n\n(async () => {\n const browserWSEndpoint =\n 'wss://production-sfo.browserless.io/chromium?token=YOUR-API-TOKEN';\n const browser = await puppeteer.connect({ browserWSEndpoint });\n const page = await browser.newPage();\n const cdp = await page.createCDPSession();\n await page.goto('https://example.com');\n\n const { liveURL } = await cdp.send('Browserless.liveURL');\n\n console.log(liveURL);\n\n // Wait for the Browserless.liveComplete event when the live page is closed.\n // Please not that not all libraries support custom CDP events.\n await new Promise((r) => cdp.on('Browserless.liveComplete', r));\n\n console.log('Done!');\n\n await browser.close();\n})();\n```\n\n**Programmatic Control**\n\n```js\nimport puppeteer from 'puppeteer-core';\n\n(async () => {\n const browserWSEndpoint =\n 'wss://production-sfo.browserless.io/chromium?token=YOUR-API-TOKEN';\n const browser = await puppeteer.connect({ browserWSEndpoint });\n const page = await browser.newPage();\n const cdp = await page.createCDPSession();\n await page.goto('https://example.com');\n\n // Having the liveURLId is required in order to close it later\n const { liveURL, liveURLId } = await cdp.send('Browserless.liveURL');\n\n await page.waitForSelector('.my-selector');\n\n // Calling this CDP API with the \"liveURLId\" will close the session, and terminate the client\n // further usage of the liveURL will fail and no more human-control is possible\n await cdp.send('Browserless.closeLiveURL', { liveURLId });\n\n // Continue to process or interact with the browser, then:\n await browser.close();\n})();\n```\n\nIt's recommended that you double check the page prior to executing further code to make sure the page is where it should be, elements are present, and so forth. This approach makes it easy to solve hard things like second-factor authentication and more in a trivial fashion.\n\n**Read-only LiveURL Sessions**\n\nThe `interactive: false` option allows you to create read-only LiveURL sessions where users can view the browser but cannot interact with it. This is useful for monitoring or demonstration purposes without allowing user input.\n\n```js\nimport puppeteer from 'puppeteer-core';\n\n(async () => {\n const browserWSEndpoint =\n 'wss://production-sfo.browserless.io/chromium?token=YOUR-API-TOKEN';\n const browser = await puppeteer.connect({ browserWSEndpoint });\n const page = await browser.newPage();\n const cdp = await page.createCDPSession();\n await page.goto('https://example.com');\n\n // Create a read-only LiveURL session that users can view but not interact with\n const { liveURL } = await cdp.send('Browserless.liveURL', {\n interactive: false,\n });\n\n console.log('Read-only LiveURL:', liveURL);\n\n await browser.close();\n})();\n```\n\n## Browserless.reconnect\n\n> This API is only available for Enterprise plans. [Contact us for more information here.](https://www.browserless.io/contact/)\n\nReconnecting allows for the underlying Chrome or Chromium process to continue to run for a specified amount of time, and subsequent reconnecting back to it. With this approach you can also \"share\" this connection URL to other clients to connect to the same browser process, allowing you to parallelize via a single Browser process.\n\nOnce a reconnection URL is retrieved, Browserless will intercept close-based commands and stop them from terminating the browser process itself. This prevents clients from accidentally closing the process via `browser.close` or similar.\n\nIn order to use this API, simply call `Browserless.reconnect` as a CDP command. You can, optionally, set a `timeout` or an `auth` property. See the below examples for details\n\n**Basic example with timeout**\n\n```js\nimport puppeteer from 'puppeteer-core';\n\n(async () => {\n const browserWSEndpoint =\n 'wss://production-sfo.browserless.io/chromium?token=YOUR-API-TOKEN';\n const browser = await puppeteer.connect({ browserWSEndpoint });\n const page = await browser.newPage();\n const cdp = await page.createCDPSession();\n await page.goto('https://example.com');\n\n // Allow this browser to run for 10 seconds, then shut down if nothing connects to it.\n // Defaults to the overall timeout set on the instance, which is 5 minutes if not specified.\n const { error, browserWSEndpoint } = await cdp.send('Browserless.reconnect', {\n timeout: 10000,\n });\n\n if (error) throw error;\n\n await browser.close();\n\n // browserWSEndpoint = 'https://production-sfo.browserless.io/reconnect/98e83bbfd396241a6963425b1feeba2f';\n})();\n```\n\nIf you want to enforce authentication, you can pass in an optional `auth` property that clients will need to use in order to connect with. Similar to how authentication works in general, a `token` query-string parameter will need to be applied.\n\n**Authentication example**\n\n```js\nimport puppeteer from 'puppeteer-core';\n\n(async () => {\n const browserWSEndpoint =\n 'wss://production-sfo.browserless.io/chromium?token=YOUR-API-TOKEN';\n const browser = await puppeteer.connect({ browserWSEndpoint });\n const page = await browser.newPage();\n const cdp = await page.createCDPSession();\n await page.goto('https://example.com');\n\n // Set a custom authentication token that clients have to use in order to connect, or otherwise\n // receive a 401 Response.\n const { error, browserWSEndpoint } = await cdp.send('Browserless.reconnect', {\n auth: 'secret-auth-token',\n });\n\n if (error) throw error;\n\n await browser.close();\n\n // NOTE the URL here doesn't include the auth token!\n // browserWSEndpoint = 'https://production-sfo.browserless.io/reconnect/98e83bbfd396241a6963425b1feeba2f';\n})();\n```\n\n**Recursive Example**\n\n```js\nimport puppeteer from 'puppeteer-core';\n\nconst job = async (reconnectURL) => {\n const browserWSEndpoint =\n reconnectURL ??\n 'wss://production-sfo.browserless.io/chromium?token=YOUR-API-TOKEN';\n const browser = await puppeteer.connect({ browserWSEndpoint });\n const [page] = await browser.page();\n const cdp = await page.createCDPSession();\n await page.goto('https://example.com');\n\n // Anytime Browserless.reconnect is called, this restarts the timer back to the provided value,\n // effectively \"bumping\" the timer forward.\n const res = await cdp.send('Browserless.reconnect', {\n timeout: 30000,\n });\n\n if (res.error) throw error;\n\n await browser.close();\n\n // Continuously reconnect back...\n return job(res.browserWSEndpoint);\n};\n\njob().catch((e) => console.error(e));\n```\n\n## Browserless.solveCaptcha\n\n> This API is only available for Enterprise and Scale and above plans on Cloud. [Contact us for more information here.](https://www.browserless.io/contact/). Only the `/chrome` and `/chromium` routes support Captcha solving.\n\nBrowserless comes with built-in captcha solving capabilities. We use a variety of techniques to try and mitigate the chances of captchas coming up, but if you happen to run into one you can simply call on our API to solve it.\n\nGiven the amount of possibilities during a captcha solve, the API returns many properties and information in order to help your script be more informed as to what happened. See the below code example for all details and fields returned by the API.\n\nPlease be aware that solving a captcha can take a few seconds up to several minutes, so you'll want to increase your timeouts accordingly for your scripts. Captcha's solved, or attempted to solve, cost 10 units.\n\n```js\nimport puppeteer from 'puppeteer-core';\n\n(async () => {\n const browser = await puppeteer.connect({\n browserWSEndpoint:\n 'wss://production-sfo.browserless.io/chromium?token=YOUR-API-TOKEN&timeout=300000',\n });\n\n const page = await browser.newPage();\n const cdp = await page.createCDPSession();\n await page.goto('https://www.google.com/recaptcha/api2/demo', {\n waitUntil: 'networkidle0',\n });\n\n const {\n // A simple boolean indicating whether the script can proceed\n ok,\n // Whether or not a captcha was found\n captchaFound,\n // A human-readable description of what occurred.\n message,\n // Whether a solve was attempted or not\n solveAttempted,\n // If the Captcha was solved, only true if found AND solved\n solved,\n } = await cdp.send('Browserless.solveCaptcha', {\n // How long to wait for a Captcha to appear to solve.\n // Defaults to 10,000ms, or 10 seconds.\n appearTimeout: 30000,\n });\n\n console.log(message);\n\n if (ok) {\n await page.click('#recaptcha-demo-submit');\n } else {\n console.error(`Error solving captcha!`);\n }\n\n await browser.close();\n})().catch((e) => {\n console.error(e);\n process.exit(1);\n});\n```\n\nIn general, if an `ok` response is sent back from this API, then your script is good to proceed with further actions. If a captcha is to suddenly appears after an action then you might want to listen for the `Browserless.foundCaptcha` event (see below) and retry solving.\n\n## Browserless.foundCaptcha\n\n> This API is only available for Enterprise and Scale and above plans on Cloud. [Contact us for more information here.](https://www.browserless.io/contact/). Only the `/chrome` and `/chromium` routes support Captcha solving.\n\n> Custom CDP Events are not supported in all libraries, including .NET Playwright.\n\nEmitted whenever a captcha widget is found on the page. Useful for checking if there's a captcha and deciding whether or not to proceed with solving.\n\nThe example below stops until a captcha is found, which may or may not be the case with every website out there.\n\n```js\nimport puppeteer from 'puppeteer-core';\n\n// Recaptcha\n(async () => {\n const browser = await puppeteer.connect({\n browserWSEndpoint:\n 'wss://production-sfo.browserless.io/chromium?token=YOUR-API-TOKEN&timeout=300000',\n });\n\n const page = await browser.newPage();\n const cdp = await page.createCDPSession();\n\n await page.goto('https://www.google.com/recaptcha/api2/demo', {\n waitUntil: 'networkidle0',\n });\n\n // Please note that not all libraries support custom CDP events.\n await new Promise((resolve) =>\n cdp.on('Browserless.captchaFound', (params) => {\n console.log('Found a captcha!');\n return resolve();\n }),\n );\n\n const { solved, error } = await cdp.send('Browserless.solveCaptcha');\n console.log({\n solved,\n error,\n });\n\n // Continue...\n await page.click('#recaptcha-demo-submit');\n})().catch((e) => {\n console.error(e);\n process.exit(1);\n});\n```\n\n### Event Parameters\n\n| Parameter | Type | Description |\n| --------- | -------- | ---------------------------------------------- |\n| `type` | `string` | Captcha type (`recaptcha`, `cloudflare`, etc.) |\n| `status` | `string` | Status: `\"found\"` or `\"solving\"` |\n\n## Browserless.captchaAutoSolved\n\n> This API is only available for Enterprise and Scale and above plans on Cloud. [Contact us for more information here.](https://www.browserless.io/contact/). Only the `/chrome` and `/chromium` routes support Captcha solving.\n\n> Custom CDP Events are not supported in all libraries, including .NET Playwright.\n\nEmitted whenever a captcha widget is solved in the page by the auto-solving feature. Note that this event is not emitted when a captcha is solved manually.\n\nTo enable this feature, you need to set the `solveCaptchas` option to `true` in your query parameters while connecting to the browser.\n\n```js\nimport puppeteer from 'puppeteer-core';\n\n// Helper function to wait for a captcha to be solved\nconst waitForCaptchaResolved = (cdp) => {\n return new Promise((resolve) => {\n const onCaptchaFound = (params) => {\n console.log('Captcha found, type:', params.type, params.status);\n cdp.on('Browserless.captchaAutoSolved', resolve);\n };\n\n cdp.on('Browserless.captchaFound', onCaptchaFound);\n });\n};\n\n// Recaptcha\n(async () => {\n const browser = await puppeteer.connect({\n browserWSEndpoint:\n 'wss://production-sfo.browserless.io/chromium?token=YOUR-API-TOKEN&solveCaptchas=true',\n });\n const page = await browser.newPage();\n const cdp = await page.target().createCDPSession();\n\n await page.goto('https://www.google.com/recaptcha/api2/demo', {\n waitUntil: 'networkidle0',\n });\n const captchaEvent = await waitForCaptchaResolved(cdp);\n console.log(captchaEvent);\n\n await browser.close();\n\n // Continue...\n await page.click('#recaptcha-demo-submit');\n})().catch((e) => {\n console.error(e);\n process.exit(1);\n});\n```\n\n### Event Parameters\n\n| Parameter | Type | Description |\n| ------------ | ---------------- | ------------------------------------------- |\n| `autoSolved` | `true` | Whether captcha was auto-solved |\n| `token` | `null \\| string` | Captcha token if solved |\n| `found` | `boolean` | Whether a captcha was found |\n| `solved` | `boolean` | Whether the captcha was successfully solved |\n| `time` | `number` | Time taken to solve (in milliseconds) |\n\n## Browserless.heartbeat\n\n> This API is only available for Enterprise hosted and Starter and above plans on Cloud. [Contact us for more information here.](https://www.browserless.io/contact/).\n\n> Custom CDP Events are not supported in all libraries, including .NET Playwright.\n\nA custom event emitted every several seconds, signaling a live connection. This is useful for a few reasons:\n\n- It ensure that your connection with the browser is still good.\n- Sending data can trigger some load-balancing technologies to not kill the connection.\n\nToday this event is emitted every 30 seconds.\n\n```js\nimport puppeteer from 'puppeteer-core';\n\nconst browserWSEndpoint = `wss://production-sfo.browserless.io/chromium?token=YOUR-API-TOKEN`;\n\n(async () => {\n const browser = await puppeteer.connect({ browserWSEndpoint });\n const page = await browser.newPage();\n await page.goto('https://example.com/');\n const client = await page.createCDPSession();\n\n client.on('Browserless.heartbeat', () => {\n console.log('Browserless.heartbeat');\n });\n})();\n```\n\n## Browserless.pageId\n\n> This API is only available for Enterprise hosted and Starter and above plans on Cloud. [Contact us for more information here.](https://www.browserless.io/contact/).\n\nA simple helper utility to return the page's unique ID. Since most libraries treat this ID as opaque, and some even hide it, knowing the page's ID can be of great help when interacting with other parts of Browserless.\n\n```js\nimport puppeteer from 'puppeteer-core';\n\n(async () => {\n const browserWSEndpoint = 'wss://production-sfo.browserless.io/chromium';\n const browser = await puppeteer.connect({ browserWSEndpoint });\n const page = await browser.newPage();\n const cdp = await page.createCDPSession();\n const { pageId } = await cdp.send('Browserless.pageId');\n\n // pageId = 'ABC12354AFDC123';\n})();\n```\n\nYou can, optionally, try and \"find\" this ID in puppeteer or similar libraries. Given that puppeteer has this property underscored, it's likely to change or be unavailable in the future, and requires the infamous `// @ts-ignore` comment to allow TypeScript compilation.\n\n```ts\nconst getPageId = (page: Page): string => {\n // @ts-ignore\n return page.target()._targetId;\n};\n```\n\n# Changelog\n
\n

Note that these changes are only for Browserless' cloud, Enterprise and self-hosted Enterprise deployments. For information on the open-source container please refer to this link.

\n
\n

Latest

\n\n

v2.95.2

\n\n

v2.95.1

\n\n

v2.95.0

\n\n

v2.94.1

\n\n

v2.94.0

\n\n

v2.93.0

\n\n

v2.92.3

\n\n

v2.92.2

\n\n

v2.92.1

\n\n

v2.92.0

\n\n

v2.91.0

\n\n

v2.90.6

\n\n

v2.90.5

\n\n

v2.90.4

\n\n

v2.90.3

\n\n

v2.90.2

\n\n

v2.90.1

\n\n

v2.90.0

\n\n

v2.89.2

\n\n

v2.89.1

\n\n

v2.89.0

\n\n

v2.88.2

\n\n

v2.88.1

\n\n

v2.87.0

\n\n

v2.86.1

\n\n

v2.86.0

\n\n

v2.85.1

\n\n

v2.85.0

\n\n

v2.84.2

\n\n

v2.84.1

\n\n

v2.84.0

\n\n

v2.83.0

\n\n

v2.82.1

\n\n

v2.82.0

\n\n

v2.81.0

\n\n

v2.80.1

\n\n

v2.80.0

\n\n

v2.79.2

\n\n

v2.79.1

\n\n

v2.79.0

\n\n

v2.78.3

\n\n

v2.78.2

\n\n

v2.78.1

\n\n

v2.78.0

\n\n

v2.77.1

\n\n

v2.77.0

\n\n

v2.76.0

\n\n

v2.75.0

\n\n

v2.74.4

\n\n

v2.74.3

\n\n

v2.74.2

\n\n

v2.74.1

\n\n

v2.74.0

\n\n

v2.73.2

\n\n

v2.73.1

\n\n

v2.73.0

\n\n

v2.72.1

\n\n

v2.72.0

\n\n

v2.71.1

\n\n

v2.71.0

\n\n

v2.70.2

\n\n

v2.70.1

\n\n

v2.70.0

\n\n

v2.69.1

\n\n

v2.69.0

\n\n

v2.68.5

\n\n

v2.68.4

\n\n

v2.68.3

\n\n

v2.68.1

\n\n

v2.68.0

\n\n

v2.67.1

\n\n

v2.67.0

\n\n

v2.66.2

\n\n

v2.66.1

\n\n

v2.66.0

\n\n

v2.65.2

\n\n

v2.65.1

\n\n

v2.65.0

\n\n

v2.64.3

\n\n

v2.64.1

\n\n

v2.64.0

\n\n

v2.63.3

\n\n

v2.63.2

\n\n

v2.63.1

\n\n

v2.63.0

\n\n

v2.62.1

\n\n

v2.62.0

\n\n

v2.61.2

\n\n

v2.61.1

\n\n

v2.61.0

\n\n

v2.60.1

\n\n

v2.60.0

\n\n

v2.59.0

\n\n

v2.57.0

\n\n

v2.56.0

\n\n

v2.55.0

\n\n

v2.54.0

\n\n

v2.53.1

\n\n

v2.53.0

\n\n

v2.52.4

\n\n

v2.52.3

\n\n

v2.52.2

\n\n

v2.52.1

\n\n

v2.52.0

\n\n" servers: [] tags: - name: Management REST APIs paths: /active: get: definitions: {} description: 'Returns a simple "204" HTTP code, with no response, indicating that the service itself is up and running. Useful for liveliness probes or other external checks.' parameters: [] requestBody: content: {} responses: '400': code: 400 description: The request contains errors or didn't properly encode content. message: HTTP/1.1 400 Bad Request '401': code: 401 description: The request is missing, or contains bad, authorization credentials. message: HTTP/1.1 401 Unauthorized '404': code: 404 description: Resource couldn't be found. message: HTTP/1.1 404 Not Found '408': code: 408 description: The request took has taken too long to process. message: HTTP/1.1 408 Request Timeout '429': code: 429 description: Too many requests are currently being processed. message: HTTP/1.1 429 Too Many Requests '500': code: 500 description: An internal error occurred when handling the request. message: HTTP/1.1 500 Internal Server Error '503': code: 503 description: Service is unavailable. message: HTTP/1.1 503 Service Unavailable summary: /active tags: - Management REST APIs /kill/+([0-9a-zA-Z-_]): get: definitions: {} description: Kill running sessions based on BrowserId or TrackingId. parameters: - in: query name: blockAds schema: description: 'Whether or nor to load ad-blocking extensions for the session. This currently uses uBlock-Lite and may cause certain sites to not load properly.' type: boolean - in: query name: browserId schema: type: string - in: query name: launch schema: description: 'Launch options, which can be either an object of puppeteer.launch options or playwright.launchServer options, depending on the API. Must be either JSON object, or a base64-encoded JSON object.' anyOf: - $ref: '#/definitions/CDPLaunchOptions' - $ref: '#/definitions/BrowserServerOptions' - type: string - in: query name: profile schema: description: 'Name of an authenticated profile to hydrate into the browser at launch. The profile''s cookies, localStorage and IndexedDB are injected via CDP before your code runs. No-op in builds without a profile subsystem.' type: string - in: query name: timeout schema: description: 'Override the system-level timeout for this request. Accepts a value in milliseconds.' type: number - in: query name: token schema: description: The authorization token type: string - in: query name: trackingId schema: description: Custom session identifier type: string requestBody: content: {} responses: '400': code: 400 description: The request contains errors or didn't properly encode content. message: HTTP/1.1 400 Bad Request '401': code: 401 description: The request is missing, or contains bad, authorization credentials. message: HTTP/1.1 401 Unauthorized '404': code: 404 description: Resource couldn't be found. message: HTTP/1.1 404 Not Found '408': code: 408 description: The request took has taken too long to process. message: HTTP/1.1 408 Request Timeout '429': code: 429 description: Too many requests are currently being processed. message: HTTP/1.1 429 Too Many Requests '500': code: 500 description: An internal error occurred when handling the request. message: HTTP/1.1 500 Internal Server Error '503': code: 503 description: Service is unavailable. message: HTTP/1.1 503 Service Unavailable summary: /kill/+([0-9a-zA-Z-_]) tags: - Management REST APIs /meta: get: definitions: {} description: Returns a JSON payload of the current system versions, including the core API version. parameters: [] requestBody: content: {} responses: '200': content: application/json: schema: type: object properties: version: description: The semantic version of the Browserless API type: string chromium: description: The version of Chromium installed, or null if not installed type: - 'null' - string webkit: description: The version of Webkit installed, or null if not installed type: - 'null' - string firefox: description: The version of Firefox installed, or null if not installed type: - 'null' - string playwright: description: The supported version(s) of puppeteer type: array items: type: string puppeteer: description: The supported version(s) of playwright type: array items: type: string additionalProperties: false required: - chromium - firefox - playwright - puppeteer - version - webkit $schema: http://json-schema.org/draft-07/schema# '400': code: 400 description: The request contains errors or didn't properly encode content. message: HTTP/1.1 400 Bad Request '401': code: 401 description: The request is missing, or contains bad, authorization credentials. message: HTTP/1.1 401 Unauthorized '404': code: 404 description: Resource couldn't be found. message: HTTP/1.1 404 Not Found '408': code: 408 description: The request took has taken too long to process. message: HTTP/1.1 408 Request Timeout '429': code: 429 description: Too many requests are currently being processed. message: HTTP/1.1 429 Too Many Requests '500': code: 500 description: An internal error occurred when handling the request. message: HTTP/1.1 500 Internal Server Error '503': code: 503 description: Service is unavailable. message: HTTP/1.1 503 Service Unavailable summary: /meta tags: - Management REST APIs /browser/*: delete: definitions: {} description: Terminates a browser instance by browserId. The browser must belong to the authenticated user. parameters: [] requestBody: content: {} responses: '400': code: 400 description: The request contains errors or didn't properly encode content. message: HTTP/1.1 400 Bad Request '401': code: 401 description: The request is missing, or contains bad, authorization credentials. message: HTTP/1.1 401 Unauthorized '404': code: 404 description: Resource couldn't be found. message: HTTP/1.1 404 Not Found '408': code: 408 description: The request took has taken too long to process. message: HTTP/1.1 408 Request Timeout '429': code: 429 description: Too many requests are currently being processed. message: HTTP/1.1 429 Too Many Requests '500': code: 500 description: An internal error occurred when handling the request. message: HTTP/1.1 500 Internal Server Error '503': code: 503 description: Service is unavailable. message: HTTP/1.1 503 Service Unavailable summary: /browser/* tags: - Management REST APIs /proxy/cities: get: definitions: {} description: 'Returns a list of available cities for proxy connections. This endpoint requires city proxying to be enabled on your plan. Query Parameters: - country (optional): Filter cities by two-letter country code (e.g., ''US'', ''GB'', ''DE'') The response includes a list of available cities grouped by country code.' parameters: - in: query name: blockAds schema: description: 'Whether or nor to load ad-blocking extensions for the session. This currently uses uBlock-Lite and may cause certain sites to not load properly.' type: boolean - in: query name: country schema: description: Optional two-letter country code to filter cities by country (e.g., 'US', 'GB', 'DE'). type: string - in: query name: launch schema: description: 'Launch options, which can be either an object of puppeteer.launch options or playwright.launchServer options, depending on the API. Must be either JSON object, or a base64-encoded JSON object.' anyOf: - $ref: '#/definitions/CDPLaunchOptions' - $ref: '#/definitions/BrowserServerOptions' - type: string - in: query name: profile schema: description: 'Name of an authenticated profile to hydrate into the browser at launch. The profile''s cookies, localStorage and IndexedDB are injected via CDP before your code runs. No-op in builds without a profile subsystem.' type: string - in: query name: timeout schema: description: 'Override the system-level timeout for this request. Accepts a value in milliseconds.' type: number - in: query name: token schema: description: The authorization token type: string - in: query name: trackingId schema: description: Custom session identifier type: string requestBody: content: {} responses: '200': content: application/json: schema: type: object properties: countries: description: Countries with their available cities type: array items: type: object properties: code: description: Two-letter country code type: string cities: description: List of city names in this country type: array items: type: string additionalProperties: false required: - cities - code totalCountries: description: Total number of countries type: number totalCities: description: Total number of cities across all countries type: number filters: description: Applied filters type: object properties: country: type: string additionalProperties: false additionalProperties: false required: - countries - filters - totalCities - totalCountries $schema: http://json-schema.org/draft-07/schema# '400': code: 400 description: The request contains errors or didn't properly encode content. message: HTTP/1.1 400 Bad Request '401': code: 401 description: The request is missing, or contains bad, authorization credentials. message: HTTP/1.1 401 Unauthorized '404': code: 404 description: Resource couldn't be found. message: HTTP/1.1 404 Not Found '408': code: 408 description: The request took has taken too long to process. message: HTTP/1.1 408 Request Timeout '429': code: 429 description: Too many requests are currently being processed. message: HTTP/1.1 429 Too Many Requests '500': code: 500 description: An internal error occurred when handling the request. message: HTTP/1.1 500 Internal Server Error '503': code: 503 description: Service is unavailable. message: HTTP/1.1 503 Service Unavailable summary: /proxy/cities tags: - Management REST APIs /session: post: definitions: {} description: 'Creates a new browser session with the specified parameters. The session can be used for persistent browser connections with well-defined lifetimes and reconnection semantics. BrowserQL support is only available for stealth sessions.' parameters: [] requestBody: content: application/json: schema: properties: ttl: description: 'The time-to-live (TTL) for the session in milliseconds. Once reached, will be forcefully terminated and all files and processes will be cleaned up. Must be a non-negative number greater than 0.' type: number processKeepAlive: description: 'An optional time, in milliseconds, to keep the underlying browser process alive after a connection to the session closes. If a connection happens within the keep-alive window, the browser process will remain running and the session can be reconnected to. If a connection happens after the keep-alive window has expired, a new browser process will be launched for the session, with the prior session data. Defaults to 0 (no keep-alive).' type: number stealth: description: Whether or not to enable advanced stealth mode. Defaults to false. type: boolean blockAds: description: Whether or not to enable ad-blocking. Defaults to false. type: boolean headless: description: 'Whether the browser should be launched in headless mode. Ignored if `stealth` is true, defaults to "true".' type: boolean args: description: 'An array of command-line arguments to pass to the browser. Defaults to an empty array.' type: array items: type: string browser: description: 'The type of browser to use for the session. ''stealth'' uses the Brave browser with advanced anti-detection. Defaults to ''chromium''.' enum: - chrome - chromium - stealth type: string url: description: 'The underlying page URL you''re attempting to automate. Some pages may required special handling in order to work correctly or unblock. This is not required, but can be useful or required for certain sites.' type: string proxy: description: 'Proxy Parameters for the session if desired. If not specified, the session will use the default network settings.' type: object properties: type: description: The type of proxy to use, currently only 'residential' is supported. type: string const: residential sticky: description: Whether or not to use the same IP address for all proxied requests. Defaults to true type: boolean country: description: The country to proxy through. Defaults to 'us' or United States type: string city: description: The city to proxy through. type: string state: description: The state to proxy through. type: string preset: description: Preset code for website-specific proxy configurations (e.g., 'px_gov01' for government sites) type: string additionalProperties: false replay: description: 'Whether to enable session recording for replay. When true, the session will be recorded and can be replayed later.' type: boolean extensions: description: 'An array of extension IDs to load into the browser session. Extensions must be previously uploaded to the browserless extension storage. This allows sessions to start with extensions pre-loaded without specifying them in launch arguments at connection time.' type: array items: type: string profile: description: 'Optional name of an authentication profile to use as initial browser state. The profile''s cookies, localStorage, and IndexedDB entries are injected via CDP before your code runs. sessionStorage is intentionally not restored — it is tab-scoped and stale values break OAuth/CSRF flows. Changes during the session do not affect the source profile.' type: string type: object required: - ttl responses: '200': content: application/json: schema: type: object properties: id: description: The ID of the session type: string connect: description: The fully-qualified URL to connect CDP-based libraries to the session type: string ttl: description: The total time of life in milliseconds type: number stop: description: The fully qualified URL to stop and remove the session with a DELETE method. type: string browserQL: description: The fully-qualified URL to run BrowserQL queries against the session type: string cloudEndpointId: description: 'The encrypted cloud endpoint ID for the session when ran in the browserless cloud. This is a cloud-specific property and is only present when using browserless cloud.' type: string additionalProperties: false required: - browserQL - cloudEndpointId - connect - id - stop - ttl $schema: http://json-schema.org/draft-07/schema# '400': code: 400 description: The request contains errors or didn't properly encode content. message: HTTP/1.1 400 Bad Request '401': code: 401 description: The request is missing, or contains bad, authorization credentials. message: HTTP/1.1 401 Unauthorized '404': code: 404 description: Resource couldn't be found. message: HTTP/1.1 404 Not Found '408': code: 408 description: The request took has taken too long to process. message: HTTP/1.1 408 Request Timeout '429': code: 429 description: Too many requests are currently being processed. message: HTTP/1.1 429 Too Many Requests '500': code: 500 description: An internal error occurred when handling the request. message: HTTP/1.1 500 Internal Server Error '503': code: 503 description: Service is unavailable. message: HTTP/1.1 503 Service Unavailable summary: /session tags: - Management REST APIs /session/*: delete: definitions: {} description: 'Deletes a session and its associated data. This will immediately terminate any active connections to the session if "force" is applied. Query Parameters: - force (optional): If true, forces deletion even if the session has active connections' parameters: - in: query name: blockAds schema: description: 'Whether or nor to load ad-blocking extensions for the session. This currently uses uBlock-Lite and may cause certain sites to not load properly.' type: boolean - in: query name: force schema: description: 'Whether to force the deletion of the session even if it has active connections. Defaults to false.' type: boolean - in: query name: launch schema: description: 'Launch options, which can be either an object of puppeteer.launch options or playwright.launchServer options, depending on the API. Must be either JSON object, or a base64-encoded JSON object.' anyOf: - $ref: '#/definitions/CDPLaunchOptions' - $ref: '#/definitions/BrowserServerOptions' - type: string - in: query name: profile schema: description: 'Name of an authenticated profile to hydrate into the browser at launch. The profile''s cookies, localStorage and IndexedDB are injected via CDP before your code runs. No-op in builds without a profile subsystem.' type: string - in: query name: timeout schema: description: 'Override the system-level timeout for this request. Accepts a value in milliseconds.' type: number - in: query name: token schema: description: The authorization token type: string - in: query name: trackingId schema: description: Custom session identifier type: string requestBody: content: {} responses: '400': code: 400 description: The request contains errors or didn't properly encode content. message: HTTP/1.1 400 Bad Request '401': code: 401 description: The request is missing, or contains bad, authorization credentials. message: HTTP/1.1 401 Unauthorized '404': code: 404 description: Resource couldn't be found. message: HTTP/1.1 404 Not Found '408': code: 408 description: The request took has taken too long to process. message: HTTP/1.1 408 Request Timeout '429': code: 429 description: Too many requests are currently being processed. message: HTTP/1.1 429 Too Many Requests '500': code: 500 description: An internal error occurred when handling the request. message: HTTP/1.1 500 Internal Server Error '503': code: 503 description: Service is unavailable. message: HTTP/1.1 503 Service Unavailable summary: /session/* tags: - Management REST APIs /session/bql/*: post: definitions: {} description: '> Executes BrowserQL queries against an existing session. The session must be a stealth session to support BrowserQL. BrowserQL is a GraphQL-based query language for browser automation that allows you to interact with web pages using a declarative syntax. Queries execute within the context of your existing session, maintaining browser state and session data across multiple operations.' parameters: - in: query name: blockAds schema: description: 'Whether or nor to load ad-blocking extensions for the session. This currently uses uBlock-Lite and may cause certain sites to not load properly.' type: boolean - in: query name: launch schema: description: 'Launch options for the browser, either as a JSON object or a JSON string. Includes options like `headless`, `args`, `defaultViewport`, etc. Must be either JSON object, or a base64-encoded JSON object.' anyOf: - $ref: '#/definitions/CDPLaunchOptions' - type: string - in: query name: profile schema: description: 'Name of an authenticated profile to hydrate into the browser at launch. The profile''s cookies, localStorage and IndexedDB are injected via CDP before your code runs. No-op in builds without a profile subsystem.' type: string - in: query name: replay schema: type: boolean - in: query name: timeout schema: description: 'Override the system-level timeout for this request. Accepts a value in milliseconds.' type: number - in: query name: token schema: description: The authorization token type: string - in: query name: trackingId schema: description: Custom session identifier type: string requestBody: content: application/json: schema: properties: query: description: 'The GraphQL query string to execute against the browser session. Example queries: - Get browser info: `query { version browser }` - Navigate and get content: `mutation { goto(url: "https://example.com") { status } title { title } url { url } }` - Fill form and submit: `mutation { goto(url: "https://example.com") { status } type(selector: "input[name=''email'']", text: "user@example.com") { time } click(selector: "button[type=''submit'']") { time } }` - Extract data: `mutation { querySelector(selector: "h1") { innerHTML } querySelectorAll(selector: ".product") { innerHTML className } }`' type: string variables: description: 'Variables to pass to the GraphQL query. Useful for dynamic values. Example: `{ "url": "https://example.com", "selector": "h1", "text": "Hello World" }`' type: object additionalProperties: {} operationName: description: 'The name of the operation to execute if the query contains multiple operations. Optional - only needed when query has multiple named operations.' type: string type: object required: - query responses: '200': content: application/json: schema: type: object properties: data: $ref: '#/definitions/Record%3Cstring%2Cany%3E' description: 'The GraphQL response data. Contains the result of the executed query. Structure depends on the specific query executed. Example responses: - Navigation + Title + Element: `{ "goto": { "status": 200 }, "title": { "title": "Example Domain" }, "querySelector": { "innerHTML": "Example Domain" } }` - Multiple elements: `{ "querySelectorAll": [{ "innerHTML": "Item 1" }, { "innerHTML": "Item 2" }] }` - Screenshot: `{ "screenshot": { "data": "base64encodedimage", "type": "png" } }` - PDF: `{ "pdf": { "data": "base64encodedpdf" } }` - System info: `{ "version": "1.0.0", "browser": "Chrome/120.0.0.0" }` - Form interaction: `{ "type": { "success": true }, "click": { "success": true } }`' errors: description: 'Array of GraphQL errors, if any occurred during query execution. Only present when errors exist.' type: array items: type: object properties: message: description: Error message describing what went wrong type: string locations: description: Locations in the query where the error occurred type: array items: type: object properties: line: type: number column: type: number additionalProperties: false required: - column - line path: description: Path to the field that caused the error type: array items: type: - string - number additionalProperties: false required: - message additionalProperties: false definitions: Record: type: object additionalProperties: false $schema: http://json-schema.org/draft-07/schema# '400': code: 400 description: The request contains errors or didn't properly encode content. message: HTTP/1.1 400 Bad Request '401': code: 401 description: The request is missing, or contains bad, authorization credentials. message: HTTP/1.1 401 Unauthorized '404': code: 404 description: Resource couldn't be found. message: HTTP/1.1 404 Not Found '408': code: 408 description: The request took has taken too long to process. message: HTTP/1.1 408 Request Timeout '429': code: 429 description: Too many requests are currently being processed. message: HTTP/1.1 429 Too Many Requests '500': code: 500 description: An internal error occurred when handling the request. message: HTTP/1.1 500 Internal Server Error '503': code: 503 description: Service is unavailable. message: HTTP/1.1 503 Service Unavailable summary: /session/bql/* tags: - Management REST APIs /profile: post: definitions: {} description: 'Launches a temporary browser session for creating an authenticated profile. Connect via the returned WebSocket URL, authenticate in the browser, then call Browserless.saveProfile via CDP to capture and persist the auth state. The profile is NOT saved automatically — you must explicitly call Browserless.saveProfile before disconnecting. The session expires after 10 minutes.' parameters: [] requestBody: content: application/json: schema: properties: name: description: 'A user-visible name for the profile. Must be unique per token.' type: string stealth: description: Whether or not to enable advanced stealth mode. Defaults to false. type: boolean browser: description: The type of browser to use. Defaults to 'stealth'. enum: - chrome - chromium - stealth type: string args: description: An array of command-line arguments to pass to the browser. type: array items: type: string proxy: description: Proxy parameters for the profile creation session. type: object properties: type: description: The type of proxy to use, currently only 'residential' is supported. type: string const: residential sticky: description: Whether or not to use the same IP address for all proxied requests. Defaults to true. type: boolean country: description: The country to proxy through. Defaults to 'us' or United States. type: string city: description: The city to proxy through. type: string state: description: The state to proxy through. type: string preset: description: Preset code for website-specific proxy configurations (e.g., 'px_gov01' for government sites). type: string additionalProperties: false type: object required: - name responses: '200': content: application/json: schema: type: object properties: id: description: Temporary session ID used for the profile creation browser type: string name: description: The profile name that will be used when saving type: string connect: description: WebSocket URL to connect to the browser type: string stop: description: URL to stop/delete the temporary session type: string additionalProperties: false required: - connect - id - name - stop $schema: http://json-schema.org/draft-07/schema# '400': code: 400 description: The request contains errors or didn't properly encode content. message: HTTP/1.1 400 Bad Request '401': code: 401 description: The request is missing, or contains bad, authorization credentials. message: HTTP/1.1 401 Unauthorized '404': code: 404 description: Resource couldn't be found. message: HTTP/1.1 404 Not Found '408': code: 408 description: The request took has taken too long to process. message: HTTP/1.1 408 Request Timeout '429': code: 429 description: Too many requests are currently being processed. message: HTTP/1.1 429 Too Many Requests '500': code: 500 description: An internal error occurred when handling the request. message: HTTP/1.1 500 Internal Server Error '503': code: 503 description: Service is unavailable. message: HTTP/1.1 503 Service Unavailable summary: /profile tags: - Management REST APIs /profile/*: delete: definitions: {} description: 'Deletes an authentication profile and its captured state. The profile name is the URL-encoded path segment after "/profile/". Returns 404 if no profile with that name exists for this token.' parameters: [] requestBody: content: {} responses: '200': content: application/json: schema: type: object properties: success: description: Always true on success. type: boolean message: description: Human-readable confirmation message. type: string name: description: Name of the profile that was deleted. type: string additionalProperties: false required: - message - name - success $schema: http://json-schema.org/draft-07/schema# '400': code: 400 description: The request contains errors or didn't properly encode content. message: HTTP/1.1 400 Bad Request '401': code: 401 description: The request is missing, or contains bad, authorization credentials. message: HTTP/1.1 401 Unauthorized '404': code: 404 description: Resource couldn't be found. message: HTTP/1.1 404 Not Found '408': code: 408 description: The request took has taken too long to process. message: HTTP/1.1 408 Request Timeout '429': code: 429 description: Too many requests are currently being processed. message: HTTP/1.1 429 Too Many Requests '500': code: 500 description: An internal error occurred when handling the request. message: HTTP/1.1 500 Internal Server Error '503': code: 503 description: Service is unavailable. message: HTTP/1.1 503 Service Unavailable summary: /profile/* tags: - Management REST APIs get: definitions: {} description: 'Returns metadata for a specific authentication profile. The profile name is the URL-encoded path segment after "/profile/". Returns 404 if no profile with that name exists for this token.' parameters: [] requestBody: content: {} responses: '200': content: application/json: schema: type: object properties: id: description: Unique profile identifier. type: string name: description: User-supplied profile name. Unique per token. type: string cookieCount: description: Number of cookies captured in the profile. type: number originCount: description: Number of distinct origins with stored localStorage or IndexedDB. type: number lastUsedAt: description: ISO timestamp of the last time this profile was applied to a session, or null if never used. type: string createdAt: description: ISO timestamp of when the profile was created. type: string updatedAt: description: ISO timestamp of the last metadata change (e.g., rename). type: string additionalProperties: false required: - cookieCount - createdAt - id - lastUsedAt - name - originCount - updatedAt $schema: http://json-schema.org/draft-07/schema# '400': code: 400 description: The request contains errors or didn't properly encode content. message: HTTP/1.1 400 Bad Request '401': code: 401 description: The request is missing, or contains bad, authorization credentials. message: HTTP/1.1 401 Unauthorized '404': code: 404 description: Resource couldn't be found. message: HTTP/1.1 404 Not Found '408': code: 408 description: The request took has taken too long to process. message: HTTP/1.1 408 Request Timeout '429': code: 429 description: Too many requests are currently being processed. message: HTTP/1.1 429 Too Many Requests '500': code: 500 description: An internal error occurred when handling the request. message: HTTP/1.1 500 Internal Server Error '503': code: 503 description: Service is unavailable. message: HTTP/1.1 503 Service Unavailable summary: /profile/* tags: - Management REST APIs put: definitions: {} description: 'Renames an authentication profile. The new name must be unique per token. The current name is the URL-encoded path segment after "/profile/". Returns 400 if the new name is already taken, 404 if the source profile is not found.' parameters: [] requestBody: content: application/json: schema: properties: name: description: The new name for the profile. type: string type: object required: - name responses: '200': content: application/json: schema: type: object properties: id: description: Unique profile identifier. type: string name: description: User-supplied profile name. Unique per token. type: string cookieCount: description: Number of cookies captured in the profile. type: number originCount: description: Number of distinct origins with stored localStorage or IndexedDB. type: number lastUsedAt: description: ISO timestamp of the last time this profile was applied to a session, or null if never used. type: string createdAt: description: ISO timestamp of when the profile was created. type: string updatedAt: description: ISO timestamp of the last metadata change (e.g., rename). type: string additionalProperties: false required: - cookieCount - createdAt - id - lastUsedAt - name - originCount - updatedAt $schema: http://json-schema.org/draft-07/schema# '400': code: 400 description: The request contains errors or didn't properly encode content. message: HTTP/1.1 400 Bad Request '401': code: 401 description: The request is missing, or contains bad, authorization credentials. message: HTTP/1.1 401 Unauthorized '404': code: 404 description: Resource couldn't be found. message: HTTP/1.1 404 Not Found '408': code: 408 description: The request took has taken too long to process. message: HTTP/1.1 408 Request Timeout '429': code: 429 description: Too many requests are currently being processed. message: HTTP/1.1 429 Too Many Requests '500': code: 500 description: An internal error occurred when handling the request. message: HTTP/1.1 500 Internal Server Error '503': code: 503 description: Service is unavailable. message: HTTP/1.1 503 Service Unavailable summary: /profile/* tags: - Management REST APIs /profiles: get: definitions: {} description: 'Lists authentication profiles owned by the requesting token. Paginated via "limit" (default 100, capped at 1000) and "offset" (default 0). Returns an empty array if the token has no profiles.' parameters: - in: query name: blockAds schema: description: 'Whether or nor to load ad-blocking extensions for the session. This currently uses uBlock-Lite and may cause certain sites to not load properly.' type: boolean - in: query name: launch schema: description: 'Launch options, which can be either an object of puppeteer.launch options or playwright.launchServer options, depending on the API. Must be either JSON object, or a base64-encoded JSON object.' anyOf: - $ref: '#/definitions/CDPLaunchOptions' - $ref: '#/definitions/BrowserServerOptions' - type: string - in: query name: limit schema: description: Maximum number of profiles to return (1–1000). Defaults to 100. type: number - in: query name: offset schema: description: Number of profiles to skip for pagination. Defaults to 0. type: number - in: query name: profile schema: description: 'Name of an authenticated profile to hydrate into the browser at launch. The profile''s cookies, localStorage and IndexedDB are injected via CDP before your code runs. No-op in builds without a profile subsystem.' type: string - in: query name: timeout schema: description: 'Override the system-level timeout for this request. Accepts a value in milliseconds.' type: number - in: query name: token schema: description: The authorization token type: string - in: query name: trackingId schema: description: Custom session identifier type: string requestBody: content: {} responses: '400': code: 400 description: The request contains errors or didn't properly encode content. message: HTTP/1.1 400 Bad Request '401': code: 401 description: The request is missing, or contains bad, authorization credentials. message: HTTP/1.1 401 Unauthorized '404': code: 404 description: Resource couldn't be found. message: HTTP/1.1 404 Not Found '408': code: 408 description: The request took has taken too long to process. message: HTTP/1.1 408 Request Timeout '429': code: 429 description: Too many requests are currently being processed. message: HTTP/1.1 429 Too Many Requests '500': code: 500 description: An internal error occurred when handling the request. message: HTTP/1.1 500 Internal Server Error '503': code: 503 description: Service is unavailable. message: HTTP/1.1 503 Service Unavailable summary: /profiles tags: - Management REST APIs /profile/refresh: post: definitions: {} description: 'Replaces the state of an existing authentication profile in place. The "name" must already exist for the requesting token. Counts of any dropped or truncated entries are surfaced under "diagnostics".' parameters: [] requestBody: content: application/json: schema: properties: name: description: 'Name of the existing profile to refresh. Must already exist for the requesting token.' type: string state: description: Pre-captured authentication state. Same shape as `POST /profile/upload`. type: object required: - name - state responses: '200': content: application/json: schema: type: object properties: diagnostics: $ref: '#/definitions/RefreshResponseDiagnostics' description: 'Per-entry counts of cookies, origins, and IndexedDB items the server dropped or truncated before persisting. All zero on a clean refresh.' id: description: Unique profile identifier. type: string name: description: User-supplied profile name. Unique per token. type: string cookieCount: description: Number of cookies captured in the profile. type: number originCount: description: Number of distinct origins with stored localStorage or IndexedDB. type: number lastUsedAt: description: ISO timestamp of the last time this profile was applied to a session, or null if never used. type: string createdAt: description: ISO timestamp of when the profile was created. type: string updatedAt: description: ISO timestamp of the last metadata change (e.g., rename). type: string additionalProperties: false required: - cookieCount - createdAt - diagnostics - id - lastUsedAt - name - originCount - updatedAt definitions: RefreshResponseDiagnostics: description: 'Per-entry counts of cookies, origins, and IndexedDB items the server dropped or truncated before persisting. All zero on a clean refresh.' type: object properties: skippedMalformedCookies: description: Cookies dropped because required fields were missing or wrong type. type: number skippedPrivateCookies: description: Cookies dropped because their domain pointed at a private/internal host. type: number skippedMalformedOrigins: description: Origins dropped because they were malformed or non-http(s). type: number skippedPrivateOrigins: description: Origins dropped because they targeted a private/internal network. type: number truncatedOrigins: description: Origins dropped because the per-profile cap was exceeded. type: number skippedMalformedIdbDatabases: description: IndexedDB databases dropped because required fields were missing. type: number truncatedIdbDatabases: description: IndexedDB databases dropped because the per-origin cap was exceeded. type: number skippedMalformedIdbStores: description: IndexedDB object-stores dropped because required fields were missing. type: number truncatedIdbEntries: description: IndexedDB entries dropped because the per-store cap was exceeded. type: number additionalProperties: false required: - skippedMalformedCookies - skippedMalformedIdbDatabases - skippedMalformedIdbStores - skippedMalformedOrigins - skippedPrivateCookies - skippedPrivateOrigins - truncatedIdbDatabases - truncatedIdbEntries - truncatedOrigins $schema: http://json-schema.org/draft-07/schema# '400': code: 400 description: The request contains errors or didn't properly encode content. message: HTTP/1.1 400 Bad Request '401': code: 401 description: The request is missing, or contains bad, authorization credentials. message: HTTP/1.1 401 Unauthorized '404': code: 404 description: Resource couldn't be found. message: HTTP/1.1 404 Not Found '408': code: 408 description: The request took has taken too long to process. message: HTTP/1.1 408 Request Timeout '429': code: 429 description: Too many requests are currently being processed. message: HTTP/1.1 429 Too Many Requests '500': code: 500 description: An internal error occurred when handling the request. message: HTTP/1.1 500 Internal Server Error '503': code: 503 description: Service is unavailable. message: HTTP/1.1 503 Service Unavailable summary: /profile/refresh tags: - Management REST APIs /profile/upload: post: definitions: {} description: 'Creates a new authentication profile from a pre-captured "state" payload (cookies plus per-origin localStorage and IndexedDB). The "name" must be unique per token. Counts of any dropped or truncated entries are surfaced under "diagnostics".' parameters: [] requestBody: content: application/json: schema: properties: name: description: A user-visible name for the profile. Must be unique per token. type: string state: description: 'Pre-captured authentication state. An object with two arrays — `cookies` (browser cookies) and `origins` (per-origin localStorage and IndexedDB).' type: object required: - name - state responses: '200': content: application/json: schema: type: object properties: diagnostics: $ref: '#/definitions/UploadResponseDiagnostics' description: 'Per-entry counts of cookies, origins, and IndexedDB items the server dropped or truncated before persisting. All zero on a clean upload.' id: description: Unique profile identifier. type: string name: description: User-supplied profile name. Unique per token. type: string cookieCount: description: Number of cookies captured in the profile. type: number originCount: description: Number of distinct origins with stored localStorage or IndexedDB. type: number lastUsedAt: description: ISO timestamp of the last time this profile was applied to a session, or null if never used. type: string createdAt: description: ISO timestamp of when the profile was created. type: string updatedAt: description: ISO timestamp of the last metadata change (e.g., rename). type: string additionalProperties: false required: - cookieCount - createdAt - diagnostics - id - lastUsedAt - name - originCount - updatedAt definitions: UploadResponseDiagnostics: description: 'Per-entry counts of cookies, origins, and IndexedDB items the server dropped or truncated before persisting. All zero on a clean upload.' type: object properties: skippedMalformedCookies: description: Cookies dropped because required fields were missing or wrong type. type: number skippedPrivateCookies: description: Cookies dropped because their domain pointed at a private/internal host. type: number skippedMalformedOrigins: description: Origins dropped because they were malformed or non-http(s). type: number skippedPrivateOrigins: description: Origins dropped because they targeted a private/internal network. type: number truncatedOrigins: description: Origins dropped because the per-profile cap was exceeded. type: number skippedMalformedIdbDatabases: description: IndexedDB databases dropped because required fields were missing. type: number truncatedIdbDatabases: description: IndexedDB databases dropped because the per-origin cap was exceeded. type: number skippedMalformedIdbStores: description: IndexedDB object-stores dropped because required fields were missing. type: number truncatedIdbEntries: description: IndexedDB entries dropped because the per-store cap was exceeded. type: number additionalProperties: false required: - skippedMalformedCookies - skippedMalformedIdbDatabases - skippedMalformedIdbStores - skippedMalformedOrigins - skippedPrivateCookies - skippedPrivateOrigins - truncatedIdbDatabases - truncatedIdbEntries - truncatedOrigins $schema: http://json-schema.org/draft-07/schema# '400': code: 400 description: The request contains errors or didn't properly encode content. message: HTTP/1.1 400 Bad Request '401': code: 401 description: The request is missing, or contains bad, authorization credentials. message: HTTP/1.1 401 Unauthorized '404': code: 404 description: Resource couldn't be found. message: HTTP/1.1 404 Not Found '408': code: 408 description: The request took has taken too long to process. message: HTTP/1.1 408 Request Timeout '429': code: 429 description: Too many requests are currently being processed. message: HTTP/1.1 429 Too Many Requests '500': code: 500 description: An internal error occurred when handling the request. message: HTTP/1.1 500 Internal Server Error '503': code: 503 description: Service is unavailable. message: HTTP/1.1 503 Service Unavailable summary: /profile/upload tags: - Management REST APIs definitions: CDPLaunchOptions: type: object properties: args: type: array items: type: string defaultViewport: type: object properties: deviceScaleFactor: type: number hasTouch: type: boolean height: type: number isLandscape: type: boolean isMobile: type: boolean width: type: number additionalProperties: false required: - height - width devtools: type: boolean dumpio: type: boolean headless: enum: - false - shell - true ignoreDefaultArgs: anyOf: - type: array items: type: string - type: boolean ignoreHTTPSErrors: type: boolean acceptInsecureCerts: type: boolean slowMo: type: number stealth: type: boolean timeout: type: number userDataDir: type: string waitForInitialPage: type: boolean additionalProperties: false UploadResponseDiagnostics: description: 'Per-entry counts of cookies, origins, and IndexedDB items the server dropped or truncated before persisting. All zero on a clean upload.' type: object properties: skippedMalformedCookies: description: Cookies dropped because required fields were missing or wrong type. type: number skippedPrivateCookies: description: Cookies dropped because their domain pointed at a private/internal host. type: number skippedMalformedOrigins: description: Origins dropped because they were malformed or non-http(s). type: number skippedPrivateOrigins: description: Origins dropped because they targeted a private/internal network. type: number truncatedOrigins: description: Origins dropped because the per-profile cap was exceeded. type: number skippedMalformedIdbDatabases: description: IndexedDB databases dropped because required fields were missing. type: number truncatedIdbDatabases: description: IndexedDB databases dropped because the per-origin cap was exceeded. type: number skippedMalformedIdbStores: description: IndexedDB object-stores dropped because required fields were missing. type: number truncatedIdbEntries: description: IndexedDB entries dropped because the per-store cap was exceeded. type: number additionalProperties: false required: - skippedMalformedCookies - skippedMalformedIdbDatabases - skippedMalformedIdbStores - skippedMalformedOrigins - skippedPrivateCookies - skippedPrivateOrigins - truncatedIdbDatabases - truncatedIdbEntries - truncatedOrigins RefreshResponseDiagnostics: description: 'Per-entry counts of cookies, origins, and IndexedDB items the server dropped or truncated before persisting. All zero on a clean refresh.' type: object properties: skippedMalformedCookies: description: Cookies dropped because required fields were missing or wrong type. type: number skippedPrivateCookies: description: Cookies dropped because their domain pointed at a private/internal host. type: number skippedMalformedOrigins: description: Origins dropped because they were malformed or non-http(s). type: number skippedPrivateOrigins: description: Origins dropped because they targeted a private/internal network. type: number truncatedOrigins: description: Origins dropped because the per-profile cap was exceeded. type: number skippedMalformedIdbDatabases: description: IndexedDB databases dropped because required fields were missing. type: number truncatedIdbDatabases: description: IndexedDB databases dropped because the per-origin cap was exceeded. type: number skippedMalformedIdbStores: description: IndexedDB object-stores dropped because required fields were missing. type: number truncatedIdbEntries: description: IndexedDB entries dropped because the per-store cap was exceeded. type: number additionalProperties: false required: - skippedMalformedCookies - skippedMalformedIdbDatabases - skippedMalformedIdbStores - skippedMalformedOrigins - skippedPrivateCookies - skippedPrivateOrigins - truncatedIdbDatabases - truncatedIdbEntries - truncatedOrigins BrowserServerOptions: type: object properties: args: type: array items: type: string chromiumSandbox: type: boolean devtools: type: boolean downloadsPath: type: string headless: type: boolean ignoreDefaultArgs: anyOf: - type: array items: type: string - type: boolean proxy: type: object properties: bypass: type: string password: type: string server: type: string username: type: string additionalProperties: false required: - server timeout: type: number tracesDir: type: string additionalProperties: false