openapi: 3.0.0 info: title: Browserless Browser 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: Browser REST APIs paths: /chrome/content: post: definitions: {} description: A JSON-based API. Given a "url" or "html" field, runs and returns HTML content after the page has loaded and JavaScript has parsed. 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: 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: 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: addScriptTag: type: array items: $ref: '#/definitions/FrameAddScriptTagOptions' addStyleTag: type: array items: $ref: '#/definitions/FrameAddStyleTagOptions' authenticate: anyOf: - $ref: '#/definitions/Credentials' - type: 'null' bestAttempt: description: 'When bestAttempt is set to true, browserless attempt to proceed when "awaited" events fail or timeout. This includes things like goto, waitForSelector, and more.' type: boolean cookies: type: array items: $ref: '#/definitions/CookieParam' emulateMediaType: type: string gotoOptions: $ref: '#/definitions/GoToOptions' html: type: string rejectRequestPattern: type: array items: type: string rejectResourceTypes: type: array items: enum: - cspviolationreport - document - eventsource - fedcm - fetch - font - image - manifest - media - other - ping - prefetch - preflight - script - signedexchange - stylesheet - texttrack - websocket - xhr type: string requestInterceptors: type: array items: description: 'An array of patterns (using `req.url().match(r.pattern)` to match) and their corresponding responses to use in order to fulfill those requests.' type: object properties: pattern: description: 'An array of patterns (using `req.url().match(r.pattern)` to match) and their corresponding responses to use in order to fulfill those requests.' type: string response: additionalProperties: false type: object properties: headers: description: 'Optional response headers. The record values will be converted to string following: Arrays'' values will be mapped to String (Used when you need multiple headers with the same name). Non-arrays will be converted to String.' $ref: '#/definitions/Record%3Cstring%2Cunknown%3E' status: type: number contentType: type: string body: description: 'A string representation of the body to return. Can be a base64-encoded string but please omit any leading content-type data (eg "data:image/png;base64,").' type: string additionalProperties: false required: - pattern - response setExtraHTTPHeaders: type: object additionalProperties: type: string setJavaScriptEnabled: description: Whether or not to allow JavaScript to run on the page. type: boolean url: type: string userAgent: type: object properties: userAgent: type: string userAgentMetadata: description: 'Used to specify User Agent Client Hints to emulate. See https://wicg.github.io/ua-client-hints Missing optional values will be filled in by the target with what it would normally use.' $ref: '#/definitions/Protocol.Emulation.UserAgentMetadata' platform: type: string additionalProperties: false viewport: anyOf: - $ref: '#/definitions/Viewport' - type: 'null' waitForEvent: type: object properties: event: type: string timeout: type: number additionalProperties: false required: - event waitForFunction: type: object properties: fn: description: The function, or statement, to be evaluated in browser context type: string polling: description: 'An interval at which the pageFunction is executed, defaults to raf. If polling is a number, then it is treated as an interval in milliseconds at which the function would be executed. If polling is a string, then it can be one of the following values: "raf" or "mutation"' type: - string - number timeout: description: 'Maximum time to wait for in milliseconds. Defaults to 30000 (30 seconds). Pass 0 to disable timeout.' type: number additionalProperties: false required: - fn waitForSelector: type: object properties: hidden: type: boolean selector: type: string timeout: type: number visible: type: boolean additionalProperties: false required: - selector waitForTimeout: type: number type: object responses: '200': content: text/html: schema: description: 'An HTML payload of the website or HTML after JavaScript parsing and execution.' type: string $schema: http://json-schema.org/draft-07/schema# description: 'An HTML payload of the website or HTML after JavaScript parsing and execution.' '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: /chrome/content tags: - Browser REST APIs /chrome/download: post: definitions: {} description: 'A JSON or JavaScript content-type API for returning files Chrome has downloaded during the execution of puppeteer code, which is ran inside context of the browser. Browserless sets up a blank page, a fresh download directory, injects your puppeteer code, and then executes it. You can load external libraries via the "import" syntax, and import ESM-style modules that are written for execution inside of the browser. Once your script is finished, any downloaded files from Chromium are returned back with the appropriate content-type header.' 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' - 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: application/json: schema: $ref: '#/definitions/JSONSchema' application/javascript: schema: type: string responses: '200': content: '*/*': schema: description: 'Responses are determined by the returned value of the downloads themselves, so there isn''t a static response type for this API.' $schema: http://json-schema.org/draft-07/schema# description: 'Responses are determined by the returned value of the downloads themselves, so there isn''t a static response type for this API.' '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: /chrome/download tags: - Browser REST APIs /chrome/function: post: definitions: {} description: 'A JSON or JavaScript content-type API for running puppeteer code in the browser''s context. Browserless sets up a blank page, injects your puppeteer code, and runs it. You can optionally load external libraries via the "import" module that are meant for browser usage. Values returned from the function are checked and an appropriate content-type and response is sent back to your HTTP call.' 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' - 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: application/json: schema: $ref: '#/definitions/JSONSchema' application/javascript: schema: type: string responses: '200': content: '*/*': schema: description: 'Responses are determined by the returned value of the function itself. Binary responses (PDF''s, screenshots) are returned back as binary data, and primitive JavaScript values are returned back by type (HTML data is "text/html", Objects are "application/json")' $schema: http://json-schema.org/draft-07/schema# description: 'Responses are determined by the returned value of the function itself. Binary responses (PDF''s, screenshots) are returned back as binary data, and primitive JavaScript values are returned back by type (HTML data is "text/html", Objects are "application/json")' '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: /chrome/function tags: - Browser REST APIs /json/new: put: definitions: {} description: 'Returns a JSON payload that acts as a pass-through to the DevTools /json/new HTTP API in Chromium. Browserless mocks this payload so that remote clients can connect to the underlying "webSocketDebuggerUrl" which will cause Browserless to start the browser and proxy that request into a blank page.' parameters: [] requestBody: content: {} responses: '200': content: application/json: schema: type: object properties: description: description: The description of the target. Generally the page's title. type: string devtoolsFrontendUrl: description: The fully-qualified URL of the Devtools inspector app. type: string id: description: A Unique Id for the underlying target. type: string title: description: The title of the target. For pages this is the page's title. type: string type: description: The type of target, generally "page" or "background_page". type: string url: description: The current URL the target is consuming or visiting. type: string webSocketDebuggerUrl: description: 'The target or page''s WebSocket Debugger URL. Primarily used for legacy libraries to connect and inspect or remote automate this target.' type: string additionalProperties: false required: - description - devtoolsFrontendUrl - id - title - type - url - webSocketDebuggerUrl $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: /json/new tags: - Browser REST APIs /json/protocol: get: definitions: {} description: Returns Protocol JSON meta-data that Chrome and Chromium come with. parameters: [] requestBody: content: {} responses: '200': content: application/json: schema: type: object properties: {} additionalProperties: true $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: /json/protocol tags: - Browser REST APIs /json/version: get: definitions: {} description: Returns a JSON payload that acts as a pass-through to the DevTools /json/version protocol in Chrome and Chromium. parameters: [] requestBody: content: {} responses: '200': content: application/json: schema: type: object properties: description: description: The description of the target. Generally the page's title. type: string devtoolsFrontendUrl: description: The fully-qualified URL of the Devtools inspector app. type: string id: description: A Unique Id for the underlying target. type: string title: description: The title of the target. For pages this is the page's title. type: string type: description: The type of target, generally "page" or "background_page". type: string url: description: The current URL the target is consuming or visiting. type: string webSocketDebuggerUrl: description: 'The target or page''s WebSocket Debugger URL. Primarily used for legacy libraries to connect and inspect or remote automate this target.' type: string additionalProperties: false required: - description - devtoolsFrontendUrl - id - title - type - url - webSocketDebuggerUrl $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: /json/version tags: - Browser REST APIs /chrome/pdf: post: definitions: {} description: 'A JSON-based API for getting a PDF binary from either a supplied "url" or "html" payload in your request. Many options exist for injecting cookies, request interceptors, user-agents and waiting for selectors, timers and more.' 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' - 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: application/json: schema: properties: addScriptTag: type: array items: $ref: '#/definitions/FrameAddScriptTagOptions' addStyleTag: type: array items: $ref: '#/definitions/FrameAddStyleTagOptions' authenticate: anyOf: - $ref: '#/definitions/Credentials' - type: 'null' bestAttempt: description: 'When bestAttempt is set to true, browserless attempt to proceed when "awaited" events fail or timeout. This includes things like goto, waitForSelector, and more.' type: boolean cookies: type: array items: $ref: '#/definitions/CookieParam' emulateMediaType: type: string gotoOptions: $ref: '#/definitions/GoToOptions' html: type: string options: additionalProperties: false type: object properties: scale: description: Scales the rendering of the web page. Amount must be between `0.1` and `2`. type: number displayHeaderFooter: description: Whether to show the header and footer. type: boolean headerTemplate: description: 'HTML template for the print header. Should be valid HTML with the following classes used to inject values into them: - `date` formatted print date - `title` document title - `url` document location - `pageNumber` current page number - `totalPages` total pages in the document' type: string footerTemplate: description: 'HTML template for the print footer. Has the same constraints and support for special classes as {@link PDFOptions.headerTemplate}.' type: string printBackground: description: Set to `true` to print background graphics. type: boolean landscape: description: Whether to print in landscape orientation. type: boolean pageRanges: description: Paper ranges to print, e.g. `1-5, 8, 11-13`. type: string format: description: All the valid paper format types when printing a PDF. enum: - A0 - A1 - A2 - A3 - A4 - A5 - A6 - LEDGER - LEGAL - LETTER - Ledger - Legal - Letter - TABLOID - Tabloid - a0 - a1 - a2 - a3 - a4 - a5 - a6 - ledger - legal - letter - tabloid type: string width: description: Sets the width of paper. You can pass in a number or a string with a unit. type: - string - number height: description: Sets the height of paper. You can pass in a number or a string with a unit. type: - string - number preferCSSPageSize: description: 'Give any CSS `@page` size declared in the page priority over what is declared in the `width` or `height` or `format` option.' type: boolean margin: description: Set the PDF margins. $ref: '#/definitions/PDFMargin' path: description: The path to save the file to. type: string omitBackground: description: Hides default white background and allows generating pdfs with transparency. type: boolean tagged: description: Generate tagged (accessible) PDF. type: boolean outline: description: Generate document outline. type: boolean timeout: description: 'Timeout in milliseconds. Pass `0` to disable timeout. The default value can be changed by using {@link Page.setDefaultTimeout}' type: number waitForFonts: description: 'If true, waits for `document.fonts.ready` to resolve. This might require activating the page using {@link Page.bringToFront} if the page is in the background.' type: boolean fullPage: type: boolean rejectRequestPattern: type: array items: type: string rejectResourceTypes: type: array items: enum: - cspviolationreport - document - eventsource - fedcm - fetch - font - image - manifest - media - other - ping - prefetch - preflight - script - signedexchange - stylesheet - texttrack - websocket - xhr type: string requestInterceptors: type: array items: description: 'An array of patterns (using `req.url().match(r.pattern)` to match) and their corresponding responses to use in order to fulfill those requests.' type: object properties: pattern: description: 'An array of patterns (using `req.url().match(r.pattern)` to match) and their corresponding responses to use in order to fulfill those requests.' type: string response: additionalProperties: false type: object properties: headers: description: 'Optional response headers. The record values will be converted to string following: Arrays'' values will be mapped to String (Used when you need multiple headers with the same name). Non-arrays will be converted to String.' $ref: '#/definitions/Record%3Cstring%2Cunknown%3E' status: type: number contentType: type: string body: description: 'A string representation of the body to return. Can be a base64-encoded string but please omit any leading content-type data (eg "data:image/png;base64,").' type: string additionalProperties: false required: - pattern - response setExtraHTTPHeaders: type: object additionalProperties: type: string setJavaScriptEnabled: type: boolean url: type: string userAgent: type: object properties: userAgent: type: string userAgentMetadata: description: 'Used to specify User Agent Client Hints to emulate. See https://wicg.github.io/ua-client-hints Missing optional values will be filled in by the target with what it would normally use.' $ref: '#/definitions/Protocol.Emulation.UserAgentMetadata' platform: type: string additionalProperties: false viewport: anyOf: - $ref: '#/definitions/Viewport' - type: 'null' waitForEvent: type: object properties: event: type: string timeout: type: number additionalProperties: false required: - event waitForFunction: type: object properties: fn: description: The function, or statement, to be evaluated in browser context type: string polling: description: 'An interval at which the pageFunction is executed, defaults to raf. If polling is a number, then it is treated as an interval in milliseconds at which the function would be executed. If polling is a string, then it can be one of the following values: "raf" or "mutation"' type: - string - number timeout: description: 'Maximum time to wait for in milliseconds. Defaults to 30000 (30 seconds). Pass 0 to disable timeout.' type: number additionalProperties: false required: - fn waitForSelector: type: object properties: hidden: type: boolean selector: type: string timeout: type: number visible: type: boolean additionalProperties: false required: - selector waitForTimeout: type: number type: object responses: '200': content: application/pdf: schema: description: Responds with an application/pdf content-type and a binary PDF type: string $schema: http://json-schema.org/draft-07/schema# description: Responds with an application/pdf content-type and a binary PDF '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: /chrome/pdf tags: - Browser REST APIs /chrome/performance: post: definitions: {} description: Run lighthouse performance audits with a supplied "url" in your JSON payload. 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' - 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: application/json: schema: properties: budgets: type: array items: type: object properties: {} additionalProperties: true config: type: object properties: {} additionalProperties: true url: type: string type: object required: - url responses: '200': content: application/json: schema: description: 'The response of the lighthouse stats. Response objects are determined by the type of budgets and config in the POST JSON body' type: object properties: {} additionalProperties: true $schema: http://json-schema.org/draft-07/schema# description: 'The response of the lighthouse stats. Response objects are determined by the type of budgets and config in the POST JSON body' '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: /chrome/performance tags: - Browser REST APIs /chrome/scrape: post: definitions: {} description: 'A JSON-based API that returns text, html, and meta-data from a given list of selectors. Debugging information is available by sending in the appropriate flags in the "debugOpts" property. Responds with an array of JSON objects.' 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: 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: 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: addScriptTag: type: array items: $ref: '#/definitions/FrameAddScriptTagOptions' addStyleTag: type: array items: $ref: '#/definitions/FrameAddStyleTagOptions' authenticate: anyOf: - $ref: '#/definitions/Credentials' - type: 'null' bestAttempt: description: 'When bestAttempt is set to true, browserless attempt to proceed when "awaited" events fail or timeout. This includes things like goto, waitForSelector, and more.' type: boolean cookies: type: array items: $ref: '#/definitions/CookieParam' debugOpts: $ref: '#/definitions/ScrapeDebugOptions' elements: type: array items: $ref: '#/definitions/ScrapeElementSelector' emulateMediaType: type: string gotoOptions: $ref: '#/definitions/GoToOptions' html: type: string rejectRequestPattern: type: array items: type: string rejectResourceTypes: type: array items: enum: - cspviolationreport - document - eventsource - fedcm - fetch - font - image - manifest - media - other - ping - prefetch - preflight - script - signedexchange - stylesheet - texttrack - websocket - xhr type: string requestInterceptors: type: array items: description: 'An array of patterns (using `req.url().match(r.pattern)` to match) and their corresponding responses to use in order to fulfill those requests.' type: object properties: pattern: description: 'An array of patterns (using `req.url().match(r.pattern)` to match) and their corresponding responses to use in order to fulfill those requests.' type: string response: additionalProperties: false type: object properties: headers: description: 'Optional response headers. The record values will be converted to string following: Arrays'' values will be mapped to String (Used when you need multiple headers with the same name). Non-arrays will be converted to String.' $ref: '#/definitions/Record%3Cstring%2Cunknown%3E' status: type: number contentType: type: string body: description: 'A string representation of the body to return. Can be a base64-encoded string but please omit any leading content-type data (eg "data:image/png;base64,").' type: string additionalProperties: false required: - pattern - response setExtraHTTPHeaders: type: object additionalProperties: type: string setJavaScriptEnabled: type: boolean url: type: string userAgent: type: object properties: userAgent: type: string userAgentMetadata: description: 'Used to specify User Agent Client Hints to emulate. See https://wicg.github.io/ua-client-hints Missing optional values will be filled in by the target with what it would normally use.' $ref: '#/definitions/Protocol.Emulation.UserAgentMetadata' platform: type: string additionalProperties: false viewport: anyOf: - $ref: '#/definitions/Viewport' - type: 'null' waitForEvent: type: object properties: event: type: string timeout: type: number additionalProperties: false required: - event waitForFunction: type: object properties: fn: description: The function, or statement, to be evaluated in browser context type: string polling: description: 'An interval at which the pageFunction is executed, defaults to raf. If polling is a number, then it is treated as an interval in milliseconds at which the function would be executed. If polling is a string, then it can be one of the following values: "raf" or "mutation"' type: - string - number timeout: description: 'Maximum time to wait for in milliseconds. Defaults to 30000 (30 seconds). Pass 0 to disable timeout.' type: number additionalProperties: false required: - fn waitForSelector: type: object properties: hidden: type: boolean selector: type: string timeout: type: number visible: type: boolean additionalProperties: false required: - selector waitForTimeout: type: number type: object required: - elements responses: '200': content: application/json: schema: description: The JSON response body type: object properties: data: anyOf: - type: array items: type: object properties: results: type: array items: type: object properties: attributes: description: A list of HTML attributes of the element type: array items: type: object properties: name: description: The name of the HTML attribute for the element type: string value: description: The value of the HTML attribute for the element type: string additionalProperties: false required: - name - value height: description: The height the element type: number html: description: The HTML the element type: string left: description: The amount of pixels from the left of the page type: number text: description: The text the element type: string top: description: The amount of pixels from the top of the page type: number width: description: The width the element type: number additionalProperties: false required: - attributes - height - html - left - text - top - width selector: description: The DOM selector of the element type: string additionalProperties: false required: - results - selector - type: 'null' debug: description: When debugOpts options are present, results are here anyOf: - type: object properties: console: description: A list of console messages from the browser type: array items: type: string cookies: description: List of cookies for the site or null anyOf: - type: array items: $ref: '#/definitions/Cookie' - type: 'null' html: description: The HTML string of the website or null type: - 'null' - string network: type: object properties: inbound: type: array items: $ref: '#/definitions/InBoundRequest' outbound: type: array items: $ref: '#/definitions/OutBoundRequest' additionalProperties: false required: - inbound - outbound screenshot: description: A base64-encoded string of the site or null type: - 'null' - string additionalProperties: false required: - console - cookies - html - network - screenshot - type: 'null' additionalProperties: false required: - data - debug definitions: Cookie: description: Represents a cookie object. type: object properties: path: description: Cookie path. type: string expires: description: 'Cookie expiration date as the number of seconds since the UNIX epoch. Set to `-1` for session cookies' type: number size: description: Cookie size. type: number secure: description: True if cookie is secure. type: boolean session: description: True in case of session cookie. type: boolean partitionKeyOpaque: description: True if cookie partition key is opaque. Supported only in Chrome. type: boolean name: description: Cookie name. type: string value: description: Cookie value. type: string domain: description: Cookie domain. type: string httpOnly: description: True if cookie is http-only. type: boolean sameSite: description: Cookie SameSite type. enum: - Default - Lax - None - Strict type: string priority: description: Cookie Priority. Supported only in Chrome. enum: - High - Low - Medium type: string sameParty: type: boolean sourceScheme: description: Cookie source scheme type. Supported only in Chrome. enum: - NonSecure - Secure - Unset type: string partitionKey: description: 'Cookie partition key. In Chrome, it matches the top-level site the partitioned cookie is available in. In Firefox, it matches the source origin in the {@link https://w3c.github.io/webdriver-bidi/#type-storage-PartitionKey PartitionKey}.' anyOf: - $ref: '#/definitions/CookiePartitionKey' - type: string additionalProperties: false required: - domain - expires - name - path - secure - session - size - value CookiePartitionKey: description: Represents a cookie partition key in Chrome. type: object properties: sourceOrigin: description: 'The site of the top-level URL the browser was visiting at the start of the request to the endpoint that set the cookie. In Chrome, maps to the CDP''s `topLevelSite` partition key.' type: string hasCrossSiteAncestor: description: 'Indicates if the cookie has any ancestors that are cross-site to the topLevelSite. Supported only in Chrome.' type: boolean additionalProperties: false required: - sourceOrigin InBoundRequest: type: object properties: headers: {} status: type: number url: type: string additionalProperties: false required: - headers - status - url OutBoundRequest: type: object properties: headers: {} method: type: string url: type: string additionalProperties: false required: - headers - method - url $schema: http://json-schema.org/draft-07/schema# description: The JSON response body '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: /chrome/scrape tags: - Browser REST APIs /chrome/screenshot: post: definitions: {} description: 'A JSON-based API for getting a screenshot binary from either a supplied "url" or "html" payload in your request. Many options exist including cookies, user-agents, setting timers and network mocks.' 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' - 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: application/json: schema: properties: addScriptTag: type: array items: $ref: '#/definitions/FrameAddScriptTagOptions' addStyleTag: type: array items: $ref: '#/definitions/FrameAddStyleTagOptions' authenticate: anyOf: - $ref: '#/definitions/Credentials' - type: 'null' bestAttempt: description: 'When bestAttempt is set to true, browserless attempt to proceed when "awaited" events fail or timeout. This includes things like goto, waitForSelector, and more.' type: boolean cookies: type: array items: $ref: '#/definitions/CookieParam' emulateMediaType: type: string gotoOptions: $ref: '#/definitions/GoToOptions' html: type: string options: $ref: '#/definitions/ScreenshotOptions' rejectRequestPattern: type: array items: type: string rejectResourceTypes: type: array items: enum: - cspviolationreport - document - eventsource - fedcm - fetch - font - image - manifest - media - other - ping - prefetch - preflight - script - signedexchange - stylesheet - texttrack - websocket - xhr type: string requestInterceptors: type: array items: description: 'An array of patterns (using `req.url().match(r.pattern)` to match) and their corresponding responses to use in order to fulfill those requests.' type: object properties: pattern: description: 'An array of patterns (using `req.url().match(r.pattern)` to match) and their corresponding responses to use in order to fulfill those requests.' type: string response: additionalProperties: false type: object properties: headers: description: 'Optional response headers. The record values will be converted to string following: Arrays'' values will be mapped to String (Used when you need multiple headers with the same name). Non-arrays will be converted to String.' $ref: '#/definitions/Record%3Cstring%2Cunknown%3E' status: type: number contentType: type: string body: description: 'A string representation of the body to return. Can be a base64-encoded string but please omit any leading content-type data (eg "data:image/png;base64,").' type: string additionalProperties: false required: - pattern - response scrollPage: type: boolean selector: type: string setExtraHTTPHeaders: type: object additionalProperties: type: string setJavaScriptEnabled: type: boolean url: type: string userAgent: type: object properties: userAgent: type: string userAgentMetadata: description: 'Used to specify User Agent Client Hints to emulate. See https://wicg.github.io/ua-client-hints Missing optional values will be filled in by the target with what it would normally use.' $ref: '#/definitions/Protocol.Emulation.UserAgentMetadata' platform: type: string additionalProperties: false viewport: anyOf: - $ref: '#/definitions/Viewport' - type: 'null' waitForEvent: type: object properties: event: type: string timeout: type: number additionalProperties: false required: - event waitForFunction: type: object properties: fn: description: The function, or statement, to be evaluated in browser context type: string polling: description: 'An interval at which the pageFunction is executed, defaults to raf. If polling is a number, then it is treated as an interval in milliseconds at which the function would be executed. If polling is a string, then it can be one of the following values: "raf" or "mutation"' type: - string - number timeout: description: 'Maximum time to wait for in milliseconds. Defaults to 30000 (30 seconds). Pass 0 to disable timeout.' type: number additionalProperties: false required: - fn waitForSelector: type: object properties: hidden: type: boolean selector: type: string timeout: type: number visible: type: boolean additionalProperties: false required: - selector waitForTimeout: type: number type: object responses: '200': content: image/png: schema: type: text image/jpeg: schema: type: text text/plain: schema: type: text description: 'Response can either be a text/plain base64 encoded body or a binary stream with png/jpeg as a content-type' '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: /chrome/screenshot tags: - Browser REST APIs /chromium/content: post: definitions: {} description: 'A JSON-based API. Given a "url" or "html" field, runs and returns HTML content after the page has loaded and JavaScript has parsed. **Note:** This endpoint is also available at: `/content` for backwards compatibility.' 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: 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: 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: addScriptTag: type: array items: $ref: '#/definitions/FrameAddScriptTagOptions' addStyleTag: type: array items: $ref: '#/definitions/FrameAddStyleTagOptions' authenticate: anyOf: - $ref: '#/definitions/Credentials' - type: 'null' bestAttempt: description: 'When bestAttempt is set to true, browserless attempt to proceed when "awaited" events fail or timeout. This includes things like goto, waitForSelector, and more.' type: boolean cookies: type: array items: $ref: '#/definitions/CookieParam' emulateMediaType: type: string gotoOptions: $ref: '#/definitions/GoToOptions' html: type: string rejectRequestPattern: type: array items: type: string rejectResourceTypes: type: array items: enum: - cspviolationreport - document - eventsource - fedcm - fetch - font - image - manifest - media - other - ping - prefetch - preflight - script - signedexchange - stylesheet - texttrack - websocket - xhr type: string requestInterceptors: type: array items: description: 'An array of patterns (using `req.url().match(r.pattern)` to match) and their corresponding responses to use in order to fulfill those requests.' type: object properties: pattern: description: 'An array of patterns (using `req.url().match(r.pattern)` to match) and their corresponding responses to use in order to fulfill those requests.' type: string response: additionalProperties: false type: object properties: headers: description: 'Optional response headers. The record values will be converted to string following: Arrays'' values will be mapped to String (Used when you need multiple headers with the same name). Non-arrays will be converted to String.' $ref: '#/definitions/Record%3Cstring%2Cunknown%3E' status: type: number contentType: type: string body: description: 'A string representation of the body to return. Can be a base64-encoded string but please omit any leading content-type data (eg "data:image/png;base64,").' type: string additionalProperties: false required: - pattern - response setExtraHTTPHeaders: type: object additionalProperties: type: string setJavaScriptEnabled: description: Whether or not to allow JavaScript to run on the page. type: boolean url: type: string userAgent: type: object properties: userAgent: type: string userAgentMetadata: description: 'Used to specify User Agent Client Hints to emulate. See https://wicg.github.io/ua-client-hints Missing optional values will be filled in by the target with what it would normally use.' $ref: '#/definitions/Protocol.Emulation.UserAgentMetadata' platform: type: string additionalProperties: false viewport: anyOf: - $ref: '#/definitions/Viewport' - type: 'null' waitForEvent: type: object properties: event: type: string timeout: type: number additionalProperties: false required: - event waitForFunction: type: object properties: fn: description: The function, or statement, to be evaluated in browser context type: string polling: description: 'An interval at which the pageFunction is executed, defaults to raf. If polling is a number, then it is treated as an interval in milliseconds at which the function would be executed. If polling is a string, then it can be one of the following values: "raf" or "mutation"' type: - string - number timeout: description: 'Maximum time to wait for in milliseconds. Defaults to 30000 (30 seconds). Pass 0 to disable timeout.' type: number additionalProperties: false required: - fn waitForSelector: type: object properties: hidden: type: boolean selector: type: string timeout: type: number visible: type: boolean additionalProperties: false required: - selector waitForTimeout: type: number type: object responses: '200': content: text/html: schema: description: 'An HTML payload of the website or HTML after JavaScript parsing and execution.' type: string $schema: http://json-schema.org/draft-07/schema# description: 'An HTML payload of the website or HTML after JavaScript parsing and execution.' '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: /chromium/content tags: - Browser REST APIs /chromium/download: post: definitions: {} description: 'A JSON or JavaScript content-type API for returning files Chrome has downloaded during the execution of puppeteer code, which is ran inside context of the browser. Browserless sets up a blank page, a fresh download directory, injects your puppeteer code, and then executes it. You can load external libraries via the "import" syntax, and import ESM-style modules that are written for execution inside of the browser. Once your script is finished, any downloaded files from Chromium are returned back with the appropriate content-type header. **Note:** This endpoint is also available at: `/download` for backwards compatibility.' 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' - 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: application/json: schema: $ref: '#/definitions/JSONSchema' application/javascript: schema: type: string responses: '200': content: '*/*': schema: description: 'Responses are determined by the returned value of the downloads themselves, so there isn''t a static response type for this API.' $schema: http://json-schema.org/draft-07/schema# description: 'Responses are determined by the returned value of the downloads themselves, so there isn''t a static response type for this API.' '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: /chromium/download tags: - Browser REST APIs /chromium/function: post: definitions: {} description: 'A JSON or JavaScript content-type API for running puppeteer code in the browser''s context. Browserless sets up a blank page, injects your puppeteer code, and runs it. You can optionally load external libraries via the "import" module that are meant for browser usage. Values returned from the function are checked and an appropriate content-type and response is sent back to your HTTP call. **Note:** This endpoint is also available at: `/function` for backwards compatibility.' 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' - 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: application/json: schema: $ref: '#/definitions/JSONSchema' application/javascript: schema: type: string responses: '200': content: '*/*': schema: description: 'Responses are determined by the returned value of the function itself. Binary responses (PDF''s, screenshots) are returned back as binary data, and primitive JavaScript values are returned back by type (HTML data is "text/html", Objects are "application/json")' $schema: http://json-schema.org/draft-07/schema# description: 'Responses are determined by the returned value of the function itself. Binary responses (PDF''s, screenshots) are returned back as binary data, and primitive JavaScript values are returned back by type (HTML data is "text/html", Objects are "application/json")' '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: /chromium/function tags: - Browser REST APIs /chromium/performance: post: definitions: {} description: 'Run lighthouse performance audits with a supplied "url" in your JSON payload. **Note:** This endpoint is also available at: `/performance` for backwards compatibility.' 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' - 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: application/json: schema: properties: budgets: type: array items: type: object properties: {} additionalProperties: true config: type: object properties: {} additionalProperties: true url: type: string type: object required: - url responses: '200': content: application/json: schema: description: 'The response of the lighthouse stats. Response objects are determined by the type of budgets and config in the POST JSON body' type: object properties: {} additionalProperties: true $schema: http://json-schema.org/draft-07/schema# description: 'The response of the lighthouse stats. Response objects are determined by the type of budgets and config in the POST JSON body' '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: /chromium/performance tags: - Browser REST APIs /chromium/scrape: post: definitions: {} description: 'A JSON-based API that returns text, html, and meta-data from a given list of selectors. Debugging information is available by sending in the appropriate flags in the "debugOpts" property. Responds with an array of JSON objects. **Note:** This endpoint is also available at: `/scrape` for backwards compatibility.' 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: 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: 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: addScriptTag: type: array items: $ref: '#/definitions/FrameAddScriptTagOptions' addStyleTag: type: array items: $ref: '#/definitions/FrameAddStyleTagOptions' authenticate: anyOf: - $ref: '#/definitions/Credentials' - type: 'null' bestAttempt: description: 'When bestAttempt is set to true, browserless attempt to proceed when "awaited" events fail or timeout. This includes things like goto, waitForSelector, and more.' type: boolean cookies: type: array items: $ref: '#/definitions/CookieParam' debugOpts: $ref: '#/definitions/ScrapeDebugOptions' elements: type: array items: $ref: '#/definitions/ScrapeElementSelector' emulateMediaType: type: string gotoOptions: $ref: '#/definitions/GoToOptions' html: type: string rejectRequestPattern: type: array items: type: string rejectResourceTypes: type: array items: enum: - cspviolationreport - document - eventsource - fedcm - fetch - font - image - manifest - media - other - ping - prefetch - preflight - script - signedexchange - stylesheet - texttrack - websocket - xhr type: string requestInterceptors: type: array items: description: 'An array of patterns (using `req.url().match(r.pattern)` to match) and their corresponding responses to use in order to fulfill those requests.' type: object properties: pattern: description: 'An array of patterns (using `req.url().match(r.pattern)` to match) and their corresponding responses to use in order to fulfill those requests.' type: string response: additionalProperties: false type: object properties: headers: description: 'Optional response headers. The record values will be converted to string following: Arrays'' values will be mapped to String (Used when you need multiple headers with the same name). Non-arrays will be converted to String.' $ref: '#/definitions/Record%3Cstring%2Cunknown%3E' status: type: number contentType: type: string body: description: 'A string representation of the body to return. Can be a base64-encoded string but please omit any leading content-type data (eg "data:image/png;base64,").' type: string additionalProperties: false required: - pattern - response setExtraHTTPHeaders: type: object additionalProperties: type: string setJavaScriptEnabled: type: boolean url: type: string userAgent: type: object properties: userAgent: type: string userAgentMetadata: description: 'Used to specify User Agent Client Hints to emulate. See https://wicg.github.io/ua-client-hints Missing optional values will be filled in by the target with what it would normally use.' $ref: '#/definitions/Protocol.Emulation.UserAgentMetadata' platform: type: string additionalProperties: false viewport: anyOf: - $ref: '#/definitions/Viewport' - type: 'null' waitForEvent: type: object properties: event: type: string timeout: type: number additionalProperties: false required: - event waitForFunction: type: object properties: fn: description: The function, or statement, to be evaluated in browser context type: string polling: description: 'An interval at which the pageFunction is executed, defaults to raf. If polling is a number, then it is treated as an interval in milliseconds at which the function would be executed. If polling is a string, then it can be one of the following values: "raf" or "mutation"' type: - string - number timeout: description: 'Maximum time to wait for in milliseconds. Defaults to 30000 (30 seconds). Pass 0 to disable timeout.' type: number additionalProperties: false required: - fn waitForSelector: type: object properties: hidden: type: boolean selector: type: string timeout: type: number visible: type: boolean additionalProperties: false required: - selector waitForTimeout: type: number type: object required: - elements responses: '200': content: application/json: schema: description: The JSON response body type: object properties: data: anyOf: - type: array items: type: object properties: results: type: array items: type: object properties: attributes: description: A list of HTML attributes of the element type: array items: type: object properties: name: description: The name of the HTML attribute for the element type: string value: description: The value of the HTML attribute for the element type: string additionalProperties: false required: - name - value height: description: The height the element type: number html: description: The HTML the element type: string left: description: The amount of pixels from the left of the page type: number text: description: The text the element type: string top: description: The amount of pixels from the top of the page type: number width: description: The width the element type: number additionalProperties: false required: - attributes - height - html - left - text - top - width selector: description: The DOM selector of the element type: string additionalProperties: false required: - results - selector - type: 'null' debug: description: When debugOpts options are present, results are here anyOf: - type: object properties: console: description: A list of console messages from the browser type: array items: type: string cookies: description: List of cookies for the site or null anyOf: - type: array items: $ref: '#/definitions/Cookie' - type: 'null' html: description: The HTML string of the website or null type: - 'null' - string network: type: object properties: inbound: type: array items: $ref: '#/definitions/InBoundRequest' outbound: type: array items: $ref: '#/definitions/OutBoundRequest' additionalProperties: false required: - inbound - outbound screenshot: description: A base64-encoded string of the site or null type: - 'null' - string additionalProperties: false required: - console - cookies - html - network - screenshot - type: 'null' additionalProperties: false required: - data - debug definitions: Cookie: description: Represents a cookie object. type: object properties: path: description: Cookie path. type: string expires: description: 'Cookie expiration date as the number of seconds since the UNIX epoch. Set to `-1` for session cookies' type: number size: description: Cookie size. type: number secure: description: True if cookie is secure. type: boolean session: description: True in case of session cookie. type: boolean partitionKeyOpaque: description: True if cookie partition key is opaque. Supported only in Chrome. type: boolean name: description: Cookie name. type: string value: description: Cookie value. type: string domain: description: Cookie domain. type: string httpOnly: description: True if cookie is http-only. type: boolean sameSite: description: Cookie SameSite type. enum: - Default - Lax - None - Strict type: string priority: description: Cookie Priority. Supported only in Chrome. enum: - High - Low - Medium type: string sameParty: type: boolean sourceScheme: description: Cookie source scheme type. Supported only in Chrome. enum: - NonSecure - Secure - Unset type: string partitionKey: description: 'Cookie partition key. In Chrome, it matches the top-level site the partitioned cookie is available in. In Firefox, it matches the source origin in the {@link https://w3c.github.io/webdriver-bidi/#type-storage-PartitionKey PartitionKey}.' anyOf: - $ref: '#/definitions/CookiePartitionKey' - type: string additionalProperties: false required: - domain - expires - name - path - secure - session - size - value CookiePartitionKey: description: Represents a cookie partition key in Chrome. type: object properties: sourceOrigin: description: 'The site of the top-level URL the browser was visiting at the start of the request to the endpoint that set the cookie. In Chrome, maps to the CDP''s `topLevelSite` partition key.' type: string hasCrossSiteAncestor: description: 'Indicates if the cookie has any ancestors that are cross-site to the topLevelSite. Supported only in Chrome.' type: boolean additionalProperties: false required: - sourceOrigin InBoundRequest: type: object properties: headers: {} status: type: number url: type: string additionalProperties: false required: - headers - status - url OutBoundRequest: type: object properties: headers: {} method: type: string url: type: string additionalProperties: false required: - headers - method - url $schema: http://json-schema.org/draft-07/schema# description: The JSON response body '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: /chromium/scrape tags: - Browser REST APIs /edge/content: post: definitions: {} description: A JSON-based API. Given a "url" or "html" field, runs and returns HTML content after the page has loaded and JavaScript has parsed. 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: 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: 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: addScriptTag: type: array items: $ref: '#/definitions/FrameAddScriptTagOptions' addStyleTag: type: array items: $ref: '#/definitions/FrameAddStyleTagOptions' authenticate: anyOf: - $ref: '#/definitions/Credentials' - type: 'null' bestAttempt: description: 'When bestAttempt is set to true, browserless attempt to proceed when "awaited" events fail or timeout. This includes things like goto, waitForSelector, and more.' type: boolean cookies: type: array items: $ref: '#/definitions/CookieParam' emulateMediaType: type: string gotoOptions: $ref: '#/definitions/GoToOptions' html: type: string rejectRequestPattern: type: array items: type: string rejectResourceTypes: type: array items: enum: - cspviolationreport - document - eventsource - fedcm - fetch - font - image - manifest - media - other - ping - prefetch - preflight - script - signedexchange - stylesheet - texttrack - websocket - xhr type: string requestInterceptors: type: array items: description: 'An array of patterns (using `req.url().match(r.pattern)` to match) and their corresponding responses to use in order to fulfill those requests.' type: object properties: pattern: description: 'An array of patterns (using `req.url().match(r.pattern)` to match) and their corresponding responses to use in order to fulfill those requests.' type: string response: additionalProperties: false type: object properties: headers: description: 'Optional response headers. The record values will be converted to string following: Arrays'' values will be mapped to String (Used when you need multiple headers with the same name). Non-arrays will be converted to String.' $ref: '#/definitions/Record%3Cstring%2Cunknown%3E' status: type: number contentType: type: string body: description: 'A string representation of the body to return. Can be a base64-encoded string but please omit any leading content-type data (eg "data:image/png;base64,").' type: string additionalProperties: false required: - pattern - response setExtraHTTPHeaders: type: object additionalProperties: type: string setJavaScriptEnabled: description: Whether or not to allow JavaScript to run on the page. type: boolean url: type: string userAgent: type: object properties: userAgent: type: string userAgentMetadata: description: 'Used to specify User Agent Client Hints to emulate. See https://wicg.github.io/ua-client-hints Missing optional values will be filled in by the target with what it would normally use.' $ref: '#/definitions/Protocol.Emulation.UserAgentMetadata' platform: type: string additionalProperties: false viewport: anyOf: - $ref: '#/definitions/Viewport' - type: 'null' waitForEvent: type: object properties: event: type: string timeout: type: number additionalProperties: false required: - event waitForFunction: type: object properties: fn: description: The function, or statement, to be evaluated in browser context type: string polling: description: 'An interval at which the pageFunction is executed, defaults to raf. If polling is a number, then it is treated as an interval in milliseconds at which the function would be executed. If polling is a string, then it can be one of the following values: "raf" or "mutation"' type: - string - number timeout: description: 'Maximum time to wait for in milliseconds. Defaults to 30000 (30 seconds). Pass 0 to disable timeout.' type: number additionalProperties: false required: - fn waitForSelector: type: object properties: hidden: type: boolean selector: type: string timeout: type: number visible: type: boolean additionalProperties: false required: - selector waitForTimeout: type: number type: object responses: '200': content: text/html: schema: description: 'An HTML payload of the website or HTML after JavaScript parsing and execution.' type: string $schema: http://json-schema.org/draft-07/schema# description: 'An HTML payload of the website or HTML after JavaScript parsing and execution.' '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: /edge/content tags: - Browser REST APIs /edge/download: post: definitions: {} description: 'A JSON or JavaScript content-type API for returning files Chrome has downloaded during the execution of puppeteer code, which is ran inside context of the browser. Browserless sets up a blank page, a fresh download directory, injects your puppeteer code, and then executes it. You can load external libraries via the "import" syntax, and import ESM-style modules that are written for execution inside of the browser. Once your script is finished, any downloaded files from Chromium are returned back with the appropriate content-type header.' 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' - 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: application/json: schema: $ref: '#/definitions/JSONSchema' application/javascript: schema: type: string responses: '200': content: '*/*': schema: description: 'Responses are determined by the returned value of the downloads themselves, so there isn''t a static response type for this API.' $schema: http://json-schema.org/draft-07/schema# description: 'Responses are determined by the returned value of the downloads themselves, so there isn''t a static response type for this API.' '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: /edge/download tags: - Browser REST APIs /edge/function: post: definitions: {} description: 'A JSON or JavaScript content-type API for running puppeteer code in the browser''s context. Browserless sets up a blank page, injects your puppeteer code, and runs it. You can optionally load external libraries via the "import" module that are meant for browser usage. Values returned from the function are checked and an appropriate content-type and response is sent back to your HTTP call.' 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' - 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: application/json: schema: $ref: '#/definitions/JSONSchema' application/javascript: schema: type: string responses: '200': content: '*/*': schema: description: 'Responses are determined by the returned value of the function itself. Binary responses (PDF''s, screenshots) are returned back as binary data, and primitive JavaScript values are returned back by type (HTML data is "text/html", Objects are "application/json")' $schema: http://json-schema.org/draft-07/schema# description: 'Responses are determined by the returned value of the function itself. Binary responses (PDF''s, screenshots) are returned back as binary data, and primitive JavaScript values are returned back by type (HTML data is "text/html", Objects are "application/json")' '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: /edge/function tags: - Browser REST APIs /edge/pdf: post: definitions: {} description: 'A JSON-based API for getting a PDF binary from either a supplied "url" or "html" payload in your request. Many options exist for injecting cookies, request interceptors, user-agents and waiting for selectors, timers and more.' 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' - 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: application/json: schema: properties: addScriptTag: type: array items: $ref: '#/definitions/FrameAddScriptTagOptions' addStyleTag: type: array items: $ref: '#/definitions/FrameAddStyleTagOptions' authenticate: anyOf: - $ref: '#/definitions/Credentials' - type: 'null' bestAttempt: description: 'When bestAttempt is set to true, browserless attempt to proceed when "awaited" events fail or timeout. This includes things like goto, waitForSelector, and more.' type: boolean cookies: type: array items: $ref: '#/definitions/CookieParam' emulateMediaType: type: string gotoOptions: $ref: '#/definitions/GoToOptions' html: type: string options: additionalProperties: false type: object properties: scale: description: Scales the rendering of the web page. Amount must be between `0.1` and `2`. type: number displayHeaderFooter: description: Whether to show the header and footer. type: boolean headerTemplate: description: 'HTML template for the print header. Should be valid HTML with the following classes used to inject values into them: - `date` formatted print date - `title` document title - `url` document location - `pageNumber` current page number - `totalPages` total pages in the document' type: string footerTemplate: description: 'HTML template for the print footer. Has the same constraints and support for special classes as {@link PDFOptions.headerTemplate}.' type: string printBackground: description: Set to `true` to print background graphics. type: boolean landscape: description: Whether to print in landscape orientation. type: boolean pageRanges: description: Paper ranges to print, e.g. `1-5, 8, 11-13`. type: string format: description: All the valid paper format types when printing a PDF. enum: - A0 - A1 - A2 - A3 - A4 - A5 - A6 - LEDGER - LEGAL - LETTER - Ledger - Legal - Letter - TABLOID - Tabloid - a0 - a1 - a2 - a3 - a4 - a5 - a6 - ledger - legal - letter - tabloid type: string width: description: Sets the width of paper. You can pass in a number or a string with a unit. type: - string - number height: description: Sets the height of paper. You can pass in a number or a string with a unit. type: - string - number preferCSSPageSize: description: 'Give any CSS `@page` size declared in the page priority over what is declared in the `width` or `height` or `format` option.' type: boolean margin: description: Set the PDF margins. $ref: '#/definitions/PDFMargin' path: description: The path to save the file to. type: string omitBackground: description: Hides default white background and allows generating pdfs with transparency. type: boolean tagged: description: Generate tagged (accessible) PDF. type: boolean outline: description: Generate document outline. type: boolean timeout: description: 'Timeout in milliseconds. Pass `0` to disable timeout. The default value can be changed by using {@link Page.setDefaultTimeout}' type: number waitForFonts: description: 'If true, waits for `document.fonts.ready` to resolve. This might require activating the page using {@link Page.bringToFront} if the page is in the background.' type: boolean fullPage: type: boolean rejectRequestPattern: type: array items: type: string rejectResourceTypes: type: array items: enum: - cspviolationreport - document - eventsource - fedcm - fetch - font - image - manifest - media - other - ping - prefetch - preflight - script - signedexchange - stylesheet - texttrack - websocket - xhr type: string requestInterceptors: type: array items: description: 'An array of patterns (using `req.url().match(r.pattern)` to match) and their corresponding responses to use in order to fulfill those requests.' type: object properties: pattern: description: 'An array of patterns (using `req.url().match(r.pattern)` to match) and their corresponding responses to use in order to fulfill those requests.' type: string response: additionalProperties: false type: object properties: headers: description: 'Optional response headers. The record values will be converted to string following: Arrays'' values will be mapped to String (Used when you need multiple headers with the same name). Non-arrays will be converted to String.' $ref: '#/definitions/Record%3Cstring%2Cunknown%3E' status: type: number contentType: type: string body: description: 'A string representation of the body to return. Can be a base64-encoded string but please omit any leading content-type data (eg "data:image/png;base64,").' type: string additionalProperties: false required: - pattern - response setExtraHTTPHeaders: type: object additionalProperties: type: string setJavaScriptEnabled: type: boolean url: type: string userAgent: type: object properties: userAgent: type: string userAgentMetadata: description: 'Used to specify User Agent Client Hints to emulate. See https://wicg.github.io/ua-client-hints Missing optional values will be filled in by the target with what it would normally use.' $ref: '#/definitions/Protocol.Emulation.UserAgentMetadata' platform: type: string additionalProperties: false viewport: anyOf: - $ref: '#/definitions/Viewport' - type: 'null' waitForEvent: type: object properties: event: type: string timeout: type: number additionalProperties: false required: - event waitForFunction: type: object properties: fn: description: The function, or statement, to be evaluated in browser context type: string polling: description: 'An interval at which the pageFunction is executed, defaults to raf. If polling is a number, then it is treated as an interval in milliseconds at which the function would be executed. If polling is a string, then it can be one of the following values: "raf" or "mutation"' type: - string - number timeout: description: 'Maximum time to wait for in milliseconds. Defaults to 30000 (30 seconds). Pass 0 to disable timeout.' type: number additionalProperties: false required: - fn waitForSelector: type: object properties: hidden: type: boolean selector: type: string timeout: type: number visible: type: boolean additionalProperties: false required: - selector waitForTimeout: type: number type: object responses: '200': content: application/pdf: schema: description: Responds with an application/pdf content-type and a binary PDF type: string $schema: http://json-schema.org/draft-07/schema# description: Responds with an application/pdf content-type and a binary PDF '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: /edge/pdf tags: - Browser REST APIs /edge/performance: post: definitions: {} description: Run lighthouse performance audits with a supplied "url" in your JSON payload. 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' - 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: application/json: schema: properties: budgets: type: array items: type: object properties: {} additionalProperties: true config: type: object properties: {} additionalProperties: true url: type: string type: object required: - url responses: '200': content: application/json: schema: description: 'The response of the lighthouse stats. Response objects are determined by the type of budgets and config in the POST JSON body' type: object properties: {} additionalProperties: true $schema: http://json-schema.org/draft-07/schema# description: 'The response of the lighthouse stats. Response objects are determined by the type of budgets and config in the POST JSON body' '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: /edge/performance tags: - Browser REST APIs /edge/scrape: post: definitions: {} description: 'A JSON-based API that returns text, html, and meta-data from a given list of selectors. Debugging information is available by sending in the appropriate flags in the "debugOpts" property. Responds with an array of JSON objects.' 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: 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: 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: addScriptTag: type: array items: $ref: '#/definitions/FrameAddScriptTagOptions' addStyleTag: type: array items: $ref: '#/definitions/FrameAddStyleTagOptions' authenticate: anyOf: - $ref: '#/definitions/Credentials' - type: 'null' bestAttempt: description: 'When bestAttempt is set to true, browserless attempt to proceed when "awaited" events fail or timeout. This includes things like goto, waitForSelector, and more.' type: boolean cookies: type: array items: $ref: '#/definitions/CookieParam' debugOpts: $ref: '#/definitions/ScrapeDebugOptions' elements: type: array items: $ref: '#/definitions/ScrapeElementSelector' emulateMediaType: type: string gotoOptions: $ref: '#/definitions/GoToOptions' html: type: string rejectRequestPattern: type: array items: type: string rejectResourceTypes: type: array items: enum: - cspviolationreport - document - eventsource - fedcm - fetch - font - image - manifest - media - other - ping - prefetch - preflight - script - signedexchange - stylesheet - texttrack - websocket - xhr type: string requestInterceptors: type: array items: description: 'An array of patterns (using `req.url().match(r.pattern)` to match) and their corresponding responses to use in order to fulfill those requests.' type: object properties: pattern: description: 'An array of patterns (using `req.url().match(r.pattern)` to match) and their corresponding responses to use in order to fulfill those requests.' type: string response: additionalProperties: false type: object properties: headers: description: 'Optional response headers. The record values will be converted to string following: Arrays'' values will be mapped to String (Used when you need multiple headers with the same name). Non-arrays will be converted to String.' $ref: '#/definitions/Record%3Cstring%2Cunknown%3E' status: type: number contentType: type: string body: description: 'A string representation of the body to return. Can be a base64-encoded string but please omit any leading content-type data (eg "data:image/png;base64,").' type: string additionalProperties: false required: - pattern - response setExtraHTTPHeaders: type: object additionalProperties: type: string setJavaScriptEnabled: type: boolean url: type: string userAgent: type: object properties: userAgent: type: string userAgentMetadata: description: 'Used to specify User Agent Client Hints to emulate. See https://wicg.github.io/ua-client-hints Missing optional values will be filled in by the target with what it would normally use.' $ref: '#/definitions/Protocol.Emulation.UserAgentMetadata' platform: type: string additionalProperties: false viewport: anyOf: - $ref: '#/definitions/Viewport' - type: 'null' waitForEvent: type: object properties: event: type: string timeout: type: number additionalProperties: false required: - event waitForFunction: type: object properties: fn: description: The function, or statement, to be evaluated in browser context type: string polling: description: 'An interval at which the pageFunction is executed, defaults to raf. If polling is a number, then it is treated as an interval in milliseconds at which the function would be executed. If polling is a string, then it can be one of the following values: "raf" or "mutation"' type: - string - number timeout: description: 'Maximum time to wait for in milliseconds. Defaults to 30000 (30 seconds). Pass 0 to disable timeout.' type: number additionalProperties: false required: - fn waitForSelector: type: object properties: hidden: type: boolean selector: type: string timeout: type: number visible: type: boolean additionalProperties: false required: - selector waitForTimeout: type: number type: object required: - elements responses: '200': content: application/json: schema: description: The JSON response body type: object properties: data: anyOf: - type: array items: type: object properties: results: type: array items: type: object properties: attributes: description: A list of HTML attributes of the element type: array items: type: object properties: name: description: The name of the HTML attribute for the element type: string value: description: The value of the HTML attribute for the element type: string additionalProperties: false required: - name - value height: description: The height the element type: number html: description: The HTML the element type: string left: description: The amount of pixels from the left of the page type: number text: description: The text the element type: string top: description: The amount of pixels from the top of the page type: number width: description: The width the element type: number additionalProperties: false required: - attributes - height - html - left - text - top - width selector: description: The DOM selector of the element type: string additionalProperties: false required: - results - selector - type: 'null' debug: description: When debugOpts options are present, results are here anyOf: - type: object properties: console: description: A list of console messages from the browser type: array items: type: string cookies: description: List of cookies for the site or null anyOf: - type: array items: $ref: '#/definitions/Cookie' - type: 'null' html: description: The HTML string of the website or null type: - 'null' - string network: type: object properties: inbound: type: array items: $ref: '#/definitions/InBoundRequest' outbound: type: array items: $ref: '#/definitions/OutBoundRequest' additionalProperties: false required: - inbound - outbound screenshot: description: A base64-encoded string of the site or null type: - 'null' - string additionalProperties: false required: - console - cookies - html - network - screenshot - type: 'null' additionalProperties: false required: - data - debug definitions: Cookie: description: Represents a cookie object. type: object properties: path: description: Cookie path. type: string expires: description: 'Cookie expiration date as the number of seconds since the UNIX epoch. Set to `-1` for session cookies' type: number size: description: Cookie size. type: number secure: description: True if cookie is secure. type: boolean session: description: True in case of session cookie. type: boolean partitionKeyOpaque: description: True if cookie partition key is opaque. Supported only in Chrome. type: boolean name: description: Cookie name. type: string value: description: Cookie value. type: string domain: description: Cookie domain. type: string httpOnly: description: True if cookie is http-only. type: boolean sameSite: description: Cookie SameSite type. enum: - Default - Lax - None - Strict type: string priority: description: Cookie Priority. Supported only in Chrome. enum: - High - Low - Medium type: string sameParty: type: boolean sourceScheme: description: Cookie source scheme type. Supported only in Chrome. enum: - NonSecure - Secure - Unset type: string partitionKey: description: 'Cookie partition key. In Chrome, it matches the top-level site the partitioned cookie is available in. In Firefox, it matches the source origin in the {@link https://w3c.github.io/webdriver-bidi/#type-storage-PartitionKey PartitionKey}.' anyOf: - $ref: '#/definitions/CookiePartitionKey' - type: string additionalProperties: false required: - domain - expires - name - path - secure - session - size - value CookiePartitionKey: description: Represents a cookie partition key in Chrome. type: object properties: sourceOrigin: description: 'The site of the top-level URL the browser was visiting at the start of the request to the endpoint that set the cookie. In Chrome, maps to the CDP''s `topLevelSite` partition key.' type: string hasCrossSiteAncestor: description: 'Indicates if the cookie has any ancestors that are cross-site to the topLevelSite. Supported only in Chrome.' type: boolean additionalProperties: false required: - sourceOrigin InBoundRequest: type: object properties: headers: {} status: type: number url: type: string additionalProperties: false required: - headers - status - url OutBoundRequest: type: object properties: headers: {} method: type: string url: type: string additionalProperties: false required: - headers - method - url $schema: http://json-schema.org/draft-07/schema# description: The JSON response body '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: /edge/scrape tags: - Browser REST APIs /edge/screenshot: post: definitions: {} description: 'A JSON-based API for getting a screenshot binary from either a supplied "url" or "html" payload in your request. Many options exist including cookies, user-agents, setting timers and network mocks.' 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' - 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: application/json: schema: properties: addScriptTag: type: array items: $ref: '#/definitions/FrameAddScriptTagOptions' addStyleTag: type: array items: $ref: '#/definitions/FrameAddStyleTagOptions' authenticate: anyOf: - $ref: '#/definitions/Credentials' - type: 'null' bestAttempt: description: 'When bestAttempt is set to true, browserless attempt to proceed when "awaited" events fail or timeout. This includes things like goto, waitForSelector, and more.' type: boolean cookies: type: array items: $ref: '#/definitions/CookieParam' emulateMediaType: type: string gotoOptions: $ref: '#/definitions/GoToOptions' html: type: string options: $ref: '#/definitions/ScreenshotOptions' rejectRequestPattern: type: array items: type: string rejectResourceTypes: type: array items: enum: - cspviolationreport - document - eventsource - fedcm - fetch - font - image - manifest - media - other - ping - prefetch - preflight - script - signedexchange - stylesheet - texttrack - websocket - xhr type: string requestInterceptors: type: array items: description: 'An array of patterns (using `req.url().match(r.pattern)` to match) and their corresponding responses to use in order to fulfill those requests.' type: object properties: pattern: description: 'An array of patterns (using `req.url().match(r.pattern)` to match) and their corresponding responses to use in order to fulfill those requests.' type: string response: additionalProperties: false type: object properties: headers: description: 'Optional response headers. The record values will be converted to string following: Arrays'' values will be mapped to String (Used when you need multiple headers with the same name). Non-arrays will be converted to String.' $ref: '#/definitions/Record%3Cstring%2Cunknown%3E' status: type: number contentType: type: string body: description: 'A string representation of the body to return. Can be a base64-encoded string but please omit any leading content-type data (eg "data:image/png;base64,").' type: string additionalProperties: false required: - pattern - response scrollPage: type: boolean selector: type: string setExtraHTTPHeaders: type: object additionalProperties: type: string setJavaScriptEnabled: type: boolean url: type: string userAgent: type: object properties: userAgent: type: string userAgentMetadata: description: 'Used to specify User Agent Client Hints to emulate. See https://wicg.github.io/ua-client-hints Missing optional values will be filled in by the target with what it would normally use.' $ref: '#/definitions/Protocol.Emulation.UserAgentMetadata' platform: type: string additionalProperties: false viewport: anyOf: - $ref: '#/definitions/Viewport' - type: 'null' waitForEvent: type: object properties: event: type: string timeout: type: number additionalProperties: false required: - event waitForFunction: type: object properties: fn: description: The function, or statement, to be evaluated in browser context type: string polling: description: 'An interval at which the pageFunction is executed, defaults to raf. If polling is a number, then it is treated as an interval in milliseconds at which the function would be executed. If polling is a string, then it can be one of the following values: "raf" or "mutation"' type: - string - number timeout: description: 'Maximum time to wait for in milliseconds. Defaults to 30000 (30 seconds). Pass 0 to disable timeout.' type: number additionalProperties: false required: - fn waitForSelector: type: object properties: hidden: type: boolean selector: type: string timeout: type: number visible: type: boolean additionalProperties: false required: - selector waitForTimeout: type: number type: object responses: '200': content: image/png: schema: type: text image/jpeg: schema: type: text text/plain: schema: type: text description: 'Response can either be a text/plain base64 encoded body or a binary stream with png/jpeg as a content-type' '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: /edge/screenshot tags: - Browser 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: - Browser REST APIs /chrome/export: post: definitions: {} description: Exports a webpage to a PDF or image format. This API is useful for generating reports, screenshots, or PDFs of web pages. 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: externalProxyServer schema: description: 'External proxy server URL for user-provided proxies. Format: http(s)://[username:password@]host:port When set, routes requests through this proxy instead of built-in residential proxies.' type: string - 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.' 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: proxy schema: description: The type of proxy to use, currently just 'residential' is supported type: string const: residential - in: query name: proxyCity schema: description: 'The city to use for the proxy. Available cities: https://production-sfo.browserless.io/proxy/cities?token=YOUR_TOKEN Documentation: https://docs.browserless.io/baas/features/proxies#built-in-residential-proxy' type: string - in: query name: proxyCountry schema: description: 'A two-letter country code for the proxy configuration. Supported codes: US, GB, FR, DE, etc. Full list: https://docs.browserless.io/bql-schema/types/enums/country-type' type: string - in: query name: proxyLocaleMatch schema: description: 'Sets the browser''s language to match the proxy''s geographic location. Recommended when using proxyCountry to ensure websites render content, currency, and formatting in the local language. Default is English (en-US).' enum: - '0' - '1' - 'false' - 'true' type: string - in: query name: proxyPreset schema: description: 'A preset code for website-specific proxy routing. Maps to specific proxy vendors internally for optimal access to certain websites. Format: "px_" (e.g., "px_gov01", "px_amazon01")' type: string - in: query name: proxyState schema: description: The state or province to use for the proxy, whitespace must be replaced with underscores type: string - in: query name: proxySticky schema: description: Whether or not to use the same IP for all requests, defaults to true enum: - '0' - '1' - 'false' - 'true' 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: application/json: schema: properties: bestAttempt: description: 'When bestAttempt is set to true, browserless will attempt to proceed when "awaited" events fail or timeout. This includes things like goto, waitForSelector, and more.' type: boolean url: description: The URL of the site you want to archive. type: string gotoOptions: $ref: '#/definitions/GoToOptions' description: An optional goto parameter object for considering when the page is done loading. waitForEvent: description: Options for waiting for a specific event to be fired on the page. type: object properties: event: type: string timeout: type: number additionalProperties: false required: - event waitForFunction: description: Options for waiting for a JavaScript function to execute. type: object properties: fn: description: The function, or statement, to be evaluated in browser context type: string polling: description: 'An interval at which the pageFunction is executed, defaults to raf. If polling is a number, then it is treated as an interval in milliseconds at which the function would be executed. If polling is a string, then it can be one of the following values: "raf" or "mutation"' type: - string - number timeout: description: 'Maximum time to wait for in milliseconds. Defaults to 30000 (30 seconds). Pass 0 to disable timeout.' type: number additionalProperties: false required: - fn waitForSelector: description: Options for waiting for a specific CSS selector to appear on the page. type: object properties: hidden: type: boolean selector: type: string timeout: type: number visible: type: boolean additionalProperties: false required: - selector waitForTimeout: description: The amount of time in milliseconds to wait before proceeding. type: number headers: description: An object containing additional HTTP headers to send with every request. type: object additionalProperties: type: string includeResources: description: 'Whether to include all linked resources (images, CSS, JS) in a zip file. When true, the response will be a zip file containing the HTML and all resources. When false or not provided, the response will be the raw content (default behavior).' type: boolean type: object required: - url responses: '200': content: application/json: schema: type: object properties: html: description: The HTML content of the page. type: string additionalProperties: false required: - html $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: /chrome/export tags: - Browser REST APIs /chrome/unblock: post: definitions: {} description: 'Unblocks the provided URL from being blocked due to bot detection. Returns a payload of Cookies, HTML, a base64 encoded screenshot, and a "browserWSEndpoint" to allow connecting to the browser when specified in the JSON Payload. Only supports CDP or Puppeteer like libraries when connecting to the "browserWSEndpoint".' 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: externalProxyServer schema: description: 'External proxy server URL for user-provided proxies. Format: http(s)://[username:password@]host:port When set, routes requests through this proxy instead of built-in residential proxies.' type: string - 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.' 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: proxy schema: description: The type of proxy to use, currently just 'residential' is supported type: string const: residential - in: query name: proxyCity schema: description: 'The city to use for the proxy. Available cities: https://production-sfo.browserless.io/proxy/cities?token=YOUR_TOKEN Documentation: https://docs.browserless.io/baas/features/proxies#built-in-residential-proxy' type: string - in: query name: proxyCountry schema: description: 'A two-letter country code for the proxy configuration. Supported codes: US, GB, FR, DE, etc. Full list: https://docs.browserless.io/bql-schema/types/enums/country-type' type: string - in: query name: proxyLocaleMatch schema: description: 'Sets the browser''s language to match the proxy''s geographic location. Recommended when using proxyCountry to ensure websites render content, currency, and formatting in the local language. Default is English (en-US).' enum: - '0' - '1' - 'false' - 'true' type: string - in: query name: proxyPreset schema: description: 'A preset code for website-specific proxy routing. Maps to specific proxy vendors internally for optimal access to certain websites. Format: "px_" (e.g., "px_gov01", "px_amazon01")' type: string - in: query name: proxyState schema: description: The state or province to use for the proxy, whitespace must be replaced with underscores type: string - in: query name: proxySticky schema: description: Whether or not to use the same IP for all requests, defaults to true enum: - '0' - '1' - 'false' - 'true' 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: application/json: schema: properties: bestAttempt: description: 'When bestAttempt is set to true, browserless will attempt to proceed when "awaited" events fail or timeout. This includes things like goto, waitForSelector, and more.' type: boolean url: description: The URL of the site you want to unblock. type: string browserWSEndpoint: description: 'Whether or not to keep the underlying browser alive and around for future reconnects. Defaults to false.' type: boolean cookies: description: Whether or not to to return cookies for the site, defaults to true. type: boolean content: description: Whether or not to to return content for the site, defaults to true. type: boolean screenshot: description: Whether or not to to return a full-page screenshot for the site, defaults to true. type: boolean ttl: description: 'When the browserWSEndpoint is requested this tells browserless how long to keep this browser alive for re-connection until shutting it down completely. Maximum of 30000 for 30 seconds (30,000ms).' type: number gotoOptions: $ref: '#/definitions/GoToOptions' description: An optional goto parameter object for considering when the page is done loading. waitForEvent: description: Options for waiting for a specific event to be fired on the page. type: object properties: event: type: string timeout: type: number additionalProperties: false required: - event waitForFunction: description: Options for waiting for a JavaScript function to execute. type: object properties: fn: description: The function, or statement, to be evaluated in browser context type: string polling: description: 'An interval at which the pageFunction is executed, defaults to raf. If polling is a number, then it is treated as an interval in milliseconds at which the function would be executed. If polling is a string, then it can be one of the following values: "raf" or "mutation"' type: - string - number timeout: description: 'Maximum time to wait for in milliseconds. Defaults to 30000 (30 seconds). Pass 0 to disable timeout.' type: number additionalProperties: false required: - fn waitForSelector: description: Options for waiting for a specific CSS selector to appear on the page. type: object properties: hidden: type: boolean selector: type: string timeout: type: number visible: type: boolean additionalProperties: false required: - selector waitForTimeout: description: The amount of time in milliseconds to wait before proceeding. type: number type: object required: - url responses: '200': content: application/json: schema: type: object properties: cookies: description: 'A list of cookies which can be used for new connections or for usage elsewhere. Value is "null" when the request body specifies cookies: false.' type: array items: $ref: '#/definitions/Cookie' content: description: 'The HTML content of the page once it is passed bot detection. Value is "null" when the request body specifies cookies: false.' type: string browserWSEndpoint: description: 'The browserWSEndpoint of the response when the POST body contains a browserWSEndpoint: true property' type: string ttl: description: 'The time the browser will remain alive until it is shutdown. Zero when browserWSEndpoint: false is set in the request payload. The limit is 30000 or 30 seconds, which is the maximum allowed time.' type: number screenshot: description: A base64 encoded JPEG of the of the final site page. type: string additionalProperties: false required: - browserWSEndpoint - content - cookies - screenshot - ttl definitions: Cookie: description: Represents a cookie object. type: object properties: path: description: Cookie path. type: string expires: description: 'Cookie expiration date as the number of seconds since the UNIX epoch. Set to `-1` for session cookies' type: number size: description: Cookie size. type: number secure: description: True if cookie is secure. type: boolean session: description: True in case of session cookie. type: boolean partitionKeyOpaque: description: True if cookie partition key is opaque. Supported only in Chrome. type: boolean name: description: Cookie name. type: string value: description: Cookie value. type: string domain: description: Cookie domain. type: string httpOnly: description: True if cookie is http-only. type: boolean sameSite: $ref: '#/definitions/CookieSameSite' description: Cookie SameSite type. priority: $ref: '#/definitions/CookiePriority' description: Cookie Priority. Supported only in Chrome. sameParty: type: boolean sourceScheme: $ref: '#/definitions/CookieSourceScheme' description: Cookie source scheme type. Supported only in Chrome. partitionKey: description: 'Cookie partition key. In Chrome, it matches the top-level site the partitioned cookie is available in. In Firefox, it matches the source origin in the {@link https://w3c.github.io/webdriver-bidi/#type-storage-PartitionKey PartitionKey}.' anyOf: - $ref: '#/definitions/CookiePartitionKey' - type: string additionalProperties: false required: - domain - expires - name - path - secure - session - size - value CookieSameSite: description: 'Represents the cookie''s ''SameSite'' status: https://tools.ietf.org/html/draft-west-first-party-cookies' enum: - Default - Lax - None - Strict type: string CookiePriority: description: 'Represents the cookie''s ''Priority'' status: https://tools.ietf.org/html/draft-west-cookie-priority-00' enum: - High - Low - Medium type: string CookieSourceScheme: description: 'Represents the source scheme of the origin that originally set the cookie. A value of "Unset" allows protocol clients to emulate legacy cookie scope for the scheme. This is a temporary ability and it will be removed in the future.' enum: - NonSecure - Secure - Unset type: string CookiePartitionKey: description: Represents a cookie partition key in Chrome. type: object properties: sourceOrigin: description: 'The site of the top-level URL the browser was visiting at the start of the request to the endpoint that set the cookie. In Chrome, maps to the CDP''s `topLevelSite` partition key.' type: string hasCrossSiteAncestor: description: 'Indicates if the cookie has any ancestors that are cross-site to the topLevelSite. Supported only in Chrome.' type: boolean additionalProperties: false required: - sourceOrigin $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: /chrome/unblock tags: - Browser REST APIs /chromium/export: post: definitions: {} description: 'Exports a webpage to a PDF or image format. This API is useful for generating reports, screenshots, or PDFs of web pages. **Note:** This endpoint is also available at: `/export` for backwards compatibility.' 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: externalProxyServer schema: description: 'External proxy server URL for user-provided proxies. Format: http(s)://[username:password@]host:port When set, routes requests through this proxy instead of built-in residential proxies.' type: string - 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.' 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: proxy schema: description: The type of proxy to use, currently just 'residential' is supported type: string const: residential - in: query name: proxyCity schema: description: 'The city to use for the proxy. Available cities: https://production-sfo.browserless.io/proxy/cities?token=YOUR_TOKEN Documentation: https://docs.browserless.io/baas/features/proxies#built-in-residential-proxy' type: string - in: query name: proxyCountry schema: description: 'A two-letter country code for the proxy configuration. Supported codes: US, GB, FR, DE, etc. Full list: https://docs.browserless.io/bql-schema/types/enums/country-type' type: string - in: query name: proxyLocaleMatch schema: description: 'Sets the browser''s language to match the proxy''s geographic location. Recommended when using proxyCountry to ensure websites render content, currency, and formatting in the local language. Default is English (en-US).' enum: - '0' - '1' - 'false' - 'true' type: string - in: query name: proxyPreset schema: description: 'A preset code for website-specific proxy routing. Maps to specific proxy vendors internally for optimal access to certain websites. Format: "px_" (e.g., "px_gov01", "px_amazon01")' type: string - in: query name: proxyState schema: description: The state or province to use for the proxy, whitespace must be replaced with underscores type: string - in: query name: proxySticky schema: description: Whether or not to use the same IP for all requests, defaults to true enum: - '0' - '1' - 'false' - 'true' 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: application/json: schema: properties: bestAttempt: description: 'When bestAttempt is set to true, browserless will attempt to proceed when "awaited" events fail or timeout. This includes things like goto, waitForSelector, and more.' type: boolean url: description: The URL of the site you want to archive. type: string gotoOptions: $ref: '#/definitions/GoToOptions' description: An optional goto parameter object for considering when the page is done loading. waitForEvent: description: Options for waiting for a specific event to be fired on the page. type: object properties: event: type: string timeout: type: number additionalProperties: false required: - event waitForFunction: description: Options for waiting for a JavaScript function to execute. type: object properties: fn: description: The function, or statement, to be evaluated in browser context type: string polling: description: 'An interval at which the pageFunction is executed, defaults to raf. If polling is a number, then it is treated as an interval in milliseconds at which the function would be executed. If polling is a string, then it can be one of the following values: "raf" or "mutation"' type: - string - number timeout: description: 'Maximum time to wait for in milliseconds. Defaults to 30000 (30 seconds). Pass 0 to disable timeout.' type: number additionalProperties: false required: - fn waitForSelector: description: Options for waiting for a specific CSS selector to appear on the page. type: object properties: hidden: type: boolean selector: type: string timeout: type: number visible: type: boolean additionalProperties: false required: - selector waitForTimeout: description: The amount of time in milliseconds to wait before proceeding. type: number headers: description: An object containing additional HTTP headers to send with every request. type: object additionalProperties: type: string includeResources: description: 'Whether to include all linked resources (images, CSS, JS) in a zip file. When true, the response will be a zip file containing the HTML and all resources. When false or not provided, the response will be the raw content (default behavior).' type: boolean type: object required: - url responses: '200': content: application/json: schema: type: object properties: html: description: The HTML content of the page. type: string additionalProperties: false required: - html $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: /chromium/export tags: - Browser REST APIs /unblock: post: definitions: {} description: 'Unblocks the provided URL from being blocked due to bot detection. Returns a payload of Cookies, HTML, a base64 encoded screenshot, and a "browserWSEndpoint" to allow connecting to the browser when specified in the JSON Payload. Only supports CDP or Puppeteer like libraries when connecting to the "browserWSEndpoint". **Note:** This endpoint is also available at: `/chromium/unblock` for backwards compatibility.' 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: externalProxyServer schema: description: 'External proxy server URL for user-provided proxies. Format: http(s)://[username:password@]host:port When set, routes requests through this proxy instead of built-in residential proxies.' type: string - 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.' 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: proxy schema: description: The type of proxy to use, currently just 'residential' is supported type: string const: residential - in: query name: proxyCity schema: description: 'The city to use for the proxy. Available cities: https://production-sfo.browserless.io/proxy/cities?token=YOUR_TOKEN Documentation: https://docs.browserless.io/baas/features/proxies#built-in-residential-proxy' type: string - in: query name: proxyCountry schema: description: 'A two-letter country code for the proxy configuration. Supported codes: US, GB, FR, DE, etc. Full list: https://docs.browserless.io/bql-schema/types/enums/country-type' type: string - in: query name: proxyLocaleMatch schema: description: 'Sets the browser''s language to match the proxy''s geographic location. Recommended when using proxyCountry to ensure websites render content, currency, and formatting in the local language. Default is English (en-US).' enum: - '0' - '1' - 'false' - 'true' type: string - in: query name: proxyPreset schema: description: 'A preset code for website-specific proxy routing. Maps to specific proxy vendors internally for optimal access to certain websites. Format: "px_" (e.g., "px_gov01", "px_amazon01")' type: string - in: query name: proxyState schema: description: The state or province to use for the proxy, whitespace must be replaced with underscores type: string - in: query name: proxySticky schema: description: Whether or not to use the same IP for all requests, defaults to true enum: - '0' - '1' - 'false' - 'true' 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: application/json: schema: properties: bestAttempt: description: 'When bestAttempt is set to true, browserless will attempt to proceed when "awaited" events fail or timeout. This includes things like goto, waitForSelector, and more.' type: boolean url: description: The URL of the site you want to unblock. type: string browserWSEndpoint: description: 'Whether or not to keep the underlying browser alive and around for future reconnects. Defaults to false.' type: boolean cookies: description: Whether or not to to return cookies for the site, defaults to true. type: boolean content: description: Whether or not to to return content for the site, defaults to true. type: boolean screenshot: description: Whether or not to to return a full-page screenshot for the site, defaults to true. type: boolean ttl: description: 'When the browserWSEndpoint is requested this tells browserless how long to keep this browser alive for re-connection until shutting it down completely. Maximum of 30000 for 30 seconds (30,000ms).' type: number gotoOptions: $ref: '#/definitions/GoToOptions' description: An optional goto parameter object for considering when the page is done loading. waitForEvent: description: Options for waiting for a specific event to be fired on the page. type: object properties: event: type: string timeout: type: number additionalProperties: false required: - event waitForFunction: description: Options for waiting for a JavaScript function to execute. type: object properties: fn: description: The function, or statement, to be evaluated in browser context type: string polling: description: 'An interval at which the pageFunction is executed, defaults to raf. If polling is a number, then it is treated as an interval in milliseconds at which the function would be executed. If polling is a string, then it can be one of the following values: "raf" or "mutation"' type: - string - number timeout: description: 'Maximum time to wait for in milliseconds. Defaults to 30000 (30 seconds). Pass 0 to disable timeout.' type: number additionalProperties: false required: - fn waitForSelector: description: Options for waiting for a specific CSS selector to appear on the page. type: object properties: hidden: type: boolean selector: type: string timeout: type: number visible: type: boolean additionalProperties: false required: - selector waitForTimeout: description: The amount of time in milliseconds to wait before proceeding. type: number type: object required: - url responses: '200': content: application/json: schema: type: object properties: cookies: description: 'A list of cookies which can be used for new connections or for usage elsewhere. Value is "null" when the request body specifies cookies: false.' type: array items: $ref: '#/definitions/Cookie' content: description: 'The HTML content of the page once it is passed bot detection. Value is "null" when the request body specifies cookies: false.' type: string browserWSEndpoint: description: 'The browserWSEndpoint of the response when the POST body contains a browserWSEndpoint: true property' type: string ttl: description: 'The time the browser will remain alive until it is shutdown. Zero when browserWSEndpoint: false is set in the request payload. The limit is 30000 or 30 seconds, which is the maximum allowed time.' type: number screenshot: description: A base64 encoded JPEG of the of the final site page. type: string additionalProperties: false required: - browserWSEndpoint - content - cookies - screenshot - ttl definitions: Cookie: description: Represents a cookie object. type: object properties: path: description: Cookie path. type: string expires: description: 'Cookie expiration date as the number of seconds since the UNIX epoch. Set to `-1` for session cookies' type: number size: description: Cookie size. type: number secure: description: True if cookie is secure. type: boolean session: description: True in case of session cookie. type: boolean partitionKeyOpaque: description: True if cookie partition key is opaque. Supported only in Chrome. type: boolean name: description: Cookie name. type: string value: description: Cookie value. type: string domain: description: Cookie domain. type: string httpOnly: description: True if cookie is http-only. type: boolean sameSite: $ref: '#/definitions/CookieSameSite' description: Cookie SameSite type. priority: $ref: '#/definitions/CookiePriority' description: Cookie Priority. Supported only in Chrome. sameParty: type: boolean sourceScheme: $ref: '#/definitions/CookieSourceScheme' description: Cookie source scheme type. Supported only in Chrome. partitionKey: description: 'Cookie partition key. In Chrome, it matches the top-level site the partitioned cookie is available in. In Firefox, it matches the source origin in the {@link https://w3c.github.io/webdriver-bidi/#type-storage-PartitionKey PartitionKey}.' anyOf: - $ref: '#/definitions/CookiePartitionKey' - type: string additionalProperties: false required: - domain - expires - name - path - secure - session - size - value CookieSameSite: description: 'Represents the cookie''s ''SameSite'' status: https://tools.ietf.org/html/draft-west-first-party-cookies' enum: - Default - Lax - None - Strict type: string CookiePriority: description: 'Represents the cookie''s ''Priority'' status: https://tools.ietf.org/html/draft-west-cookie-priority-00' enum: - High - Low - Medium type: string CookieSourceScheme: description: 'Represents the source scheme of the origin that originally set the cookie. A value of "Unset" allows protocol clients to emulate legacy cookie scope for the scheme. This is a temporary ability and it will be removed in the future.' enum: - NonSecure - Secure - Unset type: string CookiePartitionKey: description: Represents a cookie partition key in Chrome. type: object properties: sourceOrigin: description: 'The site of the top-level URL the browser was visiting at the start of the request to the endpoint that set the cookie. In Chrome, maps to the CDP''s `topLevelSite` partition key.' type: string hasCrossSiteAncestor: description: 'Indicates if the cookie has any ancestors that are cross-site to the topLevelSite. Supported only in Chrome.' type: boolean additionalProperties: false required: - sourceOrigin $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: /unblock tags: - Browser 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: - Browser REST APIs /map: post: definitions: {} description: 'Primarily discovers URLs from the site''s sitemap, supplemented with link extraction from the page via the smart-scrape strategy pipeline (HTTP-first, browser fallback for JS-rendered pages). Use the search parameter to order results by relevance.' parameters: - in: query name: timeout schema: description: Request timeout in milliseconds type: number - in: query name: token schema: description: API authentication token type: string requestBody: content: application/json: schema: properties: url: description: The base URL to start mapping from (required) type: string search: description: Search query to order results by relevance type: string limit: description: 'Maximum number of links to return (default: 5000, max: 5000)' type: number timeout: description: Request timeout in milliseconds type: number sitemap: description: 'Controls sitemap behavior: "include" (default), "skip", "only"' enum: - include - only - skip type: string includeSubdomains: description: 'Whether to include URLs from subdomains (default: true)' type: boolean ignoreQueryParameters: description: 'Exclude URLs with query parameters (default: true)' type: boolean location: description: Geo-targeting settings type: object properties: country: description: ISO 3166-1 alpha-2 country code for proxy routing (e.g., `"us"`, `"gb"`, `"de"`). Defaults to `"us"`. type: string languages: description: Preferred language codes for the request (e.g., `["en", "fr"]`). type: array items: type: string additionalProperties: false type: object required: - url 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: /map tags: - Browser REST APIs /pdf: post: definitions: {} description: 'A JSON-based API for getting a PDF binary from either a supplied "url" or "html" payload in your request. Many options exist for injecting cookies, request interceptors, user-agents and waiting for selectors, timers and more. **Note:** This endpoint is also available at: `/chromium/pdf` for backwards compatibility.' 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: externalProxyServer schema: description: 'External proxy server URL for user-provided proxies. Format: http(s)://[username:password@]host:port When set, routes requests through this proxy instead of built-in residential proxies.' type: string - 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.' 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: proxy schema: description: The type of proxy to use, currently just 'residential' is supported type: string const: residential - in: query name: proxyCity schema: description: 'The city to use for the proxy. Available cities: https://production-sfo.browserless.io/proxy/cities?token=YOUR_TOKEN Documentation: https://docs.browserless.io/baas/features/proxies#built-in-residential-proxy' type: string - in: query name: proxyCountry schema: description: 'A two-letter country code for the proxy configuration. Supported codes: US, GB, FR, DE, etc. Full list: https://docs.browserless.io/bql-schema/types/enums/country-type' type: string - in: query name: proxyLocaleMatch schema: description: 'Sets the browser''s language to match the proxy''s geographic location. Recommended when using proxyCountry to ensure websites render content, currency, and formatting in the local language. Default is English (en-US).' enum: - '0' - '1' - 'false' - 'true' type: string - in: query name: proxyPreset schema: description: 'A preset code for website-specific proxy routing. Maps to specific proxy vendors internally for optimal access to certain websites. Format: "px_" (e.g., "px_gov01", "px_amazon01")' type: string - in: query name: proxyState schema: description: The state or province to use for the proxy, whitespace must be replaced with underscores type: string - in: query name: proxySticky schema: description: Whether or not to use the same IP for all requests, defaults to true enum: - '0' - '1' - 'false' - 'true' 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: application/json: schema: properties: blockConsentModals: description: Whether to automatically block cookie consent modals and popups. type: boolean options: description: 'PDF generation options based on Puppeteer''s PDFOptions interface. Includes properties like `format`, `margin`, `printBackground`, `landscape`, etc.' additionalProperties: false type: object properties: scale: description: Scales the rendering of the web page. Amount must be between `0.1` and `2`. type: number displayHeaderFooter: description: Whether to show the header and footer. type: boolean headerTemplate: description: 'HTML template for the print header. Should be valid HTML with the following classes used to inject values into them: - `date` formatted print date - `title` document title - `url` document location - `pageNumber` current page number - `totalPages` total pages in the document' type: string footerTemplate: description: 'HTML template for the print footer. Has the same constraints and support for special classes as {@link PDFOptions.headerTemplate}.' type: string printBackground: description: Set to `true` to print background graphics. type: boolean landscape: description: Whether to print in landscape orientation. type: boolean pageRanges: description: Paper ranges to print, e.g. `1-5, 8, 11-13`. type: string format: $ref: '#/definitions/PaperFormat' width: description: Sets the width of paper. You can pass in a number or a string with a unit. type: - string - number height: description: Sets the height of paper. You can pass in a number or a string with a unit. type: - string - number preferCSSPageSize: description: 'Give any CSS `@page` size declared in the page priority over what is declared in the `width` or `height` or `format` option.' type: boolean margin: $ref: '#/definitions/PDFMargin' description: Set the PDF margins. path: description: The path to save the file to. type: string omitBackground: description: Hides default white background and allows generating pdfs with transparency. type: boolean tagged: description: Generate tagged (accessible) PDF. type: boolean outline: description: Generate document outline. type: boolean timeout: description: 'Timeout in milliseconds. Pass `0` to disable timeout. The default value can be changed by using {@link Page.setDefaultTimeout}' type: number waitForFonts: description: 'If true, waits for `document.fonts.ready` to resolve. This might require activating the page using {@link Page.bringToFront} if the page is in the background.' type: boolean fullPage: type: boolean addScriptTag: description: 'An array of script tags to add to the page before performing actions. Each object can contain either a `url`, or a `content` property.' type: array items: $ref: '#/definitions/FrameAddScriptTagOptions' addStyleTag: description: 'An array of style tags to add to the page before performing actions. Each object can contain either a `url`, or a `content` property.' type: array items: $ref: '#/definitions/FrameAddStyleTagOptions' authenticate: $ref: '#/definitions/Credentials' description: Credentials for HTTP authentication. Contains `username` and `password` properties. bestAttempt: description: 'When bestAttempt is set to true, browserless will attempt to proceed when "awaited" events fail or timeout. This includes things like goto, waitForSelector, and more.' type: boolean cookies: description: 'An array of cookies to set on the page before navigation. Each cookie object should contain at least `name` and `value` properties.' type: array items: $ref: '#/definitions/CookieParam' emulateMediaType: description: Changes the CSS media type of the page. Accepts values like "screen" or "print". type: string gotoOptions: $ref: '#/definitions/GoToOptions' description: Options to configure the page navigation, such as `timeout` and `waitUntil`. html: description: HTML content to set as the page content instead of navigating to a URL. type: string rejectRequestPattern: description: 'An array of patterns to match against request URLs for automatic rejection. Requests matching these patterns will be aborted.' type: array items: type: string rejectResourceTypes: description: 'An array of resource types to reject during page load. Common types include "image", "stylesheet", "font", "script", etc.' type: array items: enum: - cspviolationreport - document - eventsource - fedcm - fetch - font - image - manifest - media - other - ping - prefetch - preflight - script - signedexchange - stylesheet - texttrack - websocket - xhr type: string requestInterceptors: description: 'An array of request interceptors that can modify or mock network requests. Each interceptor has a `pattern` to match URLs and a `response` to return.' type: array items: description: 'An array of patterns (using `req.url().match(r.pattern)` to match) and their corresponding responses to use in order to fulfill those requests.' type: object properties: pattern: description: 'An array of patterns (using `req.url().match(r.pattern)` to match) and their corresponding responses to use in order to fulfill those requests.' type: string response: additionalProperties: false type: object properties: headers: $ref: '#/definitions/Record%3Cstring%2Cunknown%3E' description: 'Optional response headers. The record values will be converted to string following: Arrays'' values will be mapped to String (Used when you need multiple headers with the same name). Non-arrays will be converted to String.' status: type: number contentType: type: string body: description: 'A string representation of the body to return. Can be a base64-encoded string but please omit any leading content-type data (eg "data:image/png;base64,").' type: string additionalProperties: false required: - pattern - response setExtraHTTPHeaders: description: An object containing additional HTTP headers to send with every request. type: object additionalProperties: type: string setJavaScriptEnabled: description: Whether or not to allow JavaScript to run on the page. type: boolean url: description: The URL to navigate to before performing actions. type: string userAgent: description: The user agent string to use for the page. type: object properties: userAgent: type: string userAgentMetadata: $ref: '#/definitions/Protocol.Emulation.UserAgentMetadata' platform: type: string additionalProperties: false viewport: $ref: '#/definitions/Viewport' description: 'The viewport dimensions and settings for the page. Includes properties like `width`, `height`, `deviceScaleFactor`, etc.' waitForEvent: description: Options for waiting for a specific event to be fired on the page. type: object properties: event: type: string timeout: type: number additionalProperties: false required: - event waitForFunction: description: Options for waiting for a JavaScript function to execute. type: object properties: fn: description: The function, or statement, to be evaluated in browser context type: string polling: description: 'An interval at which the pageFunction is executed, defaults to raf. If polling is a number, then it is treated as an interval in milliseconds at which the function would be executed. If polling is a string, then it can be one of the following values: "raf" or "mutation"' type: - string - number timeout: description: 'Maximum time to wait for in milliseconds. Defaults to 30000 (30 seconds). Pass 0 to disable timeout.' type: number additionalProperties: false required: - fn waitForSelector: description: Options for waiting for a specific CSS selector to appear on the page. type: object properties: hidden: type: boolean selector: type: string timeout: type: number visible: type: boolean additionalProperties: false required: - selector waitForTimeout: description: The amount of time in milliseconds to wait before proceeding. type: number type: object 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: /pdf tags: - Browser REST APIs /screenshot: post: definitions: {} description: 'A JSON-based API for getting a screenshot binary from either a supplied "url" or "html" payload in your request. Many options exist including cookies, user-agents, setting timers and network mocks. **Note:** This endpoint is also available at: `/chromium/screenshot` for backwards compatibility.' 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: externalProxyServer schema: description: 'External proxy server URL for user-provided proxies. Format: http(s)://[username:password@]host:port When set, routes requests through this proxy instead of built-in residential proxies.' type: string - 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.' 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: proxy schema: description: The type of proxy to use, currently just 'residential' is supported type: string const: residential - in: query name: proxyCity schema: description: 'The city to use for the proxy. Available cities: https://production-sfo.browserless.io/proxy/cities?token=YOUR_TOKEN Documentation: https://docs.browserless.io/baas/features/proxies#built-in-residential-proxy' type: string - in: query name: proxyCountry schema: description: 'A two-letter country code for the proxy configuration. Supported codes: US, GB, FR, DE, etc. Full list: https://docs.browserless.io/bql-schema/types/enums/country-type' type: string - in: query name: proxyLocaleMatch schema: description: 'Sets the browser''s language to match the proxy''s geographic location. Recommended when using proxyCountry to ensure websites render content, currency, and formatting in the local language. Default is English (en-US).' enum: - '0' - '1' - 'false' - 'true' type: string - in: query name: proxyPreset schema: description: 'A preset code for website-specific proxy routing. Maps to specific proxy vendors internally for optimal access to certain websites. Format: "px_" (e.g., "px_gov01", "px_amazon01")' type: string - in: query name: proxyState schema: description: The state or province to use for the proxy, whitespace must be replaced with underscores type: string - in: query name: proxySticky schema: description: Whether or not to use the same IP for all requests, defaults to true enum: - '0' - '1' - 'false' - 'true' 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: application/json: schema: properties: blockConsentModals: description: Whether to automatically block cookie consent modals and popups. type: boolean options: $ref: '#/definitions/ScreenshotOptions' description: 'Screenshot options based on Puppeteer''s ScreenshotOptions interface. Includes properties like `type`, `quality`, `fullPage`, `clip`, etc.' addScriptTag: description: 'An array of script tags to add to the page before performing actions. Each object can contain either a `url`, or a `content` property.' type: array items: $ref: '#/definitions/FrameAddScriptTagOptions' addStyleTag: description: 'An array of style tags to add to the page before performing actions. Each object can contain either a `url`, or a `content` property.' type: array items: $ref: '#/definitions/FrameAddStyleTagOptions' authenticate: $ref: '#/definitions/Credentials' description: Credentials for HTTP authentication. Contains `username` and `password` properties. bestAttempt: description: 'When bestAttempt is set to true, browserless will attempt to proceed when "awaited" events fail or timeout. This includes things like goto, waitForSelector, and more.' type: boolean cookies: description: 'An array of cookies to set on the page before navigation. Each cookie object should contain at least `name` and `value` properties.' type: array items: $ref: '#/definitions/CookieParam' emulateMediaType: description: Changes the CSS media type of the page. Accepts values like "screen" or "print". type: string gotoOptions: $ref: '#/definitions/GoToOptions' description: Options to configure the page navigation, such as `timeout` and `waitUntil`. html: description: HTML content to set as the page content instead of navigating to a URL. type: string rejectRequestPattern: description: 'An array of patterns to match against request URLs for automatic rejection. Requests matching these patterns will be aborted.' type: array items: type: string rejectResourceTypes: description: 'An array of resource types to reject during page load. Common types include "image", "stylesheet", "font", "script", etc.' type: array items: enum: - cspviolationreport - document - eventsource - fedcm - fetch - font - image - manifest - media - other - ping - prefetch - preflight - script - signedexchange - stylesheet - texttrack - websocket - xhr type: string requestInterceptors: description: 'An array of request interceptors that can modify or mock network requests. Each interceptor has a `pattern` to match URLs and a `response` to return.' type: array items: description: 'An array of patterns (using `req.url().match(r.pattern)` to match) and their corresponding responses to use in order to fulfill those requests.' type: object properties: pattern: description: 'An array of patterns (using `req.url().match(r.pattern)` to match) and their corresponding responses to use in order to fulfill those requests.' type: string response: additionalProperties: false type: object properties: headers: $ref: '#/definitions/Record%3Cstring%2Cunknown%3E' description: 'Optional response headers. The record values will be converted to string following: Arrays'' values will be mapped to String (Used when you need multiple headers with the same name). Non-arrays will be converted to String.' status: type: number contentType: type: string body: description: 'A string representation of the body to return. Can be a base64-encoded string but please omit any leading content-type data (eg "data:image/png;base64,").' type: string additionalProperties: false required: - pattern - response setExtraHTTPHeaders: description: An object containing additional HTTP headers to send with every request. type: object additionalProperties: type: string setJavaScriptEnabled: description: Whether or not to allow JavaScript to run on the page. type: boolean url: description: The URL to navigate to before performing actions. type: string userAgent: description: The user agent string to use for the page. type: object properties: userAgent: type: string userAgentMetadata: $ref: '#/definitions/Protocol.Emulation.UserAgentMetadata' platform: type: string additionalProperties: false viewport: $ref: '#/definitions/Viewport' description: 'The viewport dimensions and settings for the page. Includes properties like `width`, `height`, `deviceScaleFactor`, etc.' waitForEvent: description: Options for waiting for a specific event to be fired on the page. type: object properties: event: type: string timeout: type: number additionalProperties: false required: - event waitForFunction: description: Options for waiting for a JavaScript function to execute. type: object properties: fn: description: The function, or statement, to be evaluated in browser context type: string polling: description: 'An interval at which the pageFunction is executed, defaults to raf. If polling is a number, then it is treated as an interval in milliseconds at which the function would be executed. If polling is a string, then it can be one of the following values: "raf" or "mutation"' type: - string - number timeout: description: 'Maximum time to wait for in milliseconds. Defaults to 30000 (30 seconds). Pass 0 to disable timeout.' type: number additionalProperties: false required: - fn waitForSelector: description: Options for waiting for a specific CSS selector to appear on the page. type: object properties: hidden: type: boolean selector: type: string timeout: type: number visible: type: boolean additionalProperties: false required: - selector waitForTimeout: description: The amount of time in milliseconds to wait before proceeding. type: number scrollPage: description: 'Whether to scroll through the entire page before capturing content. Useful for triggering lazy-loaded content.' type: boolean selector: description: A CSS selector to target a specific element instead of the full page. type: string type: object 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: /screenshot tags: - Browser REST APIs /search: post: definitions: {} description: Search the web and optionally scrape result pages. Accepts a query, performs a web search via SearXNG, and optionally scrapes each result URL — returning structured, LLM-ready data (markdown, HTML, links, or screenshots). parameters: - in: query name: timeout schema: description: The timeout for the search operation in milliseconds. type: number - in: query name: token schema: description: The API token for authenticating the request. type: string requestBody: content: application/json: schema: properties: query: description: The search query string. type: string limit: description: Maximum number of results per source. Defaults to `10`. Capped by plan limits. type: number lang: description: Language code for results (e.g., `"en"`, `"es"`, `"de"`). Defaults to `"en"`. type: string location: description: City or region to narrow geo-targeting (e.g., `"San Francisco"`). Use with `country`. type: string country: description: ISO 3166-1 alpha-2 country code for geo-targeted results (e.g., `"us"`, `"gb"`, `"de"`). type: string tbs: $ref: '#/definitions/TimeBasedOptions' description: Time-based filter. Accepts `"day"`, `"week"`, `"month"`, `"year"`, or raw Google TBS syntax (`"qdr:d"`, `"qdr:w"`, `"qdr:m"`, `"qdr:y"`). categories: description: Content category filters. Restricts results to `"github"` repos, `"research"` papers, or `"pdf"` documents. type: array items: enum: - github - pdf - research type: string sources: description: Sources to search. Defaults to `["web"]`. Also supports `"news"` and `"images"`. type: array items: enum: - images - news - web type: string timeout: description: Request timeout in milliseconds. type: number scrapeOptions: description: When provided, fetches and processes each result URL into structured content. type: object properties: formats: type: array items: enum: - html - links - markdown - screenshot type: string stripNonContentTags: type: boolean onlyMainContent: type: boolean removeBase64Images: type: boolean includeTags: type: array items: type: string excludeTags: type: array items: type: string additionalProperties: false required: - formats type: object required: - query 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: /search tags: - Browser 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: - Browser 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: - Browser REST APIs /smart-scrape: post: definitions: {} description: Intelligently scrapes a URL using cascading strategies (HTTP fetch, proxy, headless browser, etc). parameters: - in: query name: profile schema: description: 'Optional name of an authentication profile to hydrate into the browser before scraping. The profile''s cookies, localStorage, and IndexedDB entries are loaded into the session before navigation. Forces the browser strategy.' type: string - in: query name: timeout schema: description: The timeout for the scrape operation in milliseconds type: number - in: query name: token schema: description: The API token for authenticating the request. Can also be provided in the `Authorization` header as a Bearer token. If both are provided, the `Authorization` header takes precedence. If no token is provided, the route will attempt to authenticate the request using any legacy authentication methods (e.g. cookie-based sessions) before rejecting the request as unauthorized. type: string requestBody: content: application/json: schema: properties: url: description: The URL to scrape. Must be an http or https URL. type: string formats: description: 'Output formats to include in the response. Accepts an array of format strings such as `["markdown", "screenshot"]`. When `screenshot` or `pdf` is included, a browser strategy is forced. Mirrors the Firecrawl "formats" convention. - `markdown` – page content converted to markdown - `html` – cleaned HTML (returned by default in `content`, this is a no-op convenience value) - `screenshot` – full-page screenshot as base64-encoded PNG (forces browser strategy) - `pdf` – PDF of the page as base64-encoded string (forces browser strategy) - `links` – list of links extracted from the page' default: - html type: array items: enum: - html - links - markdown - pdf - screenshot type: string type: object required: - url responses: '200': content: application/json: schema: description: An HTML payload of the scraped page content. type: object properties: ok: description: Whether the scrape was successful or not. type: boolean statusCode: description: The HTTP status code of the response, or null if the scrape failed before an HTTP response was received (e.g. due to a network error or captcha). type: number content: description: The content of the scraped page. This will be a string for HTML content, or a parsed JSON object if the content type is JSON. Will be null if the scrape was unsuccessful. anyOf: - $ref: '#/definitions/Record%3Cstring%2Cunknown%3E' - type: string contentType: description: The content type of the scraped page, or null if the scrape was unsuccessful or the content type was unavailable. If the scrape was successful and the content type is JSON, the `content` field will contain the parsed JSON object rather than a string. type: string headers: $ref: '#/definitions/Record%3Cstring%2Cstring%3E' description: The HTTP response headers returned by the site, or an empty object if unavailable. strategy: description: The strategy that ultimately succeeded in scraping the page, or the strategy that was being attempted when the scrape failed. type: string attempted: description: The strategies that were attempted during the scrape, in order. type: array items: type: string message: description: An error message describing why the scrape failed, or null if the scrape was successful. type: string screenshot: description: A base64-encoded full-page PNG screenshot, present when `"screenshot"` is in `formats` and the scrape succeeded. type: string pdf: description: A base64-encoded PDF of the page, present when `"pdf"` is in `formats` and the scrape succeeded. type: string markdown: description: The page content converted to markdown, present when `"markdown"` is in `formats` and the scrape succeeded. type: string links: description: A list of links found on the page, present when `"links"` is in `formats` and the scrape succeeded. type: array items: type: string additionalProperties: false required: - attempted - content - contentType - headers - links - markdown - message - ok - pdf - screenshot - statusCode - strategy definitions: Record: type: object additionalProperties: false Record: type: object additionalProperties: false $schema: http://json-schema.org/draft-07/schema# description: An HTML payload of the scraped page content. '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: /smart-scrape tags: - Browser REST APIs /stealth/bql?(/*): post: definitions: {} description: Parses and executes BrowserQL requests, powered by the BrowserQL Editor or by other API integrations. See the BrowserQL Editor for more documentation on this API. 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: blockConsentModals schema: description: Whether to automatically block cookie consent modals and popups. type: boolean - in: query name: externalProxyServer schema: description: 'External proxy server URL for user-provided proxies. Format: http(s)://[username:password@]host:port When set, routes requests through this proxy instead of built-in residential proxies.' type: string - in: query name: humanlike schema: description: 'Whether to enable human-like behavior for interactions. When true, actions like typing and clicking will have randomized delays.' 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: proxy schema: description: The type of proxy to use, currently just 'residential' is supported type: string const: residential - in: query name: proxyCity schema: description: 'The city to use for the proxy. Available cities: https://production-sfo.browserless.io/proxy/cities?token=YOUR_TOKEN Documentation: https://docs.browserless.io/baas/features/proxies#built-in-residential-proxy' type: string - in: query name: proxyCountry schema: description: 'A two-letter country code for the proxy configuration. Supported codes: US, GB, FR, DE, etc. Full list: https://docs.browserless.io/bql-schema/types/enums/country-type' type: string - in: query name: proxyLocaleMatch schema: description: 'Sets the browser''s language to match the proxy''s geographic location. Recommended when using proxyCountry to ensure websites render content, currency, and formatting in the local language. Default is English (en-US).' enum: - '0' - '1' - 'false' - 'true' type: string - in: query name: proxyPreset schema: description: 'A preset code for website-specific proxy routing. Maps to specific proxy vendors internally for optimal access to certain websites. Format: "px_" (e.g., "px_gov01", "px_amazon01")' type: string - in: query name: proxyState schema: description: The state or province to use for the proxy, whitespace must be replaced with underscores type: string - in: query name: proxySticky schema: description: Whether or not to use the same IP for all requests, defaults to true enum: - '0' - '1' - 'false' - 'true' type: string - in: query name: replay schema: description: 'Whether to enable session recording for replay. When true, the session will be recorded and can be replayed later.' 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 BrowserQL query string to execute. type: string operationName: description: The name of the operation to execute if the query contains multiple operations. type: string variables: description: Variables to pass to the BrowserQL query. type: object additionalProperties: {} type: object required: - query 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: /stealth/bql?(/*) tags: - Browser REST APIs /chrome/bql?(/*): post: definitions: {} description: Parses and executes BrowserQL requests, powered by the BrowserQL Editor or by other API integrations. See the BrowserQL Editor for more documentation on this API. 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: blockConsentModals schema: description: Whether to automatically block cookie consent modals and popups. type: boolean - in: query name: externalProxyServer schema: description: 'External proxy server URL for user-provided proxies. Format: http(s)://[username:password@]host:port When set, routes requests through this proxy instead of built-in residential proxies.' type: string - in: query name: humanlike schema: description: 'Whether to enable human-like behavior for interactions. When true, actions like typing and clicking will have randomized delays.' 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: proxy schema: description: The type of proxy to use, currently just 'residential' is supported type: string const: residential - in: query name: proxyCity schema: description: 'The city to use for the proxy. Available cities: https://production-sfo.browserless.io/proxy/cities?token=YOUR_TOKEN Documentation: https://docs.browserless.io/baas/features/proxies#built-in-residential-proxy' type: string - in: query name: proxyCountry schema: description: 'A two-letter country code for the proxy configuration. Supported codes: US, GB, FR, DE, etc. Full list: https://docs.browserless.io/bql-schema/types/enums/country-type' type: string - in: query name: proxyLocaleMatch schema: description: 'Sets the browser''s language to match the proxy''s geographic location. Recommended when using proxyCountry to ensure websites render content, currency, and formatting in the local language. Default is English (en-US).' enum: - '0' - '1' - 'false' - 'true' type: string - in: query name: proxyPreset schema: description: 'A preset code for website-specific proxy routing. Maps to specific proxy vendors internally for optimal access to certain websites. Format: "px_" (e.g., "px_gov01", "px_amazon01")' type: string - in: query name: proxyState schema: description: The state or province to use for the proxy, whitespace must be replaced with underscores type: string - in: query name: proxySticky schema: description: Whether or not to use the same IP for all requests, defaults to true enum: - '0' - '1' - 'false' - 'true' type: string - in: query name: replay schema: description: 'Whether to enable session recording for replay. When true, the session will be recorded and can be replayed later.' 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 BrowserQL query string to execute. type: string operationName: description: The name of the operation to execute if the query contains multiple operations. type: string variables: description: Variables to pass to the BrowserQL query. type: object additionalProperties: {} type: object required: - query 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: /chrome/bql?(/*) tags: - Browser REST APIs /chromium/bql?(/*): post: definitions: {} description: Parses and executes BrowserQL requests, powered by the BrowserQL Editor or by other API integrations. See the BrowserQL Editor for more documentation on this API. 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: blockConsentModals schema: description: Whether to automatically block cookie consent modals and popups. type: boolean - in: query name: externalProxyServer schema: description: 'External proxy server URL for user-provided proxies. Format: http(s)://[username:password@]host:port When set, routes requests through this proxy instead of built-in residential proxies.' type: string - in: query name: humanlike schema: description: 'Whether to enable human-like behavior for interactions. When true, actions like typing and clicking will have randomized delays.' 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: proxy schema: description: The type of proxy to use, currently just 'residential' is supported type: string const: residential - in: query name: proxyCity schema: description: 'The city to use for the proxy. Available cities: https://production-sfo.browserless.io/proxy/cities?token=YOUR_TOKEN Documentation: https://docs.browserless.io/baas/features/proxies#built-in-residential-proxy' type: string - in: query name: proxyCountry schema: description: 'A two-letter country code for the proxy configuration. Supported codes: US, GB, FR, DE, etc. Full list: https://docs.browserless.io/bql-schema/types/enums/country-type' type: string - in: query name: proxyLocaleMatch schema: description: 'Sets the browser''s language to match the proxy''s geographic location. Recommended when using proxyCountry to ensure websites render content, currency, and formatting in the local language. Default is English (en-US).' enum: - '0' - '1' - 'false' - 'true' type: string - in: query name: proxyPreset schema: description: 'A preset code for website-specific proxy routing. Maps to specific proxy vendors internally for optimal access to certain websites. Format: "px_" (e.g., "px_gov01", "px_amazon01")' type: string - in: query name: proxyState schema: description: The state or province to use for the proxy, whitespace must be replaced with underscores type: string - in: query name: proxySticky schema: description: Whether or not to use the same IP for all requests, defaults to true enum: - '0' - '1' - 'false' - 'true' type: string - in: query name: replay schema: description: 'Whether to enable session recording for replay. When true, the session will be recorded and can be replayed later.' 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 BrowserQL query string to execute. type: string operationName: description: The name of the operation to execute if the query contains multiple operations. type: string variables: description: Variables to pass to the BrowserQL query. type: object additionalProperties: {} type: object required: - query 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: /chromium/bql?(/*) tags: - Browser 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: - Browser REST APIs /crawl/*: delete: definitions: {} description: Cancel a running crawl job by its ID. Any pages already completed remain available for retrieval. Returns a 409 if the crawl is already in a terminal state. parameters: - in: query name: token schema: description: The API token for authenticating the request. 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: /crawl/* tags: - Browser REST APIs get: definitions: {} description: Get the status of a crawl job and its paginated page results. Returns progress counters, per-page metadata with content URLs, and a `next` URL for offset-based pagination via the `skip` parameter. parameters: - in: query name: skip schema: description: The number of pages to skip for pagination. type: number - in: query name: token schema: description: The API token for authenticating the request. type: string requestBody: content: {} responses: '200': content: application/json: schema: type: object properties: status: $ref: '#/definitions/CrawlStatus' total: type: number completed: type: number failed: type: number expiresAt: type: string next: type: string data: type: array items: $ref: '#/definitions/CrawlPageResponse' additionalProperties: false required: - completed - data - expiresAt - failed - next - status - total definitions: CrawlStatus: enum: - cancelled - completed - failed - in-progress type: string CrawlPageResponse: type: object properties: status: $ref: '#/definitions/PageStatus' contentUrl: type: string metadata: type: object properties: title: type: string description: type: string language: type: string scrapedAt: type: string sourceURL: type: string statusCode: type: number error: type: string additionalProperties: false required: - description - error - language - scrapedAt - sourceURL - statusCode - title additionalProperties: false required: - contentUrl - metadata - status PageStatus: enum: - cancelled - completed - failed - in-progress - queued type: string $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: /crawl/* tags: - Browser REST APIs /crawl: get: definitions: {} description: List all crawl jobs for the authenticated token. Returns an array of crawl summaries with status, progress counters, and timestamps. Supports cursor-based pagination via the `nextCursor` field. parameters: - in: query name: cursor schema: description: Cursor for fetching the next page of results. type: string - in: query name: limit schema: description: Maximum number of crawls to return per page (1–100, default 20). type: number - in: query name: status schema: description: 'Filter crawls by status: in-progress, completed, failed, or cancelled.' type: string - in: query name: token schema: description: The API token for authenticating the request. type: string requestBody: content: {} responses: '200': content: application/json: schema: type: object properties: crawls: type: array items: $ref: '#/definitions/CrawlListItem' nextCursor: type: string additionalProperties: false required: - crawls - nextCursor definitions: CrawlListItem: type: object properties: id: type: string url: type: string status: $ref: '#/definitions/CrawlStatus' total: type: number completed: type: number createdAt: type: string completedAt: type: string additionalProperties: false required: - completed - completedAt - createdAt - id - status - total - url CrawlStatus: enum: - cancelled - completed - failed - in-progress type: string $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: /crawl tags: - Browser REST APIs post: definitions: {} description: Start an asynchronous crawl job that spiders a website and scrapes every discovered page. Returns a crawl ID and status URL for polling results via GET /crawl/{id}. Supports depth control, path filtering, sitemap strategies, and webhook notifications. parameters: - in: query name: profile schema: description: 'Optional name of an authentication profile to hydrate into the browser before each page is scraped. The profile''s cookies, localStorage, and IndexedDB entries are loaded into the session before navigation. Forces the browser strategy for every page.' type: string - in: query name: token schema: description: The API token for authenticating the request. type: string requestBody: content: application/json: schema: properties: url: description: The URL to crawl. Must be a valid http or https URL. type: string limit: description: Maximum number of pages to crawl. Clamped to your plan's limit. default: 100 minimum: 1 type: number maxDepth: description: Maximum link-follow depth from the root URL. default: 5 minimum: 0 type: number maxRetries: description: Number of retry attempts per failed page. default: 1 minimum: 0 type: number allowExternalLinks: description: Whether to follow links to external domains. default: false type: boolean allowSubdomains: description: Whether to follow links to subdomains of the root URL. default: false type: boolean sitemap: description: Sitemap handling strategy. default: auto enum: - auto - force - skip type: string includePaths: description: Regex patterns for URL paths to include. default: [] type: array items: type: string excludePaths: description: Regex patterns for URL paths to exclude. default: [] type: array items: type: string delay: description: Delay between requests in milliseconds. default: 200 minimum: 0 type: number scrapeOptions: description: Options controlling how each page is scraped. type: object properties: formats: description: Output formats for scraped content. default: - markdown type: array items: enum: - html - markdown - rawText type: string onlyMainContent: description: Whether to extract only the main content of the page. default: true type: boolean includeTags: description: HTML tag selectors to include. default: [] type: array items: type: string excludeTags: description: HTML tag selectors to exclude. default: [] type: array items: type: string waitFor: description: Time in ms to wait after page load before scraping. default: 0 minimum: 0 type: number headers: description: Custom HTTP headers to send with each request. type: object additionalProperties: type: string timeout: description: Navigation timeout in milliseconds. default: 150000 minimum: 1000 maximum: 180000 type: number additionalProperties: false webhook: description: Webhook configuration for crawl event notifications. type: object properties: url: description: The HTTPS URL to send webhook events to. type: string events: description: Which events to send. default: - completed type: array items: enum: - completed - failed - page type: string additionalProperties: false required: - url type: object required: - url responses: '200': content: application/json: schema: type: object properties: success: type: boolean id: type: string url: type: string additionalProperties: false required: - id - success - url $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: /crawl tags: - Browser REST APIs definitions: PuppeteerLifeCycleEvent: enum: - domcontentloaded - load - networkidle0 - networkidle2 type: string CrawlListItem: type: object properties: id: type: string url: type: string status: $ref: '#/definitions/CrawlStatus' total: type: number completed: type: number createdAt: type: string completedAt: type: string additionalProperties: false required: - completed - completedAt - createdAt - id - status - total - url ScrapeDebugOptions: type: object properties: console: type: boolean cookies: type: boolean html: type: boolean network: type: boolean screenshot: type: boolean additionalProperties: false OutBoundRequest: type: object properties: headers: {} method: type: string url: type: string additionalProperties: false required: - headers - method - url Viewport: type: object properties: width: description: The page width in CSS pixels. type: number height: description: The page height in CSS pixels. type: number deviceScaleFactor: description: 'Specify device scale factor. See {@link https://developer.mozilla.org/en-US/docs/Web/API/Window/devicePixelRatio devicePixelRatio} for more info.' type: number isMobile: description: Whether the `meta viewport` tag is taken into account. type: boolean isLandscape: description: Specifies if the viewport is in landscape mode. type: boolean hasTouch: description: Specify if the viewport supports touch events. type: boolean additionalProperties: false required: - height - width ScreenshotClip: type: object properties: scale: type: number width: description: the width of the element in pixels. type: number height: description: the height of the element in pixels. type: number x: type: number y: type: number additionalProperties: false required: - height - width - x - y PDFMargin: type: object properties: top: type: - string - number bottom: type: - string - number left: type: - string - number right: type: - string - number additionalProperties: false CookiePriority: description: 'Represents the cookie''s ''Priority'' status: https://tools.ietf.org/html/draft-west-cookie-priority-00' enum: - High - Low - Medium type: string Cookie: description: Represents a cookie object. type: object properties: path: description: Cookie path. type: string expires: description: 'Cookie expiration date as the number of seconds since the UNIX epoch. Set to `-1` for session cookies' type: number size: description: Cookie size. type: number secure: description: True if cookie is secure. type: boolean session: description: True in case of session cookie. type: boolean partitionKeyOpaque: description: True if cookie partition key is opaque. Supported only in Chrome. type: boolean name: description: Cookie name. type: string value: description: Cookie value. type: string domain: description: Cookie domain. type: string httpOnly: description: True if cookie is http-only. type: boolean sameSite: description: Cookie SameSite type. enum: - Default - Lax - None - Strict type: string priority: description: Cookie Priority. Supported only in Chrome. enum: - High - Low - Medium type: string sameParty: type: boolean sourceScheme: description: Cookie source scheme type. Supported only in Chrome. enum: - NonSecure - Secure - Unset type: string partitionKey: description: 'Cookie partition key. In Chrome, it matches the top-level site the partitioned cookie is available in. In Firefox, it matches the source origin in the {@link https://w3c.github.io/webdriver-bidi/#type-storage-PartitionKey PartitionKey}.' anyOf: - $ref: '#/definitions/CookiePartitionKey' - type: string additionalProperties: false required: - domain - expires - name - path - secure - session - size - value Protocol.Emulation.UserAgentBrandVersion: description: Used to specify User Agent Client Hints to emulate. See https://wicg.github.io/ua-client-hints type: object properties: brand: type: string version: type: string additionalProperties: false required: - brand - version CrawlPageResponse: type: object properties: status: $ref: '#/definitions/PageStatus' contentUrl: type: string metadata: type: object properties: title: type: string description: type: string language: type: string scrapedAt: type: string sourceURL: type: string statusCode: type: number error: type: string additionalProperties: false required: - description - error - language - scrapedAt - sourceURL - statusCode - title additionalProperties: false required: - contentUrl - metadata - status 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 InBoundRequest: type: object properties: headers: {} status: type: number url: type: string additionalProperties: false required: - headers - status - url Protocol.Emulation.UserAgentMetadata: description: 'Used to specify User Agent Client Hints to emulate. See https://wicg.github.io/ua-client-hints Missing optional values will be filled in by the target with what it would normally use.' type: object properties: brands: description: Brands appearing in Sec-CH-UA. type: array items: $ref: '#/definitions/Protocol.Emulation.UserAgentBrandVersion' fullVersionList: description: Brands appearing in Sec-CH-UA-Full-Version-List. type: array items: $ref: '#/definitions/Protocol.Emulation.UserAgentBrandVersion' fullVersion: type: string platform: type: string platformVersion: type: string architecture: type: string model: type: string mobile: type: boolean bitness: type: string wow64: type: boolean formFactors: description: 'Used to specify User Agent form-factor values. See https://wicg.github.io/ua-client-hints/#sec-ch-ua-form-factors' type: array items: type: string additionalProperties: false required: - architecture - mobile - model - platform - platformVersion ContextValue: anyOf: - type: array items: $ref: '#/definitions/ContextValue' - type: object additionalProperties: $ref: '#/definitions/ContextValue' - type: - 'null' - string - number - boolean CookieSourceScheme: description: 'Represents the source scheme of the origin that originally set the cookie. A value of "Unset" allows protocol clients to emulate legacy cookie scope for the scheme. This is a temporary ability and it will be removed in the future.' enum: - NonSecure - Secure - Unset type: string ScrapeElementSelector: type: object properties: selector: type: string timeout: type: number additionalProperties: false required: - selector CookiePartitionKey: description: Represents a cookie partition key in Chrome. type: object properties: sourceOrigin: description: 'The site of the top-level URL the browser was visiting at the start of the request to the endpoint that set the cookie. In Chrome, maps to the CDP''s `topLevelSite` partition key.' type: string hasCrossSiteAncestor: description: 'Indicates if the cookie has any ancestors that are cross-site to the topLevelSite. Supported only in Chrome.' type: boolean additionalProperties: false required: - sourceOrigin CrawlStatus: enum: - cancelled - completed - failed - in-progress type: string AbortSignal: type: object properties: aborted: type: boolean onabort: anyOf: - type: object additionalProperties: false - type: 'null' reason: {} additionalProperties: false required: - aborted - onabort - reason PageStatus: enum: - cancelled - completed - failed - in-progress - queued type: string CookieParam: description: 'Cookie parameter object used to set cookies in the page-level cookies API.' type: object properties: name: description: Cookie name. type: string value: description: Cookie value. type: string url: description: 'The request-URI to associate with the setting of the cookie. This value can affect the default domain, path, and source scheme values of the created cookie.' type: string domain: description: Cookie domain. type: string path: description: Cookie path. type: string secure: description: True if cookie is secure. type: boolean httpOnly: description: True if cookie is http-only. type: boolean sameSite: description: Cookie SameSite type. enum: - Default - Lax - None - Strict type: string expires: description: Cookie expiration date, session cookie if not set type: number priority: description: Cookie Priority. Supported only in Chrome. enum: - High - Low - Medium type: string sameParty: type: boolean sourceScheme: description: Cookie source scheme type. Supported only in Chrome. enum: - NonSecure - Secure - Unset type: string partitionKey: description: 'Cookie partition key. In Chrome, it matches the top-level site the partitioned cookie is available in. In Firefox, it matches the source origin in the {@link https://w3c.github.io/webdriver-bidi/#type-storage-PartitionKey PartitionKey}.' anyOf: - $ref: '#/definitions/CookiePartitionKey' - type: string additionalProperties: false required: - name - value ScreenshotOptions: type: object properties: optimizeForSpeed: type: boolean type: enum: - jpeg - png - webp type: string quality: description: Quality of the image, between 0-100. Not applicable to `png` images. type: number fromSurface: description: Capture the screenshot from the surface, rather than the view. type: boolean fullPage: description: When `true`, takes a screenshot of the full page. type: boolean omitBackground: description: Hides default white background and allows capturing screenshots with transparency. type: boolean path: description: 'The file path to save the image to. The screenshot type will be inferred from file extension. If path is a relative path, then it is resolved relative to current working directory. If no path is provided, the image won''t be saved to the disk.' type: string clip: description: Specifies the region of the page/element to clip. $ref: '#/definitions/ScreenshotClip' encoding: description: Encoding of the image. enum: - base64 - binary type: string captureBeyondViewport: description: Capture the screenshot beyond the viewport. type: boolean additionalProperties: false FrameAddScriptTagOptions: type: object properties: url: description: URL of the script to be added. type: string path: description: Path to a JavaScript file to be injected into the frame. type: string content: description: JavaScript to be injected into the frame. type: string type: description: Sets the `type` of the script. Use `module` in order to load an ES2015 module. type: string id: description: Sets the `id` of the script. type: string additionalProperties: false FrameAddStyleTagOptions: type: object properties: url: description: the URL of the CSS file to be added. type: string path: description: The path to a CSS file to be injected into the frame. type: string content: description: Raw CSS content to be injected into the frame. type: string additionalProperties: false JSONSchema: type: object properties: code: type: string context: type: object additionalProperties: $ref: '#/definitions/ContextValue' additionalProperties: false required: - code TimeBasedOptions: type: string enum: - day - week - month - year - day - week - month - year Credentials: type: object properties: username: type: string password: type: string additionalProperties: false required: - password - username 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 PaperFormat: description: All the valid paper format types when printing a PDF. enum: - A0 - A1 - A2 - A3 - A4 - A5 - A6 - LEDGER - LEGAL - LETTER - Ledger - Legal - Letter - TABLOID - Tabloid - a0 - a1 - a2 - a3 - a4 - a5 - a6 - ledger - legal - letter - tabloid type: string GoToOptions: type: object properties: referer: description: 'If provided, it will take preference over the referer header value set by {@link Page.setExtraHTTPHeaderspage.setExtraHTTPHeaders()}.' type: string referrerPolicy: description: 'If provided, it will take preference over the referer-policy header value set by {@link Page.setExtraHTTPHeaderspage.setExtraHTTPHeaders()}.' type: string timeout: description: 'Maximum wait time in milliseconds. Pass 0 to disable the timeout. The default value can be changed by using the {@link Page.setDefaultTimeout} or {@link Page.setDefaultNavigationTimeout} methods.' type: number waitUntil: description: 'When to consider waiting succeeds. Given an array of event strings, waiting is considered to be successful after all events have been fired.' anyOf: - type: array items: $ref: '#/definitions/PuppeteerLifeCycleEvent' - enum: - domcontentloaded - load - networkidle0 - networkidle2 type: string signal: description: A signal object that allows you to cancel the call. $ref: '#/definitions/AbortSignal' additionalProperties: false CookieSameSite: description: 'Represents the cookie''s ''SameSite'' status: https://tools.ietf.org/html/draft-west-first-party-cookies' enum: - Default - Lax - None - Strict type: string