{ "customSiteTitle": "Browserless Documentation", "info": { "title": "Browserless", "version": "2.54.2", "description": "This is the API reference for **Browserless Enterprise and Cloud** deployments. You'll find endpoints for capturing screenshots and PDFs, scraping content, running custom browser functions, solving CAPTCHAs, bypassing bot detection with stealth browsing, managing authenticated browser profiles, and orchestrating crawls.\n\nThe API includes REST endpoints (JSON in, JSON or binary out), WebSocket connections for direct CDP/Playwright/Puppeteer access, and [CDP extensions](https://docs.browserless.io/open-api#tag/CDP-Extensions) that expose Browserless-specific commands like `liveURL`, `solveCaptcha`, and `saveProfile`. For the open-source container API, see the [GitHub repository](https://github.com/browserless/browserless).\n\n## Just Getting Started?\n\nCheck out the [Quick Start guide](https://docs.browserless.io/baas/start) to launch your first session, or explore the [BrowserQL IDE](https://docs.browserless.io/browserql/overview) for a GraphQL-based automation workflow.\n\n## Base URL\n\nAll API requests go to your deployment's base URL. For Browserless Cloud:\n\n```plaintext\nhttps://production-sfo.browserless.io\n```\n\nSelf-hosted Enterprise deployments use the host and port where the container is running (default `http://localhost:3000`).\n\n## Authentication\n\nInclude your API token as a query parameter on every request:\n\n```plaintext\nhttps://production-sfo.browserless.io/chromium/content?token=YOUR_API_TOKEN\n```\n\nTokens are managed from the [Account dashboard](https://www.browserless.io/account). Self-hosted deployments set the token via the `TOKEN` environment variable. See [connection details](https://docs.browserless.io/baas/connection) for all authentication options.\n\n## Changelog\n\nFor release notes and version history, see the [Enterprise Changelog](https://docs.browserless.io/enterprise/changelog).\n\n## Software keys\n\nSelf-hosted Enterprise deployments use time-limited software keys for offline licensing. No external connections or callbacks are required. Keys are cryptographically secure and can't be reverse engineered. When a key expires, the container exits with a semantic error code.\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```" }, "openapi": "3.0.0", "paths": { "/screenshot": { "post": { "description": "Returns a screenshot binary from a `url` or `html` payload.\n\"url\" or \"html\" payload in your request. Many options exist including\ncookies, user-agents, setting timers and network mocks.\n\n**Note:** This is the preferred endpoint. The `/chromium/screenshot` route is equivalent.", "parameters": [ { "in": "query", "name": "allowedDomains", "schema": { "description": "Optional per-connection narrowing of the integration's allowed-domain list.\nExtracted from the JSON `allowedDomains` query parameter. Can only narrow the\nintegration's domains, never widen them.", "type": "array", "items": { "type": "string" } } }, { "in": "query", "name": "blockAds", "schema": { "description": "Whether or not to load ad-blocking extensions for the session.\nThis currently uses uBlock-Lite and may cause certain sites\nto not load properly.", "type": "boolean" } }, { "in": "query", "name": "blockAdsInclude", "schema": { "description": "Restrict blockAds to a specific set of uBlock ruleset ids (comma-separated\nlist or JSON array). Only applies when `blockAds` is true. Fewer rulesets\nmeans a faster browser launch under load; omit to load the full default set.", "type": "string" } }, { "in": "query", "name": "credentials", "schema": { "$ref": "#/components/schemas/StringRecord", "description": "Optional alias → `op://…` reference map for the integration above. Extracted\nfrom the JSON `credentials` query parameter. References are not secret;\nresolved values are never stored here. Optional — a connection can also pass\nraw `op://…` references straight to Browserless.loadSecret." } }, { "in": "query", "name": "externalProxyServer", "schema": { "description": "External proxy server URL for user-provided proxies.\nFormat: http(s)://[username:password@]host:port\nWhen set, routes requests through this proxy instead of built-in residential proxies.", "type": "string" } }, { "in": "query", "name": "integrationId", "schema": { "description": "Optional 1Password integration id for credential filling on a non-persistent\nconnection. Extracted from the `integrationId` query parameter; the persistent\nsession path carries the same data on session metadata instead.", "type": "string" } }, { "in": "query", "name": "launch", "schema": { "description": "Launch options for the browser, either as a JSON object or a JSON string.\nIncludes options like `headless`, `args`, `defaultViewport`, etc.", "anyOf": [ { "$ref": "#/components/schemas/CDPLaunchOptions" }, { "type": "string" } ] } }, { "in": "query", "name": "profile", "schema": { "description": "Name of an authenticated profile to hydrate into the browser at launch.\nThe profile's cookies, localStorage and IndexedDB are injected via CDP\nbefore your code runs. No-op in builds without a profile subsystem.", "type": "string" } }, { "in": "query", "name": "proxy", "schema": { "$ref": "#/components/schemas/ProxyType", "description": "The type of proxy to use: 'residential' or 'datacenter'." } }, { "in": "query", "name": "proxyCity", "schema": { "description": "The city to use for the proxy.\n\nAvailable cities: https://production-sfo.browserless.io/proxy/cities?token=YOUR_TOKEN\nDocumentation: 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.\n\nSupported codes: US, GB, FR, DE, etc.\nFull 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.\nRecommended when using proxyCountry to ensure websites render content,\ncurrency, 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.\nMaps to specific proxy vendors internally for optimal access to certain websites.\nFormat: \"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.\nAccepts 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": "#/components/schemas/ScreenshotOptions", "description": "Screenshot options based on Puppeteer's ScreenshotOptions interface.\nIncludes properties like `type`, `quality`, `fullPage`, `clip`, etc." }, "addScriptTag": { "description": "An array of script tags to add to the page before performing actions.\nEach object can contain either a `url`, or a `content` property.", "type": "array", "items": { "$ref": "#/components/schemas/FrameAddScriptTagOptions" } }, "addStyleTag": { "description": "An array of style tags to add to the page before performing actions.\nEach object can contain either a `url`, or a `content` property.", "type": "array", "items": { "$ref": "#/components/schemas/FrameAddStyleTagOptions" } }, "authenticate": { "$ref": "#/components/schemas/Credentials", "description": "Credentials for HTTP authentication. Contains `username` and `password` properties." }, "bestAttempt": { "description": "When bestAttempt is set to true, browserless will attempt to proceed\nwhen \"awaited\" events fail or timeout. This includes things like\ngoto, waitForSelector, and more.", "type": "boolean" }, "cookies": { "description": "An array of cookies to set on the page before navigation.\nEach cookie object should contain at least `name` and `value` properties.", "type": "array", "items": { "$ref": "#/components/schemas/CookieParam" } }, "emulateMediaType": { "description": "Changes the CSS media type of the page. Accepts values like \"screen\" or \"print\".", "type": "string" }, "gotoOptions": { "$ref": "#/components/schemas/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.\nRequests matching these patterns will be aborted.", "type": "array", "items": { "type": "string" } }, "rejectResourceTypes": { "description": "An array of resource types to reject during page load.\nCommon 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.\nEach 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\ncorresponding 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\ncorresponding responses to use in order to fulfill those requests.", "type": "string" }, "response": { "additionalProperties": false, "type": "object", "properties": { "headers": { "$ref": "#/components/schemas/AnyRecord", "description": "Optional response headers.\n\nThe record values will be converted to string following:\nArrays' values will be mapped to String\n(Used when you need multiple headers with the same name).\nNon-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\nstring 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": "#/components/schemas/Protocol.Emulation.UserAgentMetadata" }, "platform": { "type": "string" } }, "additionalProperties": false }, "viewport": { "$ref": "#/components/schemas/Viewport", "description": "The viewport dimensions and settings for the page.\nIncludes 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.\nIf polling is a number, then it is treated as an interval in milliseconds\nat which the function would be executed. If polling is a string,\nthen 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).\nPass 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.\nUseful 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", "example": { "url": "https://docs.browserless.io/" } }, "example": { "blockConsentModals": true, "options": { "optimizeForSpeed": true, "type": "jpeg", "quality": 0, "fromSurface": true, "fullPage": true, "omitBackground": true, "clip": { "scale": 0, "width": 0, "height": 0, "x": 0, "y": 0 }, "encoding": "base64", "captureBeyondViewport": true }, "addScriptTag": [ { "url": "string", "content": "string", "type": "string", "id": "string" } ], "addStyleTag": [ { "url": "string", "content": "string" } ], "authenticate": { "username": "string", "password": "string" }, "bestAttempt": true, "cookies": [ { "name": "string", "value": "string", "url": "string", "domain": "string", "path": "string", "secure": true, "httpOnly": true, "sameSite": "Default", "expires": 0, "priority": "High", "sourceScheme": "NonSecure", "partitionKey": { "sourceOrigin": "string", "hasCrossSiteAncestor": true } } ], "emulateMediaType": "string", "gotoOptions": { "referer": "string", "referrerPolicy": "string", "timeout": 0, "waitUntil": [ "domcontentloaded" ], "signal": { "aborted": true, "onabort": {}, "reason": {} } }, "html": "string", "rejectRequestPattern": [ "string" ], "rejectResourceTypes": [ "cspviolationreport" ], "requestInterceptors": [ { "pattern": "string", "response": { "headers": {}, "status": 0, "contentType": "string", "body": "string" } } ], "setExtraHTTPHeaders": {}, "setJavaScriptEnabled": true, "url": "string", "userAgent": { "userAgent": "string", "userAgentMetadata": { "brands": [ { "brand": "string", "version": "string" } ], "fullVersionList": [ { "brand": "string", "version": "string" } ], "fullVersion": "string", "platform": "string", "platformVersion": "string", "architecture": "string", "model": "string", "mobile": true, "bitness": "string", "wow64": true, "formFactors": [ "string" ] }, "platform": "string" }, "viewport": { "width": 0, "height": 0, "deviceScaleFactor": 0, "isMobile": true, "isLandscape": true, "hasTouch": true }, "waitForEvent": { "event": "string", "timeout": 0 }, "waitForFunction": { "fn": "string", "polling": "string", "timeout": 0 }, "waitForSelector": { "hidden": true, "selector": "string", "timeout": 0, "visible": true }, "waitForTimeout": 0, "scrollPage": true, "selector": "string" } } } }, "responses": { "200": { "content": { "image/png": { "schema": { "type": "string", "format": "binary" } }, "image/jpeg": { "schema": { "type": "string", "format": "binary" } }, "text/plain": { "schema": { "type": "string", "format": "byte" } } }, "description": "Response can either be a text/plain base64 encoded body\nor 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" }, "403": { "code": 403, "description": "The request targets a destination that is not allowed.", "message": "HTTP/1.1 403 Forbidden" }, "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": [ "Screenshots & PDFs" ] } }, "/pdf": { "post": { "description": "Returns a PDF binary from a `url` or `html` payload.\n\"url\" or \"html\" payload in your request. Many options exist for\ninjecting cookies, request interceptors, user-agents and waiting for\nselectors, timers and more.\n\n**Note:** This is the preferred endpoint. The `/chromium/pdf` route is equivalent.", "parameters": [ { "in": "query", "name": "allowedDomains", "schema": { "description": "Optional per-connection narrowing of the integration's allowed-domain list.\nExtracted from the JSON `allowedDomains` query parameter. Can only narrow the\nintegration's domains, never widen them.", "type": "array", "items": { "type": "string" } } }, { "in": "query", "name": "blockAds", "schema": { "description": "Whether or not to load ad-blocking extensions for the session.\nThis currently uses uBlock-Lite and may cause certain sites\nto not load properly.", "type": "boolean" } }, { "in": "query", "name": "blockAdsInclude", "schema": { "description": "Restrict blockAds to a specific set of uBlock ruleset ids (comma-separated\nlist or JSON array). Only applies when `blockAds` is true. Fewer rulesets\nmeans a faster browser launch under load; omit to load the full default set.", "type": "string" } }, { "in": "query", "name": "credentials", "schema": { "$ref": "#/components/schemas/StringRecord", "description": "Optional alias → `op://…` reference map for the integration above. Extracted\nfrom the JSON `credentials` query parameter. References are not secret;\nresolved values are never stored here. Optional — a connection can also pass\nraw `op://…` references straight to Browserless.loadSecret." } }, { "in": "query", "name": "externalProxyServer", "schema": { "description": "External proxy server URL for user-provided proxies.\nFormat: http(s)://[username:password@]host:port\nWhen set, routes requests through this proxy instead of built-in residential proxies.", "type": "string" } }, { "in": "query", "name": "integrationId", "schema": { "description": "Optional 1Password integration id for credential filling on a non-persistent\nconnection. Extracted from the `integrationId` query parameter; the persistent\nsession path carries the same data on session metadata instead.", "type": "string" } }, { "in": "query", "name": "launch", "schema": { "description": "Launch options for the browser, either as a JSON object or a JSON string.\nIncludes options like `headless`, `args`, `defaultViewport`, etc.", "anyOf": [ { "$ref": "#/components/schemas/CDPLaunchOptions" }, { "type": "string" } ] } }, { "in": "query", "name": "profile", "schema": { "description": "Name of an authenticated profile to hydrate into the browser at launch.\nThe profile's cookies, localStorage and IndexedDB are injected via CDP\nbefore your code runs. No-op in builds without a profile subsystem.", "type": "string" } }, { "in": "query", "name": "proxy", "schema": { "$ref": "#/components/schemas/ProxyType", "description": "The type of proxy to use: 'residential' or 'datacenter'." } }, { "in": "query", "name": "proxyCity", "schema": { "description": "The city to use for the proxy.\n\nAvailable cities: https://production-sfo.browserless.io/proxy/cities?token=YOUR_TOKEN\nDocumentation: 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.\n\nSupported codes: US, GB, FR, DE, etc.\nFull 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.\nRecommended when using proxyCountry to ensure websites render content,\ncurrency, 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.\nMaps to specific proxy vendors internally for optimal access to certain websites.\nFormat: \"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.\nAccepts 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.\nIncludes 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\nclasses used to inject values into them:\n\n- `date` formatted print date\n\n- `title` document title\n\n- `url` document location\n\n- `pageNumber` current page number\n\n- `totalPages` total pages in the document", "type": "string" }, "footerTemplate": { "description": "HTML template for the print footer. Has the same constraints and support\nfor 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": "#/components/schemas/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\ndeclared in the `width` or `height` or `format` option.", "type": "boolean" }, "margin": { "$ref": "#/components/schemas/PDFMargin", "description": "Set the PDF margins." }, "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.\n\nThe 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\nactivating the page using {@link Page.bringToFront} if the page is in the\nbackground.", "type": "boolean" }, "fullPage": { "type": "boolean" } } }, "addScriptTag": { "description": "An array of script tags to add to the page before performing actions.\nEach object can contain either a `url`, or a `content` property.", "type": "array", "items": { "$ref": "#/components/schemas/FrameAddScriptTagOptions" } }, "addStyleTag": { "description": "An array of style tags to add to the page before performing actions.\nEach object can contain either a `url`, or a `content` property.", "type": "array", "items": { "$ref": "#/components/schemas/FrameAddStyleTagOptions" } }, "authenticate": { "$ref": "#/components/schemas/Credentials", "description": "Credentials for HTTP authentication. Contains `username` and `password` properties." }, "bestAttempt": { "description": "When bestAttempt is set to true, browserless will attempt to proceed\nwhen \"awaited\" events fail or timeout. This includes things like\ngoto, waitForSelector, and more.", "type": "boolean" }, "cookies": { "description": "An array of cookies to set on the page before navigation.\nEach cookie object should contain at least `name` and `value` properties.", "type": "array", "items": { "$ref": "#/components/schemas/CookieParam" } }, "emulateMediaType": { "description": "Changes the CSS media type of the page. Accepts values like \"screen\" or \"print\".", "type": "string" }, "gotoOptions": { "$ref": "#/components/schemas/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.\nRequests matching these patterns will be aborted.", "type": "array", "items": { "type": "string" } }, "rejectResourceTypes": { "description": "An array of resource types to reject during page load.\nCommon 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.\nEach 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\ncorresponding 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\ncorresponding responses to use in order to fulfill those requests.", "type": "string" }, "response": { "additionalProperties": false, "type": "object", "properties": { "headers": { "$ref": "#/components/schemas/AnyRecord", "description": "Optional response headers.\n\nThe record values will be converted to string following:\nArrays' values will be mapped to String\n(Used when you need multiple headers with the same name).\nNon-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\nstring 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": "#/components/schemas/Protocol.Emulation.UserAgentMetadata" }, "platform": { "type": "string" } }, "additionalProperties": false }, "viewport": { "$ref": "#/components/schemas/Viewport", "description": "The viewport dimensions and settings for the page.\nIncludes 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.\nIf polling is a number, then it is treated as an interval in milliseconds\nat which the function would be executed. If polling is a string,\nthen 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).\nPass 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", "example": { "url": "https://docs.browserless.io/" } }, "example": { "blockConsentModals": true, "options": { "scale": 0, "displayHeaderFooter": true, "headerTemplate": "string", "footerTemplate": "string", "printBackground": true, "landscape": true, "pageRanges": "string", "format": "A0", "width": "string", "height": "string", "preferCSSPageSize": true, "margin": { "top": "string", "bottom": "string", "left": "string", "right": "string" }, "omitBackground": true, "tagged": true, "outline": true, "timeout": 0, "waitForFonts": true, "fullPage": true }, "addScriptTag": [ { "url": "string", "content": "string", "type": "string", "id": "string" } ], "addStyleTag": [ { "url": "string", "content": "string" } ], "authenticate": { "username": "string", "password": "string" }, "bestAttempt": true, "cookies": [ { "name": "string", "value": "string", "url": "string", "domain": "string", "path": "string", "secure": true, "httpOnly": true, "sameSite": "Default", "expires": 0, "priority": "High", "sourceScheme": "NonSecure", "partitionKey": { "sourceOrigin": "string", "hasCrossSiteAncestor": true } } ], "emulateMediaType": "string", "gotoOptions": { "referer": "string", "referrerPolicy": "string", "timeout": 0, "waitUntil": [ "domcontentloaded" ], "signal": { "aborted": true, "onabort": {}, "reason": {} } }, "html": "string", "rejectRequestPattern": [ "string" ], "rejectResourceTypes": [ "cspviolationreport" ], "requestInterceptors": [ { "pattern": "string", "response": { "headers": {}, "status": 0, "contentType": "string", "body": "string" } } ], "setExtraHTTPHeaders": {}, "setJavaScriptEnabled": true, "url": "string", "userAgent": { "userAgent": "string", "userAgentMetadata": { "brands": [ { "brand": "string", "version": "string" } ], "fullVersionList": [ { "brand": "string", "version": "string" } ], "fullVersion": "string", "platform": "string", "platformVersion": "string", "architecture": "string", "model": "string", "mobile": true, "bitness": "string", "wow64": true, "formFactors": [ "string" ] }, "platform": "string" }, "viewport": { "width": 0, "height": 0, "deviceScaleFactor": 0, "isMobile": true, "isLandscape": true, "hasTouch": true }, "waitForEvent": { "event": "string", "timeout": 0 }, "waitForFunction": { "fn": "string", "polling": "string", "timeout": 0 }, "waitForSelector": { "hidden": true, "selector": "string", "timeout": 0, "visible": true }, "waitForTimeout": 0 } } } }, "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" }, "403": { "code": 403, "description": "The request targets a destination that is not allowed.", "message": "HTTP/1.1 403 Forbidden" }, "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": [ "Screenshots & PDFs" ] } }, "/edge/screenshot": { "post": { "description": "Returns a screenshot binary from a `url` or `html` payload using Edge.\n\"url\" or \"html\" payload in your request. Many options exist including\ncookies, user-agents, setting timers and network mocks.", "parameters": [ { "in": "query", "name": "blockAds", "schema": { "description": "Whether or not to load ad-blocking extensions for the session.\nThis currently uses uBlock-Lite and may cause certain sites\nto not load properly.", "type": "boolean" } }, { "in": "query", "name": "launch", "schema": { "description": "Launch options, which can be either an object\nof puppeteer.launch options or playwright.launchServer\noptions, depending on the API. Must be either JSON\nobject, or a base64-encoded JSON object.", "anyOf": [ { "$ref": "#/components/schemas/CDPLaunchOptions" }, { "type": "string" } ] } }, { "in": "query", "name": "profile", "schema": { "description": "Name of an authenticated profile to hydrate into the browser at launch.\nThe profile's cookies, localStorage and IndexedDB are injected via CDP\nbefore 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.\nAccepts 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" } }, { "in": "query", "name": "allowedDomains", "schema": { "description": "Optional per-connection narrowing of the integration's allowed-domain list.\nExtracted from the JSON `allowedDomains` query parameter. Can only narrow the\nintegration's domains, never widen them.", "type": "array", "items": { "type": "string" } } }, { "in": "query", "name": "credentials", "schema": { "$ref": "#/components/schemas/StringRecord", "description": "Optional alias → `op://…` reference map for the integration above. Extracted\nfrom the JSON `credentials` query parameter. References are not secret;\nresolved values are never stored here. Optional — a connection can also pass\nraw `op://…` references straight to Browserless.loadSecret." } }, { "in": "query", "name": "externalProxyServer", "schema": { "description": "External proxy server URL for user-provided proxies.\nFormat: http(s)://[username:password@]host:port\nWhen set, routes requests through this proxy instead of built-in residential proxies.", "type": "string" } }, { "in": "query", "name": "integrationId", "schema": { "description": "Optional 1Password integration id for credential filling on a non-persistent\nconnection. Extracted from the `integrationId` query parameter; the persistent\nsession path carries the same data on session metadata instead.", "type": "string" } }, { "in": "query", "name": "proxy", "schema": { "$ref": "#/components/schemas/ProxyType", "description": "The type of proxy to use: 'residential' or 'datacenter'." } }, { "in": "query", "name": "proxyCity", "schema": { "description": "The city to use for the proxy.\n\nAvailable cities: https://production-sfo.browserless.io/proxy/cities?token=YOUR_TOKEN\nDocumentation: 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.\n\nSupported codes: US, GB, FR, DE, etc.\nFull 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.\nRecommended when using proxyCountry to ensure websites render content,\ncurrency, 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.\nMaps to specific proxy vendors internally for optimal access to certain websites.\nFormat: \"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" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "addScriptTag": { "type": "array", "items": { "$ref": "#/components/schemas/FrameAddScriptTagOptions" } }, "addStyleTag": { "type": "array", "items": { "$ref": "#/components/schemas/FrameAddStyleTagOptions" } }, "authenticate": { "anyOf": [ { "$ref": "#/components/schemas/Credentials" }, { "type": "null" } ], "description": "Credentials for HTTP authentication. Contains `username` and `password` properties." }, "bestAttempt": { "description": "When bestAttempt is set to true, browserless attempt to proceed\nwhen \"awaited\" events fail or timeout. This includes things like\ngoto, waitForSelector, and more.", "type": "boolean" }, "cookies": { "type": "array", "items": { "$ref": "#/components/schemas/CookieParam" } }, "emulateMediaType": { "type": "string" }, "gotoOptions": { "$ref": "#/components/schemas/GoToOptions", "description": "Options to configure the page navigation, such as `timeout` and `waitUntil`." }, "html": { "type": "string" }, "options": { "$ref": "#/components/schemas/ScreenshotOptions", "description": "Screenshot options based on Puppeteer's ScreenshotOptions interface.\nIncludes properties like `type`, `quality`, `fullPage`, `clip`, etc." }, "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\ncorresponding 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\ncorresponding responses to use in order to fulfill those requests.", "type": "string" }, "response": { "additionalProperties": false, "type": "object", "properties": { "headers": { "description": "Optional response headers.\n\nThe record values will be converted to string following:\nArrays' values will be mapped to String\n(Used when you need multiple headers with the same name).\nNon-arrays will be converted to String.", "$ref": "#/components/schemas/AnyRecord" }, "status": { "type": "number" }, "contentType": { "type": "string" }, "body": { "description": "A string representation of the body to return. Can be a base64-encoded\nstring 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\nMissing optional values will be filled in by the target with what it would normally use.", "$ref": "#/components/schemas/Protocol.Emulation.UserAgentMetadata" }, "platform": { "type": "string" } }, "additionalProperties": false }, "viewport": { "anyOf": [ { "$ref": "#/components/schemas/Viewport" }, { "type": "null" } ], "description": "The viewport dimensions and settings for the page.\nIncludes properties like `width`, `height`, `deviceScaleFactor`, etc." }, "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.\nIf polling is a number, then it is treated as an interval in milliseconds\nat which the function would be executed. If polling is a string,\nthen 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).\nPass 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", "example": { "url": "https://docs.browserless.io/" } }, "example": { "addScriptTag": [ { "url": "string", "content": "string", "type": "string", "id": "string" } ], "addStyleTag": [ { "url": "string", "content": "string" } ], "authenticate": { "username": "string", "password": "string" }, "bestAttempt": true, "cookies": [ { "name": "string", "value": "string", "url": "string", "domain": "string", "path": "string", "secure": true, "httpOnly": true, "sameSite": "Default", "expires": 0, "priority": "High", "sourceScheme": "NonSecure", "partitionKey": { "sourceOrigin": "string", "hasCrossSiteAncestor": true } } ], "emulateMediaType": "string", "gotoOptions": { "referer": "string", "referrerPolicy": "string", "timeout": 0, "waitUntil": [ "domcontentloaded" ], "signal": { "aborted": true, "onabort": {}, "reason": {} } }, "html": "string", "options": { "optimizeForSpeed": true, "type": "jpeg", "quality": 0, "fromSurface": true, "fullPage": true, "omitBackground": true, "clip": { "scale": 0, "width": 0, "height": 0, "x": 0, "y": 0 }, "encoding": "base64", "captureBeyondViewport": true }, "rejectRequestPattern": [ "string" ], "rejectResourceTypes": [ "cspviolationreport" ], "requestInterceptors": [ { "pattern": "string", "response": { "headers": {}, "status": 0, "contentType": "string", "body": "string" } } ], "scrollPage": true, "selector": "string", "setExtraHTTPHeaders": {}, "setJavaScriptEnabled": true, "url": "string", "userAgent": { "userAgent": "string", "userAgentMetadata": { "brands": [ { "brand": "string", "version": "string" } ], "fullVersionList": [ { "brand": "string", "version": "string" } ], "fullVersion": "string", "platform": "string", "platformVersion": "string", "architecture": "string", "model": "string", "mobile": true, "bitness": "string", "wow64": true, "formFactors": [ "string" ] }, "platform": "string" }, "viewport": { "width": 0, "height": 0, "deviceScaleFactor": 0, "isMobile": true, "isLandscape": true, "hasTouch": true }, "waitForEvent": { "event": "string", "timeout": 0 }, "waitForFunction": { "fn": "string", "polling": "string", "timeout": 0 }, "waitForSelector": { "hidden": true, "selector": "string", "timeout": 0, "visible": true }, "waitForTimeout": 0 } } } }, "responses": { "200": { "content": { "image/png": { "schema": { "type": "string", "format": "binary" } }, "image/jpeg": { "schema": { "type": "string", "format": "binary" } }, "text/plain": { "schema": { "type": "string", "format": "byte" } } }, "description": "Response can either be a text/plain base64 encoded body\nor 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" }, "403": { "code": 403, "description": "The request targets a destination that is not allowed.", "message": "HTTP/1.1 403 Forbidden" }, "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": [ "Screenshots & PDFs" ] } }, "/edge/pdf": { "post": { "description": "Returns a PDF binary from a `url` or `html` payload using Edge.\n\"url\" or \"html\" payload in your request. Many options exist for\ninjecting cookies, request interceptors, user-agents and waiting for\nselectors, timers and more.", "parameters": [ { "in": "query", "name": "blockAds", "schema": { "description": "Whether or not to load ad-blocking extensions for the session.\nThis currently uses uBlock-Lite and may cause certain sites\nto not load properly.", "type": "boolean" } }, { "in": "query", "name": "launch", "schema": { "description": "Launch options, which can be either an object\nof puppeteer.launch options or playwright.launchServer\noptions, depending on the API. Must be either JSON\nobject, or a base64-encoded JSON object.", "anyOf": [ { "$ref": "#/components/schemas/CDPLaunchOptions" }, { "type": "string" } ] } }, { "in": "query", "name": "profile", "schema": { "description": "Name of an authenticated profile to hydrate into the browser at launch.\nThe profile's cookies, localStorage and IndexedDB are injected via CDP\nbefore 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.\nAccepts 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" } }, { "in": "query", "name": "allowedDomains", "schema": { "description": "Optional per-connection narrowing of the integration's allowed-domain list.\nExtracted from the JSON `allowedDomains` query parameter. Can only narrow the\nintegration's domains, never widen them.", "type": "array", "items": { "type": "string" } } }, { "in": "query", "name": "credentials", "schema": { "$ref": "#/components/schemas/StringRecord", "description": "Optional alias → `op://…` reference map for the integration above. Extracted\nfrom the JSON `credentials` query parameter. References are not secret;\nresolved values are never stored here. Optional — a connection can also pass\nraw `op://…` references straight to Browserless.loadSecret." } }, { "in": "query", "name": "externalProxyServer", "schema": { "description": "External proxy server URL for user-provided proxies.\nFormat: http(s)://[username:password@]host:port\nWhen set, routes requests through this proxy instead of built-in residential proxies.", "type": "string" } }, { "in": "query", "name": "integrationId", "schema": { "description": "Optional 1Password integration id for credential filling on a non-persistent\nconnection. Extracted from the `integrationId` query parameter; the persistent\nsession path carries the same data on session metadata instead.", "type": "string" } }, { "in": "query", "name": "proxy", "schema": { "$ref": "#/components/schemas/ProxyType", "description": "The type of proxy to use: 'residential' or 'datacenter'." } }, { "in": "query", "name": "proxyCity", "schema": { "description": "The city to use for the proxy.\n\nAvailable cities: https://production-sfo.browserless.io/proxy/cities?token=YOUR_TOKEN\nDocumentation: 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.\n\nSupported codes: US, GB, FR, DE, etc.\nFull 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.\nRecommended when using proxyCountry to ensure websites render content,\ncurrency, 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.\nMaps to specific proxy vendors internally for optimal access to certain websites.\nFormat: \"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" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "addScriptTag": { "type": "array", "items": { "$ref": "#/components/schemas/FrameAddScriptTagOptions" } }, "addStyleTag": { "type": "array", "items": { "$ref": "#/components/schemas/FrameAddStyleTagOptions" } }, "authenticate": { "anyOf": [ { "$ref": "#/components/schemas/Credentials" }, { "type": "null" } ], "description": "Credentials for HTTP authentication. Contains `username` and `password` properties." }, "bestAttempt": { "description": "When bestAttempt is set to true, browserless attempt to proceed\nwhen \"awaited\" events fail or timeout. This includes things like\ngoto, waitForSelector, and more.", "type": "boolean" }, "cookies": { "type": "array", "items": { "$ref": "#/components/schemas/CookieParam" } }, "emulateMediaType": { "type": "string" }, "gotoOptions": { "$ref": "#/components/schemas/GoToOptions", "description": "Options to configure the page navigation, such as `timeout` and `waitUntil`." }, "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\nclasses used to inject values into them:\n\n- `date` formatted print date\n\n- `title` document title\n\n- `url` document location\n\n- `pageNumber` current page number\n\n- `totalPages` total pages in the document", "type": "string" }, "footerTemplate": { "description": "HTML template for the print footer. Has the same constraints and support\nfor 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\ndeclared in the `width` or `height` or `format` option.", "type": "boolean" }, "margin": { "description": "Set the PDF margins.", "$ref": "#/components/schemas/PDFMargin" }, "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.\n\nThe 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\nactivating the page using {@link Page.bringToFront} if the page is in the\nbackground.", "type": "boolean" }, "fullPage": { "type": "boolean" } }, "description": "PDF generation options based on Puppeteer's PDFOptions interface.\nIncludes properties like `format`, `landscape`, `margin`, `scale`, etc." }, "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\ncorresponding 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\ncorresponding responses to use in order to fulfill those requests.", "type": "string" }, "response": { "additionalProperties": false, "type": "object", "properties": { "headers": { "description": "Optional response headers.\n\nThe record values will be converted to string following:\nArrays' values will be mapped to String\n(Used when you need multiple headers with the same name).\nNon-arrays will be converted to String.", "$ref": "#/components/schemas/AnyRecord" }, "status": { "type": "number" }, "contentType": { "type": "string" }, "body": { "description": "A string representation of the body to return. Can be a base64-encoded\nstring 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\nMissing optional values will be filled in by the target with what it would normally use.", "$ref": "#/components/schemas/Protocol.Emulation.UserAgentMetadata" }, "platform": { "type": "string" } }, "additionalProperties": false }, "viewport": { "anyOf": [ { "$ref": "#/components/schemas/Viewport" }, { "type": "null" } ], "description": "The viewport dimensions and settings for the page.\nIncludes properties like `width`, `height`, `deviceScaleFactor`, etc." }, "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.\nIf polling is a number, then it is treated as an interval in milliseconds\nat which the function would be executed. If polling is a string,\nthen 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).\nPass 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", "example": { "url": "https://docs.browserless.io/" } }, "example": { "addScriptTag": [ { "url": "string", "content": "string", "type": "string", "id": "string" } ], "addStyleTag": [ { "url": "string", "content": "string" } ], "authenticate": { "username": "string", "password": "string" }, "bestAttempt": true, "cookies": [ { "name": "string", "value": "string", "url": "string", "domain": "string", "path": "string", "secure": true, "httpOnly": true, "sameSite": "Default", "expires": 0, "priority": "High", "sourceScheme": "NonSecure", "partitionKey": { "sourceOrigin": "string", "hasCrossSiteAncestor": true } } ], "emulateMediaType": "string", "gotoOptions": { "referer": "string", "referrerPolicy": "string", "timeout": 0, "waitUntil": [ "domcontentloaded" ], "signal": { "aborted": true, "onabort": {}, "reason": {} } }, "html": "string", "options": { "scale": 0, "displayHeaderFooter": true, "headerTemplate": "string", "footerTemplate": "string", "printBackground": true, "landscape": true, "pageRanges": "string", "format": "A0", "width": "string", "height": "string", "preferCSSPageSize": true, "margin": { "top": "string", "bottom": "string", "left": "string", "right": "string" }, "omitBackground": true, "tagged": true, "outline": true, "timeout": 0, "waitForFonts": true, "fullPage": true }, "rejectRequestPattern": [ "string" ], "rejectResourceTypes": [ "cspviolationreport" ], "requestInterceptors": [ { "pattern": "string", "response": { "headers": {}, "status": 0, "contentType": "string", "body": "string" } } ], "setExtraHTTPHeaders": {}, "setJavaScriptEnabled": true, "url": "string", "userAgent": { "userAgent": "string", "userAgentMetadata": { "brands": [ { "brand": "string", "version": "string" } ], "fullVersionList": [ { "brand": "string", "version": "string" } ], "fullVersion": "string", "platform": "string", "platformVersion": "string", "architecture": "string", "model": "string", "mobile": true, "bitness": "string", "wow64": true, "formFactors": [ "string" ] }, "platform": "string" }, "viewport": { "width": 0, "height": 0, "deviceScaleFactor": 0, "isMobile": true, "isLandscape": true, "hasTouch": true }, "waitForEvent": { "event": "string", "timeout": 0 }, "waitForFunction": { "fn": "string", "polling": "string", "timeout": 0 }, "waitForSelector": { "hidden": true, "selector": "string", "timeout": 0, "visible": true }, "waitForTimeout": 0 } } } }, "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" }, "403": { "code": 403, "description": "The request targets a destination that is not allowed.", "message": "HTTP/1.1 403 Forbidden" }, "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": [ "Screenshots & PDFs" ] } }, "/chromium/content": { "post": { "description": "Given a `url` or `html` field, loads the page and returns the fully rendered HTML.\n\n**Note:** Also available at `/content` as a convenience alias.", "parameters": [ { "in": "query", "name": "blockAds", "schema": { "description": "Whether or not to load ad-blocking extensions for the session.\nThis currently uses uBlock-Lite and may cause certain sites\nto not load properly.", "type": "boolean" } }, { "in": "query", "name": "launch", "schema": { "anyOf": [ { "$ref": "#/components/schemas/CDPLaunchOptions" }, { "type": "string" } ] } }, { "in": "query", "name": "profile", "schema": { "description": "Name of an authenticated profile to hydrate into the browser at launch.\nThe profile's cookies, localStorage and IndexedDB are injected via CDP\nbefore 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.\nAccepts 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" } }, { "in": "query", "name": "allowedDomains", "schema": { "description": "Optional per-connection narrowing of the integration's allowed-domain list.\nExtracted from the JSON `allowedDomains` query parameter. Can only narrow the\nintegration's domains, never widen them.", "type": "array", "items": { "type": "string" } } }, { "in": "query", "name": "credentials", "schema": { "$ref": "#/components/schemas/StringRecord", "description": "Optional alias → `op://…` reference map for the integration above. Extracted\nfrom the JSON `credentials` query parameter. References are not secret;\nresolved values are never stored here. Optional — a connection can also pass\nraw `op://…` references straight to Browserless.loadSecret." } }, { "in": "query", "name": "externalProxyServer", "schema": { "description": "External proxy server URL for user-provided proxies.\nFormat: http(s)://[username:password@]host:port\nWhen set, routes requests through this proxy instead of built-in residential proxies.", "type": "string" } }, { "in": "query", "name": "integrationId", "schema": { "description": "Optional 1Password integration id for credential filling on a non-persistent\nconnection. Extracted from the `integrationId` query parameter; the persistent\nsession path carries the same data on session metadata instead.", "type": "string" } }, { "in": "query", "name": "proxy", "schema": { "$ref": "#/components/schemas/ProxyType", "description": "The type of proxy to use: 'residential' or 'datacenter'." } }, { "in": "query", "name": "proxyCity", "schema": { "description": "The city to use for the proxy.\n\nAvailable cities: https://production-sfo.browserless.io/proxy/cities?token=YOUR_TOKEN\nDocumentation: 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.\n\nSupported codes: US, GB, FR, DE, etc.\nFull 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.\nRecommended when using proxyCountry to ensure websites render content,\ncurrency, 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.\nMaps to specific proxy vendors internally for optimal access to certain websites.\nFormat: \"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" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "addScriptTag": { "type": "array", "items": { "$ref": "#/components/schemas/FrameAddScriptTagOptions" } }, "addStyleTag": { "type": "array", "items": { "$ref": "#/components/schemas/FrameAddStyleTagOptions" } }, "authenticate": { "anyOf": [ { "$ref": "#/components/schemas/Credentials" }, { "type": "null" } ], "description": "Credentials for HTTP authentication. Contains `username` and `password` properties." }, "bestAttempt": { "description": "When bestAttempt is set to true, browserless attempt to proceed\nwhen \"awaited\" events fail or timeout. This includes things like\ngoto, waitForSelector, and more.", "type": "boolean" }, "cookies": { "type": "array", "items": { "$ref": "#/components/schemas/CookieParam" } }, "emulateMediaType": { "type": "string" }, "gotoOptions": { "$ref": "#/components/schemas/GoToOptions", "description": "Options to configure the page navigation, such as `timeout` and `waitUntil`." }, "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\ncorresponding 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\ncorresponding responses to use in order to fulfill those requests.", "type": "string" }, "response": { "additionalProperties": false, "type": "object", "properties": { "headers": { "description": "Optional response headers.\n\nThe record values will be converted to string following:\nArrays' values will be mapped to String\n(Used when you need multiple headers with the same name).\nNon-arrays will be converted to String.", "$ref": "#/components/schemas/AnyRecord" }, "status": { "type": "number" }, "contentType": { "type": "string" }, "body": { "description": "A string representation of the body to return. Can be a base64-encoded\nstring 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\nMissing optional values will be filled in by the target with what it would normally use.", "$ref": "#/components/schemas/Protocol.Emulation.UserAgentMetadata" }, "platform": { "type": "string" } }, "additionalProperties": false }, "viewport": { "anyOf": [ { "$ref": "#/components/schemas/Viewport" }, { "type": "null" } ], "description": "The viewport dimensions and settings for the page.\nIncludes properties like `width`, `height`, `deviceScaleFactor`, etc." }, "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.\nIf polling is a number, then it is treated as an interval in milliseconds\nat which the function would be executed. If polling is a string,\nthen 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).\nPass 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", "example": { "url": "https://docs.browserless.io/" } }, "example": { "addScriptTag": [ { "url": "string", "content": "string", "type": "string", "id": "string" } ], "addStyleTag": [ { "url": "string", "content": "string" } ], "authenticate": { "username": "string", "password": "string" }, "bestAttempt": true, "cookies": [ { "name": "string", "value": "string", "url": "string", "domain": "string", "path": "string", "secure": true, "httpOnly": true, "sameSite": "Default", "expires": 0, "priority": "High", "sourceScheme": "NonSecure", "partitionKey": { "sourceOrigin": "string", "hasCrossSiteAncestor": true } } ], "emulateMediaType": "string", "gotoOptions": { "referer": "string", "referrerPolicy": "string", "timeout": 0, "waitUntil": [ "domcontentloaded" ], "signal": { "aborted": true, "onabort": {}, "reason": {} } }, "html": "string", "rejectRequestPattern": [ "string" ], "rejectResourceTypes": [ "cspviolationreport" ], "requestInterceptors": [ { "pattern": "string", "response": { "headers": {}, "status": 0, "contentType": "string", "body": "string" } } ], "setExtraHTTPHeaders": {}, "setJavaScriptEnabled": true, "url": "string", "userAgent": { "userAgent": "string", "userAgentMetadata": { "brands": [ { "brand": "string", "version": "string" } ], "fullVersionList": [ { "brand": "string", "version": "string" } ], "fullVersion": "string", "platform": "string", "platformVersion": "string", "architecture": "string", "model": "string", "mobile": true, "bitness": "string", "wow64": true, "formFactors": [ "string" ] }, "platform": "string" }, "viewport": { "width": 0, "height": 0, "deviceScaleFactor": 0, "isMobile": true, "isLandscape": true, "hasTouch": true }, "waitForEvent": { "event": "string", "timeout": 0 }, "waitForFunction": { "fn": "string", "polling": "string", "timeout": 0 }, "waitForSelector": { "hidden": true, "selector": "string", "timeout": 0, "visible": true }, "waitForTimeout": 0 } } } }, "responses": { "200": { "content": { "text/html": { "schema": { "description": "An HTML payload of the website or HTML after JavaScript\nparsing and execution.", "type": "string", "$schema": "http://json-schema.org/draft-07/schema#" } } }, "description": "An HTML payload of the website or HTML after JavaScript\nparsing 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" }, "403": { "code": 403, "description": "The request targets a destination that is not allowed.", "message": "HTTP/1.1 403 Forbidden" }, "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": [ "Scraping & Content" ] } }, "/chromium/scrape": { "post": { "description": "Returns text, HTML, and metadata from a given list of CSS selectors against the rendered DOM.\nDebugging information is available by sending in the appropriate flags in the \"debugOpts\"\nproperty. Responds with an array of JSON objects.\n\n**Note:** Also available at `/scrape` as a convenience alias.", "parameters": [ { "in": "query", "name": "blockAds", "schema": { "description": "Whether or not to load ad-blocking extensions for the session.\nThis currently uses uBlock-Lite and may cause certain sites\nto not load properly.", "type": "boolean" } }, { "in": "query", "name": "launch", "schema": { "anyOf": [ { "$ref": "#/components/schemas/CDPLaunchOptions" }, { "type": "string" } ] } }, { "in": "query", "name": "profile", "schema": { "description": "Name of an authenticated profile to hydrate into the browser at launch.\nThe profile's cookies, localStorage and IndexedDB are injected via CDP\nbefore 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.\nAccepts 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" } }, { "in": "query", "name": "allowedDomains", "schema": { "description": "Optional per-connection narrowing of the integration's allowed-domain list.\nExtracted from the JSON `allowedDomains` query parameter. Can only narrow the\nintegration's domains, never widen them.", "type": "array", "items": { "type": "string" } } }, { "in": "query", "name": "credentials", "schema": { "$ref": "#/components/schemas/StringRecord", "description": "Optional alias → `op://…` reference map for the integration above. Extracted\nfrom the JSON `credentials` query parameter. References are not secret;\nresolved values are never stored here. Optional — a connection can also pass\nraw `op://…` references straight to Browserless.loadSecret." } }, { "in": "query", "name": "externalProxyServer", "schema": { "description": "External proxy server URL for user-provided proxies.\nFormat: http(s)://[username:password@]host:port\nWhen set, routes requests through this proxy instead of built-in residential proxies.", "type": "string" } }, { "in": "query", "name": "integrationId", "schema": { "description": "Optional 1Password integration id for credential filling on a non-persistent\nconnection. Extracted from the `integrationId` query parameter; the persistent\nsession path carries the same data on session metadata instead.", "type": "string" } }, { "in": "query", "name": "proxy", "schema": { "$ref": "#/components/schemas/ProxyType", "description": "The type of proxy to use: 'residential' or 'datacenter'." } }, { "in": "query", "name": "proxyCity", "schema": { "description": "The city to use for the proxy.\n\nAvailable cities: https://production-sfo.browserless.io/proxy/cities?token=YOUR_TOKEN\nDocumentation: 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.\n\nSupported codes: US, GB, FR, DE, etc.\nFull 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.\nRecommended when using proxyCountry to ensure websites render content,\ncurrency, 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.\nMaps to specific proxy vendors internally for optimal access to certain websites.\nFormat: \"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" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "addScriptTag": { "type": "array", "items": { "$ref": "#/components/schemas/FrameAddScriptTagOptions" } }, "addStyleTag": { "type": "array", "items": { "$ref": "#/components/schemas/FrameAddStyleTagOptions" } }, "authenticate": { "anyOf": [ { "$ref": "#/components/schemas/Credentials" }, { "type": "null" } ], "description": "Credentials for HTTP authentication. Contains `username` and `password` properties." }, "bestAttempt": { "description": "When bestAttempt is set to true, browserless attempt to proceed\nwhen \"awaited\" events fail or timeout. This includes things like\ngoto, waitForSelector, and more.", "type": "boolean" }, "cookies": { "type": "array", "items": { "$ref": "#/components/schemas/CookieParam" } }, "debugOpts": { "$ref": "#/components/schemas/ScrapeDebugOptions" }, "elements": { "type": "array", "items": { "$ref": "#/components/schemas/ScrapeElementSelector" } }, "emulateMediaType": { "type": "string" }, "gotoOptions": { "$ref": "#/components/schemas/GoToOptions", "description": "Options to configure the page navigation, such as `timeout` and `waitUntil`." }, "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\ncorresponding 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\ncorresponding responses to use in order to fulfill those requests.", "type": "string" }, "response": { "additionalProperties": false, "type": "object", "properties": { "headers": { "description": "Optional response headers.\n\nThe record values will be converted to string following:\nArrays' values will be mapped to String\n(Used when you need multiple headers with the same name).\nNon-arrays will be converted to String.", "$ref": "#/components/schemas/AnyRecord" }, "status": { "type": "number" }, "contentType": { "type": "string" }, "body": { "description": "A string representation of the body to return. Can be a base64-encoded\nstring 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\nMissing optional values will be filled in by the target with what it would normally use.", "$ref": "#/components/schemas/Protocol.Emulation.UserAgentMetadata" }, "platform": { "type": "string" } }, "additionalProperties": false }, "viewport": { "anyOf": [ { "$ref": "#/components/schemas/Viewport" }, { "type": "null" } ], "description": "The viewport dimensions and settings for the page.\nIncludes properties like `width`, `height`, `deviceScaleFactor`, etc." }, "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.\nIf polling is a number, then it is treated as an interval in milliseconds\nat which the function would be executed. If polling is a string,\nthen 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).\nPass 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" ], "example": { "url": "https://docs.browserless.io/", "elements": [ { "selector": "h1" } ] } }, "example": { "addScriptTag": [ { "url": "string", "content": "string", "type": "string", "id": "string" } ], "addStyleTag": [ { "url": "string", "content": "string" } ], "authenticate": { "username": "string", "password": "string" }, "bestAttempt": true, "cookies": [ { "name": "string", "value": "string", "url": "string", "domain": "string", "path": "string", "secure": true, "httpOnly": true, "sameSite": "Default", "expires": 0, "priority": "High", "sourceScheme": "NonSecure", "partitionKey": { "sourceOrigin": "string", "hasCrossSiteAncestor": true } } ], "debugOpts": { "console": true, "cookies": true, "html": true, "network": true, "screenshot": true }, "elements": [ { "selector": "string", "timeout": 0 } ], "emulateMediaType": "string", "gotoOptions": { "referer": "string", "referrerPolicy": "string", "timeout": 0, "waitUntil": [ "domcontentloaded" ], "signal": { "aborted": true, "onabort": {}, "reason": {} } }, "html": "string", "rejectRequestPattern": [ "string" ], "rejectResourceTypes": [ "cspviolationreport" ], "requestInterceptors": [ { "pattern": "string", "response": { "headers": {}, "status": 0, "contentType": "string", "body": "string" } } ], "setExtraHTTPHeaders": {}, "setJavaScriptEnabled": true, "url": "string", "userAgent": { "userAgent": "string", "userAgentMetadata": { "brands": [ { "brand": "string", "version": "string" } ], "fullVersionList": [ { "brand": "string", "version": "string" } ], "fullVersion": "string", "platform": "string", "platformVersion": "string", "architecture": "string", "model": "string", "mobile": true, "bitness": "string", "wow64": true, "formFactors": [ "string" ] }, "platform": "string" }, "viewport": { "width": 0, "height": 0, "deviceScaleFactor": 0, "isMobile": true, "isLandscape": true, "hasTouch": true }, "waitForEvent": { "event": "string", "timeout": 0 }, "waitForFunction": { "fn": "string", "polling": "string", "timeout": 0 }, "waitForSelector": { "hidden": true, "selector": "string", "timeout": 0, "visible": true }, "waitForTimeout": 0 } } } }, "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": "#/components/schemas/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": "#/components/schemas/InBoundRequest" } }, "outbound": { "type": "array", "items": { "$ref": "#/components/schemas/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\nsession 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" }, "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\npartitioned cookie is available in. In Firefox, it matches the\nsource origin in the\n{@link https://w3c.github.io/webdriver-bidi/#type-storage-PartitionKey PartitionKey}.", "anyOf": [ { "$ref": "#/components/schemas/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\nto the endpoint that set the cookie.\n\nIn 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\nthe topLevelSite.\n\nSupported 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" }, "403": { "code": 403, "description": "The request targets a destination that is not allowed.", "message": "HTTP/1.1 403 Forbidden" }, "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": [ "Scraping & Content" ] } }, "/smart-scrape": { "post": { "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\nbefore scraping. The profile's cookies, localStorage, and IndexedDB\nentries are loaded into the session before navigation. Forces the\nbrowser 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" } }, { "in": "query", "name": "allowedDomains", "schema": { "description": "Optional per-connection narrowing of the integration's allowed-domain list.\nExtracted from the JSON `allowedDomains` query parameter. Can only narrow the\nintegration's domains, never widen them.", "type": "array", "items": { "type": "string" } } }, { "in": "query", "name": "credentials", "schema": { "$ref": "#/components/schemas/StringRecord", "description": "Optional alias → `op://…` reference map for the integration above. Extracted\nfrom the JSON `credentials` query parameter. References are not secret;\nresolved values are never stored here. Optional — a connection can also pass\nraw `op://…` references straight to Browserless.loadSecret." } }, { "in": "query", "name": "externalProxyServer", "schema": { "description": "External proxy server URL for user-provided proxies.\nFormat: http(s)://[username:password@]host:port\nWhen set, routes requests through this proxy instead of built-in residential proxies.", "type": "string" } }, { "in": "query", "name": "integrationId", "schema": { "description": "Optional 1Password integration id for credential filling on a non-persistent\nconnection. Extracted from the `integrationId` query parameter; the persistent\nsession path carries the same data on session metadata instead.", "type": "string" } }, { "in": "query", "name": "proxy", "schema": { "$ref": "#/components/schemas/ProxyType", "description": "The type of proxy to use: 'residential' or 'datacenter'." } }, { "in": "query", "name": "proxyCity", "schema": { "description": "The city to use for the proxy.\n\nAvailable cities: https://production-sfo.browserless.io/proxy/cities?token=YOUR_TOKEN\nDocumentation: 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.\n\nSupported codes: US, GB, FR, DE, etc.\nFull 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.\nRecommended when using proxyCountry to ensure websites render content,\ncurrency, 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.\nMaps to specific proxy vendors internally for optimal access to certain websites.\nFormat: \"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" } } ], "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\nstrings such as `[\"markdown\", \"screenshot\"]`. When `screenshot` or `pdf`\nis included, a browser strategy is forced.\nMirrors the Firecrawl \"formats\" convention.\n\n- `markdown` – page content converted to markdown\n- `html` – cleaned HTML (returned by default in `content`, this is a no-op convenience value)\n- `screenshot` – full-page screenshot as base64-encoded PNG (forces browser strategy)\n- `pdf` – PDF of the page as base64-encoded string (forces browser strategy)\n- `links` – list of links extracted from the page", "default": [ "html" ], "type": "array", "items": { "enum": [ "html", "links", "markdown", "pdf", "screenshot" ], "type": "string" } }, "proxy": { "description": "The proxy network to route the scrape through. Defaults to `residential`.\nUse `datacenter` for the cheaper datacenter pool.", "enum": [ "datacenter", "residential" ], "type": "string" } }, "type": "object", "required": [ "url" ], "example": { "url": "https://docs.browserless.io/" } }, "example": { "url": "string", "formats": [ "html" ], "proxy": "datacenter" } } } }, "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": "#/components/schemas/AnyRecord" }, { "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": "#/components/schemas/StringRecord", "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" }, "403": { "code": 403, "description": "The request targets a destination that is not allowed.", "message": "HTTP/1.1 403 Forbidden" }, "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": [ "Scraping & Content" ] } }, "/search": { "post": { "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" } }, { "in": "query", "name": "allowedDomains", "schema": { "description": "Optional per-connection narrowing of the integration's allowed-domain list.\nExtracted from the JSON `allowedDomains` query parameter. Can only narrow the\nintegration's domains, never widen them.", "type": "array", "items": { "type": "string" } } }, { "in": "query", "name": "credentials", "schema": { "$ref": "#/components/schemas/StringRecord", "description": "Optional alias → `op://…` reference map for the integration above. Extracted\nfrom the JSON `credentials` query parameter. References are not secret;\nresolved values are never stored here. Optional — a connection can also pass\nraw `op://…` references straight to Browserless.loadSecret." } }, { "in": "query", "name": "externalProxyServer", "schema": { "description": "External proxy server URL for user-provided proxies.\nFormat: http(s)://[username:password@]host:port\nWhen set, routes requests through this proxy instead of built-in residential proxies.", "type": "string" } }, { "in": "query", "name": "integrationId", "schema": { "description": "Optional 1Password integration id for credential filling on a non-persistent\nconnection. Extracted from the `integrationId` query parameter; the persistent\nsession path carries the same data on session metadata instead.", "type": "string" } }, { "in": "query", "name": "proxy", "schema": { "$ref": "#/components/schemas/ProxyType", "description": "The type of proxy to use: 'residential' or 'datacenter'." } }, { "in": "query", "name": "proxyCity", "schema": { "description": "The city to use for the proxy.\n\nAvailable cities: https://production-sfo.browserless.io/proxy/cities?token=YOUR_TOKEN\nDocumentation: 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.\n\nSupported codes: US, GB, FR, DE, etc.\nFull 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.\nRecommended when using proxyCountry to ensure websites render content,\ncurrency, 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.\nMaps to specific proxy vendors internally for optimal access to certain websites.\nFormat: \"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" } } ], "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" }, "proxy": { "description": "Proxy network to route result scraping through: `\"residential\"` (default) or `\"datacenter\"`.", "enum": [ "datacenter", "residential" ], "type": "string" }, "tbs": { "description": "Time-based filter. Accepts `\"day\"`, `\"week\"`, `\"month\"`, `\"year\"`, or raw Google TBS syntax (`\"qdr:d\"`, `\"qdr:w\"`, `\"qdr:m\"`, `\"qdr:y\"`).", "enum": [ "day", "month", "qdr:d", "qdr:m", "qdr:w", "qdr:y", "week", "year" ], "type": "string" }, "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": { "200": { "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "$ref": "#/components/schemas/SearchResponseData" }, "totalResults": { "type": "number" }, "error": { "type": "string" } }, "additionalProperties": false, "required": [ "data", "success", "totalResults" ], "definitions": { "SearchResponseData": { "type": "object", "properties": { "web": { "type": "array", "items": { "$ref": "#/components/schemas/WebSearchResult" } }, "news": { "type": "array", "items": { "$ref": "#/components/schemas/NewsSearchResult" } }, "images": { "type": "array", "items": { "$ref": "#/components/schemas/ImageSearchResult" } } }, "additionalProperties": false }, "WebSearchResult": { "type": "object", "properties": { "title": { "type": "string" }, "url": { "type": "string" }, "description": { "type": "string" }, "position": { "type": "number" }, "markdown": { "type": "string" }, "html": { "type": "string" }, "links": { "type": "array", "items": { "type": "string" } }, "screenshot": { "type": "string" }, "metadata": { "type": "object", "properties": { "statusCode": { "type": "number" }, "strategy": { "type": "string" }, "error": { "type": "string" } }, "additionalProperties": false, "required": [ "statusCode" ] } }, "additionalProperties": false, "required": [ "description", "title", "url" ] }, "NewsSearchResult": { "type": "object", "properties": { "date": { "type": "string" }, "imageUrl": { "type": "string" }, "title": { "type": "string" }, "url": { "type": "string" }, "description": { "type": "string" }, "position": { "type": "number" }, "markdown": { "type": "string" }, "html": { "type": "string" }, "links": { "type": "array", "items": { "type": "string" } }, "screenshot": { "type": "string" }, "metadata": { "type": "object", "properties": { "statusCode": { "type": "number" }, "strategy": { "type": "string" }, "error": { "type": "string" } }, "additionalProperties": false, "required": [ "statusCode" ] } }, "additionalProperties": false, "required": [ "description", "title", "url" ] }, "ImageSearchResult": { "type": "object", "properties": { "title": { "type": "string" }, "imageUrl": { "type": "string" }, "imageWidth": { "type": "number" }, "imageHeight": { "type": "number" }, "url": { "type": "string" }, "position": { "type": "number" } }, "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" }, "403": { "code": 403, "description": "The request targets a destination that is not allowed.", "message": "HTTP/1.1 403 Forbidden" }, "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": [ "Scraping & Content" ] } }, "/map": { "post": { "description": "Primarily discovers URLs from the site's sitemap, supplemented\nwith link extraction from the page via the smart-scrape strategy\npipeline (HTTP-first, browser fallback for JS-rendered pages).\nUse 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" } }, { "in": "query", "name": "allowedDomains", "schema": { "description": "Optional per-connection narrowing of the integration's allowed-domain list.\nExtracted from the JSON `allowedDomains` query parameter. Can only narrow the\nintegration's domains, never widen them.", "type": "array", "items": { "type": "string" } } }, { "in": "query", "name": "credentials", "schema": { "$ref": "#/components/schemas/StringRecord", "description": "Optional alias → `op://…` reference map for the integration above. Extracted\nfrom the JSON `credentials` query parameter. References are not secret;\nresolved values are never stored here. Optional — a connection can also pass\nraw `op://…` references straight to Browserless.loadSecret." } }, { "in": "query", "name": "externalProxyServer", "schema": { "description": "External proxy server URL for user-provided proxies.\nFormat: http(s)://[username:password@]host:port\nWhen set, routes requests through this proxy instead of built-in residential proxies.", "type": "string" } }, { "in": "query", "name": "integrationId", "schema": { "description": "Optional 1Password integration id for credential filling on a non-persistent\nconnection. Extracted from the `integrationId` query parameter; the persistent\nsession path carries the same data on session metadata instead.", "type": "string" } }, { "in": "query", "name": "proxy", "schema": { "$ref": "#/components/schemas/ProxyType", "description": "The type of proxy to use: 'residential' or 'datacenter'." } }, { "in": "query", "name": "proxyCity", "schema": { "description": "The city to use for the proxy.\n\nAvailable cities: https://production-sfo.browserless.io/proxy/cities?token=YOUR_TOKEN\nDocumentation: 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.\n\nSupported codes: US, GB, FR, DE, etc.\nFull 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.\nRecommended when using proxyCountry to ensure websites render content,\ncurrency, 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.\nMaps to specific proxy vendors internally for optimal access to certain websites.\nFormat: \"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" } } ], "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 }, "proxy": { "description": "Proxy network to route through: `\"residential\"` (default) or `\"datacenter\"`.", "enum": [ "datacenter", "residential" ], "type": "string" } }, "type": "object", "required": [ "url" ], "example": { "url": "https://docs.browserless.io/" } }, "example": { "url": "string", "search": "string", "limit": 0, "timeout": 0, "sitemap": "include", "includeSubdomains": true, "ignoreQueryParameters": true, "location": { "country": "string", "languages": [ "string" ] }, "proxy": "datacenter" } } } }, "responses": { "200": { "content": { "application/json": { "schema": { "type": "array", "items": { "type": "string" }, "description": "An array of URLs discovered on the target page, including links found in the HTML, sitemap entries, and any other discoverable URLs." } } }, "description": "An array of discovered URLs from the target page and its sitemap." }, "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" }, "403": { "code": 403, "description": "The request targets a destination that is not allowed.", "message": "HTTP/1.1 403 Forbidden" }, "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": [ "Scraping & Content" ] } }, "/edge/content": { "post": { "description": "Given a `url` or `html` field, loads the page in Edge and returns the fully rendered HTML.", "parameters": [ { "in": "query", "name": "blockAds", "schema": { "description": "Whether or not to load ad-blocking extensions for the session.\nThis currently uses uBlock-Lite and may cause certain sites\nto not load properly.", "type": "boolean" } }, { "in": "query", "name": "launch", "schema": { "anyOf": [ { "$ref": "#/components/schemas/CDPLaunchOptions" }, { "type": "string" } ] } }, { "in": "query", "name": "profile", "schema": { "description": "Name of an authenticated profile to hydrate into the browser at launch.\nThe profile's cookies, localStorage and IndexedDB are injected via CDP\nbefore 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.\nAccepts 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" } }, { "in": "query", "name": "allowedDomains", "schema": { "description": "Optional per-connection narrowing of the integration's allowed-domain list.\nExtracted from the JSON `allowedDomains` query parameter. Can only narrow the\nintegration's domains, never widen them.", "type": "array", "items": { "type": "string" } } }, { "in": "query", "name": "credentials", "schema": { "$ref": "#/components/schemas/StringRecord", "description": "Optional alias → `op://…` reference map for the integration above. Extracted\nfrom the JSON `credentials` query parameter. References are not secret;\nresolved values are never stored here. Optional — a connection can also pass\nraw `op://…` references straight to Browserless.loadSecret." } }, { "in": "query", "name": "externalProxyServer", "schema": { "description": "External proxy server URL for user-provided proxies.\nFormat: http(s)://[username:password@]host:port\nWhen set, routes requests through this proxy instead of built-in residential proxies.", "type": "string" } }, { "in": "query", "name": "integrationId", "schema": { "description": "Optional 1Password integration id for credential filling on a non-persistent\nconnection. Extracted from the `integrationId` query parameter; the persistent\nsession path carries the same data on session metadata instead.", "type": "string" } }, { "in": "query", "name": "proxy", "schema": { "$ref": "#/components/schemas/ProxyType", "description": "The type of proxy to use: 'residential' or 'datacenter'." } }, { "in": "query", "name": "proxyCity", "schema": { "description": "The city to use for the proxy.\n\nAvailable cities: https://production-sfo.browserless.io/proxy/cities?token=YOUR_TOKEN\nDocumentation: 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.\n\nSupported codes: US, GB, FR, DE, etc.\nFull 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.\nRecommended when using proxyCountry to ensure websites render content,\ncurrency, 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.\nMaps to specific proxy vendors internally for optimal access to certain websites.\nFormat: \"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" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "addScriptTag": { "type": "array", "items": { "$ref": "#/components/schemas/FrameAddScriptTagOptions" } }, "addStyleTag": { "type": "array", "items": { "$ref": "#/components/schemas/FrameAddStyleTagOptions" } }, "authenticate": { "anyOf": [ { "$ref": "#/components/schemas/Credentials" }, { "type": "null" } ], "description": "Credentials for HTTP authentication. Contains `username` and `password` properties." }, "bestAttempt": { "description": "When bestAttempt is set to true, browserless attempt to proceed\nwhen \"awaited\" events fail or timeout. This includes things like\ngoto, waitForSelector, and more.", "type": "boolean" }, "cookies": { "type": "array", "items": { "$ref": "#/components/schemas/CookieParam" } }, "emulateMediaType": { "type": "string" }, "gotoOptions": { "$ref": "#/components/schemas/GoToOptions", "description": "Options to configure the page navigation, such as `timeout` and `waitUntil`." }, "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\ncorresponding 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\ncorresponding responses to use in order to fulfill those requests.", "type": "string" }, "response": { "additionalProperties": false, "type": "object", "properties": { "headers": { "description": "Optional response headers.\n\nThe record values will be converted to string following:\nArrays' values will be mapped to String\n(Used when you need multiple headers with the same name).\nNon-arrays will be converted to String.", "$ref": "#/components/schemas/AnyRecord" }, "status": { "type": "number" }, "contentType": { "type": "string" }, "body": { "description": "A string representation of the body to return. Can be a base64-encoded\nstring 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\nMissing optional values will be filled in by the target with what it would normally use.", "$ref": "#/components/schemas/Protocol.Emulation.UserAgentMetadata" }, "platform": { "type": "string" } }, "additionalProperties": false }, "viewport": { "anyOf": [ { "$ref": "#/components/schemas/Viewport" }, { "type": "null" } ], "description": "The viewport dimensions and settings for the page.\nIncludes properties like `width`, `height`, `deviceScaleFactor`, etc." }, "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.\nIf polling is a number, then it is treated as an interval in milliseconds\nat which the function would be executed. If polling is a string,\nthen 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).\nPass 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", "example": { "url": "https://docs.browserless.io/" } }, "example": { "addScriptTag": [ { "url": "string", "content": "string", "type": "string", "id": "string" } ], "addStyleTag": [ { "url": "string", "content": "string" } ], "authenticate": { "username": "string", "password": "string" }, "bestAttempt": true, "cookies": [ { "name": "string", "value": "string", "url": "string", "domain": "string", "path": "string", "secure": true, "httpOnly": true, "sameSite": "Default", "expires": 0, "priority": "High", "sourceScheme": "NonSecure", "partitionKey": { "sourceOrigin": "string", "hasCrossSiteAncestor": true } } ], "emulateMediaType": "string", "gotoOptions": { "referer": "string", "referrerPolicy": "string", "timeout": 0, "waitUntil": [ "domcontentloaded" ], "signal": { "aborted": true, "onabort": {}, "reason": {} } }, "html": "string", "rejectRequestPattern": [ "string" ], "rejectResourceTypes": [ "cspviolationreport" ], "requestInterceptors": [ { "pattern": "string", "response": { "headers": {}, "status": 0, "contentType": "string", "body": "string" } } ], "setExtraHTTPHeaders": {}, "setJavaScriptEnabled": true, "url": "string", "userAgent": { "userAgent": "string", "userAgentMetadata": { "brands": [ { "brand": "string", "version": "string" } ], "fullVersionList": [ { "brand": "string", "version": "string" } ], "fullVersion": "string", "platform": "string", "platformVersion": "string", "architecture": "string", "model": "string", "mobile": true, "bitness": "string", "wow64": true, "formFactors": [ "string" ] }, "platform": "string" }, "viewport": { "width": 0, "height": 0, "deviceScaleFactor": 0, "isMobile": true, "isLandscape": true, "hasTouch": true }, "waitForEvent": { "event": "string", "timeout": 0 }, "waitForFunction": { "fn": "string", "polling": "string", "timeout": 0 }, "waitForSelector": { "hidden": true, "selector": "string", "timeout": 0, "visible": true }, "waitForTimeout": 0 } } } }, "responses": { "200": { "content": { "text/html": { "schema": { "description": "An HTML payload of the website or HTML after JavaScript\nparsing and execution.", "type": "string", "$schema": "http://json-schema.org/draft-07/schema#" } } }, "description": "An HTML payload of the website or HTML after JavaScript\nparsing 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" }, "403": { "code": 403, "description": "The request targets a destination that is not allowed.", "message": "HTTP/1.1 403 Forbidden" }, "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": [ "Scraping & Content" ] } }, "/edge/scrape": { "post": { "description": "Returns text, HTML, and metadata from a given list of CSS selectors against the rendered DOM (Edge).\nDebugging information is available by sending in the appropriate flags in the \"debugOpts\"\nproperty. Responds with an array of JSON objects.", "parameters": [ { "in": "query", "name": "blockAds", "schema": { "description": "Whether or not to load ad-blocking extensions for the session.\nThis currently uses uBlock-Lite and may cause certain sites\nto not load properly.", "type": "boolean" } }, { "in": "query", "name": "launch", "schema": { "anyOf": [ { "$ref": "#/components/schemas/CDPLaunchOptions" }, { "type": "string" } ] } }, { "in": "query", "name": "profile", "schema": { "description": "Name of an authenticated profile to hydrate into the browser at launch.\nThe profile's cookies, localStorage and IndexedDB are injected via CDP\nbefore 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.\nAccepts 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" } }, { "in": "query", "name": "allowedDomains", "schema": { "description": "Optional per-connection narrowing of the integration's allowed-domain list.\nExtracted from the JSON `allowedDomains` query parameter. Can only narrow the\nintegration's domains, never widen them.", "type": "array", "items": { "type": "string" } } }, { "in": "query", "name": "credentials", "schema": { "$ref": "#/components/schemas/StringRecord", "description": "Optional alias → `op://…` reference map for the integration above. Extracted\nfrom the JSON `credentials` query parameter. References are not secret;\nresolved values are never stored here. Optional — a connection can also pass\nraw `op://…` references straight to Browserless.loadSecret." } }, { "in": "query", "name": "externalProxyServer", "schema": { "description": "External proxy server URL for user-provided proxies.\nFormat: http(s)://[username:password@]host:port\nWhen set, routes requests through this proxy instead of built-in residential proxies.", "type": "string" } }, { "in": "query", "name": "integrationId", "schema": { "description": "Optional 1Password integration id for credential filling on a non-persistent\nconnection. Extracted from the `integrationId` query parameter; the persistent\nsession path carries the same data on session metadata instead.", "type": "string" } }, { "in": "query", "name": "proxy", "schema": { "$ref": "#/components/schemas/ProxyType", "description": "The type of proxy to use: 'residential' or 'datacenter'." } }, { "in": "query", "name": "proxyCity", "schema": { "description": "The city to use for the proxy.\n\nAvailable cities: https://production-sfo.browserless.io/proxy/cities?token=YOUR_TOKEN\nDocumentation: 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.\n\nSupported codes: US, GB, FR, DE, etc.\nFull 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.\nRecommended when using proxyCountry to ensure websites render content,\ncurrency, 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.\nMaps to specific proxy vendors internally for optimal access to certain websites.\nFormat: \"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" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "addScriptTag": { "type": "array", "items": { "$ref": "#/components/schemas/FrameAddScriptTagOptions" } }, "addStyleTag": { "type": "array", "items": { "$ref": "#/components/schemas/FrameAddStyleTagOptions" } }, "authenticate": { "anyOf": [ { "$ref": "#/components/schemas/Credentials" }, { "type": "null" } ], "description": "Credentials for HTTP authentication. Contains `username` and `password` properties." }, "bestAttempt": { "description": "When bestAttempt is set to true, browserless attempt to proceed\nwhen \"awaited\" events fail or timeout. This includes things like\ngoto, waitForSelector, and more.", "type": "boolean" }, "cookies": { "type": "array", "items": { "$ref": "#/components/schemas/CookieParam" } }, "debugOpts": { "$ref": "#/components/schemas/ScrapeDebugOptions" }, "elements": { "type": "array", "items": { "$ref": "#/components/schemas/ScrapeElementSelector" } }, "emulateMediaType": { "type": "string" }, "gotoOptions": { "$ref": "#/components/schemas/GoToOptions", "description": "Options to configure the page navigation, such as `timeout` and `waitUntil`." }, "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\ncorresponding 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\ncorresponding responses to use in order to fulfill those requests.", "type": "string" }, "response": { "additionalProperties": false, "type": "object", "properties": { "headers": { "description": "Optional response headers.\n\nThe record values will be converted to string following:\nArrays' values will be mapped to String\n(Used when you need multiple headers with the same name).\nNon-arrays will be converted to String.", "$ref": "#/components/schemas/AnyRecord" }, "status": { "type": "number" }, "contentType": { "type": "string" }, "body": { "description": "A string representation of the body to return. Can be a base64-encoded\nstring 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\nMissing optional values will be filled in by the target with what it would normally use.", "$ref": "#/components/schemas/Protocol.Emulation.UserAgentMetadata" }, "platform": { "type": "string" } }, "additionalProperties": false }, "viewport": { "anyOf": [ { "$ref": "#/components/schemas/Viewport" }, { "type": "null" } ], "description": "The viewport dimensions and settings for the page.\nIncludes properties like `width`, `height`, `deviceScaleFactor`, etc." }, "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.\nIf polling is a number, then it is treated as an interval in milliseconds\nat which the function would be executed. If polling is a string,\nthen 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).\nPass 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" ], "example": { "url": "https://docs.browserless.io/", "elements": [ { "selector": "h1" } ] } }, "example": { "addScriptTag": [ { "url": "string", "content": "string", "type": "string", "id": "string" } ], "addStyleTag": [ { "url": "string", "content": "string" } ], "authenticate": { "username": "string", "password": "string" }, "bestAttempt": true, "cookies": [ { "name": "string", "value": "string", "url": "string", "domain": "string", "path": "string", "secure": true, "httpOnly": true, "sameSite": "Default", "expires": 0, "priority": "High", "sourceScheme": "NonSecure", "partitionKey": { "sourceOrigin": "string", "hasCrossSiteAncestor": true } } ], "debugOpts": { "console": true, "cookies": true, "html": true, "network": true, "screenshot": true }, "elements": [ { "selector": "string", "timeout": 0 } ], "emulateMediaType": "string", "gotoOptions": { "referer": "string", "referrerPolicy": "string", "timeout": 0, "waitUntil": [ "domcontentloaded" ], "signal": { "aborted": true, "onabort": {}, "reason": {} } }, "html": "string", "rejectRequestPattern": [ "string" ], "rejectResourceTypes": [ "cspviolationreport" ], "requestInterceptors": [ { "pattern": "string", "response": { "headers": {}, "status": 0, "contentType": "string", "body": "string" } } ], "setExtraHTTPHeaders": {}, "setJavaScriptEnabled": true, "url": "string", "userAgent": { "userAgent": "string", "userAgentMetadata": { "brands": [ { "brand": "string", "version": "string" } ], "fullVersionList": [ { "brand": "string", "version": "string" } ], "fullVersion": "string", "platform": "string", "platformVersion": "string", "architecture": "string", "model": "string", "mobile": true, "bitness": "string", "wow64": true, "formFactors": [ "string" ] }, "platform": "string" }, "viewport": { "width": 0, "height": 0, "deviceScaleFactor": 0, "isMobile": true, "isLandscape": true, "hasTouch": true }, "waitForEvent": { "event": "string", "timeout": 0 }, "waitForFunction": { "fn": "string", "polling": "string", "timeout": 0 }, "waitForSelector": { "hidden": true, "selector": "string", "timeout": 0, "visible": true }, "waitForTimeout": 0 } } } }, "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": "#/components/schemas/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": "#/components/schemas/InBoundRequest" } }, "outbound": { "type": "array", "items": { "$ref": "#/components/schemas/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\nsession 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" }, "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\npartitioned cookie is available in. In Firefox, it matches the\nsource origin in the\n{@link https://w3c.github.io/webdriver-bidi/#type-storage-PartitionKey PartitionKey}.", "anyOf": [ { "$ref": "#/components/schemas/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\nto the endpoint that set the cookie.\n\nIn 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\nthe topLevelSite.\n\nSupported 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" }, "403": { "code": 403, "description": "The request targets a destination that is not allowed.", "message": "HTTP/1.1 403 Forbidden" }, "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": [ "Scraping & Content" ] } }, "/chromium/performance": { "post": { "description": "Run lighthouse performance audits with a supplied \"url\" in your JSON payload.\n\n**Note:** Also available at `/performance` as a convenience alias.", "parameters": [ { "in": "query", "name": "blockAds", "schema": { "description": "Whether or not to load ad-blocking extensions for the session.\nThis currently uses uBlock-Lite and may cause certain sites\nto not load properly.", "type": "boolean" } }, { "in": "query", "name": "launch", "schema": { "description": "Launch options, which can be either an object\nof puppeteer.launch options or playwright.launchServer\noptions, depending on the API. Must be either JSON\nobject, or a base64-encoded JSON object.", "anyOf": [ { "$ref": "#/components/schemas/CDPLaunchOptions" }, { "type": "string" } ] } }, { "in": "query", "name": "profile", "schema": { "description": "Name of an authenticated profile to hydrate into the browser at launch.\nThe profile's cookies, localStorage and IndexedDB are injected via CDP\nbefore 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.\nAccepts 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" } }, { "in": "query", "name": "allowedDomains", "schema": { "description": "Optional per-connection narrowing of the integration's allowed-domain list.\nExtracted from the JSON `allowedDomains` query parameter. Can only narrow the\nintegration's domains, never widen them.", "type": "array", "items": { "type": "string" } } }, { "in": "query", "name": "credentials", "schema": { "$ref": "#/components/schemas/StringRecord", "description": "Optional alias → `op://…` reference map for the integration above. Extracted\nfrom the JSON `credentials` query parameter. References are not secret;\nresolved values are never stored here. Optional — a connection can also pass\nraw `op://…` references straight to Browserless.loadSecret." } }, { "in": "query", "name": "externalProxyServer", "schema": { "description": "External proxy server URL for user-provided proxies.\nFormat: http(s)://[username:password@]host:port\nWhen set, routes requests through this proxy instead of built-in residential proxies.", "type": "string" } }, { "in": "query", "name": "integrationId", "schema": { "description": "Optional 1Password integration id for credential filling on a non-persistent\nconnection. Extracted from the `integrationId` query parameter; the persistent\nsession path carries the same data on session metadata instead.", "type": "string" } }, { "in": "query", "name": "proxy", "schema": { "$ref": "#/components/schemas/ProxyType", "description": "The type of proxy to use: 'residential' or 'datacenter'." } }, { "in": "query", "name": "proxyCity", "schema": { "description": "The city to use for the proxy.\n\nAvailable cities: https://production-sfo.browserless.io/proxy/cities?token=YOUR_TOKEN\nDocumentation: 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.\n\nSupported codes: US, GB, FR, DE, etc.\nFull 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.\nRecommended when using proxyCountry to ensure websites render content,\ncurrency, 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.\nMaps to specific proxy vendors internally for optimal access to certain websites.\nFormat: \"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" } } ], "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" ], "example": { "url": "https://docs.browserless.io/" } }, "example": { "budgets": [ {} ], "config": {}, "url": "string" } } } }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "The response of the lighthouse stats. Response objects are\ndetermined by the type of budgets and config in the POST\nJSON body", "type": "object", "properties": {}, "additionalProperties": true, "$schema": "http://json-schema.org/draft-07/schema#" } } }, "description": "The response of the lighthouse stats. Response objects are\ndetermined by the type of budgets and config in the POST\nJSON 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" }, "403": { "code": 403, "description": "The request targets a destination that is not allowed.", "message": "HTTP/1.1 403 Forbidden" }, "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": [ "Scraping & Content" ] } }, "/edge/performance": { "post": { "description": "Run lighthouse performance audits with a supplied \"url\" in your JSON payload.", "parameters": [ { "in": "query", "name": "blockAds", "schema": { "description": "Whether or not to load ad-blocking extensions for the session.\nThis currently uses uBlock-Lite and may cause certain sites\nto not load properly.", "type": "boolean" } }, { "in": "query", "name": "launch", "schema": { "description": "Launch options, which can be either an object\nof puppeteer.launch options or playwright.launchServer\noptions, depending on the API. Must be either JSON\nobject, or a base64-encoded JSON object.", "anyOf": [ { "$ref": "#/components/schemas/CDPLaunchOptions" }, { "type": "string" } ] } }, { "in": "query", "name": "profile", "schema": { "description": "Name of an authenticated profile to hydrate into the browser at launch.\nThe profile's cookies, localStorage and IndexedDB are injected via CDP\nbefore 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.\nAccepts 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" } }, { "in": "query", "name": "allowedDomains", "schema": { "description": "Optional per-connection narrowing of the integration's allowed-domain list.\nExtracted from the JSON `allowedDomains` query parameter. Can only narrow the\nintegration's domains, never widen them.", "type": "array", "items": { "type": "string" } } }, { "in": "query", "name": "credentials", "schema": { "$ref": "#/components/schemas/StringRecord", "description": "Optional alias → `op://…` reference map for the integration above. Extracted\nfrom the JSON `credentials` query parameter. References are not secret;\nresolved values are never stored here. Optional — a connection can also pass\nraw `op://…` references straight to Browserless.loadSecret." } }, { "in": "query", "name": "externalProxyServer", "schema": { "description": "External proxy server URL for user-provided proxies.\nFormat: http(s)://[username:password@]host:port\nWhen set, routes requests through this proxy instead of built-in residential proxies.", "type": "string" } }, { "in": "query", "name": "integrationId", "schema": { "description": "Optional 1Password integration id for credential filling on a non-persistent\nconnection. Extracted from the `integrationId` query parameter; the persistent\nsession path carries the same data on session metadata instead.", "type": "string" } }, { "in": "query", "name": "proxy", "schema": { "$ref": "#/components/schemas/ProxyType", "description": "The type of proxy to use: 'residential' or 'datacenter'." } }, { "in": "query", "name": "proxyCity", "schema": { "description": "The city to use for the proxy.\n\nAvailable cities: https://production-sfo.browserless.io/proxy/cities?token=YOUR_TOKEN\nDocumentation: 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.\n\nSupported codes: US, GB, FR, DE, etc.\nFull 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.\nRecommended when using proxyCountry to ensure websites render content,\ncurrency, 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.\nMaps to specific proxy vendors internally for optimal access to certain websites.\nFormat: \"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" } } ], "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" ], "example": { "url": "https://docs.browserless.io/" } }, "example": { "budgets": [ {} ], "config": {}, "url": "string" } } } }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "The response of the lighthouse stats. Response objects are\ndetermined by the type of budgets and config in the POST\nJSON body", "type": "object", "properties": {}, "additionalProperties": true, "$schema": "http://json-schema.org/draft-07/schema#" } } }, "description": "The response of the lighthouse stats. Response objects are\ndetermined by the type of budgets and config in the POST\nJSON 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" }, "403": { "code": 403, "description": "The request targets a destination that is not allowed.", "message": "HTTP/1.1 403 Forbidden" }, "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": [ "Scraping & Content" ] } }, "/chromium/function": { "post": { "description": "Executes a Puppeteer or Playwright script in the browser context and returns the result.\nBrowserless sets up a blank page, injects your puppeteer code, and runs it.\nYou can optionally load external libraries via the \"import\" module that are meant for browser usage.\nValues returned from the function are checked and an appropriate content-type and response is sent back\nto your HTTP call.\n\n**Note:** Also available at `/function` as a convenience alias.", "parameters": [ { "in": "query", "name": "blockAds", "schema": { "description": "Whether or not to load ad-blocking extensions for the session.\nThis currently uses uBlock-Lite and may cause certain sites\nto not load properly.", "type": "boolean" } }, { "in": "query", "name": "launch", "schema": { "description": "Launch options, which can be either an object\nof puppeteer.launch options or playwright.launchServer\noptions, depending on the API. Must be either JSON\nobject, or a base64-encoded JSON object.", "anyOf": [ { "$ref": "#/components/schemas/CDPLaunchOptions" }, { "type": "string" } ] } }, { "in": "query", "name": "profile", "schema": { "description": "Name of an authenticated profile to hydrate into the browser at launch.\nThe profile's cookies, localStorage and IndexedDB are injected via CDP\nbefore 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.\nAccepts 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" } }, { "in": "query", "name": "allowedDomains", "schema": { "description": "Optional per-connection narrowing of the integration's allowed-domain list.\nExtracted from the JSON `allowedDomains` query parameter. Can only narrow the\nintegration's domains, never widen them.", "type": "array", "items": { "type": "string" } } }, { "in": "query", "name": "credentials", "schema": { "$ref": "#/components/schemas/StringRecord", "description": "Optional alias → `op://…` reference map for the integration above. Extracted\nfrom the JSON `credentials` query parameter. References are not secret;\nresolved values are never stored here. Optional — a connection can also pass\nraw `op://…` references straight to Browserless.loadSecret." } }, { "in": "query", "name": "externalProxyServer", "schema": { "description": "External proxy server URL for user-provided proxies.\nFormat: http(s)://[username:password@]host:port\nWhen set, routes requests through this proxy instead of built-in residential proxies.", "type": "string" } }, { "in": "query", "name": "integrationId", "schema": { "description": "Optional 1Password integration id for credential filling on a non-persistent\nconnection. Extracted from the `integrationId` query parameter; the persistent\nsession path carries the same data on session metadata instead.", "type": "string" } }, { "in": "query", "name": "proxy", "schema": { "$ref": "#/components/schemas/ProxyType", "description": "The type of proxy to use: 'residential' or 'datacenter'." } }, { "in": "query", "name": "proxyCity", "schema": { "description": "The city to use for the proxy.\n\nAvailable cities: https://production-sfo.browserless.io/proxy/cities?token=YOUR_TOKEN\nDocumentation: 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.\n\nSupported codes: US, GB, FR, DE, etc.\nFull 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.\nRecommended when using proxyCountry to ensure websites render content,\ncurrency, 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.\nMaps to specific proxy vendors internally for optimal access to certain websites.\nFormat: \"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" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JSONSchema" } }, "application/javascript": { "schema": { "type": "string" } } } }, "responses": { "200": { "content": { "*/*": { "schema": { "description": "Responses are determined by the returned value of the function\nitself. Binary responses (PDF's, screenshots) are returned back\nas binary data, and primitive JavaScript values are returned back\nby 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\nitself. Binary responses (PDF's, screenshots) are returned back\nas binary data, and primitive JavaScript values are returned back\nby 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" }, "403": { "code": 403, "description": "The request targets a destination that is not allowed.", "message": "HTTP/1.1 403 Forbidden" }, "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": [ "Functions & Downloads" ] } }, "/chromium/download": { "post": { "description": "Runs a Puppeteer or Playwright script and returns any files the browser downloaded during execution.\nthe execution of puppeteer code, which is ran inside context of the browser.\nBrowserless sets up a blank page, a fresh download directory, injects your puppeteer code, and then executes it.\nYou can load external libraries via the \"import\" syntax, and import ESM-style modules\nthat are written for execution inside of the browser. Once your script is finished, any\ndownloaded files from Chromium are returned back with the appropriate content-type header.\n\n**Note:** Also available at `/download` as a convenience alias.", "parameters": [ { "in": "query", "name": "blockAds", "schema": { "description": "Whether or not to load ad-blocking extensions for the session.\nThis currently uses uBlock-Lite and may cause certain sites\nto not load properly.", "type": "boolean" } }, { "in": "query", "name": "launch", "schema": { "description": "Launch options, which can be either an object\nof puppeteer.launch options or playwright.launchServer\noptions, depending on the API. Must be either JSON\nobject, or a base64-encoded JSON object.", "anyOf": [ { "$ref": "#/components/schemas/CDPLaunchOptions" }, { "type": "string" } ] } }, { "in": "query", "name": "profile", "schema": { "description": "Name of an authenticated profile to hydrate into the browser at launch.\nThe profile's cookies, localStorage and IndexedDB are injected via CDP\nbefore 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.\nAccepts 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" } }, { "in": "query", "name": "allowedDomains", "schema": { "description": "Optional per-connection narrowing of the integration's allowed-domain list.\nExtracted from the JSON `allowedDomains` query parameter. Can only narrow the\nintegration's domains, never widen them.", "type": "array", "items": { "type": "string" } } }, { "in": "query", "name": "credentials", "schema": { "$ref": "#/components/schemas/StringRecord", "description": "Optional alias → `op://…` reference map for the integration above. Extracted\nfrom the JSON `credentials` query parameter. References are not secret;\nresolved values are never stored here. Optional — a connection can also pass\nraw `op://…` references straight to Browserless.loadSecret." } }, { "in": "query", "name": "externalProxyServer", "schema": { "description": "External proxy server URL for user-provided proxies.\nFormat: http(s)://[username:password@]host:port\nWhen set, routes requests through this proxy instead of built-in residential proxies.", "type": "string" } }, { "in": "query", "name": "integrationId", "schema": { "description": "Optional 1Password integration id for credential filling on a non-persistent\nconnection. Extracted from the `integrationId` query parameter; the persistent\nsession path carries the same data on session metadata instead.", "type": "string" } }, { "in": "query", "name": "proxy", "schema": { "$ref": "#/components/schemas/ProxyType", "description": "The type of proxy to use: 'residential' or 'datacenter'." } }, { "in": "query", "name": "proxyCity", "schema": { "description": "The city to use for the proxy.\n\nAvailable cities: https://production-sfo.browserless.io/proxy/cities?token=YOUR_TOKEN\nDocumentation: 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.\n\nSupported codes: US, GB, FR, DE, etc.\nFull 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.\nRecommended when using proxyCountry to ensure websites render content,\ncurrency, 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.\nMaps to specific proxy vendors internally for optimal access to certain websites.\nFormat: \"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" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JSONSchema" } }, "application/javascript": { "schema": { "type": "string" } } } }, "responses": { "200": { "content": { "*/*": { "schema": { "description": "Responses are determined by the returned value of the downloads\nthemselves, 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\nthemselves, 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" }, "403": { "code": 403, "description": "The request targets a destination that is not allowed.", "message": "HTTP/1.1 403 Forbidden" }, "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": [ "Functions & Downloads" ] } }, "/edge/function": { "post": { "description": "Executes a Puppeteer or Playwright script in the Edge browser context and returns the result.\nBrowserless sets up a blank page, injects your puppeteer code, and runs it.\nYou can optionally load external libraries via the \"import\" module that are meant for browser usage.\nValues returned from the function are checked and an appropriate content-type and response is sent back\nto your HTTP call.", "parameters": [ { "in": "query", "name": "blockAds", "schema": { "description": "Whether or not to load ad-blocking extensions for the session.\nThis currently uses uBlock-Lite and may cause certain sites\nto not load properly.", "type": "boolean" } }, { "in": "query", "name": "launch", "schema": { "description": "Launch options, which can be either an object\nof puppeteer.launch options or playwright.launchServer\noptions, depending on the API. Must be either JSON\nobject, or a base64-encoded JSON object.", "anyOf": [ { "$ref": "#/components/schemas/CDPLaunchOptions" }, { "type": "string" } ] } }, { "in": "query", "name": "profile", "schema": { "description": "Name of an authenticated profile to hydrate into the browser at launch.\nThe profile's cookies, localStorage and IndexedDB are injected via CDP\nbefore 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.\nAccepts 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" } }, { "in": "query", "name": "allowedDomains", "schema": { "description": "Optional per-connection narrowing of the integration's allowed-domain list.\nExtracted from the JSON `allowedDomains` query parameter. Can only narrow the\nintegration's domains, never widen them.", "type": "array", "items": { "type": "string" } } }, { "in": "query", "name": "credentials", "schema": { "$ref": "#/components/schemas/StringRecord", "description": "Optional alias → `op://…` reference map for the integration above. Extracted\nfrom the JSON `credentials` query parameter. References are not secret;\nresolved values are never stored here. Optional — a connection can also pass\nraw `op://…` references straight to Browserless.loadSecret." } }, { "in": "query", "name": "externalProxyServer", "schema": { "description": "External proxy server URL for user-provided proxies.\nFormat: http(s)://[username:password@]host:port\nWhen set, routes requests through this proxy instead of built-in residential proxies.", "type": "string" } }, { "in": "query", "name": "integrationId", "schema": { "description": "Optional 1Password integration id for credential filling on a non-persistent\nconnection. Extracted from the `integrationId` query parameter; the persistent\nsession path carries the same data on session metadata instead.", "type": "string" } }, { "in": "query", "name": "proxy", "schema": { "$ref": "#/components/schemas/ProxyType", "description": "The type of proxy to use: 'residential' or 'datacenter'." } }, { "in": "query", "name": "proxyCity", "schema": { "description": "The city to use for the proxy.\n\nAvailable cities: https://production-sfo.browserless.io/proxy/cities?token=YOUR_TOKEN\nDocumentation: 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.\n\nSupported codes: US, GB, FR, DE, etc.\nFull 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.\nRecommended when using proxyCountry to ensure websites render content,\ncurrency, 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.\nMaps to specific proxy vendors internally for optimal access to certain websites.\nFormat: \"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" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JSONSchema" } }, "application/javascript": { "schema": { "type": "string" } } } }, "responses": { "200": { "content": { "*/*": { "schema": { "description": "Responses are determined by the returned value of the function\nitself. Binary responses (PDF's, screenshots) are returned back\nas binary data, and primitive JavaScript values are returned back\nby 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\nitself. Binary responses (PDF's, screenshots) are returned back\nas binary data, and primitive JavaScript values are returned back\nby 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" }, "403": { "code": 403, "description": "The request targets a destination that is not allowed.", "message": "HTTP/1.1 403 Forbidden" }, "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": [ "Functions & Downloads" ] } }, "/edge/download": { "post": { "description": "Runs a Puppeteer or Playwright script in Edge and returns any files the browser downloaded during execution.\nthe execution of puppeteer code, which is ran inside context of the browser.\nBrowserless sets up a blank page, a fresh download directory, injects your puppeteer code, and then executes it.\nYou can load external libraries via the \"import\" syntax, and import ESM-style modules\nthat are written for execution inside of the browser. Once your script is finished, any\ndownloaded files from Chromium are returned back with the appropriate content-type header.", "parameters": [ { "in": "query", "name": "blockAds", "schema": { "description": "Whether or not to load ad-blocking extensions for the session.\nThis currently uses uBlock-Lite and may cause certain sites\nto not load properly.", "type": "boolean" } }, { "in": "query", "name": "launch", "schema": { "description": "Launch options, which can be either an object\nof puppeteer.launch options or playwright.launchServer\noptions, depending on the API. Must be either JSON\nobject, or a base64-encoded JSON object.", "anyOf": [ { "$ref": "#/components/schemas/CDPLaunchOptions" }, { "type": "string" } ] } }, { "in": "query", "name": "profile", "schema": { "description": "Name of an authenticated profile to hydrate into the browser at launch.\nThe profile's cookies, localStorage and IndexedDB are injected via CDP\nbefore 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.\nAccepts 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" } }, { "in": "query", "name": "allowedDomains", "schema": { "description": "Optional per-connection narrowing of the integration's allowed-domain list.\nExtracted from the JSON `allowedDomains` query parameter. Can only narrow the\nintegration's domains, never widen them.", "type": "array", "items": { "type": "string" } } }, { "in": "query", "name": "credentials", "schema": { "$ref": "#/components/schemas/StringRecord", "description": "Optional alias → `op://…` reference map for the integration above. Extracted\nfrom the JSON `credentials` query parameter. References are not secret;\nresolved values are never stored here. Optional — a connection can also pass\nraw `op://…` references straight to Browserless.loadSecret." } }, { "in": "query", "name": "externalProxyServer", "schema": { "description": "External proxy server URL for user-provided proxies.\nFormat: http(s)://[username:password@]host:port\nWhen set, routes requests through this proxy instead of built-in residential proxies.", "type": "string" } }, { "in": "query", "name": "integrationId", "schema": { "description": "Optional 1Password integration id for credential filling on a non-persistent\nconnection. Extracted from the `integrationId` query parameter; the persistent\nsession path carries the same data on session metadata instead.", "type": "string" } }, { "in": "query", "name": "proxy", "schema": { "$ref": "#/components/schemas/ProxyType", "description": "The type of proxy to use: 'residential' or 'datacenter'." } }, { "in": "query", "name": "proxyCity", "schema": { "description": "The city to use for the proxy.\n\nAvailable cities: https://production-sfo.browserless.io/proxy/cities?token=YOUR_TOKEN\nDocumentation: 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.\n\nSupported codes: US, GB, FR, DE, etc.\nFull 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.\nRecommended when using proxyCountry to ensure websites render content,\ncurrency, 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.\nMaps to specific proxy vendors internally for optimal access to certain websites.\nFormat: \"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" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JSONSchema" } }, "application/javascript": { "schema": { "type": "string" } } } }, "responses": { "200": { "content": { "*/*": { "schema": { "description": "Responses are determined by the returned value of the downloads\nthemselves, 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\nthemselves, 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" }, "403": { "code": 403, "description": "The request targets a destination that is not allowed.", "message": "HTTP/1.1 403 Forbidden" }, "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": [ "Functions & Downloads" ] } }, "/chromium/export": { "post": { "description": "Exports a webpage to a PDF or image format. This API is useful for generating reports, screenshots, or PDFs of web pages.\n\n**Note:** Also available at `/export` as a convenience alias.", "parameters": [ { "in": "query", "name": "allowedDomains", "schema": { "description": "Optional per-connection narrowing of the integration's allowed-domain list.\nExtracted from the JSON `allowedDomains` query parameter. Can only narrow the\nintegration's domains, never widen them.", "type": "array", "items": { "type": "string" } } }, { "in": "query", "name": "blockAds", "schema": { "description": "Whether or not to load ad-blocking extensions for the session.\nThis currently uses uBlock-Lite and may cause certain sites\nto not load properly.", "type": "boolean" } }, { "in": "query", "name": "credentials", "schema": { "$ref": "#/components/schemas/StringRecord", "description": "Optional alias → `op://…` reference map for the integration above. Extracted\nfrom the JSON `credentials` query parameter. References are not secret;\nresolved values are never stored here. Optional — a connection can also pass\nraw `op://…` references straight to Browserless.loadSecret." } }, { "in": "query", "name": "externalProxyServer", "schema": { "description": "External proxy server URL for user-provided proxies.\nFormat: http(s)://[username:password@]host:port\nWhen set, routes requests through this proxy instead of built-in residential proxies.", "type": "string" } }, { "in": "query", "name": "integrationId", "schema": { "description": "Optional 1Password integration id for credential filling on a non-persistent\nconnection. Extracted from the `integrationId` query parameter; the persistent\nsession path carries the same data on session metadata instead.", "type": "string" } }, { "in": "query", "name": "launch", "schema": { "description": "Launch options for the browser, either as a JSON object or a JSON string.\nIncludes options like `headless`, `args`, `defaultViewport`, etc.", "anyOf": [ { "$ref": "#/components/schemas/CDPLaunchOptions" }, { "type": "string" } ] } }, { "in": "query", "name": "profile", "schema": { "description": "Name of an authenticated profile to hydrate into the browser at launch.\nThe profile's cookies, localStorage and IndexedDB are injected via CDP\nbefore your code runs. No-op in builds without a profile subsystem.", "type": "string" } }, { "in": "query", "name": "proxy", "schema": { "$ref": "#/components/schemas/ProxyType", "description": "The type of proxy to use: 'residential' or 'datacenter'." } }, { "in": "query", "name": "proxyCity", "schema": { "description": "The city to use for the proxy.\n\nAvailable cities: https://production-sfo.browserless.io/proxy/cities?token=YOUR_TOKEN\nDocumentation: 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.\n\nSupported codes: US, GB, FR, DE, etc.\nFull 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.\nRecommended when using proxyCountry to ensure websites render content,\ncurrency, 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.\nMaps to specific proxy vendors internally for optimal access to certain websites.\nFormat: \"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.\nAccepts 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\nwhen \"awaited\" events fail or timeout. This includes things like\ngoto, waitForSelector, and more.", "type": "boolean" }, "url": { "description": "The URL of the site you want to archive.", "type": "string" }, "gotoOptions": { "$ref": "#/components/schemas/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.\nIf polling is a number, then it is treated as an interval in milliseconds\nat which the function would be executed. If polling is a string,\nthen 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).\nPass 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.\nWhen true, the response will be a zip file containing the HTML and all resources.\nWhen false or not provided, the response will be the raw content (default behavior).", "type": "boolean" } }, "type": "object", "required": [ "url" ], "example": { "url": "https://docs.browserless.io/" } }, "example": { "bestAttempt": true, "url": "string", "gotoOptions": { "referer": "string", "referrerPolicy": "string", "timeout": 0, "waitUntil": [ "domcontentloaded" ], "signal": { "aborted": true, "onabort": {}, "reason": {} } }, "waitForEvent": { "event": "string", "timeout": 0 }, "waitForFunction": { "fn": "string", "polling": "string", "timeout": 0 }, "waitForSelector": { "hidden": true, "selector": "string", "timeout": 0, "visible": true }, "waitForTimeout": 0, "headers": {}, "includeResources": true } } } }, "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" }, "403": { "code": 403, "description": "The request targets a destination that is not allowed.", "message": "HTTP/1.1 403 Forbidden" }, "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": [ "Functions & Downloads" ] } }, "/session": { "post": { "description": "Creates a new browser session with the specified parameters. The session can be used for persistent browser connections\nwith 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\nand 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.\nIf a connection happens within the keep-alive window, the browser process will remain running and the session can be reconnected to.\nIf a connection happens after the keep-alive window has expired, a new browser process will be launched for the session, with the prior\nsession 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.\nIgnored if `stealth` is true, defaults to \"true\".", "type": "boolean" }, "args": { "description": "An array of command-line arguments to pass to the browser.\nDefaults to an empty array.", "type": "array", "items": { "type": "string" } }, "browser": { "description": "The type of browser to use for the session.\n'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\nrequired special handling in order to work correctly or unblock.\nThis is not required, but can be useful or required for certain sites.", "type": "string" }, "proxy": { "description": "Proxy Parameters for the session if desired.\nIf not specified, the session will use the default network settings.", "type": "object", "properties": { "type": { "description": "The type of proxy to use: 'residential' or 'datacenter'.", "enum": [ "datacenter", "residential" ], "type": "string" }, "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.\nWhen 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.\nExtensions must be previously uploaded to the browserless extension storage.\nThis allows sessions to start with extensions pre-loaded without specifying\nthem 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.\nThe profile's cookies, localStorage, and IndexedDB entries are injected via\nCDP before your code runs. sessionStorage is intentionally not restored —\nit is tab-scoped and stale values break OAuth/CSRF flows. Changes during\nthe session do not affect the source profile.", "type": "string" }, "integrationId": { "description": "Optional 1Password integration id. When set, Browserless.loadSecret can\nresolve credentials from this integration during the session. Validated at\nsession creation; a missing or expired integration rejects the request.", "type": "string" }, "credentials": { "description": "Maps caller aliases to 1Password op:// references, e.g.\n{ \"password\": \"op://Prod/GitHub/password\" }. Reference strings are not\nsecret; resolved values are never stored on the session.", "type": "object", "additionalProperties": { "type": "string" } }, "allowedDomains": { "description": "Optionally narrows the integration's allowed-domain list for this session.\nCannot widen it — the effective list is the intersection of the two.", "type": "array", "items": { "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.\nThis 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" }, "403": { "code": 403, "description": "The request targets a destination that is not allowed.", "message": "HTTP/1.1 403 Forbidden" }, "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": [ "Sessions & Connections" ], "operationId": "session-create" } }, "/json/new": { "put": { "description": "Returns a JSON payload that acts as a pass-through to the DevTools /json/new HTTP API in Chromium.\nBrowserless mocks this payload so that remote clients can connect to the underlying \"webSocketDebuggerUrl\"\nwhich 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\nlibraries 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" }, "403": { "code": 403, "description": "The request targets a destination that is not allowed.", "message": "HTTP/1.1 403 Forbidden" }, "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": [ "Sessions & Connections" ] } }, "/json/version": { "get": { "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\nlibraries 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" }, "403": { "code": 403, "description": "The request targets a destination that is not allowed.", "message": "HTTP/1.1 403 Forbidden" }, "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": [ "Sessions & Connections" ] } }, "/json/protocol": { "get": { "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" }, "403": { "code": 403, "description": "The request targets a destination that is not allowed.", "message": "HTTP/1.1 403 Forbidden" }, "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": [ "Sessions & Connections" ] } }, "/active": { "get": { "description": "Returns a simple \"204\" HTTP code, with no response, indicating that the service itself is up and running.\nUseful for liveliness probes or other external checks.", "parameters": [], "requestBody": { "content": {} }, "responses": { "400": { "code": 400, "description": "The request contains errors or didn't properly encode content.", "message": "HTTP/1.1 400 Bad Request" }, "401": { "code": 401, "description": "The request is missing, or contains bad, authorization credentials.", "message": "HTTP/1.1 401 Unauthorized" }, "403": { "code": 403, "description": "The request targets a destination that is not allowed.", "message": "HTTP/1.1 403 Forbidden" }, "404": { "code": 404, "description": "Resource couldn't be found.", "message": "HTTP/1.1 404 Not Found" }, "408": { "code": 408, "description": "The request took has taken too long to process.", "message": "HTTP/1.1 408 Request Timeout" }, "429": { "code": 429, "description": "Too many requests are currently being processed.", "message": "HTTP/1.1 429 Too Many Requests" }, "500": { "code": 500, "description": "An internal error occurred when handling the request.", "message": "HTTP/1.1 500 Internal Server Error" }, "503": { "code": 503, "description": "Service is unavailable.", "message": "HTTP/1.1 503 Service Unavailable" } }, "summary": "/active", "tags": [ "Browser Management" ] } }, "/kill/+([0-9a-zA-Z-_])": { "get": { "description": "Kill running sessions based on BrowserId or TrackingId.", "parameters": [ { "in": "query", "name": "blockAds", "schema": { "description": "Whether or not to load ad-blocking extensions for the session.\nThis currently uses uBlock-Lite and may cause certain sites\nto not load properly.", "type": "boolean" } }, { "in": "query", "name": "browserId", "schema": { "type": "string" } }, { "in": "query", "name": "launch", "schema": { "description": "Launch options, which can be either an object\nof puppeteer.launch options or playwright.launchServer\noptions, depending on the API. Must be either JSON\nobject, or a base64-encoded JSON object.", "anyOf": [ { "$ref": "#/components/schemas/CDPLaunchOptions" }, { "$ref": "#/components/schemas/BrowserServerOptions" }, { "type": "string" } ] } }, { "in": "query", "name": "profile", "schema": { "description": "Name of an authenticated profile to hydrate into the browser at launch.\nThe profile's cookies, localStorage and IndexedDB are injected via CDP\nbefore 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.\nAccepts 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": "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" }, "403": { "code": 403, "description": "The request targets a destination that is not allowed.", "message": "HTTP/1.1 403 Forbidden" }, "404": { "code": 404, "description": "Resource couldn't be found.", "message": "HTTP/1.1 404 Not Found" }, "408": { "code": 408, "description": "The request took has taken too long to process.", "message": "HTTP/1.1 408 Request Timeout" }, "429": { "code": 429, "description": "Too many requests are currently being processed.", "message": "HTTP/1.1 429 Too Many Requests" }, "500": { "code": 500, "description": "An internal error occurred when handling the request.", "message": "HTTP/1.1 500 Internal Server Error" }, "503": { "code": 503, "description": "Service is unavailable.", "message": "HTTP/1.1 503 Service Unavailable" } }, "summary": "/kill/+([0-9a-zA-Z-_])", "tags": [ "Browser Management" ] } }, "/meta": { "get": { "description": "Returns a JSON payload of the current system versions, including the core API version.", "parameters": [], "requestBody": { "content": {} }, "responses": { "200": { "content": { "application/json": { "schema": { "type": "object", "properties": { "version": { "description": "The semantic version of the Browserless API", "type": "string" }, "chromium": { "description": "The version of Chromium installed, or null if not installed", "type": [ "null", "string" ] }, "webkit": { "description": "The version of Webkit installed, or null if not installed", "type": [ "null", "string" ] }, "firefox": { "description": "The version of Firefox installed, or null if not installed", "type": [ "null", "string" ] }, "playwright": { "description": "The supported version(s) of puppeteer", "type": "array", "items": { "type": "string" } }, "puppeteer": { "description": "The supported version(s) of playwright", "type": "array", "items": { "type": "string" } } }, "additionalProperties": false, "required": [ "chromium", "firefox", "playwright", "puppeteer", "version", "webkit" ], "$schema": "http://json-schema.org/draft-07/schema#" } } } }, "400": { "code": 400, "description": "The request contains errors or didn't properly encode content.", "message": "HTTP/1.1 400 Bad Request" }, "401": { "code": 401, "description": "The request is missing, or contains bad, authorization credentials.", "message": "HTTP/1.1 401 Unauthorized" }, "403": { "code": 403, "description": "The request targets a destination that is not allowed.", "message": "HTTP/1.1 403 Forbidden" }, "404": { "code": 404, "description": "Resource couldn't be found.", "message": "HTTP/1.1 404 Not Found" }, "408": { "code": 408, "description": "The request took has taken too long to process.", "message": "HTTP/1.1 408 Request Timeout" }, "429": { "code": 429, "description": "Too many requests are currently being processed.", "message": "HTTP/1.1 429 Too Many Requests" }, "500": { "code": 500, "description": "An internal error occurred when handling the request.", "message": "HTTP/1.1 500 Internal Server Error" }, "503": { "code": 503, "description": "Service is unavailable.", "message": "HTTP/1.1 503 Service Unavailable" } }, "summary": "/meta", "tags": [ "Browser Management" ] } }, "/browser/*": { "delete": { "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" }, "403": { "code": 403, "description": "The request targets a destination that is not allowed.", "message": "HTTP/1.1 403 Forbidden" }, "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 Management" ] } }, "/crawl": { "get": { "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": "#/components/schemas/CrawlListItem" } }, "nextCursor": { "type": "string" } }, "additionalProperties": false, "required": [ "crawls", "nextCursor" ], "definitions": { "CrawlListItem": { "type": "object", "properties": { "id": { "type": "string" }, "url": { "type": "string" }, "status": { "$ref": "#/components/schemas/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" }, "403": { "code": 403, "description": "The request targets a destination that is not allowed.", "message": "HTTP/1.1 403 Forbidden" }, "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": [ "Crawling" ], "operationId": "crawl-list" }, "post": { "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\nbefore each page is scraped. The profile's cookies, localStorage, and\nIndexedDB entries are loaded into the session before navigation. Forces\nthe 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" }, "proxy": { "description": "Proxy network to route page fetches through: `\"residential\"` (default)\nor `\"datacenter\"`.", "enum": [ "datacenter", "residential" ], "type": "string" } }, "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" ], "example": { "url": "https://docs.browserless.io/" } }, "example": { "url": "string", "limit": 100, "maxDepth": 5, "maxRetries": 1, "allowExternalLinks": false, "allowSubdomains": false, "sitemap": "auto", "includePaths": [ "string" ], "excludePaths": [ "string" ], "delay": 200, "scrapeOptions": { "formats": [ "html" ], "onlyMainContent": true, "includeTags": [ "string" ], "excludeTags": [ "string" ], "waitFor": 0, "headers": {}, "timeout": 150000, "proxy": "datacenter" }, "webhook": { "url": "string", "events": [ "completed" ] } } } } }, "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" }, "403": { "code": 403, "description": "The request targets a destination that is not allowed.", "message": "HTTP/1.1 403 Forbidden" }, "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": [ "Crawling" ], "operationId": "crawl-start" } }, "/crawl/*": { "delete": { "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" }, "403": { "code": 403, "description": "The request targets a destination that is not allowed.", "message": "HTTP/1.1 403 Forbidden" }, "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": [ "Crawling" ], "operationId": "crawl-cancel" }, "get": { "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": "#/components/schemas/CrawlStatus" }, "total": { "type": "number" }, "completed": { "type": "number" }, "failed": { "type": "number" }, "expiresAt": { "type": "string" }, "next": { "type": "string" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/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": "#/components/schemas/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" }, "403": { "code": 403, "description": "The request targets a destination that is not allowed.", "message": "HTTP/1.1 403 Forbidden" }, "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": [ "Crawling" ], "operationId": "crawl-status" } }, "/unblock": { "post": { "description": "Unblocks the provided URL from being blocked due to bot detection.\nReturns a payload of Cookies, HTML, a base64 encoded screenshot,\nand a \"browserWSEndpoint\" to allow connecting to the browser when\nspecified in the JSON Payload. Only supports CDP or Puppeteer\nlike libraries when connecting to the \"browserWSEndpoint\".\n\n**Note:** Also available at `/chromium/unblock` as a convenience alias.", "parameters": [ { "in": "query", "name": "allowedDomains", "schema": { "description": "Optional per-connection narrowing of the integration's allowed-domain list.\nExtracted from the JSON `allowedDomains` query parameter. Can only narrow the\nintegration's domains, never widen them.", "type": "array", "items": { "type": "string" } } }, { "in": "query", "name": "blockAds", "schema": { "description": "Whether or not to load ad-blocking extensions for the session.\nThis currently uses uBlock-Lite and may cause certain sites\nto not load properly.", "type": "boolean" } }, { "in": "query", "name": "blockAdsInclude", "schema": { "description": "Restrict blockAds to a specific set of uBlock ruleset ids (comma-separated\nlist or JSON array). Only applies when `blockAds` is true. Fewer rulesets\nmeans a faster browser launch under load; omit to load the full default set.", "type": "string" } }, { "in": "query", "name": "credentials", "schema": { "$ref": "#/components/schemas/StringRecord", "description": "Optional alias → `op://…` reference map for the integration above. Extracted\nfrom the JSON `credentials` query parameter. References are not secret;\nresolved values are never stored here. Optional — a connection can also pass\nraw `op://…` references straight to Browserless.loadSecret." } }, { "in": "query", "name": "externalProxyServer", "schema": { "description": "External proxy server URL for user-provided proxies.\nFormat: http(s)://[username:password@]host:port\nWhen set, routes requests through this proxy instead of built-in residential proxies.", "type": "string" } }, { "in": "query", "name": "integrationId", "schema": { "description": "Optional 1Password integration id for credential filling on a non-persistent\nconnection. Extracted from the `integrationId` query parameter; the persistent\nsession path carries the same data on session metadata instead.", "type": "string" } }, { "in": "query", "name": "launch", "schema": { "description": "Launch options for the browser, either as a JSON object or a JSON string.\nIncludes options like `headless`, `args`, `defaultViewport`, etc.", "anyOf": [ { "$ref": "#/components/schemas/CDPLaunchOptions" }, { "type": "string" } ] } }, { "in": "query", "name": "profile", "schema": { "description": "Name of an authenticated profile to hydrate into the browser at launch.\nThe profile's cookies, localStorage and IndexedDB are injected via CDP\nbefore your code runs. No-op in builds without a profile subsystem.", "type": "string" } }, { "in": "query", "name": "proxy", "schema": { "$ref": "#/components/schemas/ProxyType", "description": "The type of proxy to use: 'residential' or 'datacenter'." } }, { "in": "query", "name": "proxyCity", "schema": { "description": "The city to use for the proxy.\n\nAvailable cities: https://production-sfo.browserless.io/proxy/cities?token=YOUR_TOKEN\nDocumentation: 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.\n\nSupported codes: US, GB, FR, DE, etc.\nFull 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.\nRecommended when using proxyCountry to ensure websites render content,\ncurrency, 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.\nMaps to specific proxy vendors internally for optimal access to certain websites.\nFormat: \"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": "When true, records the unblock session for replay (rrweb) and uploads the\ncaptured replay on cleanup, reusing the same recording pipeline as\nBrowserQL. Like every other Browserless route, replay is a\nconnection-level flag supplied via this `?replay=true` query parameter\n(the browser's recording config is resolved from the URL at launch).\nDefaults to false.", "type": "boolean" } }, { "in": "query", "name": "solveCaptchas", "schema": { "description": "When `browserWSEndpoint` is requested, persists captcha-solving on the\nkept-alive session so reconnections automatically solve captchas without\nhaving to re-add `?solveCaptchas=true` to the returned reconnect URL.\nConnection-level flag supplied via this `?solveCaptchas=true` query\nparameter, mirroring `replay`. Defaults to false.", "type": "boolean" } }, { "in": "query", "name": "timeout", "schema": { "description": "Override the system-level timeout for this request.\nAccepts 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\nwhen \"awaited\" events fail or timeout. This includes things like\ngoto, 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\nfuture 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\nbrowserless how long to keep this browser alive for\nre-connection until shutting it down completely.\nMaximum of 30000 for 30 seconds (30,000ms).", "type": "number" }, "gotoOptions": { "$ref": "#/components/schemas/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.\nIf polling is a number, then it is treated as an interval in milliseconds\nat which the function would be executed. If polling is a string,\nthen 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).\nPass 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" ], "example": { "url": "https://docs.browserless.io/" } }, "example": { "bestAttempt": true, "url": "string", "browserWSEndpoint": true, "cookies": true, "content": true, "screenshot": true, "ttl": 0, "gotoOptions": { "referer": "string", "referrerPolicy": "string", "timeout": 0, "waitUntil": [ "domcontentloaded" ], "signal": { "aborted": true, "onabort": {}, "reason": {} } }, "waitForEvent": { "event": "string", "timeout": 0 }, "waitForFunction": { "fn": "string", "polling": "string", "timeout": 0 }, "waitForSelector": { "hidden": true, "selector": "string", "timeout": 0, "visible": true }, "waitForTimeout": 0 } } } }, "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.\nValue is \"null\" when the request body specifies cookies: false.", "type": "array", "items": { "$ref": "#/components/schemas/UnblockCookie" } }, "content": { "description": "The HTML content of the page once it is passed bot detection.\nValue is \"null\" when the request body specifies content: false.", "type": "string" }, "browserWSEndpoint": { "description": "The browserWSEndpoint of the response when the POST body contains a\nbrowserWSEndpoint: true property", "type": "string" }, "ttl": { "description": "The time the browser will remain alive until it is shutdown. Zero\nwhen browserWSEndpoint: false is set in the request payload. The limit\nis 60000 or 60 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": { "UnblockCookie": { "type": "object", "properties": { "name": { "type": "string" }, "value": { "type": "string" }, "domain": { "type": "string" }, "path": { "type": "string" }, "expires": { "type": "number" }, "httpOnly": { "type": "boolean" }, "secure": { "type": "boolean" }, "sameSite": { "type": "string" }, "url": { "type": "string" } }, "additionalProperties": false, "required": [ "domain", "expires", "httpOnly", "name", "path", "sameSite", "secure", "url", "value" ] } }, "$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" }, "403": { "code": 403, "description": "The request targets a destination that is not allowed.", "message": "HTTP/1.1 403 Forbidden" }, "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": [ "Unblock & Stealth" ] } }, "/proxy/cities": { "get": { "description": "Returns a list of available cities for proxy connections.\n\nThis endpoint requires city proxying to be enabled on your plan.\n\nQuery Parameters:\n- country (optional): Filter cities by two-letter country code (e.g., 'US', 'GB', 'DE')\n\nThe response includes a list of available cities grouped by country code.", "parameters": [ { "in": "query", "name": "blockAds", "schema": { "description": "Whether or not to load ad-blocking extensions for the session.\nThis currently uses uBlock-Lite and may cause certain sites\nto 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\nof puppeteer.launch options or playwright.launchServer\noptions, depending on the API. Must be either JSON\nobject, or a base64-encoded JSON object.", "anyOf": [ { "$ref": "#/components/schemas/CDPLaunchOptions" }, { "$ref": "#/components/schemas/BrowserServerOptions" }, { "type": "string" } ] } }, { "in": "query", "name": "profile", "schema": { "description": "Name of an authenticated profile to hydrate into the browser at launch.\nThe profile's cookies, localStorage and IndexedDB are injected via CDP\nbefore 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.\nAccepts 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" }, "403": { "code": 403, "description": "The request targets a destination that is not allowed.", "message": "HTTP/1.1 403 Forbidden" }, "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": [ "Proxy" ] } }, "/profile": { "post": { "description": "Launches a temporary browser session for creating an authenticated profile.\nConnect via the returned WebSocket URL, authenticate in the browser,\nthen call Browserless.saveProfile via CDP to capture and persist the auth state.\nThe profile is NOT saved automatically — you must explicitly call\nBrowserless.saveProfile before disconnecting. The session expires after 10 minutes.", "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "properties": { "name": { "description": "A user-visible name for the profile.\nMust be unique per token.", "type": "string" }, "stealth": { "description": "Whether or not to enable advanced stealth mode. Defaults to false.", "type": "boolean" }, "browser": { "description": "The type of browser to use. Defaults to 'stealth'.", "enum": [ "chrome", "chromium", "stealth" ], "type": "string" }, "args": { "description": "An array of command-line arguments to pass to the browser.", "type": "array", "items": { "type": "string" } }, "proxy": { "description": "Proxy parameters for the profile creation session.", "type": "object", "properties": { "type": { "description": "The type of proxy to use: 'residential' or 'datacenter'.", "enum": [ "datacenter", "residential" ], "type": "string" }, "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 }, "integrationId": { "description": "Optional 1Password integration id. When set, the profile-authoring session\ncan fill credentials via Browserless.loadSecret.", "type": "string" }, "credentials": { "description": "Optional alias → op:// reference map for the integration above.", "type": "object", "additionalProperties": { "type": "string" } }, "allowedDomains": { "description": "Optional per-session narrowing of the integration's allowed domains.", "type": "array", "items": { "type": "string" } } }, "type": "object", "required": [ "name" ] } } } }, "responses": { "200": { "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "description": "Temporary session ID used for the profile creation browser", "type": "string" }, "name": { "description": "The profile name that will be used when saving", "type": "string" }, "connect": { "description": "WebSocket URL to connect to the browser", "type": "string" }, "stop": { "description": "URL to stop/delete the temporary session", "type": "string" } }, "additionalProperties": false, "required": [ "connect", "id", "name", "stop" ], "$schema": "http://json-schema.org/draft-07/schema#" } } } }, "400": { "code": 400, "description": "The request contains errors or didn't properly encode content.", "message": "HTTP/1.1 400 Bad Request" }, "401": { "code": 401, "description": "The request is missing, or contains bad, authorization credentials.", "message": "HTTP/1.1 401 Unauthorized" }, "403": { "code": 403, "description": "The request targets a destination that is not allowed.", "message": "HTTP/1.1 403 Forbidden" }, "404": { "code": 404, "description": "Resource couldn't be found.", "message": "HTTP/1.1 404 Not Found" }, "408": { "code": 408, "description": "The request took has taken too long to process.", "message": "HTTP/1.1 408 Request Timeout" }, "429": { "code": 429, "description": "Too many requests are currently being processed.", "message": "HTTP/1.1 429 Too Many Requests" }, "500": { "code": 500, "description": "An internal error occurred when handling the request.", "message": "HTTP/1.1 500 Internal Server Error" }, "503": { "code": 503, "description": "Service is unavailable.", "message": "HTTP/1.1 503 Service Unavailable" } }, "summary": "/profile", "tags": [ "Profiles" ], "operationId": "profile-create" } }, "/profiles": { "get": { "description": "Lists authentication profiles owned by the requesting token.\nPaginated via \"limit\" (default 100, capped at 1000) and \"offset\" (default 0).\nReturns an empty array if the token has no profiles.", "parameters": [ { "in": "query", "name": "blockAds", "schema": { "description": "Whether or not to load ad-blocking extensions for the session.\nThis currently uses uBlock-Lite and may cause certain sites\nto not load properly.", "type": "boolean" } }, { "in": "query", "name": "launch", "schema": { "description": "Launch options, which can be either an object\nof puppeteer.launch options or playwright.launchServer\noptions, depending on the API. Must be either JSON\nobject, or a base64-encoded JSON object.", "anyOf": [ { "$ref": "#/components/schemas/CDPLaunchOptions" }, { "$ref": "#/components/schemas/BrowserServerOptions" }, { "type": "string" } ] } }, { "in": "query", "name": "limit", "schema": { "description": "Maximum number of profiles to return (1–1000). Defaults to 100.", "type": "number" } }, { "in": "query", "name": "offset", "schema": { "description": "Number of profiles to skip for pagination. Defaults to 0.", "type": "number" } }, { "in": "query", "name": "profile", "schema": { "description": "Name of an authenticated profile to hydrate into the browser at launch.\nThe profile's cookies, localStorage and IndexedDB are injected via CDP\nbefore 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.\nAccepts 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": "array", "items": { "$ref": "#/components/schemas/ProfileResponse" }, "definitions": { "ProfileResponse": { "description": "Public-facing profile response returned by HTTP routes.\nOmits internal fields like token_hash and storage_key.", "type": "object", "properties": { "id": { "description": "Unique profile identifier.", "type": "string" }, "name": { "description": "User-supplied profile name. Unique per token.", "type": "string" }, "cookieCount": { "description": "Number of cookies captured in the profile.", "type": "number" }, "originCount": { "description": "Number of distinct origins with stored localStorage or IndexedDB.", "type": "number" }, "lastUsedAt": { "description": "ISO timestamp of the last time this profile was applied to a session, or null if never used.", "type": "string" }, "createdAt": { "description": "ISO timestamp of when the profile was created.", "type": "string" }, "updatedAt": { "description": "ISO timestamp of the last metadata change (e.g., rename).", "type": "string" } }, "additionalProperties": false, "required": [ "cookieCount", "createdAt", "id", "lastUsedAt", "name", "originCount", "updatedAt" ] } }, "$schema": "http://json-schema.org/draft-07/schema#" } } } }, "400": { "code": 400, "description": "The request contains errors or didn't properly encode content.", "message": "HTTP/1.1 400 Bad Request" }, "401": { "code": 401, "description": "The request is missing, or contains bad, authorization credentials.", "message": "HTTP/1.1 401 Unauthorized" }, "403": { "code": 403, "description": "The request targets a destination that is not allowed.", "message": "HTTP/1.1 403 Forbidden" }, "404": { "code": 404, "description": "Resource couldn't be found.", "message": "HTTP/1.1 404 Not Found" }, "408": { "code": 408, "description": "The request took has taken too long to process.", "message": "HTTP/1.1 408 Request Timeout" }, "429": { "code": 429, "description": "Too many requests are currently being processed.", "message": "HTTP/1.1 429 Too Many Requests" }, "500": { "code": 500, "description": "An internal error occurred when handling the request.", "message": "HTTP/1.1 500 Internal Server Error" }, "503": { "code": 503, "description": "Service is unavailable.", "message": "HTTP/1.1 503 Service Unavailable" } }, "summary": "/profiles", "tags": [ "Profiles" ] } }, "/profile/*": { "delete": { "description": "Deletes an authentication profile and its captured state.\nThe profile name is the URL-encoded path segment after \"/profile/\".\nReturns 404 if no profile with that name exists for this token.", "parameters": [], "requestBody": { "content": {} }, "responses": { "200": { "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "description": "Always true on success.", "type": "boolean" }, "message": { "description": "Human-readable confirmation message.", "type": "string" }, "name": { "description": "Name of the profile that was deleted.", "type": "string" } }, "additionalProperties": false, "required": [ "message", "name", "success" ], "$schema": "http://json-schema.org/draft-07/schema#" } } } }, "400": { "code": 400, "description": "The request contains errors or didn't properly encode content.", "message": "HTTP/1.1 400 Bad Request" }, "401": { "code": 401, "description": "The request is missing, or contains bad, authorization credentials.", "message": "HTTP/1.1 401 Unauthorized" }, "403": { "code": 403, "description": "The request targets a destination that is not allowed.", "message": "HTTP/1.1 403 Forbidden" }, "404": { "code": 404, "description": "Resource couldn't be found.", "message": "HTTP/1.1 404 Not Found" }, "408": { "code": 408, "description": "The request took has taken too long to process.", "message": "HTTP/1.1 408 Request Timeout" }, "429": { "code": 429, "description": "Too many requests are currently being processed.", "message": "HTTP/1.1 429 Too Many Requests" }, "500": { "code": 500, "description": "An internal error occurred when handling the request.", "message": "HTTP/1.1 500 Internal Server Error" }, "503": { "code": 503, "description": "Service is unavailable.", "message": "HTTP/1.1 503 Service Unavailable" } }, "summary": "/profile/*", "tags": [ "Profiles" ], "operationId": "profile-delete" }, "get": { "description": "Returns metadata for a specific authentication profile.\nThe profile name is the URL-encoded path segment after \"/profile/\".\nReturns 404 if no profile with that name exists for this token.", "parameters": [], "requestBody": { "content": {} }, "responses": { "200": { "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "description": "Unique profile identifier.", "type": "string" }, "name": { "description": "User-supplied profile name. Unique per token.", "type": "string" }, "cookieCount": { "description": "Number of cookies captured in the profile.", "type": "number" }, "originCount": { "description": "Number of distinct origins with stored localStorage or IndexedDB.", "type": "number" }, "lastUsedAt": { "description": "ISO timestamp of the last time this profile was applied to a session, or null if never used.", "type": "string" }, "createdAt": { "description": "ISO timestamp of when the profile was created.", "type": "string" }, "updatedAt": { "description": "ISO timestamp of the last metadata change (e.g., rename).", "type": "string" } }, "additionalProperties": false, "required": [ "cookieCount", "createdAt", "id", "lastUsedAt", "name", "originCount", "updatedAt" ], "$schema": "http://json-schema.org/draft-07/schema#" } } } }, "400": { "code": 400, "description": "The request contains errors or didn't properly encode content.", "message": "HTTP/1.1 400 Bad Request" }, "401": { "code": 401, "description": "The request is missing, or contains bad, authorization credentials.", "message": "HTTP/1.1 401 Unauthorized" }, "403": { "code": 403, "description": "The request targets a destination that is not allowed.", "message": "HTTP/1.1 403 Forbidden" }, "404": { "code": 404, "description": "Resource couldn't be found.", "message": "HTTP/1.1 404 Not Found" }, "408": { "code": 408, "description": "The request took has taken too long to process.", "message": "HTTP/1.1 408 Request Timeout" }, "429": { "code": 429, "description": "Too many requests are currently being processed.", "message": "HTTP/1.1 429 Too Many Requests" }, "500": { "code": 500, "description": "An internal error occurred when handling the request.", "message": "HTTP/1.1 500 Internal Server Error" }, "503": { "code": 503, "description": "Service is unavailable.", "message": "HTTP/1.1 503 Service Unavailable" } }, "summary": "/profile/*", "tags": [ "Profiles" ], "operationId": "profile-get" }, "put": { "description": "Renames an authentication profile. The new name must be unique per token.\nThe current name is the URL-encoded path segment after \"/profile/\".\nReturns 400 if the new name is already taken, 404 if the source profile is not found.", "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "properties": { "name": { "description": "The new name for the profile.", "type": "string" } }, "type": "object", "required": [ "name" ] } } } }, "responses": { "200": { "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "description": "Unique profile identifier.", "type": "string" }, "name": { "description": "User-supplied profile name. Unique per token.", "type": "string" }, "cookieCount": { "description": "Number of cookies captured in the profile.", "type": "number" }, "originCount": { "description": "Number of distinct origins with stored localStorage or IndexedDB.", "type": "number" }, "lastUsedAt": { "description": "ISO timestamp of the last time this profile was applied to a session, or null if never used.", "type": "string" }, "createdAt": { "description": "ISO timestamp of when the profile was created.", "type": "string" }, "updatedAt": { "description": "ISO timestamp of the last metadata change (e.g., rename).", "type": "string" } }, "additionalProperties": false, "required": [ "cookieCount", "createdAt", "id", "lastUsedAt", "name", "originCount", "updatedAt" ], "$schema": "http://json-schema.org/draft-07/schema#" } } } }, "400": { "code": 400, "description": "The request contains errors or didn't properly encode content.", "message": "HTTP/1.1 400 Bad Request" }, "401": { "code": 401, "description": "The request is missing, or contains bad, authorization credentials.", "message": "HTTP/1.1 401 Unauthorized" }, "403": { "code": 403, "description": "The request targets a destination that is not allowed.", "message": "HTTP/1.1 403 Forbidden" }, "404": { "code": 404, "description": "Resource couldn't be found.", "message": "HTTP/1.1 404 Not Found" }, "408": { "code": 408, "description": "The request took has taken too long to process.", "message": "HTTP/1.1 408 Request Timeout" }, "429": { "code": 429, "description": "Too many requests are currently being processed.", "message": "HTTP/1.1 429 Too Many Requests" }, "500": { "code": 500, "description": "An internal error occurred when handling the request.", "message": "HTTP/1.1 500 Internal Server Error" }, "503": { "code": 503, "description": "Service is unavailable.", "message": "HTTP/1.1 503 Service Unavailable" } }, "summary": "/profile/*", "tags": [ "Profiles" ], "operationId": "profile-rename" } }, "/profile/refresh": { "post": { "description": "Replaces the state of an existing authentication profile in place.\nThe \"name\" must already exist for the requesting token. Counts of any\ndropped or truncated entries are surfaced under \"diagnostics\".", "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "properties": { "name": { "description": "Name of the existing profile to refresh. Must already exist for the\nrequesting token.", "type": "string" }, "state": { "description": "Pre-captured authentication state. Same shape as `POST /profile/upload`." } }, "type": "object", "required": [ "name", "state" ] } } } }, "responses": { "200": { "content": { "application/json": { "schema": { "type": "object", "properties": { "diagnostics": { "$ref": "#/components/schemas/RefreshResponseDiagnostics", "description": "Per-entry counts of cookies, origins, and IndexedDB items the server\ndropped or truncated before persisting. All zero on a clean refresh." }, "id": { "description": "Unique profile identifier.", "type": "string" }, "name": { "description": "User-supplied profile name. Unique per token.", "type": "string" }, "cookieCount": { "description": "Number of cookies captured in the profile.", "type": "number" }, "originCount": { "description": "Number of distinct origins with stored localStorage or IndexedDB.", "type": "number" }, "lastUsedAt": { "description": "ISO timestamp of the last time this profile was applied to a session, or null if never used.", "type": "string" }, "createdAt": { "description": "ISO timestamp of when the profile was created.", "type": "string" }, "updatedAt": { "description": "ISO timestamp of the last metadata change (e.g., rename).", "type": "string" } }, "additionalProperties": false, "required": [ "cookieCount", "createdAt", "diagnostics", "id", "lastUsedAt", "name", "originCount", "updatedAt" ], "definitions": { "RefreshResponseDiagnostics": { "description": "Per-entry counts of cookies, origins, and IndexedDB items the server\ndropped or truncated before persisting. All zero on a clean refresh.", "type": "object", "properties": { "skippedMalformedCookies": { "description": "Cookies dropped because required fields were missing or wrong type.", "type": "number" }, "skippedPrivateCookies": { "description": "Cookies dropped because their domain pointed at a private/internal host.", "type": "number" }, "skippedMalformedOrigins": { "description": "Origins dropped because they were malformed or non-http(s).", "type": "number" }, "skippedPrivateOrigins": { "description": "Origins dropped because they targeted a private/internal network.", "type": "number" }, "truncatedOrigins": { "description": "Origins dropped because the per-profile cap was exceeded.", "type": "number" }, "skippedMalformedIdbDatabases": { "description": "IndexedDB databases dropped because required fields were missing.", "type": "number" }, "truncatedIdbDatabases": { "description": "IndexedDB databases dropped because the per-origin cap was exceeded.", "type": "number" }, "skippedMalformedIdbStores": { "description": "IndexedDB object-stores dropped because required fields were missing.", "type": "number" }, "truncatedIdbEntries": { "description": "IndexedDB entries dropped because the per-store cap was exceeded.", "type": "number" } }, "additionalProperties": false, "required": [ "skippedMalformedCookies", "skippedMalformedIdbDatabases", "skippedMalformedIdbStores", "skippedMalformedOrigins", "skippedPrivateCookies", "skippedPrivateOrigins", "truncatedIdbDatabases", "truncatedIdbEntries", "truncatedOrigins" ] } }, "$schema": "http://json-schema.org/draft-07/schema#" } } } }, "400": { "code": 400, "description": "The request contains errors or didn't properly encode content.", "message": "HTTP/1.1 400 Bad Request" }, "401": { "code": 401, "description": "The request is missing, or contains bad, authorization credentials.", "message": "HTTP/1.1 401 Unauthorized" }, "403": { "code": 403, "description": "The request targets a destination that is not allowed.", "message": "HTTP/1.1 403 Forbidden" }, "404": { "code": 404, "description": "Resource couldn't be found.", "message": "HTTP/1.1 404 Not Found" }, "408": { "code": 408, "description": "The request took has taken too long to process.", "message": "HTTP/1.1 408 Request Timeout" }, "429": { "code": 429, "description": "Too many requests are currently being processed.", "message": "HTTP/1.1 429 Too Many Requests" }, "500": { "code": 500, "description": "An internal error occurred when handling the request.", "message": "HTTP/1.1 500 Internal Server Error" }, "503": { "code": 503, "description": "Service is unavailable.", "message": "HTTP/1.1 503 Service Unavailable" } }, "summary": "/profile/refresh", "tags": [ "Profiles" ] } }, "/profile/upload": { "post": { "description": "Creates a new authentication profile from a pre-captured \"state\" payload\n(cookies plus per-origin localStorage and IndexedDB). The \"name\" must be\nunique per token. Counts of any dropped or truncated entries are\nsurfaced under \"diagnostics\".", "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "properties": { "name": { "description": "A user-visible name for the profile. Must be unique per token.", "type": "string" }, "state": { "description": "Pre-captured authentication state. An object with two arrays —\n`cookies` (browser cookies) and `origins` (per-origin localStorage and\nIndexedDB)." } }, "type": "object", "required": [ "name", "state" ] } } } }, "responses": { "200": { "content": { "application/json": { "schema": { "type": "object", "properties": { "diagnostics": { "$ref": "#/components/schemas/UploadResponseDiagnostics", "description": "Per-entry counts of cookies, origins, and IndexedDB items the server\ndropped or truncated before persisting. All zero on a clean upload." }, "id": { "description": "Unique profile identifier.", "type": "string" }, "name": { "description": "User-supplied profile name. Unique per token.", "type": "string" }, "cookieCount": { "description": "Number of cookies captured in the profile.", "type": "number" }, "originCount": { "description": "Number of distinct origins with stored localStorage or IndexedDB.", "type": "number" }, "lastUsedAt": { "description": "ISO timestamp of the last time this profile was applied to a session, or null if never used.", "type": "string" }, "createdAt": { "description": "ISO timestamp of when the profile was created.", "type": "string" }, "updatedAt": { "description": "ISO timestamp of the last metadata change (e.g., rename).", "type": "string" } }, "additionalProperties": false, "required": [ "cookieCount", "createdAt", "diagnostics", "id", "lastUsedAt", "name", "originCount", "updatedAt" ], "definitions": { "UploadResponseDiagnostics": { "description": "Per-entry counts of cookies, origins, and IndexedDB items the server\ndropped or truncated before persisting. All zero on a clean upload.", "type": "object", "properties": { "skippedMalformedCookies": { "description": "Cookies dropped because required fields were missing or wrong type.", "type": "number" }, "skippedPrivateCookies": { "description": "Cookies dropped because their domain pointed at a private/internal host.", "type": "number" }, "skippedMalformedOrigins": { "description": "Origins dropped because they were malformed or non-http(s).", "type": "number" }, "skippedPrivateOrigins": { "description": "Origins dropped because they targeted a private/internal network.", "type": "number" }, "truncatedOrigins": { "description": "Origins dropped because the per-profile cap was exceeded.", "type": "number" }, "skippedMalformedIdbDatabases": { "description": "IndexedDB databases dropped because required fields were missing.", "type": "number" }, "truncatedIdbDatabases": { "description": "IndexedDB databases dropped because the per-origin cap was exceeded.", "type": "number" }, "skippedMalformedIdbStores": { "description": "IndexedDB object-stores dropped because required fields were missing.", "type": "number" }, "truncatedIdbEntries": { "description": "IndexedDB entries dropped because the per-store cap was exceeded.", "type": "number" } }, "additionalProperties": false, "required": [ "skippedMalformedCookies", "skippedMalformedIdbDatabases", "skippedMalformedIdbStores", "skippedMalformedOrigins", "skippedPrivateCookies", "skippedPrivateOrigins", "truncatedIdbDatabases", "truncatedIdbEntries", "truncatedOrigins" ] } }, "$schema": "http://json-schema.org/draft-07/schema#" } } } }, "400": { "code": 400, "description": "The request contains errors or didn't properly encode content.", "message": "HTTP/1.1 400 Bad Request" }, "401": { "code": 401, "description": "The request is missing, or contains bad, authorization credentials.", "message": "HTTP/1.1 401 Unauthorized" }, "403": { "code": 403, "description": "The request targets a destination that is not allowed.", "message": "HTTP/1.1 403 Forbidden" }, "404": { "code": 404, "description": "Resource couldn't be found.", "message": "HTTP/1.1 404 Not Found" }, "408": { "code": 408, "description": "The request took has taken too long to process.", "message": "HTTP/1.1 408 Request Timeout" }, "429": { "code": 429, "description": "Too many requests are currently being processed.", "message": "HTTP/1.1 429 Too Many Requests" }, "500": { "code": 500, "description": "An internal error occurred when handling the request.", "message": "HTTP/1.1 500 Internal Server Error" }, "503": { "code": 503, "description": "Service is unavailable.", "message": "HTTP/1.1 503 Service Unavailable" } }, "summary": "/profile/upload", "tags": [ "Profiles" ] } }, "/integrations/onepassword": { "post": { "description": "Registers a 1Password integration for the requesting token. The supplied\nservice-account token is encrypted at rest and is never returned by this or\nany other endpoint. Returns the created integration without any token field.", "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "properties": { "label": { "description": "A user-visible label for the integration. Unique per token.", "type": "string" }, "kind": { "description": "Integration kind. Defaults to \"service_account\".", "enum": [ "connect", "service_account" ], "type": "string" }, "serviceAccountToken": { "description": "The 1Password service-account token (or Connect access token when\nkind is \"connect\"). Encrypted at rest; never returned by any API.", "type": "string" }, "allowedDomains": { "description": "Origins this integration may fill credentials into. Empty means no fills pass.", "type": "array", "items": { "type": "string" } }, "connectUrl": { "description": "Connect server URL. Required when kind is \"connect\", rejected otherwise.", "type": "string" } }, "type": "object", "required": [ "label", "serviceAccountToken" ] } } } }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Public-facing integration response returned by HTTP routes.\nOmits internal fields — never includes token_hash or any token material.", "type": "object", "properties": { "id": { "description": "Unique integration identifier.", "type": "string" }, "label": { "description": "User-supplied label. Unique per token.", "type": "string" }, "kind": { "$ref": "#/components/schemas/OpIntegrationKind", "description": "Integration kind: `service_account` (default) or `connect`." }, "allowedDomains": { "description": "Origins this integration is allowed to fill into.", "type": "array", "items": { "type": "string" } }, "connectUrl": { "description": "Connect server URL when kind is `connect`, otherwise null.", "type": "string" }, "expiresAt": { "description": "ISO timestamp after which the integration is treated as expired, or null.", "type": "string" }, "lastResolvedAt": { "description": "ISO timestamp of the last successful secret resolve, or null if never used.", "type": "string" }, "createdAt": { "description": "ISO timestamp of when the integration was created.", "type": "string" }, "updatedAt": { "description": "ISO timestamp of the last metadata change.", "type": "string" } }, "additionalProperties": false, "required": [ "allowedDomains", "connectUrl", "createdAt", "expiresAt", "id", "kind", "label", "lastResolvedAt", "updatedAt" ], "definitions": { "OpIntegrationKind": { "enum": [ "connect", "service_account" ], "type": "string" } }, "$schema": "http://json-schema.org/draft-07/schema#" } } }, "description": "Public-facing integration response returned by HTTP routes.\nOmits internal fields — never includes token_hash or any token material." }, "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" }, "403": { "code": 403, "description": "The request targets a destination that is not allowed.", "message": "HTTP/1.1 403 Forbidden" }, "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": "/integrations/onepassword", "tags": [ "Integrations" ], "operationId": "onepassword-register" }, "get": { "description": "Lists the 1Password integrations owned by the requesting token. Paginated\nvia \"limit\" (default 100, capped at 1000) and \"offset\" (default 0). Records\nnever include any token material.", "parameters": [ { "in": "query", "name": "blockAds", "schema": { "description": "Whether or not to load ad-blocking extensions for the session.\nThis currently uses uBlock-Lite and may cause certain sites\nto not load properly.", "type": "boolean" } }, { "in": "query", "name": "launch", "schema": { "description": "Launch options, which can be either an object\nof puppeteer.launch options or playwright.launchServer\noptions, depending on the API. Must be either JSON\nobject, or a base64-encoded JSON object.", "anyOf": [ { "$ref": "#/components/schemas/CDPLaunchOptions" }, { "$ref": "#/components/schemas/BrowserServerOptions" }, { "type": "string" } ] } }, { "in": "query", "name": "limit", "schema": { "description": "Maximum number of integrations to return (1–1000). Defaults to 100.", "type": "number" } }, { "in": "query", "name": "offset", "schema": { "description": "Number of integrations to skip for pagination. Defaults to 0.", "type": "number" } }, { "in": "query", "name": "profile", "schema": { "description": "Name of an authenticated profile to hydrate into the browser at launch.\nThe profile's cookies, localStorage and IndexedDB are injected via CDP\nbefore 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.\nAccepts 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": "array", "items": { "$ref": "#/components/schemas/OpIntegrationResponse" }, "definitions": { "OpIntegrationResponse": { "description": "Public-facing integration response returned by HTTP routes.\nOmits internal fields — never includes token_hash or any token material.", "type": "object", "properties": { "id": { "description": "Unique integration identifier.", "type": "string" }, "label": { "description": "User-supplied label. Unique per token.", "type": "string" }, "kind": { "$ref": "#/components/schemas/OpIntegrationKind", "description": "Integration kind: `service_account` (default) or `connect`." }, "allowedDomains": { "description": "Origins this integration is allowed to fill into.", "type": "array", "items": { "type": "string" } }, "connectUrl": { "description": "Connect server URL when kind is `connect`, otherwise null.", "type": "string" }, "expiresAt": { "description": "ISO timestamp after which the integration is treated as expired, or null.", "type": "string" }, "lastResolvedAt": { "description": "ISO timestamp of the last successful secret resolve, or null if never used.", "type": "string" }, "createdAt": { "description": "ISO timestamp of when the integration was created.", "type": "string" }, "updatedAt": { "description": "ISO timestamp of the last metadata change.", "type": "string" } }, "additionalProperties": false, "required": [ "allowedDomains", "connectUrl", "createdAt", "expiresAt", "id", "kind", "label", "lastResolvedAt", "updatedAt" ] }, "OpIntegrationKind": { "enum": [ "connect", "service_account" ], "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" }, "403": { "code": 403, "description": "The request targets a destination that is not allowed.", "message": "HTTP/1.1 403 Forbidden" }, "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": "/integrations/onepassword", "tags": [ "Integrations" ], "operationId": "onepassword-list" } }, "/integrations/onepassword/*": { "delete": { "description": "Deletes a 1Password integration owned by the requesting token. The id is the\nURL-encoded path segment after \"/integrations/onepassword/\". Returns 404 if\nno integration with that id exists for this token. Deleting an integration\ndoes not touch any authentication profile.", "parameters": [], "requestBody": { "content": {} }, "responses": { "200": { "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "description": "Always true on success.", "type": "boolean" }, "message": { "description": "Human-readable confirmation message.", "type": "string" }, "id": { "description": "Id of the integration that was deleted.", "type": "string" } }, "additionalProperties": false, "required": [ "id", "message", "success" ], "$schema": "http://json-schema.org/draft-07/schema#" } } } }, "400": { "code": 400, "description": "The request contains errors or didn't properly encode content.", "message": "HTTP/1.1 400 Bad Request" }, "401": { "code": 401, "description": "The request is missing, or contains bad, authorization credentials.", "message": "HTTP/1.1 401 Unauthorized" }, "403": { "code": 403, "description": "The request targets a destination that is not allowed.", "message": "HTTP/1.1 403 Forbidden" }, "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": "/integrations/onepassword/*", "tags": [ "Integrations" ], "operationId": "onepassword-delete" }, "get": { "description": "Returns metadata for a specific 1Password integration owned by the token.\nThe id is the URL-encoded path segment after \"/integrations/onepassword/\".\nReturns 404 if no integration with that id exists for this token. The\nresponse never includes any token material.", "parameters": [], "requestBody": { "content": {} }, "responses": { "200": { "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "description": "Unique integration identifier.", "type": "string" }, "label": { "description": "User-supplied label. Unique per token.", "type": "string" }, "kind": { "$ref": "#/components/schemas/OpIntegrationKind", "description": "Integration kind: `service_account` (default) or `connect`." }, "allowedDomains": { "description": "Origins this integration is allowed to fill into.", "type": "array", "items": { "type": "string" } }, "connectUrl": { "description": "Connect server URL when kind is `connect`, otherwise null.", "type": "string" }, "expiresAt": { "description": "ISO timestamp after which the integration is treated as expired, or null.", "type": "string" }, "lastResolvedAt": { "description": "ISO timestamp of the last successful secret resolve, or null if never used.", "type": "string" }, "createdAt": { "description": "ISO timestamp of when the integration was created.", "type": "string" }, "updatedAt": { "description": "ISO timestamp of the last metadata change.", "type": "string" } }, "additionalProperties": false, "required": [ "allowedDomains", "connectUrl", "createdAt", "expiresAt", "id", "kind", "label", "lastResolvedAt", "updatedAt" ], "definitions": { "OpIntegrationKind": { "enum": [ "connect", "service_account" ], "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" }, "403": { "code": 403, "description": "The request targets a destination that is not allowed.", "message": "HTTP/1.1 403 Forbidden" }, "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": "/integrations/onepassword/*", "tags": [ "Integrations" ], "operationId": "onepassword-get" } }, "/integrations/onepassword/*/audit": { "get": { "description": "Lists recent credential-fill activity for a single 1Password integration\nowned by the token, newest first. One entry per Browserless.loadSecret\nattempt: outcome, error code, the credential reference, and non-secret\ntarget metadata. A resolved secret value is never recorded or returned.\nPaginated via \"limit\" (default 100, capped at 1000) and \"offset\" (default 0).\nReturns 404 if no integration with that id exists for this token.", "parameters": [ { "in": "query", "name": "blockAds", "schema": { "description": "Whether or not to load ad-blocking extensions for the session.\nThis currently uses uBlock-Lite and may cause certain sites\nto not load properly.", "type": "boolean" } }, { "in": "query", "name": "launch", "schema": { "description": "Launch options, which can be either an object\nof puppeteer.launch options or playwright.launchServer\noptions, depending on the API. Must be either JSON\nobject, or a base64-encoded JSON object.", "anyOf": [ { "$ref": "#/components/schemas/CDPLaunchOptions" }, { "$ref": "#/components/schemas/BrowserServerOptions" }, { "type": "string" } ] } }, { "in": "query", "name": "limit", "schema": { "description": "Maximum number of audit entries to return (1–1000). Defaults to 100.", "type": "number" } }, { "in": "query", "name": "offset", "schema": { "description": "Number of audit entries to skip for pagination. Defaults to 0.", "type": "number" } }, { "in": "query", "name": "profile", "schema": { "description": "Name of an authenticated profile to hydrate into the browser at launch.\nThe profile's cookies, localStorage and IndexedDB are injected via CDP\nbefore 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.\nAccepts 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": "array", "items": { "$ref": "#/components/schemas/OpAuditLogResponse" }, "definitions": { "OpAuditLogResponse": { "description": "Public-facing audit-log entry returned by the audit HTTP route. Omits\ntoken_hash — never includes any token material — and carries the credential\nreference plus non-secret target metadata only.", "type": "object", "properties": { "id": { "description": "Unique audit-entry identifier.", "type": "string" }, "integrationId": { "description": "Integration this fill attempt was made through.", "type": "string" }, "profileId": { "description": "Authentication profile the fill targeted, or null.", "type": "string" }, "secretRef": { "description": "The alias or op:// reference requested. Never a resolved value.", "type": "string" }, "targetOrigin": { "description": "Document origin the fill was attempted on, or null.", "type": "string" }, "targetSelector": { "description": "CSS selector supplied by the caller, or null.", "type": "string" }, "targetDescriptor": { "description": "Non-secret descriptor of the focused element, or null.", "type": "string" }, "outcome": { "$ref": "#/components/schemas/OpAuditOutcome", "description": "`success` if the value was filled, otherwise `failure`." }, "errorCode": { "description": "Error code when the outcome is `failure`, otherwise null.", "type": "string" }, "createdAt": { "description": "ISO timestamp of the attempt.", "type": "string" } }, "additionalProperties": false, "required": [ "createdAt", "errorCode", "id", "integrationId", "outcome", "profileId", "secretRef", "targetDescriptor", "targetOrigin", "targetSelector" ] }, "OpAuditOutcome": { "description": "Outcome recorded for a single Browserless.loadSecret attempt.", "enum": [ "failure", "success" ], "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" }, "403": { "code": 403, "description": "The request targets a destination that is not allowed.", "message": "HTTP/1.1 403 Forbidden" }, "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": "/integrations/onepassword/*/audit", "tags": [ "Integrations" ] } }, "/integrations/onepassword/profile": { "post": { "description": "Kicks off an autologin task: a managed agent creates a browser profile by\nlogging into the integration's domains, then saves it. Returns a taskId to\npoll via GET /integrations/onepassword/profile/:taskId. (POC: the integration\nis resolved from an in-memory fixture rather than a real 1Password record.)", "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "properties": { "name": { "description": "Name to save the resulting profile under. Unique per token.", "type": "string" }, "integrationId": { "description": "Integration id — resolved from the in-memory fixture in this POC.", "type": "string" }, "allowedDomains": { "description": "Optional subset of the integration's allowed domains.", "type": "array", "items": { "type": "string" } } }, "type": "object", "required": [ "integrationId", "name" ] } } } }, "responses": { "200": { "content": { "application/json": { "schema": { "type": "object", "properties": { "taskId": { "type": "string" } }, "additionalProperties": false, "required": [ "taskId" ], "$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" }, "403": { "code": 403, "description": "The request targets a destination that is not allowed.", "message": "HTTP/1.1 403 Forbidden" }, "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": "/integrations/onepassword/profile", "tags": [ "Integrations" ], "operationId": "onepassword-autologin-start" } }, "/integrations/onepassword/profile/*": { "get": { "description": "Poll an autologin task by id. Returns its state, the current live rationale,\nand (on success) the saved profile id plus a per-domain breakdown. Scoped to\nthe requesting token — returns 404 for unknown ids or another token's task.", "parameters": [], "requestBody": { "content": {} }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Public polling shape returned by GET /integrations/onepassword/profile/:taskId.", "type": "object", "properties": { "taskId": { "type": "string" }, "state": { "$ref": "#/components/schemas/AutologinState" }, "currentRationale": { "description": "User-facing reason for the current state — drives the dashboard's live line.", "type": "string" }, "profileId": { "type": "string" }, "profileName": { "type": "string" }, "domains": { "type": "array", "items": { "$ref": "#/components/schemas/AutologinDomainResult" } }, "errorCode": { "type": "string" }, "errorMessage": { "type": "string" }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } }, "additionalProperties": false, "required": [ "createdAt", "currentRationale", "state", "taskId", "updatedAt" ], "definitions": { "AutologinState": { "description": "Lifecycle state of an autologin task.", "enum": [ "failed", "pending", "running", "success" ], "type": "string" }, "AutologinDomainResult": { "type": "object", "properties": { "origin": { "type": "string" }, "status": { "$ref": "#/components/schemas/AutologinDomainStatus" }, "error": { "type": "string" } }, "additionalProperties": false, "required": [ "origin", "status" ] }, "AutologinDomainStatus": { "description": "Per-origin progress/outcome as the agent works through the domain list.\nLive: `pending` (not reached), `active` (currently attempting), `tried`\n(moved past — outcome not yet known). Terminal: `success` | `failed`.", "enum": [ "active", "failed", "pending", "success", "tried" ], "type": "string" } }, "$schema": "http://json-schema.org/draft-07/schema#" } } }, "description": "Public polling shape returned by GET /integrations/onepassword/profile/:taskId." }, "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" }, "403": { "code": 403, "description": "The request targets a destination that is not allowed.", "message": "HTTP/1.1 403 Forbidden" }, "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": "/integrations/onepassword/profile/*", "tags": [ "Integrations" ], "operationId": "onepassword-autologin-status" } }, "/integrations/onepassword/autologin/form": { "get": { "description": "Returns the selectable references for building an autologin profile: the\n1Password integration's login origins and, per origin, the field labels it\nfills (never values). Drives the create-profile form.", "parameters": [ { "in": "query", "name": "blockAds", "schema": { "description": "Whether or not to load ad-blocking extensions for the session.\nThis currently uses uBlock-Lite and may cause certain sites\nto not load properly.", "type": "boolean" } }, { "in": "query", "name": "integrationId", "schema": { "description": "Which registered 1Password integration's login items to return.", "type": "string" } }, { "in": "query", "name": "launch", "schema": { "description": "Launch options, which can be either an object\nof puppeteer.launch options or playwright.launchServer\noptions, depending on the API. Must be either JSON\nobject, or a base64-encoded JSON object.", "anyOf": [ { "$ref": "#/components/schemas/CDPLaunchOptions" }, { "$ref": "#/components/schemas/BrowserServerOptions" }, { "type": "string" } ] } }, { "in": "query", "name": "profile", "schema": { "description": "Name of an authenticated profile to hydrate into the browser at launch.\nThe profile's cookies, localStorage and IndexedDB are injected via CDP\nbefore 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.\nAccepts 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": { "integrationId": { "type": "string" }, "domains": { "type": "array", "items": { "type": "object", "properties": { "origin": { "type": "string" }, "credentialTypes": { "type": "array", "items": { "type": "string" } } }, "additionalProperties": false, "required": [ "credentialTypes", "origin" ] } } }, "additionalProperties": false, "required": [ "domains", "integrationId" ], "$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" }, "403": { "code": 403, "description": "The request targets a destination that is not allowed.", "message": "HTTP/1.1 403 Forbidden" }, "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": "/integrations/onepassword/autologin/form", "tags": [ "Integrations" ] } }, "/": { "get": { "description": "Launch and connect to Chromium with a library like puppeteer or others that work over chrome-devtools-protocol.\n\n**Note:** Also available at `/chromium` as a convenience alias.", "parameters": [ { "in": "query", "name": "allowedDomains", "schema": { "description": "Optional per-connection narrowing of the integration's allowed-domain list.\nExtracted from the JSON `allowedDomains` query parameter. Can only narrow the\nintegration's domains, never widen them.", "type": "array", "items": { "type": "string" } } }, { "in": "query", "name": "blockAds", "schema": { "description": "Whether or not to load ad-blocking extensions for the session.\nThis currently uses uBlock-Lite and may cause certain sites\nto not load properly.", "type": "boolean" } }, { "in": "query", "name": "credentials", "schema": { "$ref": "#/components/schemas/StringRecord", "description": "Optional alias → `op://…` reference map for the integration above. Extracted\nfrom the JSON `credentials` query parameter. References are not secret;\nresolved values are never stored here. Optional — a connection can also pass\nraw `op://…` references straight to Browserless.loadSecret." } }, { "in": "query", "name": "externalProxyServer", "schema": { "description": "External proxy server URL for user-provided proxies.\nFormat: http(s)://[username:password@]host:port\nWhen set, routes requests through this proxy instead of built-in residential proxies.", "type": "string" } }, { "in": "query", "name": "integrationId", "schema": { "description": "Optional 1Password integration id for credential filling on a non-persistent\nconnection. Extracted from the `integrationId` query parameter; the persistent\nsession path carries the same data on session metadata instead.", "type": "string" } }, { "in": "query", "name": "integrations", "schema": { "type": "string" } }, { "in": "query", "name": "launch", "schema": { "description": "Launch options, which can be either an object\nof puppeteer.launch options or playwright.launchServer\noptions, depending on the API. Must be either JSON\nobject, or a base64-encoded JSON object.", "anyOf": [ { "$ref": "#/components/schemas/CDPLaunchOptions" }, { "type": "string" } ] } }, { "in": "query", "name": "profile", "schema": { "description": "Name of an authenticated profile to hydrate into the browser at launch.\nThe profile's cookies, localStorage and IndexedDB are injected via CDP\nbefore your code runs. No-op in builds without a profile subsystem.", "type": "string" } }, { "in": "query", "name": "proxy", "schema": { "$ref": "#/components/schemas/ProxyType", "description": "The type of proxy to use: 'residential' or 'datacenter'." } }, { "in": "query", "name": "proxyCity", "schema": { "description": "The city to use for the proxy.\n\nAvailable cities: https://production-sfo.browserless.io/proxy/cities?token=YOUR_TOKEN\nDocumentation: 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.\n\nSupported codes: US, GB, FR, DE, etc.\nFull 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.\nRecommended when using proxyCountry to ensure websites render content,\ncurrency, 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.\nMaps to specific proxy vendors internally for optimal access to certain websites.\nFormat: \"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": "record", "schema": { "type": "boolean" } }, { "in": "query", "name": "replay", "schema": { "type": "boolean" } }, { "in": "query", "name": "solveCaptchas", "schema": { "type": "boolean" } }, { "in": "query", "name": "timeout", "schema": { "description": "Override the system-level timeout for this request.\nAccepts 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": { "101": { "description": "Indicates successful WebSocket upgrade." }, "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" }, "403": { "code": 403, "description": "The request targets a destination that is not allowed.", "message": "HTTP/1.1 403 Forbidden" }, "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": "/", "tags": [ "WebSocket APIs" ], "operationId": "chromium-root" } }, "/chromium": { "get": { "description": "Launch and connect to Chromium with a library like puppeteer or others that work over chrome-devtools-protocol.\n\n**Note:** This endpoint is also available at: `/` for backwards compatibility.", "parameters": [ { "in": "query", "name": "blockAds", "schema": { "description": "Whether or not to load ad-blocking extensions for the session.\nThis currently uses uBlock-Lite and may cause certain sites\nto not load properly.", "type": "boolean" } }, { "in": "query", "name": "launch", "schema": { "description": "Launch options, which can be either an object\nof puppeteer.launch options or playwright.launchServer\noptions, depending on the API. Must be either JSON\nobject, or a base64-encoded JSON object.", "anyOf": [ { "$ref": "#/components/schemas/CDPLaunchOptions" }, { "type": "string" } ] } }, { "in": "query", "name": "profile", "schema": { "description": "Name of an authenticated profile to hydrate into the browser at launch.\nThe profile's cookies, localStorage and IndexedDB are injected via CDP\nbefore 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.\nAccepts 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" } }, { "in": "query", "name": "allowedDomains", "schema": { "description": "Optional per-connection narrowing of the integration's allowed-domain list.\nExtracted from the JSON `allowedDomains` query parameter. Can only narrow the\nintegration's domains, never widen them.", "type": "array", "items": { "type": "string" } } }, { "in": "query", "name": "credentials", "schema": { "$ref": "#/components/schemas/StringRecord", "description": "Optional alias → `op://…` reference map for the integration above. Extracted\nfrom the JSON `credentials` query parameter. References are not secret;\nresolved values are never stored here. Optional — a connection can also pass\nraw `op://…` references straight to Browserless.loadSecret." } }, { "in": "query", "name": "externalProxyServer", "schema": { "description": "External proxy server URL for user-provided proxies.\nFormat: http(s)://[username:password@]host:port\nWhen set, routes requests through this proxy instead of built-in residential proxies.", "type": "string" } }, { "in": "query", "name": "integrationId", "schema": { "description": "Optional 1Password integration id for credential filling on a non-persistent\nconnection. Extracted from the `integrationId` query parameter; the persistent\nsession path carries the same data on session metadata instead.", "type": "string" } }, { "in": "query", "name": "proxy", "schema": { "$ref": "#/components/schemas/ProxyType", "description": "The type of proxy to use: 'residential' or 'datacenter'." } }, { "in": "query", "name": "proxyCity", "schema": { "description": "The city to use for the proxy.\n\nAvailable cities: https://production-sfo.browserless.io/proxy/cities?token=YOUR_TOKEN\nDocumentation: 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.\n\nSupported codes: US, GB, FR, DE, etc.\nFull 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.\nRecommended when using proxyCountry to ensure websites render content,\ncurrency, 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.\nMaps to specific proxy vendors internally for optimal access to certain websites.\nFormat: \"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" } } ], "requestBody": { "content": {} }, "responses": { "101": { "description": "Indicates successful WebSocket upgrade." }, "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" }, "403": { "code": 403, "description": "The request targets a destination that is not allowed.", "message": "HTTP/1.1 403 Forbidden" }, "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", "tags": [ "WebSocket APIs" ] } }, "/chromium/playwright": { "get": { "description": "Connect to Chromium with any playwright style library.\n\n**Note:** Also available at `/playwright` as a convenience alias.", "parameters": [ { "in": "query", "name": "blockAds", "schema": { "description": "Whether or not to load ad-blocking extensions for the session.\nThis currently uses uBlock-Lite and may cause certain sites\nto not load properly.", "type": "boolean" } }, { "in": "query", "name": "launch", "schema": { "description": "Launch options, which can be either an object\nof puppeteer.launch options or playwright.launchServer\noptions, depending on the API. Must be either JSON\nobject, or a base64-encoded JSON object.", "anyOf": [ { "$ref": "#/components/schemas/BrowserServerOptions" }, { "type": "string" } ] } }, { "in": "query", "name": "profile", "schema": { "description": "Name of an authenticated profile to hydrate into the browser at launch.\nThe profile's cookies, localStorage and IndexedDB are injected via CDP\nbefore 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.\nAccepts 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" } }, { "in": "query", "name": "allowedDomains", "schema": { "description": "Optional per-connection narrowing of the integration's allowed-domain list.\nExtracted from the JSON `allowedDomains` query parameter. Can only narrow the\nintegration's domains, never widen them.", "type": "array", "items": { "type": "string" } } }, { "in": "query", "name": "credentials", "schema": { "$ref": "#/components/schemas/StringRecord", "description": "Optional alias → `op://…` reference map for the integration above. Extracted\nfrom the JSON `credentials` query parameter. References are not secret;\nresolved values are never stored here. Optional — a connection can also pass\nraw `op://…` references straight to Browserless.loadSecret." } }, { "in": "query", "name": "externalProxyServer", "schema": { "description": "External proxy server URL for user-provided proxies.\nFormat: http(s)://[username:password@]host:port\nWhen set, routes requests through this proxy instead of built-in residential proxies.", "type": "string" } }, { "in": "query", "name": "integrationId", "schema": { "description": "Optional 1Password integration id for credential filling on a non-persistent\nconnection. Extracted from the `integrationId` query parameter; the persistent\nsession path carries the same data on session metadata instead.", "type": "string" } }, { "in": "query", "name": "proxy", "schema": { "$ref": "#/components/schemas/ProxyType", "description": "The type of proxy to use: 'residential' or 'datacenter'." } }, { "in": "query", "name": "proxyCity", "schema": { "description": "The city to use for the proxy.\n\nAvailable cities: https://production-sfo.browserless.io/proxy/cities?token=YOUR_TOKEN\nDocumentation: 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.\n\nSupported codes: US, GB, FR, DE, etc.\nFull 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.\nRecommended when using proxyCountry to ensure websites render content,\ncurrency, 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.\nMaps to specific proxy vendors internally for optimal access to certain websites.\nFormat: \"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" } } ], "requestBody": { "content": {} }, "responses": { "101": { "description": "Indicates successful WebSocket upgrade." }, "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" }, "403": { "code": 403, "description": "The request targets a destination that is not allowed.", "message": "HTTP/1.1 403 Forbidden" }, "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/playwright", "tags": [ "WebSocket APIs" ] } }, "/edge": { "get": { "description": "Launch and connect to Chromium with a library like puppeteer or others that work over chrome-devtools-protocol.", "parameters": [ { "in": "query", "name": "allowedDomains", "schema": { "description": "Optional per-connection narrowing of the integration's allowed-domain list.\nExtracted from the JSON `allowedDomains` query parameter. Can only narrow the\nintegration's domains, never widen them.", "type": "array", "items": { "type": "string" } } }, { "in": "query", "name": "blockAds", "schema": { "description": "Whether or not to load ad-blocking extensions for the session.\nThis currently uses uBlock-Lite and may cause certain sites\nto not load properly.", "type": "boolean" } }, { "in": "query", "name": "credentials", "schema": { "$ref": "#/components/schemas/StringRecord", "description": "Optional alias → `op://…` reference map for the integration above. Extracted\nfrom the JSON `credentials` query parameter. References are not secret;\nresolved values are never stored here. Optional — a connection can also pass\nraw `op://…` references straight to Browserless.loadSecret." } }, { "in": "query", "name": "externalProxyServer", "schema": { "description": "External proxy server URL for user-provided proxies.\nFormat: http(s)://[username:password@]host:port\nWhen set, routes requests through this proxy instead of built-in residential proxies.", "type": "string" } }, { "in": "query", "name": "integrationId", "schema": { "description": "Optional 1Password integration id for credential filling on a non-persistent\nconnection. Extracted from the `integrationId` query parameter; the persistent\nsession path carries the same data on session metadata instead.", "type": "string" } }, { "in": "query", "name": "integrations", "schema": { "type": "string" } }, { "in": "query", "name": "launch", "schema": { "description": "Launch options, which can be either an object\nof puppeteer.launch options or playwright.launchServer\noptions, depending on the API. Must be either JSON\nobject, or a base64-encoded JSON object.", "anyOf": [ { "$ref": "#/components/schemas/CDPLaunchOptions" }, { "type": "string" } ] } }, { "in": "query", "name": "profile", "schema": { "description": "Name of an authenticated profile to hydrate into the browser at launch.\nThe profile's cookies, localStorage and IndexedDB are injected via CDP\nbefore your code runs. No-op in builds without a profile subsystem.", "type": "string" } }, { "in": "query", "name": "proxy", "schema": { "$ref": "#/components/schemas/ProxyType", "description": "The type of proxy to use: 'residential' or 'datacenter'." } }, { "in": "query", "name": "proxyCity", "schema": { "description": "The city to use for the proxy.\n\nAvailable cities: https://production-sfo.browserless.io/proxy/cities?token=YOUR_TOKEN\nDocumentation: 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.\n\nSupported codes: US, GB, FR, DE, etc.\nFull 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.\nRecommended when using proxyCountry to ensure websites render content,\ncurrency, 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.\nMaps to specific proxy vendors internally for optimal access to certain websites.\nFormat: \"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": "record", "schema": { "type": "boolean" } }, { "in": "query", "name": "replay", "schema": { "type": "boolean" } }, { "in": "query", "name": "solveCaptchas", "schema": { "type": "boolean" } }, { "in": "query", "name": "timeout", "schema": { "description": "Override the system-level timeout for this request.\nAccepts 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": { "101": { "description": "Indicates successful WebSocket upgrade." }, "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" }, "403": { "code": 403, "description": "The request targets a destination that is not allowed.", "message": "HTTP/1.1 403 Forbidden" }, "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", "tags": [ "WebSocket APIs" ] } }, "/edge/playwright": { "get": { "description": "Connect to Chromium with any playwright style library.", "parameters": [ { "in": "query", "name": "blockAds", "schema": { "description": "Whether or not to load ad-blocking extensions for the session.\nThis currently uses uBlock-Lite and may cause certain sites\nto not load properly.", "type": "boolean" } }, { "in": "query", "name": "launch", "schema": { "description": "Launch options, which can be either an object\nof puppeteer.launch options or playwright.launchServer\noptions, depending on the API. Must be either JSON\nobject, or a base64-encoded JSON object.", "anyOf": [ { "$ref": "#/components/schemas/BrowserServerOptions" }, { "type": "string" } ] } }, { "in": "query", "name": "profile", "schema": { "description": "Name of an authenticated profile to hydrate into the browser at launch.\nThe profile's cookies, localStorage and IndexedDB are injected via CDP\nbefore 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.\nAccepts 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" } }, { "in": "query", "name": "allowedDomains", "schema": { "description": "Optional per-connection narrowing of the integration's allowed-domain list.\nExtracted from the JSON `allowedDomains` query parameter. Can only narrow the\nintegration's domains, never widen them.", "type": "array", "items": { "type": "string" } } }, { "in": "query", "name": "credentials", "schema": { "$ref": "#/components/schemas/StringRecord", "description": "Optional alias → `op://…` reference map for the integration above. Extracted\nfrom the JSON `credentials` query parameter. References are not secret;\nresolved values are never stored here. Optional — a connection can also pass\nraw `op://…` references straight to Browserless.loadSecret." } }, { "in": "query", "name": "externalProxyServer", "schema": { "description": "External proxy server URL for user-provided proxies.\nFormat: http(s)://[username:password@]host:port\nWhen set, routes requests through this proxy instead of built-in residential proxies.", "type": "string" } }, { "in": "query", "name": "integrationId", "schema": { "description": "Optional 1Password integration id for credential filling on a non-persistent\nconnection. Extracted from the `integrationId` query parameter; the persistent\nsession path carries the same data on session metadata instead.", "type": "string" } }, { "in": "query", "name": "proxy", "schema": { "$ref": "#/components/schemas/ProxyType", "description": "The type of proxy to use: 'residential' or 'datacenter'." } }, { "in": "query", "name": "proxyCity", "schema": { "description": "The city to use for the proxy.\n\nAvailable cities: https://production-sfo.browserless.io/proxy/cities?token=YOUR_TOKEN\nDocumentation: 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.\n\nSupported codes: US, GB, FR, DE, etc.\nFull 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.\nRecommended when using proxyCountry to ensure websites render content,\ncurrency, 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.\nMaps to specific proxy vendors internally for optimal access to certain websites.\nFormat: \"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" } } ], "requestBody": { "content": {} }, "responses": { "101": { "description": "Indicates successful WebSocket upgrade." }, "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" }, "403": { "code": 403, "description": "The request targets a destination that is not allowed.", "message": "HTTP/1.1 403 Forbidden" }, "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/playwright", "tags": [ "WebSocket APIs" ] } }, "/firefox/playwright": { "get": { "description": "Connect to Firefox with any playwright-compliant library.\n\n**Note:** Also available at `/playwright/firefox` as a convenience alias.", "parameters": [ { "in": "query", "name": "blockAds", "schema": { "description": "Whether or not to load ad-blocking extensions for the session.\nThis currently uses uBlock-Lite and may cause certain sites\nto not load properly.", "type": "boolean" } }, { "in": "query", "name": "launch", "schema": { "description": "Launch options, which can be either an object\nof puppeteer.launch options or playwright.launchServer\noptions, depending on the API. Must be either JSON\nobject, or a base64-encoded JSON object.", "additionalProperties": false, "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" }, "firefoxUserPrefs": { "type": "object", "additionalProperties": { "type": [ "string", "number", "boolean" ] } } } } }, { "in": "query", "name": "profile", "schema": { "description": "Name of an authenticated profile to hydrate into the browser at launch.\nThe profile's cookies, localStorage and IndexedDB are injected via CDP\nbefore 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.\nAccepts 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" } }, { "in": "query", "name": "allowedDomains", "schema": { "description": "Optional per-connection narrowing of the integration's allowed-domain list.\nExtracted from the JSON `allowedDomains` query parameter. Can only narrow the\nintegration's domains, never widen them.", "type": "array", "items": { "type": "string" } } }, { "in": "query", "name": "credentials", "schema": { "$ref": "#/components/schemas/StringRecord", "description": "Optional alias → `op://…` reference map for the integration above. Extracted\nfrom the JSON `credentials` query parameter. References are not secret;\nresolved values are never stored here. Optional — a connection can also pass\nraw `op://…` references straight to Browserless.loadSecret." } }, { "in": "query", "name": "externalProxyServer", "schema": { "description": "External proxy server URL for user-provided proxies.\nFormat: http(s)://[username:password@]host:port\nWhen set, routes requests through this proxy instead of built-in residential proxies.", "type": "string" } }, { "in": "query", "name": "integrationId", "schema": { "description": "Optional 1Password integration id for credential filling on a non-persistent\nconnection. Extracted from the `integrationId` query parameter; the persistent\nsession path carries the same data on session metadata instead.", "type": "string" } }, { "in": "query", "name": "proxy", "schema": { "$ref": "#/components/schemas/ProxyType", "description": "The type of proxy to use: 'residential' or 'datacenter'." } }, { "in": "query", "name": "proxyCity", "schema": { "description": "The city to use for the proxy.\n\nAvailable cities: https://production-sfo.browserless.io/proxy/cities?token=YOUR_TOKEN\nDocumentation: 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.\n\nSupported codes: US, GB, FR, DE, etc.\nFull 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.\nRecommended when using proxyCountry to ensure websites render content,\ncurrency, 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.\nMaps to specific proxy vendors internally for optimal access to certain websites.\nFormat: \"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" } } ], "requestBody": { "content": {} }, "responses": { "101": { "description": "Indicates successful WebSocket upgrade." }, "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" }, "403": { "code": 403, "description": "The request targets a destination that is not allowed.", "message": "HTTP/1.1 403 Forbidden" }, "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": "/firefox/playwright", "tags": [ "WebSocket APIs" ] } }, "/webkit/playwright": { "get": { "description": "Connect to Webkit with any playwright-compliant library.\n\n**Note:** Also available at `/playwright/webkit` as a convenience alias.", "parameters": [ { "in": "query", "name": "blockAds", "schema": { "description": "Whether or not to load ad-blocking extensions for the session.\nThis currently uses uBlock-Lite and may cause certain sites\nto not load properly.", "type": "boolean" } }, { "in": "query", "name": "launch", "schema": { "description": "Launch options, which can be either an object\nof puppeteer.launch options or playwright.launchServer\noptions, depending on the API. Must be either JSON\nobject, or a base64-encoded JSON object.", "anyOf": [ { "$ref": "#/components/schemas/BrowserServerOptions" }, { "type": "string" } ] } }, { "in": "query", "name": "profile", "schema": { "description": "Name of an authenticated profile to hydrate into the browser at launch.\nThe profile's cookies, localStorage and IndexedDB are injected via CDP\nbefore 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.\nAccepts 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" } }, { "in": "query", "name": "allowedDomains", "schema": { "description": "Optional per-connection narrowing of the integration's allowed-domain list.\nExtracted from the JSON `allowedDomains` query parameter. Can only narrow the\nintegration's domains, never widen them.", "type": "array", "items": { "type": "string" } } }, { "in": "query", "name": "credentials", "schema": { "$ref": "#/components/schemas/StringRecord", "description": "Optional alias → `op://…` reference map for the integration above. Extracted\nfrom the JSON `credentials` query parameter. References are not secret;\nresolved values are never stored here. Optional — a connection can also pass\nraw `op://…` references straight to Browserless.loadSecret." } }, { "in": "query", "name": "externalProxyServer", "schema": { "description": "External proxy server URL for user-provided proxies.\nFormat: http(s)://[username:password@]host:port\nWhen set, routes requests through this proxy instead of built-in residential proxies.", "type": "string" } }, { "in": "query", "name": "integrationId", "schema": { "description": "Optional 1Password integration id for credential filling on a non-persistent\nconnection. Extracted from the `integrationId` query parameter; the persistent\nsession path carries the same data on session metadata instead.", "type": "string" } }, { "in": "query", "name": "proxy", "schema": { "$ref": "#/components/schemas/ProxyType", "description": "The type of proxy to use: 'residential' or 'datacenter'." } }, { "in": "query", "name": "proxyCity", "schema": { "description": "The city to use for the proxy.\n\nAvailable cities: https://production-sfo.browserless.io/proxy/cities?token=YOUR_TOKEN\nDocumentation: 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.\n\nSupported codes: US, GB, FR, DE, etc.\nFull 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.\nRecommended when using proxyCountry to ensure websites render content,\ncurrency, 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.\nMaps to specific proxy vendors internally for optimal access to certain websites.\nFormat: \"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" } } ], "requestBody": { "content": {} }, "responses": { "101": { "description": "Indicates successful WebSocket upgrade." }, "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" }, "403": { "code": 403, "description": "The request targets a destination that is not allowed.", "message": "HTTP/1.1 403 Forbidden" }, "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": "/webkit/playwright", "tags": [ "WebSocket APIs" ] } }, "/live/*": { "get": { "description": "> This API is only available on paid plans. [Sign-up here](https://www.browserless.io/pricing/).\n\nWebsocket back-end that powers the live session experience.\n\n**Note:** Also available at `/chromium/live/*` as a convenience alias.", "parameters": [], "requestBody": { "content": {} }, "responses": { "101": { "description": "Indicates successful WebSocket upgrade." }, "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" }, "403": { "code": 403, "description": "The request targets a destination that is not allowed.", "message": "HTTP/1.1 403 Forbidden" }, "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": "/live/*", "tags": [ "WebSocket APIs" ] } }, "/session/bql/*": { "post": { "description": "> Executes BrowserQL queries against an existing session. The session must be a stealth session to support BrowserQL.\n\nBrowserQL is a GraphQL-based query language for browser automation that allows you to interact with web pages using a declarative syntax.\nQueries 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 not to load ad-blocking extensions for the session.\nThis currently uses uBlock-Lite and may cause certain sites\nto 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.\nIncludes options like `headless`, `args`, `defaultViewport`, etc.\nMust be either JSON object, or a base64-encoded JSON object.", "anyOf": [ { "$ref": "#/components/schemas/CDPLaunchOptions" }, { "type": "string" } ] } }, { "in": "query", "name": "profile", "schema": { "description": "Name of an authenticated profile to hydrate into the browser at launch.\nThe profile's cookies, localStorage and IndexedDB are injected via CDP\nbefore 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.\nAccepts 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" } }, { "in": "query", "name": "allowedDomains", "schema": { "description": "Optional per-connection narrowing of the integration's allowed-domain list.\nExtracted from the JSON `allowedDomains` query parameter. Can only narrow the\nintegration's domains, never widen them.", "type": "array", "items": { "type": "string" } } }, { "in": "query", "name": "credentials", "schema": { "$ref": "#/components/schemas/StringRecord", "description": "Optional alias → `op://…` reference map for the integration above. Extracted\nfrom the JSON `credentials` query parameter. References are not secret;\nresolved values are never stored here. Optional — a connection can also pass\nraw `op://…` references straight to Browserless.loadSecret." } }, { "in": "query", "name": "externalProxyServer", "schema": { "description": "External proxy server URL for user-provided proxies.\nFormat: http(s)://[username:password@]host:port\nWhen set, routes requests through this proxy instead of built-in residential proxies.", "type": "string" } }, { "in": "query", "name": "integrationId", "schema": { "description": "Optional 1Password integration id for credential filling on a non-persistent\nconnection. Extracted from the `integrationId` query parameter; the persistent\nsession path carries the same data on session metadata instead.", "type": "string" } }, { "in": "query", "name": "proxy", "schema": { "$ref": "#/components/schemas/ProxyType", "description": "The type of proxy to use: 'residential' or 'datacenter'." } }, { "in": "query", "name": "proxyCity", "schema": { "description": "The city to use for the proxy.\n\nAvailable cities: https://production-sfo.browserless.io/proxy/cities?token=YOUR_TOKEN\nDocumentation: 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.\n\nSupported codes: US, GB, FR, DE, etc.\nFull 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.\nRecommended when using proxyCountry to ensure websites render content,\ncurrency, 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.\nMaps to specific proxy vendors internally for optimal access to certain websites.\nFormat: \"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" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "query": { "description": "The GraphQL query string to execute against the browser session.\n\nExample queries:\n- Get browser info: `query { version browser }`\n- Navigate and get content: `mutation { goto(url: \"https://example.com\") { status } title { title } url { url } }`\n- 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 } }`\n- 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.\n\nExample: `{ \"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.\nOptional - 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": "#/components/schemas/AnyRecord", "description": "The GraphQL response data. Contains the result of the executed query.\nStructure depends on the specific query executed.\n\nExample responses:\n- Navigation + Title + Element: `{ \"goto\": { \"status\": 200 }, \"title\": { \"title\": \"Example Domain\" }, \"querySelector\": { \"innerHTML\": \"Example Domain\" } }`\n- Multiple elements: `{ \"querySelectorAll\": [{ \"innerHTML\": \"Item 1\" }, { \"innerHTML\": \"Item 2\" }] }`\n- Screenshot: `{ \"screenshot\": { \"data\": \"base64encodedimage\", \"type\": \"png\" } }`\n- PDF: `{ \"pdf\": { \"data\": \"base64encodedpdf\" } }`\n- System info: `{ \"version\": \"1.0.0\", \"browser\": \"Chrome/120.0.0.0\" }`\n- Form interaction: `{ \"type\": { \"success\": true }, \"click\": { \"success\": true } }`" }, "errors": { "description": "Array of GraphQL errors, if any occurred during query execution.\nOnly 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" }, "403": { "code": 403, "description": "The request targets a destination that is not allowed.", "message": "HTTP/1.1 403 Forbidden" }, "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": [ "Sessions & Connections" ] } }, "/reconnect/*": { "get": { "description": "Reconnect to an existing Chromium or Chrome session with a library like puppeteer or others that work over chrome-devtools-protocol.", "parameters": [ { "in": "query", "name": "blockAds", "schema": { "description": "Whether or not to load ad-blocking extensions for the session.\nThis currently uses uBlock-Lite and may cause certain sites\nto not load properly.", "type": "boolean" } }, { "in": "query", "name": "integrations", "schema": { "type": "string" } }, { "in": "query", "name": "launch", "schema": { "description": "Launch options, which can be either an object\nof puppeteer.launch options or playwright.launchServer\noptions, depending on the API. Must be either JSON\nobject, or a base64-encoded JSON object.", "anyOf": [ { "$ref": "#/components/schemas/CDPLaunchOptions" }, { "$ref": "#/components/schemas/BrowserServerOptions" }, { "type": "string" } ] } }, { "in": "query", "name": "profile", "schema": { "description": "Name of an authenticated profile to hydrate into the browser at launch.\nThe profile's cookies, localStorage and IndexedDB are injected via CDP\nbefore your code runs. No-op in builds without a profile subsystem.", "type": "string" } }, { "in": "query", "name": "replay", "schema": { "type": "boolean" } }, { "in": "query", "name": "solveCaptchas", "schema": { "type": "boolean" } }, { "in": "query", "name": "timeout", "schema": { "description": "Override the system-level timeout for this request.\nAccepts 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" } }, { "in": "query", "name": "allowedDomains", "schema": { "description": "Optional per-connection narrowing of the integration's allowed-domain list.\nExtracted from the JSON `allowedDomains` query parameter. Can only narrow the\nintegration's domains, never widen them.", "type": "array", "items": { "type": "string" } } }, { "in": "query", "name": "credentials", "schema": { "$ref": "#/components/schemas/StringRecord", "description": "Optional alias → `op://…` reference map for the integration above. Extracted\nfrom the JSON `credentials` query parameter. References are not secret;\nresolved values are never stored here. Optional — a connection can also pass\nraw `op://…` references straight to Browserless.loadSecret." } }, { "in": "query", "name": "externalProxyServer", "schema": { "description": "External proxy server URL for user-provided proxies.\nFormat: http(s)://[username:password@]host:port\nWhen set, routes requests through this proxy instead of built-in residential proxies.", "type": "string" } }, { "in": "query", "name": "integrationId", "schema": { "description": "Optional 1Password integration id for credential filling on a non-persistent\nconnection. Extracted from the `integrationId` query parameter; the persistent\nsession path carries the same data on session metadata instead.", "type": "string" } }, { "in": "query", "name": "proxy", "schema": { "$ref": "#/components/schemas/ProxyType", "description": "The type of proxy to use: 'residential' or 'datacenter'." } }, { "in": "query", "name": "proxyCity", "schema": { "description": "The city to use for the proxy.\n\nAvailable cities: https://production-sfo.browserless.io/proxy/cities?token=YOUR_TOKEN\nDocumentation: 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.\n\nSupported codes: US, GB, FR, DE, etc.\nFull 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.\nRecommended when using proxyCountry to ensure websites render content,\ncurrency, 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.\nMaps to specific proxy vendors internally for optimal access to certain websites.\nFormat: \"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" } } ], "requestBody": { "content": {} }, "responses": { "101": { "description": "Indicates successful WebSocket upgrade." }, "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" }, "403": { "code": 403, "description": "The request targets a destination that is not allowed.", "message": "HTTP/1.1 403 Forbidden" }, "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": "/reconnect/*", "tags": [ "Sessions & Connections" ] } }, "/session/connect/*": { "get": { "description": "Connect to an existing session with a library like puppeteer or playwright that work over chrome-devtools-protocol. See documentation for more details on how to start the session.\n\nThe browser type (Chrome/Chromium, stealth/regular) is determined from the session metadata when it was created initially.", "parameters": [ { "in": "query", "name": "launch", "schema": { "anyOf": [ { "$ref": "#/components/schemas/CDPLaunchOptions" }, { "type": "string" } ] } }, { "in": "query", "name": "replay", "schema": { "type": "boolean" } }, { "in": "query", "name": "timeout", "schema": { "type": "number" } }, { "in": "query", "name": "token", "schema": { "type": "string" } }, { "in": "query", "name": "allowedDomains", "schema": { "description": "Optional per-connection narrowing of the integration's allowed-domain list.\nExtracted from the JSON `allowedDomains` query parameter. Can only narrow the\nintegration's domains, never widen them.", "type": "array", "items": { "type": "string" } } }, { "in": "query", "name": "credentials", "schema": { "$ref": "#/components/schemas/StringRecord", "description": "Optional alias → `op://…` reference map for the integration above. Extracted\nfrom the JSON `credentials` query parameter. References are not secret;\nresolved values are never stored here. Optional — a connection can also pass\nraw `op://…` references straight to Browserless.loadSecret." } }, { "in": "query", "name": "externalProxyServer", "schema": { "description": "External proxy server URL for user-provided proxies.\nFormat: http(s)://[username:password@]host:port\nWhen set, routes requests through this proxy instead of built-in residential proxies.", "type": "string" } }, { "in": "query", "name": "integrationId", "schema": { "description": "Optional 1Password integration id for credential filling on a non-persistent\nconnection. Extracted from the `integrationId` query parameter; the persistent\nsession path carries the same data on session metadata instead.", "type": "string" } }, { "in": "query", "name": "proxy", "schema": { "$ref": "#/components/schemas/ProxyType", "description": "The type of proxy to use: 'residential' or 'datacenter'." } }, { "in": "query", "name": "proxyCity", "schema": { "description": "The city to use for the proxy.\n\nAvailable cities: https://production-sfo.browserless.io/proxy/cities?token=YOUR_TOKEN\nDocumentation: 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.\n\nSupported codes: US, GB, FR, DE, etc.\nFull 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.\nRecommended when using proxyCountry to ensure websites render content,\ncurrency, 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.\nMaps to specific proxy vendors internally for optimal access to certain websites.\nFormat: \"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" } } ], "requestBody": { "content": {} }, "responses": { "101": { "description": "Indicates successful WebSocket upgrade." }, "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" }, "403": { "code": 403, "description": "The request targets a destination that is not allowed.", "message": "HTTP/1.1 403 Forbidden" }, "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/connect/*", "tags": [ "Sessions & Connections" ] } }, "/chrome/screenshot": { "post": { "description": "Returns a screenshot binary from a `url` or `html` payload (Chrome, legacy).\n\"url\" or \"html\" payload in your request. Many options exist including\ncookies, user-agents, setting timers and network mocks.", "parameters": [ { "in": "query", "name": "blockAds", "schema": { "description": "Whether or not to load ad-blocking extensions for the session.\nThis currently uses uBlock-Lite and may cause certain sites\nto not load properly.", "type": "boolean" } }, { "in": "query", "name": "launch", "schema": { "description": "Launch options, which can be either an object\nof puppeteer.launch options or playwright.launchServer\noptions, depending on the API. Must be either JSON\nobject, or a base64-encoded JSON object.", "anyOf": [ { "$ref": "#/components/schemas/CDPLaunchOptions" }, { "type": "string" } ] } }, { "in": "query", "name": "profile", "schema": { "description": "Name of an authenticated profile to hydrate into the browser at launch.\nThe profile's cookies, localStorage and IndexedDB are injected via CDP\nbefore 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.\nAccepts 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" } }, { "in": "query", "name": "allowedDomains", "schema": { "description": "Optional per-connection narrowing of the integration's allowed-domain list.\nExtracted from the JSON `allowedDomains` query parameter. Can only narrow the\nintegration's domains, never widen them.", "type": "array", "items": { "type": "string" } } }, { "in": "query", "name": "credentials", "schema": { "$ref": "#/components/schemas/StringRecord", "description": "Optional alias → `op://…` reference map for the integration above. Extracted\nfrom the JSON `credentials` query parameter. References are not secret;\nresolved values are never stored here. Optional — a connection can also pass\nraw `op://…` references straight to Browserless.loadSecret." } }, { "in": "query", "name": "externalProxyServer", "schema": { "description": "External proxy server URL for user-provided proxies.\nFormat: http(s)://[username:password@]host:port\nWhen set, routes requests through this proxy instead of built-in residential proxies.", "type": "string" } }, { "in": "query", "name": "integrationId", "schema": { "description": "Optional 1Password integration id for credential filling on a non-persistent\nconnection. Extracted from the `integrationId` query parameter; the persistent\nsession path carries the same data on session metadata instead.", "type": "string" } }, { "in": "query", "name": "proxy", "schema": { "$ref": "#/components/schemas/ProxyType", "description": "The type of proxy to use: 'residential' or 'datacenter'." } }, { "in": "query", "name": "proxyCity", "schema": { "description": "The city to use for the proxy.\n\nAvailable cities: https://production-sfo.browserless.io/proxy/cities?token=YOUR_TOKEN\nDocumentation: 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.\n\nSupported codes: US, GB, FR, DE, etc.\nFull 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.\nRecommended when using proxyCountry to ensure websites render content,\ncurrency, 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.\nMaps to specific proxy vendors internally for optimal access to certain websites.\nFormat: \"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" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "addScriptTag": { "type": "array", "items": { "$ref": "#/components/schemas/FrameAddScriptTagOptions" } }, "addStyleTag": { "type": "array", "items": { "$ref": "#/components/schemas/FrameAddStyleTagOptions" } }, "authenticate": { "anyOf": [ { "$ref": "#/components/schemas/Credentials" }, { "type": "null" } ], "description": "Credentials for HTTP authentication. Contains `username` and `password` properties." }, "bestAttempt": { "description": "When bestAttempt is set to true, browserless attempt to proceed\nwhen \"awaited\" events fail or timeout. This includes things like\ngoto, waitForSelector, and more.", "type": "boolean" }, "cookies": { "type": "array", "items": { "$ref": "#/components/schemas/CookieParam" } }, "emulateMediaType": { "type": "string" }, "gotoOptions": { "$ref": "#/components/schemas/GoToOptions", "description": "Options to configure the page navigation, such as `timeout` and `waitUntil`." }, "html": { "type": "string" }, "options": { "$ref": "#/components/schemas/ScreenshotOptions", "description": "Screenshot options based on Puppeteer's ScreenshotOptions interface.\nIncludes properties like `type`, `quality`, `fullPage`, `clip`, etc." }, "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\ncorresponding 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\ncorresponding responses to use in order to fulfill those requests.", "type": "string" }, "response": { "additionalProperties": false, "type": "object", "properties": { "headers": { "description": "Optional response headers.\n\nThe record values will be converted to string following:\nArrays' values will be mapped to String\n(Used when you need multiple headers with the same name).\nNon-arrays will be converted to String.", "$ref": "#/components/schemas/AnyRecord" }, "status": { "type": "number" }, "contentType": { "type": "string" }, "body": { "description": "A string representation of the body to return. Can be a base64-encoded\nstring 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\nMissing optional values will be filled in by the target with what it would normally use.", "$ref": "#/components/schemas/Protocol.Emulation.UserAgentMetadata" }, "platform": { "type": "string" } }, "additionalProperties": false }, "viewport": { "anyOf": [ { "$ref": "#/components/schemas/Viewport" }, { "type": "null" } ], "description": "The viewport dimensions and settings for the page.\nIncludes properties like `width`, `height`, `deviceScaleFactor`, etc." }, "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.\nIf polling is a number, then it is treated as an interval in milliseconds\nat which the function would be executed. If polling is a string,\nthen 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).\nPass 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", "example": { "url": "https://docs.browserless.io/" } }, "example": { "addScriptTag": [ { "url": "string", "content": "string", "type": "string", "id": "string" } ], "addStyleTag": [ { "url": "string", "content": "string" } ], "authenticate": { "username": "string", "password": "string" }, "bestAttempt": true, "cookies": [ { "name": "string", "value": "string", "url": "string", "domain": "string", "path": "string", "secure": true, "httpOnly": true, "sameSite": "Default", "expires": 0, "priority": "High", "sourceScheme": "NonSecure", "partitionKey": { "sourceOrigin": "string", "hasCrossSiteAncestor": true } } ], "emulateMediaType": "string", "gotoOptions": { "referer": "string", "referrerPolicy": "string", "timeout": 0, "waitUntil": [ "domcontentloaded" ], "signal": { "aborted": true, "onabort": {}, "reason": {} } }, "html": "string", "options": { "optimizeForSpeed": true, "type": "jpeg", "quality": 0, "fromSurface": true, "fullPage": true, "omitBackground": true, "clip": { "scale": 0, "width": 0, "height": 0, "x": 0, "y": 0 }, "encoding": "base64", "captureBeyondViewport": true }, "rejectRequestPattern": [ "string" ], "rejectResourceTypes": [ "cspviolationreport" ], "requestInterceptors": [ { "pattern": "string", "response": { "headers": {}, "status": 0, "contentType": "string", "body": "string" } } ], "scrollPage": true, "selector": "string", "setExtraHTTPHeaders": {}, "setJavaScriptEnabled": true, "url": "string", "userAgent": { "userAgent": "string", "userAgentMetadata": { "brands": [ { "brand": "string", "version": "string" } ], "fullVersionList": [ { "brand": "string", "version": "string" } ], "fullVersion": "string", "platform": "string", "platformVersion": "string", "architecture": "string", "model": "string", "mobile": true, "bitness": "string", "wow64": true, "formFactors": [ "string" ] }, "platform": "string" }, "viewport": { "width": 0, "height": 0, "deviceScaleFactor": 0, "isMobile": true, "isLandscape": true, "hasTouch": true }, "waitForEvent": { "event": "string", "timeout": 0 }, "waitForFunction": { "fn": "string", "polling": "string", "timeout": 0 }, "waitForSelector": { "hidden": true, "selector": "string", "timeout": 0, "visible": true }, "waitForTimeout": 0 } } } }, "responses": { "200": { "content": { "image/png": { "schema": { "type": "string", "format": "binary" } }, "image/jpeg": { "schema": { "type": "string", "format": "binary" } }, "text/plain": { "schema": { "type": "string", "format": "byte" } } }, "description": "Response can either be a text/plain base64 encoded body\nor 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" }, "403": { "code": 403, "description": "The request targets a destination that is not allowed.", "message": "HTTP/1.1 403 Forbidden" }, "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": [ "Chrome (licensed build)" ] } }, "/chrome/pdf": { "post": { "description": "Returns a PDF binary from a `url` or `html` payload (Chrome, legacy).\n\"url\" or \"html\" payload in your request. Many options exist for\ninjecting cookies, request interceptors, user-agents and waiting for\nselectors, timers and more.", "parameters": [ { "in": "query", "name": "blockAds", "schema": { "description": "Whether or not to load ad-blocking extensions for the session.\nThis currently uses uBlock-Lite and may cause certain sites\nto not load properly.", "type": "boolean" } }, { "in": "query", "name": "launch", "schema": { "description": "Launch options, which can be either an object\nof puppeteer.launch options or playwright.launchServer\noptions, depending on the API. Must be either JSON\nobject, or a base64-encoded JSON object.", "anyOf": [ { "$ref": "#/components/schemas/CDPLaunchOptions" }, { "type": "string" } ] } }, { "in": "query", "name": "profile", "schema": { "description": "Name of an authenticated profile to hydrate into the browser at launch.\nThe profile's cookies, localStorage and IndexedDB are injected via CDP\nbefore 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.\nAccepts 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" } }, { "in": "query", "name": "allowedDomains", "schema": { "description": "Optional per-connection narrowing of the integration's allowed-domain list.\nExtracted from the JSON `allowedDomains` query parameter. Can only narrow the\nintegration's domains, never widen them.", "type": "array", "items": { "type": "string" } } }, { "in": "query", "name": "credentials", "schema": { "$ref": "#/components/schemas/StringRecord", "description": "Optional alias → `op://…` reference map for the integration above. Extracted\nfrom the JSON `credentials` query parameter. References are not secret;\nresolved values are never stored here. Optional — a connection can also pass\nraw `op://…` references straight to Browserless.loadSecret." } }, { "in": "query", "name": "externalProxyServer", "schema": { "description": "External proxy server URL for user-provided proxies.\nFormat: http(s)://[username:password@]host:port\nWhen set, routes requests through this proxy instead of built-in residential proxies.", "type": "string" } }, { "in": "query", "name": "integrationId", "schema": { "description": "Optional 1Password integration id for credential filling on a non-persistent\nconnection. Extracted from the `integrationId` query parameter; the persistent\nsession path carries the same data on session metadata instead.", "type": "string" } }, { "in": "query", "name": "proxy", "schema": { "$ref": "#/components/schemas/ProxyType", "description": "The type of proxy to use: 'residential' or 'datacenter'." } }, { "in": "query", "name": "proxyCity", "schema": { "description": "The city to use for the proxy.\n\nAvailable cities: https://production-sfo.browserless.io/proxy/cities?token=YOUR_TOKEN\nDocumentation: 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.\n\nSupported codes: US, GB, FR, DE, etc.\nFull 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.\nRecommended when using proxyCountry to ensure websites render content,\ncurrency, 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.\nMaps to specific proxy vendors internally for optimal access to certain websites.\nFormat: \"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" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "addScriptTag": { "type": "array", "items": { "$ref": "#/components/schemas/FrameAddScriptTagOptions" } }, "addStyleTag": { "type": "array", "items": { "$ref": "#/components/schemas/FrameAddStyleTagOptions" } }, "authenticate": { "anyOf": [ { "$ref": "#/components/schemas/Credentials" }, { "type": "null" } ], "description": "Credentials for HTTP authentication. Contains `username` and `password` properties." }, "bestAttempt": { "description": "When bestAttempt is set to true, browserless attempt to proceed\nwhen \"awaited\" events fail or timeout. This includes things like\ngoto, waitForSelector, and more.", "type": "boolean" }, "cookies": { "type": "array", "items": { "$ref": "#/components/schemas/CookieParam" } }, "emulateMediaType": { "type": "string" }, "gotoOptions": { "$ref": "#/components/schemas/GoToOptions", "description": "Options to configure the page navigation, such as `timeout` and `waitUntil`." }, "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\nclasses used to inject values into them:\n\n- `date` formatted print date\n\n- `title` document title\n\n- `url` document location\n\n- `pageNumber` current page number\n\n- `totalPages` total pages in the document", "type": "string" }, "footerTemplate": { "description": "HTML template for the print footer. Has the same constraints and support\nfor 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\ndeclared in the `width` or `height` or `format` option.", "type": "boolean" }, "margin": { "description": "Set the PDF margins.", "$ref": "#/components/schemas/PDFMargin" }, "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.\n\nThe 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\nactivating the page using {@link Page.bringToFront} if the page is in the\nbackground.", "type": "boolean" }, "fullPage": { "type": "boolean" } }, "description": "PDF generation options based on Puppeteer's PDFOptions interface.\nIncludes properties like `format`, `landscape`, `margin`, `scale`, etc." }, "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\ncorresponding 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\ncorresponding responses to use in order to fulfill those requests.", "type": "string" }, "response": { "additionalProperties": false, "type": "object", "properties": { "headers": { "description": "Optional response headers.\n\nThe record values will be converted to string following:\nArrays' values will be mapped to String\n(Used when you need multiple headers with the same name).\nNon-arrays will be converted to String.", "$ref": "#/components/schemas/AnyRecord" }, "status": { "type": "number" }, "contentType": { "type": "string" }, "body": { "description": "A string representation of the body to return. Can be a base64-encoded\nstring 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\nMissing optional values will be filled in by the target with what it would normally use.", "$ref": "#/components/schemas/Protocol.Emulation.UserAgentMetadata" }, "platform": { "type": "string" } }, "additionalProperties": false }, "viewport": { "anyOf": [ { "$ref": "#/components/schemas/Viewport" }, { "type": "null" } ], "description": "The viewport dimensions and settings for the page.\nIncludes properties like `width`, `height`, `deviceScaleFactor`, etc." }, "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.\nIf polling is a number, then it is treated as an interval in milliseconds\nat which the function would be executed. If polling is a string,\nthen 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).\nPass 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", "example": { "url": "https://docs.browserless.io/" } }, "example": { "addScriptTag": [ { "url": "string", "content": "string", "type": "string", "id": "string" } ], "addStyleTag": [ { "url": "string", "content": "string" } ], "authenticate": { "username": "string", "password": "string" }, "bestAttempt": true, "cookies": [ { "name": "string", "value": "string", "url": "string", "domain": "string", "path": "string", "secure": true, "httpOnly": true, "sameSite": "Default", "expires": 0, "priority": "High", "sourceScheme": "NonSecure", "partitionKey": { "sourceOrigin": "string", "hasCrossSiteAncestor": true } } ], "emulateMediaType": "string", "gotoOptions": { "referer": "string", "referrerPolicy": "string", "timeout": 0, "waitUntil": [ "domcontentloaded" ], "signal": { "aborted": true, "onabort": {}, "reason": {} } }, "html": "string", "options": { "scale": 0, "displayHeaderFooter": true, "headerTemplate": "string", "footerTemplate": "string", "printBackground": true, "landscape": true, "pageRanges": "string", "format": "A0", "width": "string", "height": "string", "preferCSSPageSize": true, "margin": { "top": "string", "bottom": "string", "left": "string", "right": "string" }, "omitBackground": true, "tagged": true, "outline": true, "timeout": 0, "waitForFonts": true, "fullPage": true }, "rejectRequestPattern": [ "string" ], "rejectResourceTypes": [ "cspviolationreport" ], "requestInterceptors": [ { "pattern": "string", "response": { "headers": {}, "status": 0, "contentType": "string", "body": "string" } } ], "setExtraHTTPHeaders": {}, "setJavaScriptEnabled": true, "url": "string", "userAgent": { "userAgent": "string", "userAgentMetadata": { "brands": [ { "brand": "string", "version": "string" } ], "fullVersionList": [ { "brand": "string", "version": "string" } ], "fullVersion": "string", "platform": "string", "platformVersion": "string", "architecture": "string", "model": "string", "mobile": true, "bitness": "string", "wow64": true, "formFactors": [ "string" ] }, "platform": "string" }, "viewport": { "width": 0, "height": 0, "deviceScaleFactor": 0, "isMobile": true, "isLandscape": true, "hasTouch": true }, "waitForEvent": { "event": "string", "timeout": 0 }, "waitForFunction": { "fn": "string", "polling": "string", "timeout": 0 }, "waitForSelector": { "hidden": true, "selector": "string", "timeout": 0, "visible": true }, "waitForTimeout": 0 } } } }, "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" }, "403": { "code": 403, "description": "The request targets a destination that is not allowed.", "message": "HTTP/1.1 403 Forbidden" }, "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": [ "Chrome (licensed build)" ] } }, "/chrome/content": { "post": { "description": "Given a `url` or `html` field, loads the page in Chrome and returns the fully rendered HTML.", "parameters": [ { "in": "query", "name": "blockAds", "schema": { "description": "Whether or not to load ad-blocking extensions for the session.\nThis currently uses uBlock-Lite and may cause certain sites\nto not load properly.", "type": "boolean" } }, { "in": "query", "name": "launch", "schema": { "anyOf": [ { "$ref": "#/components/schemas/CDPLaunchOptions" }, { "type": "string" } ] } }, { "in": "query", "name": "profile", "schema": { "description": "Name of an authenticated profile to hydrate into the browser at launch.\nThe profile's cookies, localStorage and IndexedDB are injected via CDP\nbefore 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.\nAccepts 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" } }, { "in": "query", "name": "allowedDomains", "schema": { "description": "Optional per-connection narrowing of the integration's allowed-domain list.\nExtracted from the JSON `allowedDomains` query parameter. Can only narrow the\nintegration's domains, never widen them.", "type": "array", "items": { "type": "string" } } }, { "in": "query", "name": "credentials", "schema": { "$ref": "#/components/schemas/StringRecord", "description": "Optional alias → `op://…` reference map for the integration above. Extracted\nfrom the JSON `credentials` query parameter. References are not secret;\nresolved values are never stored here. Optional — a connection can also pass\nraw `op://…` references straight to Browserless.loadSecret." } }, { "in": "query", "name": "externalProxyServer", "schema": { "description": "External proxy server URL for user-provided proxies.\nFormat: http(s)://[username:password@]host:port\nWhen set, routes requests through this proxy instead of built-in residential proxies.", "type": "string" } }, { "in": "query", "name": "integrationId", "schema": { "description": "Optional 1Password integration id for credential filling on a non-persistent\nconnection. Extracted from the `integrationId` query parameter; the persistent\nsession path carries the same data on session metadata instead.", "type": "string" } }, { "in": "query", "name": "proxy", "schema": { "$ref": "#/components/schemas/ProxyType", "description": "The type of proxy to use: 'residential' or 'datacenter'." } }, { "in": "query", "name": "proxyCity", "schema": { "description": "The city to use for the proxy.\n\nAvailable cities: https://production-sfo.browserless.io/proxy/cities?token=YOUR_TOKEN\nDocumentation: 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.\n\nSupported codes: US, GB, FR, DE, etc.\nFull 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.\nRecommended when using proxyCountry to ensure websites render content,\ncurrency, 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.\nMaps to specific proxy vendors internally for optimal access to certain websites.\nFormat: \"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" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "addScriptTag": { "type": "array", "items": { "$ref": "#/components/schemas/FrameAddScriptTagOptions" } }, "addStyleTag": { "type": "array", "items": { "$ref": "#/components/schemas/FrameAddStyleTagOptions" } }, "authenticate": { "anyOf": [ { "$ref": "#/components/schemas/Credentials" }, { "type": "null" } ], "description": "Credentials for HTTP authentication. Contains `username` and `password` properties." }, "bestAttempt": { "description": "When bestAttempt is set to true, browserless attempt to proceed\nwhen \"awaited\" events fail or timeout. This includes things like\ngoto, waitForSelector, and more.", "type": "boolean" }, "cookies": { "type": "array", "items": { "$ref": "#/components/schemas/CookieParam" } }, "emulateMediaType": { "type": "string" }, "gotoOptions": { "$ref": "#/components/schemas/GoToOptions", "description": "Options to configure the page navigation, such as `timeout` and `waitUntil`." }, "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\ncorresponding 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\ncorresponding responses to use in order to fulfill those requests.", "type": "string" }, "response": { "additionalProperties": false, "type": "object", "properties": { "headers": { "description": "Optional response headers.\n\nThe record values will be converted to string following:\nArrays' values will be mapped to String\n(Used when you need multiple headers with the same name).\nNon-arrays will be converted to String.", "$ref": "#/components/schemas/AnyRecord" }, "status": { "type": "number" }, "contentType": { "type": "string" }, "body": { "description": "A string representation of the body to return. Can be a base64-encoded\nstring 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\nMissing optional values will be filled in by the target with what it would normally use.", "$ref": "#/components/schemas/Protocol.Emulation.UserAgentMetadata" }, "platform": { "type": "string" } }, "additionalProperties": false }, "viewport": { "anyOf": [ { "$ref": "#/components/schemas/Viewport" }, { "type": "null" } ], "description": "The viewport dimensions and settings for the page.\nIncludes properties like `width`, `height`, `deviceScaleFactor`, etc." }, "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.\nIf polling is a number, then it is treated as an interval in milliseconds\nat which the function would be executed. If polling is a string,\nthen 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).\nPass 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", "example": { "url": "https://docs.browserless.io/" } }, "example": { "addScriptTag": [ { "url": "string", "content": "string", "type": "string", "id": "string" } ], "addStyleTag": [ { "url": "string", "content": "string" } ], "authenticate": { "username": "string", "password": "string" }, "bestAttempt": true, "cookies": [ { "name": "string", "value": "string", "url": "string", "domain": "string", "path": "string", "secure": true, "httpOnly": true, "sameSite": "Default", "expires": 0, "priority": "High", "sourceScheme": "NonSecure", "partitionKey": { "sourceOrigin": "string", "hasCrossSiteAncestor": true } } ], "emulateMediaType": "string", "gotoOptions": { "referer": "string", "referrerPolicy": "string", "timeout": 0, "waitUntil": [ "domcontentloaded" ], "signal": { "aborted": true, "onabort": {}, "reason": {} } }, "html": "string", "rejectRequestPattern": [ "string" ], "rejectResourceTypes": [ "cspviolationreport" ], "requestInterceptors": [ { "pattern": "string", "response": { "headers": {}, "status": 0, "contentType": "string", "body": "string" } } ], "setExtraHTTPHeaders": {}, "setJavaScriptEnabled": true, "url": "string", "userAgent": { "userAgent": "string", "userAgentMetadata": { "brands": [ { "brand": "string", "version": "string" } ], "fullVersionList": [ { "brand": "string", "version": "string" } ], "fullVersion": "string", "platform": "string", "platformVersion": "string", "architecture": "string", "model": "string", "mobile": true, "bitness": "string", "wow64": true, "formFactors": [ "string" ] }, "platform": "string" }, "viewport": { "width": 0, "height": 0, "deviceScaleFactor": 0, "isMobile": true, "isLandscape": true, "hasTouch": true }, "waitForEvent": { "event": "string", "timeout": 0 }, "waitForFunction": { "fn": "string", "polling": "string", "timeout": 0 }, "waitForSelector": { "hidden": true, "selector": "string", "timeout": 0, "visible": true }, "waitForTimeout": 0 } } } }, "responses": { "200": { "content": { "text/html": { "schema": { "description": "An HTML payload of the website or HTML after JavaScript\nparsing and execution.", "type": "string", "$schema": "http://json-schema.org/draft-07/schema#" } } }, "description": "An HTML payload of the website or HTML after JavaScript\nparsing 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" }, "403": { "code": 403, "description": "The request targets a destination that is not allowed.", "message": "HTTP/1.1 403 Forbidden" }, "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": [ "Chrome (licensed build)" ] } }, "/chrome/scrape": { "post": { "description": "Returns text, HTML, and metadata from a given list of CSS selectors against the rendered DOM (Chrome, legacy).\nDebugging information is available by sending in the appropriate flags in the \"debugOpts\"\nproperty. Responds with an array of JSON objects.", "parameters": [ { "in": "query", "name": "blockAds", "schema": { "description": "Whether or not to load ad-blocking extensions for the session.\nThis currently uses uBlock-Lite and may cause certain sites\nto not load properly.", "type": "boolean" } }, { "in": "query", "name": "launch", "schema": { "anyOf": [ { "$ref": "#/components/schemas/CDPLaunchOptions" }, { "type": "string" } ] } }, { "in": "query", "name": "profile", "schema": { "description": "Name of an authenticated profile to hydrate into the browser at launch.\nThe profile's cookies, localStorage and IndexedDB are injected via CDP\nbefore 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.\nAccepts 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" } }, { "in": "query", "name": "allowedDomains", "schema": { "description": "Optional per-connection narrowing of the integration's allowed-domain list.\nExtracted from the JSON `allowedDomains` query parameter. Can only narrow the\nintegration's domains, never widen them.", "type": "array", "items": { "type": "string" } } }, { "in": "query", "name": "credentials", "schema": { "$ref": "#/components/schemas/StringRecord", "description": "Optional alias → `op://…` reference map for the integration above. Extracted\nfrom the JSON `credentials` query parameter. References are not secret;\nresolved values are never stored here. Optional — a connection can also pass\nraw `op://…` references straight to Browserless.loadSecret." } }, { "in": "query", "name": "externalProxyServer", "schema": { "description": "External proxy server URL for user-provided proxies.\nFormat: http(s)://[username:password@]host:port\nWhen set, routes requests through this proxy instead of built-in residential proxies.", "type": "string" } }, { "in": "query", "name": "integrationId", "schema": { "description": "Optional 1Password integration id for credential filling on a non-persistent\nconnection. Extracted from the `integrationId` query parameter; the persistent\nsession path carries the same data on session metadata instead.", "type": "string" } }, { "in": "query", "name": "proxy", "schema": { "$ref": "#/components/schemas/ProxyType", "description": "The type of proxy to use: 'residential' or 'datacenter'." } }, { "in": "query", "name": "proxyCity", "schema": { "description": "The city to use for the proxy.\n\nAvailable cities: https://production-sfo.browserless.io/proxy/cities?token=YOUR_TOKEN\nDocumentation: 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.\n\nSupported codes: US, GB, FR, DE, etc.\nFull 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.\nRecommended when using proxyCountry to ensure websites render content,\ncurrency, 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.\nMaps to specific proxy vendors internally for optimal access to certain websites.\nFormat: \"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" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "addScriptTag": { "type": "array", "items": { "$ref": "#/components/schemas/FrameAddScriptTagOptions" } }, "addStyleTag": { "type": "array", "items": { "$ref": "#/components/schemas/FrameAddStyleTagOptions" } }, "authenticate": { "anyOf": [ { "$ref": "#/components/schemas/Credentials" }, { "type": "null" } ], "description": "Credentials for HTTP authentication. Contains `username` and `password` properties." }, "bestAttempt": { "description": "When bestAttempt is set to true, browserless attempt to proceed\nwhen \"awaited\" events fail or timeout. This includes things like\ngoto, waitForSelector, and more.", "type": "boolean" }, "cookies": { "type": "array", "items": { "$ref": "#/components/schemas/CookieParam" } }, "debugOpts": { "$ref": "#/components/schemas/ScrapeDebugOptions" }, "elements": { "type": "array", "items": { "$ref": "#/components/schemas/ScrapeElementSelector" } }, "emulateMediaType": { "type": "string" }, "gotoOptions": { "$ref": "#/components/schemas/GoToOptions", "description": "Options to configure the page navigation, such as `timeout` and `waitUntil`." }, "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\ncorresponding 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\ncorresponding responses to use in order to fulfill those requests.", "type": "string" }, "response": { "additionalProperties": false, "type": "object", "properties": { "headers": { "description": "Optional response headers.\n\nThe record values will be converted to string following:\nArrays' values will be mapped to String\n(Used when you need multiple headers with the same name).\nNon-arrays will be converted to String.", "$ref": "#/components/schemas/AnyRecord" }, "status": { "type": "number" }, "contentType": { "type": "string" }, "body": { "description": "A string representation of the body to return. Can be a base64-encoded\nstring 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\nMissing optional values will be filled in by the target with what it would normally use.", "$ref": "#/components/schemas/Protocol.Emulation.UserAgentMetadata" }, "platform": { "type": "string" } }, "additionalProperties": false }, "viewport": { "anyOf": [ { "$ref": "#/components/schemas/Viewport" }, { "type": "null" } ], "description": "The viewport dimensions and settings for the page.\nIncludes properties like `width`, `height`, `deviceScaleFactor`, etc." }, "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.\nIf polling is a number, then it is treated as an interval in milliseconds\nat which the function would be executed. If polling is a string,\nthen 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).\nPass 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" ], "example": { "url": "https://docs.browserless.io/", "elements": [ { "selector": "h1" } ] } }, "example": { "addScriptTag": [ { "url": "string", "content": "string", "type": "string", "id": "string" } ], "addStyleTag": [ { "url": "string", "content": "string" } ], "authenticate": { "username": "string", "password": "string" }, "bestAttempt": true, "cookies": [ { "name": "string", "value": "string", "url": "string", "domain": "string", "path": "string", "secure": true, "httpOnly": true, "sameSite": "Default", "expires": 0, "priority": "High", "sourceScheme": "NonSecure", "partitionKey": { "sourceOrigin": "string", "hasCrossSiteAncestor": true } } ], "debugOpts": { "console": true, "cookies": true, "html": true, "network": true, "screenshot": true }, "elements": [ { "selector": "string", "timeout": 0 } ], "emulateMediaType": "string", "gotoOptions": { "referer": "string", "referrerPolicy": "string", "timeout": 0, "waitUntil": [ "domcontentloaded" ], "signal": { "aborted": true, "onabort": {}, "reason": {} } }, "html": "string", "rejectRequestPattern": [ "string" ], "rejectResourceTypes": [ "cspviolationreport" ], "requestInterceptors": [ { "pattern": "string", "response": { "headers": {}, "status": 0, "contentType": "string", "body": "string" } } ], "setExtraHTTPHeaders": {}, "setJavaScriptEnabled": true, "url": "string", "userAgent": { "userAgent": "string", "userAgentMetadata": { "brands": [ { "brand": "string", "version": "string" } ], "fullVersionList": [ { "brand": "string", "version": "string" } ], "fullVersion": "string", "platform": "string", "platformVersion": "string", "architecture": "string", "model": "string", "mobile": true, "bitness": "string", "wow64": true, "formFactors": [ "string" ] }, "platform": "string" }, "viewport": { "width": 0, "height": 0, "deviceScaleFactor": 0, "isMobile": true, "isLandscape": true, "hasTouch": true }, "waitForEvent": { "event": "string", "timeout": 0 }, "waitForFunction": { "fn": "string", "polling": "string", "timeout": 0 }, "waitForSelector": { "hidden": true, "selector": "string", "timeout": 0, "visible": true }, "waitForTimeout": 0 } } } }, "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": "#/components/schemas/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": "#/components/schemas/InBoundRequest" } }, "outbound": { "type": "array", "items": { "$ref": "#/components/schemas/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\nsession 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" }, "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\npartitioned cookie is available in. In Firefox, it matches the\nsource origin in the\n{@link https://w3c.github.io/webdriver-bidi/#type-storage-PartitionKey PartitionKey}.", "anyOf": [ { "$ref": "#/components/schemas/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\nto the endpoint that set the cookie.\n\nIn 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\nthe topLevelSite.\n\nSupported 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" }, "403": { "code": 403, "description": "The request targets a destination that is not allowed.", "message": "HTTP/1.1 403 Forbidden" }, "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": [ "Chrome (licensed build)" ] } }, "/chrome/performance": { "post": { "description": "Run lighthouse performance audits with a supplied \"url\" in your JSON payload.", "parameters": [ { "in": "query", "name": "blockAds", "schema": { "description": "Whether or not to load ad-blocking extensions for the session.\nThis currently uses uBlock-Lite and may cause certain sites\nto not load properly.", "type": "boolean" } }, { "in": "query", "name": "launch", "schema": { "description": "Launch options, which can be either an object\nof puppeteer.launch options or playwright.launchServer\noptions, depending on the API. Must be either JSON\nobject, or a base64-encoded JSON object.", "anyOf": [ { "$ref": "#/components/schemas/CDPLaunchOptions" }, { "type": "string" } ] } }, { "in": "query", "name": "profile", "schema": { "description": "Name of an authenticated profile to hydrate into the browser at launch.\nThe profile's cookies, localStorage and IndexedDB are injected via CDP\nbefore 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.\nAccepts 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" } }, { "in": "query", "name": "allowedDomains", "schema": { "description": "Optional per-connection narrowing of the integration's allowed-domain list.\nExtracted from the JSON `allowedDomains` query parameter. Can only narrow the\nintegration's domains, never widen them.", "type": "array", "items": { "type": "string" } } }, { "in": "query", "name": "credentials", "schema": { "$ref": "#/components/schemas/StringRecord", "description": "Optional alias → `op://…` reference map for the integration above. Extracted\nfrom the JSON `credentials` query parameter. References are not secret;\nresolved values are never stored here. Optional — a connection can also pass\nraw `op://…` references straight to Browserless.loadSecret." } }, { "in": "query", "name": "externalProxyServer", "schema": { "description": "External proxy server URL for user-provided proxies.\nFormat: http(s)://[username:password@]host:port\nWhen set, routes requests through this proxy instead of built-in residential proxies.", "type": "string" } }, { "in": "query", "name": "integrationId", "schema": { "description": "Optional 1Password integration id for credential filling on a non-persistent\nconnection. Extracted from the `integrationId` query parameter; the persistent\nsession path carries the same data on session metadata instead.", "type": "string" } }, { "in": "query", "name": "proxy", "schema": { "$ref": "#/components/schemas/ProxyType", "description": "The type of proxy to use: 'residential' or 'datacenter'." } }, { "in": "query", "name": "proxyCity", "schema": { "description": "The city to use for the proxy.\n\nAvailable cities: https://production-sfo.browserless.io/proxy/cities?token=YOUR_TOKEN\nDocumentation: 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.\n\nSupported codes: US, GB, FR, DE, etc.\nFull 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.\nRecommended when using proxyCountry to ensure websites render content,\ncurrency, 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.\nMaps to specific proxy vendors internally for optimal access to certain websites.\nFormat: \"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" } } ], "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" ], "example": { "url": "https://docs.browserless.io/" } }, "example": { "budgets": [ {} ], "config": {}, "url": "string" } } } }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "The response of the lighthouse stats. Response objects are\ndetermined by the type of budgets and config in the POST\nJSON body", "type": "object", "properties": {}, "additionalProperties": true, "$schema": "http://json-schema.org/draft-07/schema#" } } }, "description": "The response of the lighthouse stats. Response objects are\ndetermined by the type of budgets and config in the POST\nJSON 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" }, "403": { "code": 403, "description": "The request targets a destination that is not allowed.", "message": "HTTP/1.1 403 Forbidden" }, "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": [ "Chrome (licensed build)" ] } }, "/chrome/function": { "post": { "description": "Executes a Puppeteer or Playwright script in the Chrome browser context and returns the result.\nBrowserless sets up a blank page, injects your puppeteer code, and runs it.\nYou can optionally load external libraries via the \"import\" module that are meant for browser usage.\nValues returned from the function are checked and an appropriate content-type and response is sent back\nto your HTTP call.", "parameters": [ { "in": "query", "name": "blockAds", "schema": { "description": "Whether or not to load ad-blocking extensions for the session.\nThis currently uses uBlock-Lite and may cause certain sites\nto not load properly.", "type": "boolean" } }, { "in": "query", "name": "launch", "schema": { "description": "Launch options, which can be either an object\nof puppeteer.launch options or playwright.launchServer\noptions, depending on the API. Must be either JSON\nobject, or a base64-encoded JSON object.", "anyOf": [ { "$ref": "#/components/schemas/CDPLaunchOptions" }, { "type": "string" } ] } }, { "in": "query", "name": "profile", "schema": { "description": "Name of an authenticated profile to hydrate into the browser at launch.\nThe profile's cookies, localStorage and IndexedDB are injected via CDP\nbefore 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.\nAccepts 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" } }, { "in": "query", "name": "allowedDomains", "schema": { "description": "Optional per-connection narrowing of the integration's allowed-domain list.\nExtracted from the JSON `allowedDomains` query parameter. Can only narrow the\nintegration's domains, never widen them.", "type": "array", "items": { "type": "string" } } }, { "in": "query", "name": "credentials", "schema": { "$ref": "#/components/schemas/StringRecord", "description": "Optional alias → `op://…` reference map for the integration above. Extracted\nfrom the JSON `credentials` query parameter. References are not secret;\nresolved values are never stored here. Optional — a connection can also pass\nraw `op://…` references straight to Browserless.loadSecret." } }, { "in": "query", "name": "externalProxyServer", "schema": { "description": "External proxy server URL for user-provided proxies.\nFormat: http(s)://[username:password@]host:port\nWhen set, routes requests through this proxy instead of built-in residential proxies.", "type": "string" } }, { "in": "query", "name": "integrationId", "schema": { "description": "Optional 1Password integration id for credential filling on a non-persistent\nconnection. Extracted from the `integrationId` query parameter; the persistent\nsession path carries the same data on session metadata instead.", "type": "string" } }, { "in": "query", "name": "proxy", "schema": { "$ref": "#/components/schemas/ProxyType", "description": "The type of proxy to use: 'residential' or 'datacenter'." } }, { "in": "query", "name": "proxyCity", "schema": { "description": "The city to use for the proxy.\n\nAvailable cities: https://production-sfo.browserless.io/proxy/cities?token=YOUR_TOKEN\nDocumentation: 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.\n\nSupported codes: US, GB, FR, DE, etc.\nFull 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.\nRecommended when using proxyCountry to ensure websites render content,\ncurrency, 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.\nMaps to specific proxy vendors internally for optimal access to certain websites.\nFormat: \"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" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JSONSchema" } }, "application/javascript": { "schema": { "type": "string" } } } }, "responses": { "200": { "content": { "*/*": { "schema": { "description": "Responses are determined by the returned value of the function\nitself. Binary responses (PDF's, screenshots) are returned back\nas binary data, and primitive JavaScript values are returned back\nby 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\nitself. Binary responses (PDF's, screenshots) are returned back\nas binary data, and primitive JavaScript values are returned back\nby 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" }, "403": { "code": 403, "description": "The request targets a destination that is not allowed.", "message": "HTTP/1.1 403 Forbidden" }, "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": [ "Chrome (licensed build)" ] } }, "/chrome/download": { "post": { "description": "Runs a Puppeteer or Playwright script in Chrome and returns any files the browser downloaded during execution.\nthe execution of puppeteer code, which is ran inside context of the browser.\nBrowserless sets up a blank page, a fresh download directory, injects your puppeteer code, and then executes it.\nYou can load external libraries via the \"import\" syntax, and import ESM-style modules\nthat are written for execution inside of the browser. Once your script is finished, any\ndownloaded files from Chromium are returned back with the appropriate content-type header.", "parameters": [ { "in": "query", "name": "blockAds", "schema": { "description": "Whether or not to load ad-blocking extensions for the session.\nThis currently uses uBlock-Lite and may cause certain sites\nto not load properly.", "type": "boolean" } }, { "in": "query", "name": "launch", "schema": { "description": "Launch options, which can be either an object\nof puppeteer.launch options or playwright.launchServer\noptions, depending on the API. Must be either JSON\nobject, or a base64-encoded JSON object.", "anyOf": [ { "$ref": "#/components/schemas/CDPLaunchOptions" }, { "type": "string" } ] } }, { "in": "query", "name": "profile", "schema": { "description": "Name of an authenticated profile to hydrate into the browser at launch.\nThe profile's cookies, localStorage and IndexedDB are injected via CDP\nbefore 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.\nAccepts 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" } }, { "in": "query", "name": "allowedDomains", "schema": { "description": "Optional per-connection narrowing of the integration's allowed-domain list.\nExtracted from the JSON `allowedDomains` query parameter. Can only narrow the\nintegration's domains, never widen them.", "type": "array", "items": { "type": "string" } } }, { "in": "query", "name": "credentials", "schema": { "$ref": "#/components/schemas/StringRecord", "description": "Optional alias → `op://…` reference map for the integration above. Extracted\nfrom the JSON `credentials` query parameter. References are not secret;\nresolved values are never stored here. Optional — a connection can also pass\nraw `op://…` references straight to Browserless.loadSecret." } }, { "in": "query", "name": "externalProxyServer", "schema": { "description": "External proxy server URL for user-provided proxies.\nFormat: http(s)://[username:password@]host:port\nWhen set, routes requests through this proxy instead of built-in residential proxies.", "type": "string" } }, { "in": "query", "name": "integrationId", "schema": { "description": "Optional 1Password integration id for credential filling on a non-persistent\nconnection. Extracted from the `integrationId` query parameter; the persistent\nsession path carries the same data on session metadata instead.", "type": "string" } }, { "in": "query", "name": "proxy", "schema": { "$ref": "#/components/schemas/ProxyType", "description": "The type of proxy to use: 'residential' or 'datacenter'." } }, { "in": "query", "name": "proxyCity", "schema": { "description": "The city to use for the proxy.\n\nAvailable cities: https://production-sfo.browserless.io/proxy/cities?token=YOUR_TOKEN\nDocumentation: 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.\n\nSupported codes: US, GB, FR, DE, etc.\nFull 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.\nRecommended when using proxyCountry to ensure websites render content,\ncurrency, 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.\nMaps to specific proxy vendors internally for optimal access to certain websites.\nFormat: \"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" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JSONSchema" } }, "application/javascript": { "schema": { "type": "string" } } } }, "responses": { "200": { "content": { "*/*": { "schema": { "description": "Responses are determined by the returned value of the downloads\nthemselves, 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\nthemselves, 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" }, "403": { "code": 403, "description": "The request targets a destination that is not allowed.", "message": "HTTP/1.1 403 Forbidden" }, "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": [ "Chrome (licensed build)" ] } }, "/chrome/export": { "post": { "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": "allowedDomains", "schema": { "description": "Optional per-connection narrowing of the integration's allowed-domain list.\nExtracted from the JSON `allowedDomains` query parameter. Can only narrow the\nintegration's domains, never widen them.", "type": "array", "items": { "type": "string" } } }, { "in": "query", "name": "blockAds", "schema": { "description": "Whether or not to load ad-blocking extensions for the session.\nThis currently uses uBlock-Lite and may cause certain sites\nto not load properly.", "type": "boolean" } }, { "in": "query", "name": "credentials", "schema": { "$ref": "#/components/schemas/StringRecord", "description": "Optional alias → `op://…` reference map for the integration above. Extracted\nfrom the JSON `credentials` query parameter. References are not secret;\nresolved values are never stored here. Optional — a connection can also pass\nraw `op://…` references straight to Browserless.loadSecret." } }, { "in": "query", "name": "externalProxyServer", "schema": { "description": "External proxy server URL for user-provided proxies.\nFormat: http(s)://[username:password@]host:port\nWhen set, routes requests through this proxy instead of built-in residential proxies.", "type": "string" } }, { "in": "query", "name": "integrationId", "schema": { "description": "Optional 1Password integration id for credential filling on a non-persistent\nconnection. Extracted from the `integrationId` query parameter; the persistent\nsession path carries the same data on session metadata instead.", "type": "string" } }, { "in": "query", "name": "launch", "schema": { "description": "Launch options for the browser, either as a JSON object or a JSON string.\nIncludes options like `headless`, `args`, `defaultViewport`, etc.", "anyOf": [ { "$ref": "#/components/schemas/CDPLaunchOptions" }, { "type": "string" } ] } }, { "in": "query", "name": "profile", "schema": { "description": "Name of an authenticated profile to hydrate into the browser at launch.\nThe profile's cookies, localStorage and IndexedDB are injected via CDP\nbefore your code runs. No-op in builds without a profile subsystem.", "type": "string" } }, { "in": "query", "name": "proxy", "schema": { "$ref": "#/components/schemas/ProxyType", "description": "The type of proxy to use: 'residential' or 'datacenter'." } }, { "in": "query", "name": "proxyCity", "schema": { "description": "The city to use for the proxy.\n\nAvailable cities: https://production-sfo.browserless.io/proxy/cities?token=YOUR_TOKEN\nDocumentation: 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.\n\nSupported codes: US, GB, FR, DE, etc.\nFull 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.\nRecommended when using proxyCountry to ensure websites render content,\ncurrency, 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.\nMaps to specific proxy vendors internally for optimal access to certain websites.\nFormat: \"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.\nAccepts 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\nwhen \"awaited\" events fail or timeout. This includes things like\ngoto, waitForSelector, and more.", "type": "boolean" }, "url": { "description": "The URL of the site you want to archive.", "type": "string" }, "gotoOptions": { "$ref": "#/components/schemas/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.\nIf polling is a number, then it is treated as an interval in milliseconds\nat which the function would be executed. If polling is a string,\nthen 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).\nPass 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.\nWhen true, the response will be a zip file containing the HTML and all resources.\nWhen false or not provided, the response will be the raw content (default behavior).", "type": "boolean" } }, "type": "object", "required": [ "url" ], "example": { "url": "https://docs.browserless.io/" } }, "example": { "bestAttempt": true, "url": "string", "gotoOptions": { "referer": "string", "referrerPolicy": "string", "timeout": 0, "waitUntil": [ "domcontentloaded" ], "signal": { "aborted": true, "onabort": {}, "reason": {} } }, "waitForEvent": { "event": "string", "timeout": 0 }, "waitForFunction": { "fn": "string", "polling": "string", "timeout": 0 }, "waitForSelector": { "hidden": true, "selector": "string", "timeout": 0, "visible": true }, "waitForTimeout": 0, "headers": {}, "includeResources": true } } } }, "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" }, "403": { "code": 403, "description": "The request targets a destination that is not allowed.", "message": "HTTP/1.1 403 Forbidden" }, "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": [ "Chrome (licensed build)" ] } }, "/chrome/unblock": { "post": { "description": "Unblocks the provided URL from being blocked due to bot detection.\nReturns a payload of Cookies, HTML, a base64 encoded screenshot,\nand a \"browserWSEndpoint\" to allow connecting to the browser when\nspecified in the JSON Payload. Only supports CDP or Puppeteer\nlike libraries when connecting to the \"browserWSEndpoint\".", "parameters": [ { "in": "query", "name": "allowedDomains", "schema": { "description": "Optional per-connection narrowing of the integration's allowed-domain list.\nExtracted from the JSON `allowedDomains` query parameter. Can only narrow the\nintegration's domains, never widen them.", "type": "array", "items": { "type": "string" } } }, { "in": "query", "name": "blockAds", "schema": { "description": "Whether or not to load ad-blocking extensions for the session.\nThis currently uses uBlock-Lite and may cause certain sites\nto not load properly.", "type": "boolean" } }, { "in": "query", "name": "blockAdsInclude", "schema": { "description": "Restrict blockAds to a specific set of uBlock ruleset ids (comma-separated\nlist or JSON array). Only applies when `blockAds` is true. Fewer rulesets\nmeans a faster browser launch under load; omit to load the full default set.", "type": "string" } }, { "in": "query", "name": "credentials", "schema": { "$ref": "#/components/schemas/StringRecord", "description": "Optional alias → `op://…` reference map for the integration above. Extracted\nfrom the JSON `credentials` query parameter. References are not secret;\nresolved values are never stored here. Optional — a connection can also pass\nraw `op://…` references straight to Browserless.loadSecret." } }, { "in": "query", "name": "externalProxyServer", "schema": { "description": "External proxy server URL for user-provided proxies.\nFormat: http(s)://[username:password@]host:port\nWhen set, routes requests through this proxy instead of built-in residential proxies.", "type": "string" } }, { "in": "query", "name": "integrationId", "schema": { "description": "Optional 1Password integration id for credential filling on a non-persistent\nconnection. Extracted from the `integrationId` query parameter; the persistent\nsession path carries the same data on session metadata instead.", "type": "string" } }, { "in": "query", "name": "launch", "schema": { "description": "Launch options for the browser, either as a JSON object or a JSON string.\nIncludes options like `headless`, `args`, `defaultViewport`, etc.", "anyOf": [ { "$ref": "#/components/schemas/CDPLaunchOptions" }, { "type": "string" } ] } }, { "in": "query", "name": "profile", "schema": { "description": "Name of an authenticated profile to hydrate into the browser at launch.\nThe profile's cookies, localStorage and IndexedDB are injected via CDP\nbefore your code runs. No-op in builds without a profile subsystem.", "type": "string" } }, { "in": "query", "name": "proxy", "schema": { "$ref": "#/components/schemas/ProxyType", "description": "The type of proxy to use: 'residential' or 'datacenter'." } }, { "in": "query", "name": "proxyCity", "schema": { "description": "The city to use for the proxy.\n\nAvailable cities: https://production-sfo.browserless.io/proxy/cities?token=YOUR_TOKEN\nDocumentation: 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.\n\nSupported codes: US, GB, FR, DE, etc.\nFull 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.\nRecommended when using proxyCountry to ensure websites render content,\ncurrency, 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.\nMaps to specific proxy vendors internally for optimal access to certain websites.\nFormat: \"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": "When true, records the unblock session for replay (rrweb) and uploads the\ncaptured replay on cleanup, reusing the same recording pipeline as\nBrowserQL. Like every other Browserless route, replay is a\nconnection-level flag supplied via this `?replay=true` query parameter\n(the browser's recording config is resolved from the URL at launch).\nDefaults to false.", "type": "boolean" } }, { "in": "query", "name": "solveCaptchas", "schema": { "description": "When `browserWSEndpoint` is requested, persists captcha-solving on the\nkept-alive session so reconnections automatically solve captchas without\nhaving to re-add `?solveCaptchas=true` to the returned reconnect URL.\nConnection-level flag supplied via this `?solveCaptchas=true` query\nparameter, mirroring `replay`. Defaults to false.", "type": "boolean" } }, { "in": "query", "name": "timeout", "schema": { "description": "Override the system-level timeout for this request.\nAccepts 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\nwhen \"awaited\" events fail or timeout. This includes things like\ngoto, 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\nfuture 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\nbrowserless how long to keep this browser alive for\nre-connection until shutting it down completely.\nMaximum of 30000 for 30 seconds (30,000ms).", "type": "number" }, "gotoOptions": { "$ref": "#/components/schemas/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.\nIf polling is a number, then it is treated as an interval in milliseconds\nat which the function would be executed. If polling is a string,\nthen 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).\nPass 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" ], "example": { "url": "https://docs.browserless.io/" } }, "example": { "bestAttempt": true, "url": "string", "browserWSEndpoint": true, "cookies": true, "content": true, "screenshot": true, "ttl": 0, "gotoOptions": { "referer": "string", "referrerPolicy": "string", "timeout": 0, "waitUntil": [ "domcontentloaded" ], "signal": { "aborted": true, "onabort": {}, "reason": {} } }, "waitForEvent": { "event": "string", "timeout": 0 }, "waitForFunction": { "fn": "string", "polling": "string", "timeout": 0 }, "waitForSelector": { "hidden": true, "selector": "string", "timeout": 0, "visible": true }, "waitForTimeout": 0 } } } }, "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.\nValue is \"null\" when the request body specifies cookies: false.", "type": "array", "items": { "$ref": "#/components/schemas/UnblockCookie" } }, "content": { "description": "The HTML content of the page once it is passed bot detection.\nValue is \"null\" when the request body specifies content: false.", "type": "string" }, "browserWSEndpoint": { "description": "The browserWSEndpoint of the response when the POST body contains a\nbrowserWSEndpoint: true property", "type": "string" }, "ttl": { "description": "The time the browser will remain alive until it is shutdown. Zero\nwhen browserWSEndpoint: false is set in the request payload. The limit\nis 60000 or 60 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": { "UnblockCookie": { "type": "object", "properties": { "name": { "type": "string" }, "value": { "type": "string" }, "domain": { "type": "string" }, "path": { "type": "string" }, "expires": { "type": "number" }, "httpOnly": { "type": "boolean" }, "secure": { "type": "boolean" }, "sameSite": { "type": "string" }, "url": { "type": "string" } }, "additionalProperties": false, "required": [ "domain", "expires", "httpOnly", "name", "path", "sameSite", "secure", "url", "value" ] } }, "$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" }, "403": { "code": 403, "description": "The request targets a destination that is not allowed.", "message": "HTTP/1.1 403 Forbidden" }, "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": [ "Chrome (licensed build)" ] } }, "/chrome": { "get": { "description": "Launch and connect to Chromium with a library like puppeteer or others that work over chrome-devtools-protocol.", "parameters": [ { "in": "query", "name": "allowedDomains", "schema": { "description": "Optional per-connection narrowing of the integration's allowed-domain list.\nExtracted from the JSON `allowedDomains` query parameter. Can only narrow the\nintegration's domains, never widen them.", "type": "array", "items": { "type": "string" } } }, { "in": "query", "name": "blockAds", "schema": { "description": "Whether or not to load ad-blocking extensions for the session.\nThis currently uses uBlock-Lite and may cause certain sites\nto not load properly.", "type": "boolean" } }, { "in": "query", "name": "credentials", "schema": { "$ref": "#/components/schemas/StringRecord", "description": "Optional alias → `op://…` reference map for the integration above. Extracted\nfrom the JSON `credentials` query parameter. References are not secret;\nresolved values are never stored here. Optional — a connection can also pass\nraw `op://…` references straight to Browserless.loadSecret." } }, { "in": "query", "name": "externalProxyServer", "schema": { "description": "External proxy server URL for user-provided proxies.\nFormat: http(s)://[username:password@]host:port\nWhen set, routes requests through this proxy instead of built-in residential proxies.", "type": "string" } }, { "in": "query", "name": "integrationId", "schema": { "description": "Optional 1Password integration id for credential filling on a non-persistent\nconnection. Extracted from the `integrationId` query parameter; the persistent\nsession path carries the same data on session metadata instead.", "type": "string" } }, { "in": "query", "name": "integrations", "schema": { "type": "string" } }, { "in": "query", "name": "launch", "schema": { "description": "Launch options, which can be either an object\nof puppeteer.launch options or playwright.launchServer\noptions, depending on the API. Must be either JSON\nobject, or a base64-encoded JSON object.", "anyOf": [ { "$ref": "#/components/schemas/CDPLaunchOptions" }, { "type": "string" } ] } }, { "in": "query", "name": "profile", "schema": { "description": "Name of an authenticated profile to hydrate into the browser at launch.\nThe profile's cookies, localStorage and IndexedDB are injected via CDP\nbefore your code runs. No-op in builds without a profile subsystem.", "type": "string" } }, { "in": "query", "name": "proxy", "schema": { "$ref": "#/components/schemas/ProxyType", "description": "The type of proxy to use: 'residential' or 'datacenter'." } }, { "in": "query", "name": "proxyCity", "schema": { "description": "The city to use for the proxy.\n\nAvailable cities: https://production-sfo.browserless.io/proxy/cities?token=YOUR_TOKEN\nDocumentation: 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.\n\nSupported codes: US, GB, FR, DE, etc.\nFull 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.\nRecommended when using proxyCountry to ensure websites render content,\ncurrency, 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.\nMaps to specific proxy vendors internally for optimal access to certain websites.\nFormat: \"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": "record", "schema": { "type": "boolean" } }, { "in": "query", "name": "replay", "schema": { "type": "boolean" } }, { "in": "query", "name": "solveCaptchas", "schema": { "type": "boolean" } }, { "in": "query", "name": "timeout", "schema": { "description": "Override the system-level timeout for this request.\nAccepts 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": { "101": { "description": "Indicates successful WebSocket upgrade." }, "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" }, "403": { "code": 403, "description": "The request targets a destination that is not allowed.", "message": "HTTP/1.1 403 Forbidden" }, "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", "tags": [ "Chrome (licensed build)" ] } }, "/chrome/playwright": { "get": { "description": "Connect to Chromium with any playwright style library.", "parameters": [ { "in": "query", "name": "blockAds", "schema": { "description": "Whether or not to load ad-blocking extensions for the session.\nThis currently uses uBlock-Lite and may cause certain sites\nto not load properly.", "type": "boolean" } }, { "in": "query", "name": "launch", "schema": { "description": "Launch options, which can be either an object\nof puppeteer.launch options or playwright.launchServer\noptions, depending on the API. Must be either JSON\nobject, or a base64-encoded JSON object.", "anyOf": [ { "$ref": "#/components/schemas/BrowserServerOptions" }, { "type": "string" } ] } }, { "in": "query", "name": "profile", "schema": { "description": "Name of an authenticated profile to hydrate into the browser at launch.\nThe profile's cookies, localStorage and IndexedDB are injected via CDP\nbefore 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.\nAccepts 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" } }, { "in": "query", "name": "allowedDomains", "schema": { "description": "Optional per-connection narrowing of the integration's allowed-domain list.\nExtracted from the JSON `allowedDomains` query parameter. Can only narrow the\nintegration's domains, never widen them.", "type": "array", "items": { "type": "string" } } }, { "in": "query", "name": "credentials", "schema": { "$ref": "#/components/schemas/StringRecord", "description": "Optional alias → `op://…` reference map for the integration above. Extracted\nfrom the JSON `credentials` query parameter. References are not secret;\nresolved values are never stored here. Optional — a connection can also pass\nraw `op://…` references straight to Browserless.loadSecret." } }, { "in": "query", "name": "externalProxyServer", "schema": { "description": "External proxy server URL for user-provided proxies.\nFormat: http(s)://[username:password@]host:port\nWhen set, routes requests through this proxy instead of built-in residential proxies.", "type": "string" } }, { "in": "query", "name": "integrationId", "schema": { "description": "Optional 1Password integration id for credential filling on a non-persistent\nconnection. Extracted from the `integrationId` query parameter; the persistent\nsession path carries the same data on session metadata instead.", "type": "string" } }, { "in": "query", "name": "proxy", "schema": { "$ref": "#/components/schemas/ProxyType", "description": "The type of proxy to use: 'residential' or 'datacenter'." } }, { "in": "query", "name": "proxyCity", "schema": { "description": "The city to use for the proxy.\n\nAvailable cities: https://production-sfo.browserless.io/proxy/cities?token=YOUR_TOKEN\nDocumentation: 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.\n\nSupported codes: US, GB, FR, DE, etc.\nFull 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.\nRecommended when using proxyCountry to ensure websites render content,\ncurrency, 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.\nMaps to specific proxy vendors internally for optimal access to certain websites.\nFormat: \"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" } } ], "requestBody": { "content": {} }, "responses": { "101": { "description": "Indicates successful WebSocket upgrade." }, "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" }, "403": { "code": 403, "description": "The request targets a destination that is not allowed.", "message": "HTTP/1.1 403 Forbidden" }, "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/playwright", "tags": [ "Chrome (licensed build)" ] } }, "/chrome/stealth": { "get": { "description": "Launch and connect to Stealthy Chrome with a library like puppeteer or others that work over chrome-devtools-protocol for scraping in a more stealth-like fashion.", "parameters": [ { "in": "query", "name": "allowedDomains", "schema": { "description": "Optional per-connection narrowing of the integration's allowed-domain list.\nExtracted from the JSON `allowedDomains` query parameter. Can only narrow the\nintegration's domains, never widen them.", "type": "array", "items": { "type": "string" } } }, { "in": "query", "name": "blockAds", "schema": { "description": "Whether or not to load ad-blocking extensions for the session.\nThis currently uses uBlock-Lite and may cause certain sites\nto not load properly.", "type": "boolean" } }, { "in": "query", "name": "credentials", "schema": { "$ref": "#/components/schemas/StringRecord", "description": "Optional alias → `op://…` reference map for the integration above. Extracted\nfrom the JSON `credentials` query parameter. References are not secret;\nresolved values are never stored here. Optional — a connection can also pass\nraw `op://…` references straight to Browserless.loadSecret." } }, { "in": "query", "name": "emulationOs", "schema": { "$ref": "#/components/schemas/Platform", "description": "Spoof OS for full per-platform stealth: windows | macos | linux." } }, { "in": "query", "name": "externalProxyServer", "schema": { "description": "External proxy server URL for user-provided proxies.\nFormat: http(s)://[username:password@]host:port\nWhen set, routes requests through this proxy instead of built-in residential proxies.", "type": "string" } }, { "in": "query", "name": "integrationId", "schema": { "description": "Optional 1Password integration id for credential filling on a non-persistent\nconnection. Extracted from the `integrationId` query parameter; the persistent\nsession path carries the same data on session metadata instead.", "type": "string" } }, { "in": "query", "name": "integrations", "schema": { "type": "string" } }, { "in": "query", "name": "launch", "schema": { "description": "Launch options, which can be either an object\nof puppeteer.launch options or playwright.launchServer\noptions, depending on the API. Must be either JSON\nobject, or a base64-encoded JSON object.", "anyOf": [ { "$ref": "#/components/schemas/CDPLaunchOptions" }, { "type": "string" } ] } }, { "in": "query", "name": "profile", "schema": { "description": "Name of an authenticated profile to hydrate into the browser at launch.\nThe profile's cookies, localStorage and IndexedDB are injected via CDP\nbefore your code runs. No-op in builds without a profile subsystem.", "type": "string" } }, { "in": "query", "name": "proxy", "schema": { "$ref": "#/components/schemas/ProxyType", "description": "The type of proxy to use: 'residential' or 'datacenter'." } }, { "in": "query", "name": "proxyCity", "schema": { "description": "The city to use for the proxy.\n\nAvailable cities: https://production-sfo.browserless.io/proxy/cities?token=YOUR_TOKEN\nDocumentation: 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.\n\nSupported codes: US, GB, FR, DE, etc.\nFull 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.\nRecommended when using proxyCountry to ensure websites render content,\ncurrency, 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.\nMaps to specific proxy vendors internally for optimal access to certain websites.\nFormat: \"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": "record", "schema": { "type": "boolean" } }, { "in": "query", "name": "replay", "schema": { "type": "boolean" } }, { "in": "query", "name": "solveCaptchas", "schema": { "type": "boolean" } }, { "in": "query", "name": "timeout", "schema": { "description": "Override the system-level timeout for this request.\nAccepts 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": { "101": { "description": "Indicates successful WebSocket upgrade." }, "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" }, "403": { "code": 403, "description": "The request targets a destination that is not allowed.", "message": "HTTP/1.1 403 Forbidden" }, "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/stealth", "tags": [ "Unblock & Stealth" ] } }, "/chromium/stealth": { "get": { "description": "Launch and connect to Stealthy Chromium with a library like puppeteer or others that work over chrome-devtools-protocol for scraping in a more stealth-like fashion.", "parameters": [ { "in": "query", "name": "allowedDomains", "schema": { "description": "Optional per-connection narrowing of the integration's allowed-domain list.\nExtracted from the JSON `allowedDomains` query parameter. Can only narrow the\nintegration's domains, never widen them.", "type": "array", "items": { "type": "string" } } }, { "in": "query", "name": "blockAds", "schema": { "description": "Whether or not to load ad-blocking extensions for the session.\nThis currently uses uBlock-Lite and may cause certain sites\nto not load properly.", "type": "boolean" } }, { "in": "query", "name": "credentials", "schema": { "$ref": "#/components/schemas/StringRecord", "description": "Optional alias → `op://…` reference map for the integration above. Extracted\nfrom the JSON `credentials` query parameter. References are not secret;\nresolved values are never stored here. Optional — a connection can also pass\nraw `op://…` references straight to Browserless.loadSecret." } }, { "in": "query", "name": "emulationOs", "schema": { "$ref": "#/components/schemas/Platform", "description": "Spoof OS for full per-platform stealth: windows | macos | linux." } }, { "in": "query", "name": "externalProxyServer", "schema": { "description": "External proxy server URL for user-provided proxies.\nFormat: http(s)://[username:password@]host:port\nWhen set, routes requests through this proxy instead of built-in residential proxies.", "type": "string" } }, { "in": "query", "name": "integrationId", "schema": { "description": "Optional 1Password integration id for credential filling on a non-persistent\nconnection. Extracted from the `integrationId` query parameter; the persistent\nsession path carries the same data on session metadata instead.", "type": "string" } }, { "in": "query", "name": "integrations", "schema": { "type": "string" } }, { "in": "query", "name": "launch", "schema": { "description": "Launch options, which can be either an object\nof puppeteer.launch options or playwright.launchServer\noptions, depending on the API. Must be either JSON\nobject, or a base64-encoded JSON object.", "anyOf": [ { "$ref": "#/components/schemas/CDPLaunchOptions" }, { "type": "string" } ] } }, { "in": "query", "name": "profile", "schema": { "description": "Name of an authenticated profile to hydrate into the browser at launch.\nThe profile's cookies, localStorage and IndexedDB are injected via CDP\nbefore your code runs. No-op in builds without a profile subsystem.", "type": "string" } }, { "in": "query", "name": "proxy", "schema": { "$ref": "#/components/schemas/ProxyType", "description": "The type of proxy to use: 'residential' or 'datacenter'." } }, { "in": "query", "name": "proxyCity", "schema": { "description": "The city to use for the proxy.\n\nAvailable cities: https://production-sfo.browserless.io/proxy/cities?token=YOUR_TOKEN\nDocumentation: 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.\n\nSupported codes: US, GB, FR, DE, etc.\nFull 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.\nRecommended when using proxyCountry to ensure websites render content,\ncurrency, 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.\nMaps to specific proxy vendors internally for optimal access to certain websites.\nFormat: \"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": "record", "schema": { "type": "boolean" } }, { "in": "query", "name": "replay", "schema": { "type": "boolean" } }, { "in": "query", "name": "solveCaptchas", "schema": { "type": "boolean" } }, { "in": "query", "name": "timeout", "schema": { "description": "Override the system-level timeout for this request.\nAccepts 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": { "101": { "description": "Indicates successful WebSocket upgrade." }, "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" }, "403": { "code": 403, "description": "The request targets a destination that is not allowed.", "message": "HTTP/1.1 403 Forbidden" }, "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/stealth", "tags": [ "Unblock & Stealth" ] } }, "/stealth": { "get": { "description": "Launch and connect to Stealthy Chromium with a library like puppeteer or others that work over chrome-devtools-protocol for scraping in a more stealth-like fashion.", "parameters": [ { "in": "query", "name": "allowedDomains", "schema": { "description": "Optional per-connection narrowing of the integration's allowed-domain list.\nExtracted from the JSON `allowedDomains` query parameter. Can only narrow the\nintegration's domains, never widen them.", "type": "array", "items": { "type": "string" } } }, { "in": "query", "name": "blockAds", "schema": { "description": "Whether or not to load ad-blocking extensions for the session.\nThis currently uses uBlock-Lite and may cause certain sites\nto not load properly.", "type": "boolean" } }, { "in": "query", "name": "credentials", "schema": { "$ref": "#/components/schemas/StringRecord", "description": "Optional alias → `op://…` reference map for the integration above. Extracted\nfrom the JSON `credentials` query parameter. References are not secret;\nresolved values are never stored here. Optional — a connection can also pass\nraw `op://…` references straight to Browserless.loadSecret." } }, { "in": "query", "name": "emulationOs", "schema": { "$ref": "#/components/schemas/Platform", "description": "Spoof OS for full per-platform stealth: windows | macos | linux." } }, { "in": "query", "name": "externalProxyServer", "schema": { "description": "External proxy server URL for user-provided proxies.\nFormat: http(s)://[username:password@]host:port\nWhen set, routes requests through this proxy instead of built-in residential proxies.", "type": "string" } }, { "in": "query", "name": "integrationId", "schema": { "description": "Optional 1Password integration id for credential filling on a non-persistent\nconnection. Extracted from the `integrationId` query parameter; the persistent\nsession path carries the same data on session metadata instead.", "type": "string" } }, { "in": "query", "name": "integrations", "schema": { "type": "string" } }, { "in": "query", "name": "launch", "schema": { "description": "Launch options, which can be either an object\nof puppeteer.launch options or playwright.launchServer\noptions, depending on the API. Must be either JSON\nobject, or a base64-encoded JSON object.", "anyOf": [ { "$ref": "#/components/schemas/CDPLaunchOptions" }, { "type": "string" } ] } }, { "in": "query", "name": "profile", "schema": { "description": "Name of an authenticated profile to hydrate into the browser at launch.\nThe profile's cookies, localStorage and IndexedDB are injected via CDP\nbefore your code runs. No-op in builds without a profile subsystem.", "type": "string" } }, { "in": "query", "name": "proxy", "schema": { "$ref": "#/components/schemas/ProxyType", "description": "The type of proxy to use: 'residential' or 'datacenter'." } }, { "in": "query", "name": "proxyCity", "schema": { "description": "The city to use for the proxy.\n\nAvailable cities: https://production-sfo.browserless.io/proxy/cities?token=YOUR_TOKEN\nDocumentation: 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.\n\nSupported codes: US, GB, FR, DE, etc.\nFull 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.\nRecommended when using proxyCountry to ensure websites render content,\ncurrency, 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.\nMaps to specific proxy vendors internally for optimal access to certain websites.\nFormat: \"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": "record", "schema": { "type": "boolean" } }, { "in": "query", "name": "replay", "schema": { "type": "boolean" } }, { "in": "query", "name": "solveCaptchas", "schema": { "type": "boolean" } }, { "in": "query", "name": "timeout", "schema": { "description": "Override the system-level timeout for this request.\nAccepts 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": { "101": { "description": "Indicates successful WebSocket upgrade." }, "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" }, "403": { "code": 403, "description": "The request targets a destination that is not allowed.", "message": "HTTP/1.1 403 Forbidden" }, "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", "tags": [ "Unblock & Stealth" ] } }, "/chrome/live/*": { "get": { "description": "> This API is only available on paid plans. [Sign-up here](https://www.browserless.io/pricing/).\n\nWebsocket back-end that powers the live session experience.", "parameters": [], "requestBody": { "content": {} }, "responses": { "101": { "description": "Indicates successful WebSocket upgrade." }, "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" }, "403": { "code": 403, "description": "The request targets a destination that is not allowed.", "message": "HTTP/1.1 403 Forbidden" }, "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/live/*", "tags": [ "WebSocket APIs" ] } }, "/chrome/bql?(/*)": { "post": { "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": "acceptInsecureCerts", "schema": { "description": "Whether to ignore TLS certificate errors (e.g. self-signed or untrusted\nauthorities) so the browser navigates to sites with invalid certificates.", "type": "boolean" } }, { "in": "query", "name": "allowedDomains", "schema": { "description": "Optional per-connection narrowing of the integration's allowed-domain list.\nExtracted from the JSON `allowedDomains` query parameter. Can only narrow the\nintegration's domains, never widen them.", "type": "array", "items": { "type": "string" } } }, { "in": "query", "name": "blockAds", "schema": { "description": "Whether or not to load ad-blocking extensions for the session.\nThis currently uses uBlock-Lite and may cause certain sites\nto not load properly.", "type": "boolean" } }, { "in": "query", "name": "blockAdsInclude", "schema": { "description": "Restrict blockAds to a specific set of uBlock ruleset ids (comma-separated\nlist or JSON array). Only applies when `blockAds` is true. Fewer rulesets\nmeans a faster browser launch under load; omit to load the full default set.", "type": "string" } }, { "in": "query", "name": "blockConsentModals", "schema": { "description": "Whether to automatically block cookie consent modals and popups.", "type": "boolean" } }, { "in": "query", "name": "credentials", "schema": { "$ref": "#/components/schemas/StringRecord", "description": "Optional alias → `op://…` reference map for the integration above. Extracted\nfrom the JSON `credentials` query parameter. References are not secret;\nresolved values are never stored here. Optional — a connection can also pass\nraw `op://…` references straight to Browserless.loadSecret." } }, { "in": "query", "name": "emulationOs", "schema": { "$ref": "#/components/schemas/Platform", "description": "Spoof OS for the session: 'windows', 'macos', or 'linux'. When set, the\nsession runs the full per-platform stealth stack (User-Agent, UA Client\nHints, navigator.platform, GPU, fonts, and media/speech/audio fingerprints)\n— the same stack the /stealth routes use. Omit for the native (Linux) host\nidentity." } }, { "in": "query", "name": "externalProxyServer", "schema": { "description": "External proxy server URL for user-provided proxies.\nFormat: http(s)://[username:password@]host:port\nWhen 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.\nWhen true, actions like typing and clicking will have randomized delays.", "type": "boolean" } }, { "in": "query", "name": "integrationId", "schema": { "description": "Optional 1Password integration id for credential filling on a non-persistent\nconnection. Extracted from the `integrationId` query parameter; the persistent\nsession path carries the same data on session metadata instead.", "type": "string" } }, { "in": "query", "name": "launch", "schema": { "description": "Launch options for the browser, either as a JSON object or a JSON string.\nIncludes options like `headless`, `args`, `defaultViewport`, etc.\nMust be either JSON object, or a base64-encoded JSON object.", "anyOf": [ { "$ref": "#/components/schemas/CDPLaunchOptions" }, { "type": "string" } ] } }, { "in": "query", "name": "profile", "schema": { "description": "Name of an authenticated profile to hydrate into the browser at launch.\nThe profile's cookies, localStorage and IndexedDB are injected via CDP\nbefore your code runs. No-op in builds without a profile subsystem.", "type": "string" } }, { "in": "query", "name": "proxy", "schema": { "$ref": "#/components/schemas/ProxyType", "description": "The type of proxy to use: 'residential' or 'datacenter'." } }, { "in": "query", "name": "proxyCity", "schema": { "description": "The city to use for the proxy.\n\nAvailable cities: https://production-sfo.browserless.io/proxy/cities?token=YOUR_TOKEN\nDocumentation: 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.\n\nSupported codes: US, GB, FR, DE, etc.\nFull 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.\nRecommended when using proxyCountry to ensure websites render content,\ncurrency, 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.\nMaps to specific proxy vendors internally for optimal access to certain websites.\nFormat: \"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.\nWhen 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.\nAccepts 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" }, "403": { "code": 403, "description": "The request targets a destination that is not allowed.", "message": "HTTP/1.1 403 Forbidden" }, "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": [ "Chrome (licensed build)" ], "operationId": "chrome-bql-execute" }, "get": { "description": "WebSocket endpoint for BrowserQL. Connect to establish a persistent browser\nsession, then send multiple GraphQL operations as JSON messages. The browser\nand page state persist across all messages for the connection duration.\n\nMessages use the same JSON format as the HTTP POST endpoint:\nSend: { \"query\": \"mutation { goto(url: \\\"..\\\") { status } }\", \"variables\": {} }\nReceive: { \"data\": { \"goto\": { \"status\": 200 } } }", "parameters": [ { "in": "query", "name": "acceptInsecureCerts", "schema": { "description": "Whether to ignore TLS certificate errors (e.g. self-signed or untrusted\nauthorities) so the browser navigates to sites with invalid certificates.", "type": "boolean" } }, { "in": "query", "name": "allowedDomains", "schema": { "description": "Optional per-connection narrowing of the integration's allowed-domain list.\nExtracted from the JSON `allowedDomains` query parameter. Can only narrow the\nintegration's domains, never widen them.", "type": "array", "items": { "type": "string" } } }, { "in": "query", "name": "blockAds", "schema": { "description": "Whether or not to load ad-blocking extensions for the session.\nThis currently uses uBlock-Lite and may cause certain sites\nto not load properly.", "type": "boolean" } }, { "in": "query", "name": "blockAdsInclude", "schema": { "description": "Restrict blockAds to a specific set of uBlock ruleset ids (comma-separated\nlist or JSON array). Only applies when `blockAds` is true. Fewer rulesets\nmeans a faster browser launch under load; omit to load the full default set.", "type": "string" } }, { "in": "query", "name": "blockConsentModals", "schema": { "type": "boolean" } }, { "in": "query", "name": "credentials", "schema": { "$ref": "#/components/schemas/StringRecord", "description": "Optional alias → `op://…` reference map for the integration above. Extracted\nfrom the JSON `credentials` query parameter. References are not secret;\nresolved values are never stored here. Optional — a connection can also pass\nraw `op://…` references straight to Browserless.loadSecret." } }, { "in": "query", "name": "emulationOs", "schema": { "$ref": "#/components/schemas/Platform", "description": "Spoof OS for the session: 'windows', 'macos', or 'linux'. When set, the\nsession runs the full per-platform stealth stack (User-Agent, UA Client\nHints, navigator.platform, GPU, fonts, and media/speech/audio fingerprints)\n— the same stack the /stealth routes use. Omit for the native (Linux) host\nidentity." } }, { "in": "query", "name": "externalProxyServer", "schema": { "description": "External proxy server URL for user-provided proxies.\nFormat: http(s)://[username:password@]host:port\nWhen set, routes requests through this proxy instead of built-in residential proxies.", "type": "string" } }, { "in": "query", "name": "humanlike", "schema": { "type": "boolean" } }, { "in": "query", "name": "integrationId", "schema": { "description": "Optional 1Password integration id for credential filling on a non-persistent\nconnection. Extracted from the `integrationId` query parameter; the persistent\nsession path carries the same data on session metadata instead.", "type": "string" } }, { "in": "query", "name": "launch", "schema": { "description": "Launch options for the browser, either as a JSON object or a JSON string.\nIncludes options like `headless`, `args`, `defaultViewport`, etc.\nMust be either JSON object, or a base64-encoded JSON object.", "anyOf": [ { "$ref": "#/components/schemas/CDPLaunchOptions" }, { "type": "string" } ] } }, { "in": "query", "name": "profile", "schema": { "description": "Name of an authenticated profile to hydrate into the browser at launch.\nThe profile's cookies, localStorage and IndexedDB are injected via CDP\nbefore your code runs. No-op in builds without a profile subsystem.", "type": "string" } }, { "in": "query", "name": "proxy", "schema": { "$ref": "#/components/schemas/ProxyType", "description": "The type of proxy to use: 'residential' or 'datacenter'." } }, { "in": "query", "name": "proxyCity", "schema": { "description": "The city to use for the proxy.\n\nAvailable cities: https://production-sfo.browserless.io/proxy/cities?token=YOUR_TOKEN\nDocumentation: 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.\n\nSupported codes: US, GB, FR, DE, etc.\nFull 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.\nRecommended when using proxyCountry to ensure websites render content,\ncurrency, 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.\nMaps to specific proxy vendors internally for optimal access to certain websites.\nFormat: \"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": { "type": "boolean" } }, { "in": "query", "name": "timeout", "schema": { "description": "Override the system-level timeout for this request.\nAccepts 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": { "101": { "description": "Indicates successful WebSocket upgrade." }, "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" }, "403": { "code": 403, "description": "The request targets a destination that is not allowed.", "message": "HTTP/1.1 403 Forbidden" }, "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": [ "Chrome (licensed build)" ], "operationId": "chrome-bql-connect" } }, "/chromium/agent": { "get": { "description": "WebSocket endpoint for agentic browser interaction. Connect to establish a\npersistent browser session, then send JSON-RPC messages to control the browser.\n\nUses a simple JSON protocol instead of GraphQL:\nSend: { \"id\": 1, \"method\": \"goto\", \"params\": { \"url\": \"https://example.com\" } }\nReceive: { \"id\": 1, \"result\": { \"status\": 200, \"url\": \"https://example.com\" } }\n\nAll BQL mutations are available as methods (goto, click, type, screenshot, etc.).\nAdditionally supports a \"snapshot\" method that returns interactive page elements\nwith CSS selectors, plus tab-management methods (getTabs, switchTab, createTab,\ncloseTab) for multi-tab workflows.", "parameters": [ { "in": "query", "name": "allowedDomains", "schema": { "description": "Optional per-connection narrowing of the integration's allowed-domain list.\nExtracted from the JSON `allowedDomains` query parameter. Can only narrow the\nintegration's domains, never widen them.", "type": "array", "items": { "type": "string" } } }, { "in": "query", "name": "blockAds", "schema": { "description": "Whether or not to load ad-blocking extensions for the session.\nThis currently uses uBlock-Lite and may cause certain sites\nto not load properly.", "type": "boolean" } }, { "in": "query", "name": "blockConsentModals", "schema": { "type": "boolean" } }, { "in": "query", "name": "credentials", "schema": { "$ref": "#/components/schemas/StringRecord", "description": "Optional alias → `op://…` reference map for the integration above. Extracted\nfrom the JSON `credentials` query parameter. References are not secret;\nresolved values are never stored here. Optional — a connection can also pass\nraw `op://…` references straight to Browserless.loadSecret." } }, { "in": "query", "name": "externalProxyServer", "schema": { "description": "External proxy server URL for user-provided proxies.\nFormat: http(s)://[username:password@]host:port\nWhen set, routes requests through this proxy instead of built-in residential proxies.", "type": "string" } }, { "in": "query", "name": "humanlike", "schema": { "type": "boolean" } }, { "in": "query", "name": "integrationId", "schema": { "description": "Optional 1Password integration id for credential filling on a non-persistent\nconnection. Extracted from the `integrationId` query parameter; the persistent\nsession path carries the same data on session metadata instead.", "type": "string" } }, { "in": "query", "name": "launch", "schema": { "description": "Launch options, which can be either an object\nof puppeteer.launch options or playwright.launchServer\noptions, depending on the API. Must be either JSON\nobject, or a base64-encoded JSON object.", "anyOf": [ { "$ref": "#/components/schemas/CDPLaunchOptions" }, { "type": "string" } ] } }, { "in": "query", "name": "profile", "schema": { "description": "Name of an authenticated profile to hydrate into the browser at launch.\nThe profile's cookies, localStorage and IndexedDB are injected via CDP\nbefore your code runs. No-op in builds without a profile subsystem.", "type": "string" } }, { "in": "query", "name": "proxy", "schema": { "$ref": "#/components/schemas/ProxyType", "description": "The type of proxy to use: 'residential' or 'datacenter'." } }, { "in": "query", "name": "proxyCity", "schema": { "description": "The city to use for the proxy.\n\nAvailable cities: https://production-sfo.browserless.io/proxy/cities?token=YOUR_TOKEN\nDocumentation: 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.\n\nSupported codes: US, GB, FR, DE, etc.\nFull 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.\nRecommended when using proxyCountry to ensure websites render content,\ncurrency, 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.\nMaps to specific proxy vendors internally for optimal access to certain websites.\nFormat: \"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": { "type": "boolean" } }, { "in": "query", "name": "sessionId", "schema": { "description": "Attach to a pre-created profile/creation session (autologin).", "type": "string" } }, { "in": "query", "name": "timeout", "schema": { "description": "Override the system-level timeout for this request.\nAccepts 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": { "101": { "description": "Indicates successful WebSocket upgrade." }, "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" }, "403": { "code": 403, "description": "The request targets a destination that is not allowed.", "message": "HTTP/1.1 403 Forbidden" }, "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/agent", "tags": [ "Browser WebSocket APIs" ] } }, "/chromium/bql?(/*)": { "post": { "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": "acceptInsecureCerts", "schema": { "description": "Whether to ignore TLS certificate errors (e.g. self-signed or untrusted\nauthorities) so the browser navigates to sites with invalid certificates.", "type": "boolean" } }, { "in": "query", "name": "allowedDomains", "schema": { "description": "Optional per-connection narrowing of the integration's allowed-domain list.\nExtracted from the JSON `allowedDomains` query parameter. Can only narrow the\nintegration's domains, never widen them.", "type": "array", "items": { "type": "string" } } }, { "in": "query", "name": "blockAds", "schema": { "description": "Whether or not to load ad-blocking extensions for the session.\nThis currently uses uBlock-Lite and may cause certain sites\nto not load properly.", "type": "boolean" } }, { "in": "query", "name": "blockAdsInclude", "schema": { "description": "Restrict blockAds to a specific set of uBlock ruleset ids (comma-separated\nlist or JSON array). Only applies when `blockAds` is true. Fewer rulesets\nmeans a faster browser launch under load; omit to load the full default set.", "type": "string" } }, { "in": "query", "name": "blockConsentModals", "schema": { "description": "Whether to automatically block cookie consent modals and popups.", "type": "boolean" } }, { "in": "query", "name": "credentials", "schema": { "$ref": "#/components/schemas/StringRecord", "description": "Optional alias → `op://…` reference map for the integration above. Extracted\nfrom the JSON `credentials` query parameter. References are not secret;\nresolved values are never stored here. Optional — a connection can also pass\nraw `op://…` references straight to Browserless.loadSecret." } }, { "in": "query", "name": "emulationOs", "schema": { "$ref": "#/components/schemas/Platform", "description": "Spoof OS for the session: 'windows', 'macos', or 'linux'. When set, the\nsession runs the full per-platform stealth stack (User-Agent, UA Client\nHints, navigator.platform, GPU, fonts, and media/speech/audio fingerprints)\n— the same stack the /stealth routes use. Omit for the native (Linux) host\nidentity." } }, { "in": "query", "name": "externalProxyServer", "schema": { "description": "External proxy server URL for user-provided proxies.\nFormat: http(s)://[username:password@]host:port\nWhen 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.\nWhen true, actions like typing and clicking will have randomized delays.", "type": "boolean" } }, { "in": "query", "name": "integrationId", "schema": { "description": "Optional 1Password integration id for credential filling on a non-persistent\nconnection. Extracted from the `integrationId` query parameter; the persistent\nsession path carries the same data on session metadata instead.", "type": "string" } }, { "in": "query", "name": "launch", "schema": { "description": "Launch options for the browser, either as a JSON object or a JSON string.\nIncludes options like `headless`, `args`, `defaultViewport`, etc.\nMust be either JSON object, or a base64-encoded JSON object.", "anyOf": [ { "$ref": "#/components/schemas/CDPLaunchOptions" }, { "type": "string" } ] } }, { "in": "query", "name": "profile", "schema": { "description": "Name of an authenticated profile to hydrate into the browser at launch.\nThe profile's cookies, localStorage and IndexedDB are injected via CDP\nbefore your code runs. No-op in builds without a profile subsystem.", "type": "string" } }, { "in": "query", "name": "proxy", "schema": { "$ref": "#/components/schemas/ProxyType", "description": "The type of proxy to use: 'residential' or 'datacenter'." } }, { "in": "query", "name": "proxyCity", "schema": { "description": "The city to use for the proxy.\n\nAvailable cities: https://production-sfo.browserless.io/proxy/cities?token=YOUR_TOKEN\nDocumentation: 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.\n\nSupported codes: US, GB, FR, DE, etc.\nFull 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.\nRecommended when using proxyCountry to ensure websites render content,\ncurrency, 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.\nMaps to specific proxy vendors internally for optimal access to certain websites.\nFormat: \"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.\nWhen 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.\nAccepts 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" }, "403": { "code": 403, "description": "The request targets a destination that is not allowed.", "message": "HTTP/1.1 403 Forbidden" }, "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" ], "operationId": "chromium-bql-execute" }, "get": { "description": "WebSocket endpoint for BrowserQL. Connect to establish a persistent browser\nsession, then send multiple GraphQL operations as JSON messages. The browser\nand page state persist across all messages for the connection duration.\n\nMessages use the same JSON format as the HTTP POST endpoint:\nSend: { \"query\": \"mutation { goto(url: \\\"..\\\") { status } }\", \"variables\": {} }\nReceive: { \"data\": { \"goto\": { \"status\": 200 } } }", "parameters": [ { "in": "query", "name": "acceptInsecureCerts", "schema": { "description": "Whether to ignore TLS certificate errors (e.g. self-signed or untrusted\nauthorities) so the browser navigates to sites with invalid certificates.", "type": "boolean" } }, { "in": "query", "name": "allowedDomains", "schema": { "description": "Optional per-connection narrowing of the integration's allowed-domain list.\nExtracted from the JSON `allowedDomains` query parameter. Can only narrow the\nintegration's domains, never widen them.", "type": "array", "items": { "type": "string" } } }, { "in": "query", "name": "blockAds", "schema": { "description": "Whether or not to load ad-blocking extensions for the session.\nThis currently uses uBlock-Lite and may cause certain sites\nto not load properly.", "type": "boolean" } }, { "in": "query", "name": "blockAdsInclude", "schema": { "description": "Restrict blockAds to a specific set of uBlock ruleset ids (comma-separated\nlist or JSON array). Only applies when `blockAds` is true. Fewer rulesets\nmeans a faster browser launch under load; omit to load the full default set.", "type": "string" } }, { "in": "query", "name": "blockConsentModals", "schema": { "type": "boolean" } }, { "in": "query", "name": "credentials", "schema": { "$ref": "#/components/schemas/StringRecord", "description": "Optional alias → `op://…` reference map for the integration above. Extracted\nfrom the JSON `credentials` query parameter. References are not secret;\nresolved values are never stored here. Optional — a connection can also pass\nraw `op://…` references straight to Browserless.loadSecret." } }, { "in": "query", "name": "emulationOs", "schema": { "$ref": "#/components/schemas/Platform", "description": "Spoof OS for the session: 'windows', 'macos', or 'linux'. When set, the\nsession runs the full per-platform stealth stack (User-Agent, UA Client\nHints, navigator.platform, GPU, fonts, and media/speech/audio fingerprints)\n— the same stack the /stealth routes use. Omit for the native (Linux) host\nidentity." } }, { "in": "query", "name": "externalProxyServer", "schema": { "description": "External proxy server URL for user-provided proxies.\nFormat: http(s)://[username:password@]host:port\nWhen set, routes requests through this proxy instead of built-in residential proxies.", "type": "string" } }, { "in": "query", "name": "humanlike", "schema": { "type": "boolean" } }, { "in": "query", "name": "integrationId", "schema": { "description": "Optional 1Password integration id for credential filling on a non-persistent\nconnection. Extracted from the `integrationId` query parameter; the persistent\nsession path carries the same data on session metadata instead.", "type": "string" } }, { "in": "query", "name": "launch", "schema": { "description": "Launch options for the browser, either as a JSON object or a JSON string.\nIncludes options like `headless`, `args`, `defaultViewport`, etc.\nMust be either JSON object, or a base64-encoded JSON object.", "anyOf": [ { "$ref": "#/components/schemas/CDPLaunchOptions" }, { "type": "string" } ] } }, { "in": "query", "name": "profile", "schema": { "description": "Name of an authenticated profile to hydrate into the browser at launch.\nThe profile's cookies, localStorage and IndexedDB are injected via CDP\nbefore your code runs. No-op in builds without a profile subsystem.", "type": "string" } }, { "in": "query", "name": "proxy", "schema": { "$ref": "#/components/schemas/ProxyType", "description": "The type of proxy to use: 'residential' or 'datacenter'." } }, { "in": "query", "name": "proxyCity", "schema": { "description": "The city to use for the proxy.\n\nAvailable cities: https://production-sfo.browserless.io/proxy/cities?token=YOUR_TOKEN\nDocumentation: 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.\n\nSupported codes: US, GB, FR, DE, etc.\nFull 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.\nRecommended when using proxyCountry to ensure websites render content,\ncurrency, 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.\nMaps to specific proxy vendors internally for optimal access to certain websites.\nFormat: \"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": { "type": "boolean" } }, { "in": "query", "name": "timeout", "schema": { "description": "Override the system-level timeout for this request.\nAccepts 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": { "101": { "description": "Indicates successful WebSocket upgrade." }, "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" }, "403": { "code": 403, "description": "The request targets a destination that is not allowed.", "message": "HTTP/1.1 403 Forbidden" }, "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 WebSocket APIs" ], "operationId": "chromium-bql-connect" } }, "/chromium/cli": { "get": { "description": "Interactive hosted-agent chat. Browserless runs the LLM server-side (no\ncustomer key) and drives a browser to complete the task. Send newline-JSON\ncontrol frames ({\"type\":\"start\",\"prompt\":\"...\"}) and receive a stream of\ndata / tool_call / tool_result / usage / awaiting_input / end events.", "parameters": [ { "in": "query", "name": "token", "schema": { "type": "string" } }, { "in": "query", "name": "allowedDomains", "schema": { "description": "Optional per-connection narrowing of the integration's allowed-domain list.\nExtracted from the JSON `allowedDomains` query parameter. Can only narrow the\nintegration's domains, never widen them.", "type": "array", "items": { "type": "string" } } }, { "in": "query", "name": "credentials", "schema": { "$ref": "#/components/schemas/StringRecord", "description": "Optional alias → `op://…` reference map for the integration above. Extracted\nfrom the JSON `credentials` query parameter. References are not secret;\nresolved values are never stored here. Optional — a connection can also pass\nraw `op://…` references straight to Browserless.loadSecret." } }, { "in": "query", "name": "externalProxyServer", "schema": { "description": "External proxy server URL for user-provided proxies.\nFormat: http(s)://[username:password@]host:port\nWhen set, routes requests through this proxy instead of built-in residential proxies.", "type": "string" } }, { "in": "query", "name": "integrationId", "schema": { "description": "Optional 1Password integration id for credential filling on a non-persistent\nconnection. Extracted from the `integrationId` query parameter; the persistent\nsession path carries the same data on session metadata instead.", "type": "string" } }, { "in": "query", "name": "proxy", "schema": { "$ref": "#/components/schemas/ProxyType", "description": "The type of proxy to use: 'residential' or 'datacenter'." } }, { "in": "query", "name": "proxyCity", "schema": { "description": "The city to use for the proxy.\n\nAvailable cities: https://production-sfo.browserless.io/proxy/cities?token=YOUR_TOKEN\nDocumentation: 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.\n\nSupported codes: US, GB, FR, DE, etc.\nFull 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.\nRecommended when using proxyCountry to ensure websites render content,\ncurrency, 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.\nMaps to specific proxy vendors internally for optimal access to certain websites.\nFormat: \"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" } } ], "requestBody": { "content": {} }, "responses": { "101": { "description": "Indicates successful WebSocket upgrade." }, "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" }, "403": { "code": 403, "description": "The request targets a destination that is not allowed.", "message": "HTTP/1.1 403 Forbidden" }, "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/cli", "tags": [ "Browser WebSocket APIs" ] } }, "/chromium/stealth/reconnect/*": { "get": { "description": "Reconnect to an existing stealth browser session (e.g. from /unblock) with CDP proxy features like solveCaptchas and stealth-mode fingerprint masking.", "parameters": [ { "in": "query", "name": "blockAds", "schema": { "description": "Whether or not to load ad-blocking extensions for the session.\nThis currently uses uBlock-Lite and may cause certain sites\nto not load properly.", "type": "boolean" } }, { "in": "query", "name": "integrations", "schema": { "type": "string" } }, { "in": "query", "name": "launch", "schema": { "description": "Launch options, which can be either an object\nof puppeteer.launch options or playwright.launchServer\noptions, depending on the API. Must be either JSON\nobject, or a base64-encoded JSON object.", "anyOf": [ { "$ref": "#/components/schemas/CDPLaunchOptions" }, { "$ref": "#/components/schemas/BrowserServerOptions" }, { "type": "string" } ] } }, { "in": "query", "name": "profile", "schema": { "description": "Name of an authenticated profile to hydrate into the browser at launch.\nThe profile's cookies, localStorage and IndexedDB are injected via CDP\nbefore your code runs. No-op in builds without a profile subsystem.", "type": "string" } }, { "in": "query", "name": "replay", "schema": { "type": "boolean" } }, { "in": "query", "name": "solveCaptchas", "schema": { "type": "boolean" } }, { "in": "query", "name": "timeout", "schema": { "description": "Override the system-level timeout for this request.\nAccepts 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" } }, { "in": "query", "name": "allowedDomains", "schema": { "description": "Optional per-connection narrowing of the integration's allowed-domain list.\nExtracted from the JSON `allowedDomains` query parameter. Can only narrow the\nintegration's domains, never widen them.", "type": "array", "items": { "type": "string" } } }, { "in": "query", "name": "credentials", "schema": { "$ref": "#/components/schemas/StringRecord", "description": "Optional alias → `op://…` reference map for the integration above. Extracted\nfrom the JSON `credentials` query parameter. References are not secret;\nresolved values are never stored here. Optional — a connection can also pass\nraw `op://…` references straight to Browserless.loadSecret." } }, { "in": "query", "name": "externalProxyServer", "schema": { "description": "External proxy server URL for user-provided proxies.\nFormat: http(s)://[username:password@]host:port\nWhen set, routes requests through this proxy instead of built-in residential proxies.", "type": "string" } }, { "in": "query", "name": "integrationId", "schema": { "description": "Optional 1Password integration id for credential filling on a non-persistent\nconnection. Extracted from the `integrationId` query parameter; the persistent\nsession path carries the same data on session metadata instead.", "type": "string" } }, { "in": "query", "name": "proxy", "schema": { "$ref": "#/components/schemas/ProxyType", "description": "The type of proxy to use: 'residential' or 'datacenter'." } }, { "in": "query", "name": "proxyCity", "schema": { "description": "The city to use for the proxy.\n\nAvailable cities: https://production-sfo.browserless.io/proxy/cities?token=YOUR_TOKEN\nDocumentation: 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.\n\nSupported codes: US, GB, FR, DE, etc.\nFull 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.\nRecommended when using proxyCountry to ensure websites render content,\ncurrency, 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.\nMaps to specific proxy vendors internally for optimal access to certain websites.\nFormat: \"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" } } ], "requestBody": { "content": {} }, "responses": { "101": { "description": "Indicates successful WebSocket upgrade." }, "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" }, "403": { "code": 403, "description": "The request targets a destination that is not allowed.", "message": "HTTP/1.1 403 Forbidden" }, "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/stealth/reconnect/*", "tags": [ "Browser WebSocket APIs" ] } }, "/devtools/browser/*": { "get": { "description": "Connect to an already-running Chromium process with a library like\npuppeteer, or others, that work over chrome-devtools-protocol. Chromium\nmust already be launched in order to not return a 404.", "parameters": [ { "in": "query", "name": "blockAds", "schema": { "description": "Whether or not to load ad-blocking extensions for the session.\nThis currently uses uBlock-Lite and may cause certain sites\nto not load properly.", "type": "boolean" } }, { "in": "query", "name": "launch", "schema": { "description": "Launch options, which can be either an object\nof puppeteer.launch options or playwright.launchServer\noptions, depending on the API. Must be either JSON\nobject, or a base64-encoded JSON object.", "anyOf": [ { "$ref": "#/components/schemas/CDPLaunchOptions" }, { "type": "string" } ] } }, { "in": "query", "name": "profile", "schema": { "description": "Name of an authenticated profile to hydrate into the browser at launch.\nThe profile's cookies, localStorage and IndexedDB are injected via CDP\nbefore 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.\nAccepts 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" } }, { "in": "query", "name": "allowedDomains", "schema": { "description": "Optional per-connection narrowing of the integration's allowed-domain list.\nExtracted from the JSON `allowedDomains` query parameter. Can only narrow the\nintegration's domains, never widen them.", "type": "array", "items": { "type": "string" } } }, { "in": "query", "name": "credentials", "schema": { "$ref": "#/components/schemas/StringRecord", "description": "Optional alias → `op://…` reference map for the integration above. Extracted\nfrom the JSON `credentials` query parameter. References are not secret;\nresolved values are never stored here. Optional — a connection can also pass\nraw `op://…` references straight to Browserless.loadSecret." } }, { "in": "query", "name": "externalProxyServer", "schema": { "description": "External proxy server URL for user-provided proxies.\nFormat: http(s)://[username:password@]host:port\nWhen set, routes requests through this proxy instead of built-in residential proxies.", "type": "string" } }, { "in": "query", "name": "integrationId", "schema": { "description": "Optional 1Password integration id for credential filling on a non-persistent\nconnection. Extracted from the `integrationId` query parameter; the persistent\nsession path carries the same data on session metadata instead.", "type": "string" } }, { "in": "query", "name": "proxy", "schema": { "$ref": "#/components/schemas/ProxyType", "description": "The type of proxy to use: 'residential' or 'datacenter'." } }, { "in": "query", "name": "proxyCity", "schema": { "description": "The city to use for the proxy.\n\nAvailable cities: https://production-sfo.browserless.io/proxy/cities?token=YOUR_TOKEN\nDocumentation: 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.\n\nSupported codes: US, GB, FR, DE, etc.\nFull 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.\nRecommended when using proxyCountry to ensure websites render content,\ncurrency, 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.\nMaps to specific proxy vendors internally for optimal access to certain websites.\nFormat: \"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" } } ], "requestBody": { "content": {} }, "responses": { "101": { "description": "Indicates successful WebSocket upgrade." }, "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" }, "403": { "code": 403, "description": "The request targets a destination that is not allowed.", "message": "HTTP/1.1 403 Forbidden" }, "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": "/devtools/browser/*", "tags": [ "Browser WebSocket APIs" ] } }, "/devtools/page/*": { "get": { "description": "Connect to an existing page in Chromium with a library like\nchrome-remote-interface or others that work the page websocketDebugger\nURL. You can get this unique URL by calling the /json/list API\nor by finding the page's unique ID from your library of choice.", "parameters": [ { "in": "query", "name": "blockAds", "schema": { "description": "Whether or not to load ad-blocking extensions for the session.\nThis currently uses uBlock-Lite and may cause certain sites\nto not load properly.", "type": "boolean" } }, { "in": "query", "name": "launch", "schema": { "description": "Launch options, which can be either an object\nof puppeteer.launch options or playwright.launchServer\noptions, depending on the API. Must be either JSON\nobject, or a base64-encoded JSON object.", "anyOf": [ { "$ref": "#/components/schemas/CDPLaunchOptions" }, { "type": "string" } ] } }, { "in": "query", "name": "profile", "schema": { "description": "Name of an authenticated profile to hydrate into the browser at launch.\nThe profile's cookies, localStorage and IndexedDB are injected via CDP\nbefore 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.\nAccepts 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" } }, { "in": "query", "name": "allowedDomains", "schema": { "description": "Optional per-connection narrowing of the integration's allowed-domain list.\nExtracted from the JSON `allowedDomains` query parameter. Can only narrow the\nintegration's domains, never widen them.", "type": "array", "items": { "type": "string" } } }, { "in": "query", "name": "credentials", "schema": { "$ref": "#/components/schemas/StringRecord", "description": "Optional alias → `op://…` reference map for the integration above. Extracted\nfrom the JSON `credentials` query parameter. References are not secret;\nresolved values are never stored here. Optional — a connection can also pass\nraw `op://…` references straight to Browserless.loadSecret." } }, { "in": "query", "name": "externalProxyServer", "schema": { "description": "External proxy server URL for user-provided proxies.\nFormat: http(s)://[username:password@]host:port\nWhen set, routes requests through this proxy instead of built-in residential proxies.", "type": "string" } }, { "in": "query", "name": "integrationId", "schema": { "description": "Optional 1Password integration id for credential filling on a non-persistent\nconnection. Extracted from the `integrationId` query parameter; the persistent\nsession path carries the same data on session metadata instead.", "type": "string" } }, { "in": "query", "name": "proxy", "schema": { "$ref": "#/components/schemas/ProxyType", "description": "The type of proxy to use: 'residential' or 'datacenter'." } }, { "in": "query", "name": "proxyCity", "schema": { "description": "The city to use for the proxy.\n\nAvailable cities: https://production-sfo.browserless.io/proxy/cities?token=YOUR_TOKEN\nDocumentation: 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.\n\nSupported codes: US, GB, FR, DE, etc.\nFull 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.\nRecommended when using proxyCountry to ensure websites render content,\ncurrency, 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.\nMaps to specific proxy vendors internally for optimal access to certain websites.\nFormat: \"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" } } ], "requestBody": { "content": {} }, "responses": { "101": { "description": "Indicates successful WebSocket upgrade." }, "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" }, "403": { "code": 403, "description": "The request targets a destination that is not allowed.", "message": "HTTP/1.1 403 Forbidden" }, "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": "/devtools/page/*", "tags": [ "Browser WebSocket APIs" ] } }, "/function/connect/*": { "get": { "description": "Internally used by the POST /function API to connect the underlying client-side code to. Not intended for direct use but documented for completeness and to distinguish between other reconnect style calls.", "parameters": [ { "in": "query", "name": "blockAds", "schema": { "description": "Whether or not to load ad-blocking extensions for the session.\nThis currently uses uBlock-Lite and may cause certain sites\nto not load properly.", "type": "boolean" } }, { "in": "query", "name": "launch", "schema": { "description": "Launch options, which can be either an object\nof puppeteer.launch options or playwright.launchServer\noptions, depending on the API. Must be either JSON\nobject, or a base64-encoded JSON object.", "anyOf": [ { "$ref": "#/components/schemas/CDPLaunchOptions" }, { "type": "string" } ] } }, { "in": "query", "name": "profile", "schema": { "description": "Name of an authenticated profile to hydrate into the browser at launch.\nThe profile's cookies, localStorage and IndexedDB are injected via CDP\nbefore 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.\nAccepts 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" } }, { "in": "query", "name": "allowedDomains", "schema": { "description": "Optional per-connection narrowing of the integration's allowed-domain list.\nExtracted from the JSON `allowedDomains` query parameter. Can only narrow the\nintegration's domains, never widen them.", "type": "array", "items": { "type": "string" } } }, { "in": "query", "name": "credentials", "schema": { "$ref": "#/components/schemas/StringRecord", "description": "Optional alias → `op://…` reference map for the integration above. Extracted\nfrom the JSON `credentials` query parameter. References are not secret;\nresolved values are never stored here. Optional — a connection can also pass\nraw `op://…` references straight to Browserless.loadSecret." } }, { "in": "query", "name": "externalProxyServer", "schema": { "description": "External proxy server URL for user-provided proxies.\nFormat: http(s)://[username:password@]host:port\nWhen set, routes requests through this proxy instead of built-in residential proxies.", "type": "string" } }, { "in": "query", "name": "integrationId", "schema": { "description": "Optional 1Password integration id for credential filling on a non-persistent\nconnection. Extracted from the `integrationId` query parameter; the persistent\nsession path carries the same data on session metadata instead.", "type": "string" } }, { "in": "query", "name": "proxy", "schema": { "$ref": "#/components/schemas/ProxyType", "description": "The type of proxy to use: 'residential' or 'datacenter'." } }, { "in": "query", "name": "proxyCity", "schema": { "description": "The city to use for the proxy.\n\nAvailable cities: https://production-sfo.browserless.io/proxy/cities?token=YOUR_TOKEN\nDocumentation: 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.\n\nSupported codes: US, GB, FR, DE, etc.\nFull 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.\nRecommended when using proxyCountry to ensure websites render content,\ncurrency, 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.\nMaps to specific proxy vendors internally for optimal access to certain websites.\nFormat: \"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" } } ], "requestBody": { "content": {} }, "responses": { "101": { "description": "Indicates successful WebSocket upgrade." }, "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" }, "403": { "code": 403, "description": "The request targets a destination that is not allowed.", "message": "HTTP/1.1 403 Forbidden" }, "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": "/function/connect/*", "tags": [ "Browser WebSocket APIs" ] } }, "/integrations/script-generator": { "post": { "description": "Generates a Browserless automation script (BrowserQL / Playwright JS /\nPlaywright Python) from a natural-language task. A managed agent drives a\nbrowser session; its ordered tool-call transcript is rendered into the\nrequested script(s). Streams Server-Sent Events: status, script, complete,\nerror.", "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" }, "403": { "code": 403, "description": "The request targets a destination that is not allowed.", "message": "HTTP/1.1 403 Forbidden" }, "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": "/integrations/script-generator", "tags": [ "Integrations" ] } }, "/session/*": { "delete": { "description": "Deletes a session and its associated data. This will immediately terminate any active connections to the session if \"force\" is applied.\n\nQuery Parameters:\n- force (optional): If true, forces deletion even if the session has active connections", "parameters": [ { "in": "query", "name": "blockAds", "schema": { "description": "Whether or not to load ad-blocking extensions for the session.\nThis currently uses uBlock-Lite and may cause certain sites\nto 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.\nDefaults to false.", "type": "boolean" } }, { "in": "query", "name": "launch", "schema": { "description": "Launch options, which can be either an object\nof puppeteer.launch options or playwright.launchServer\noptions, depending on the API. Must be either JSON\nobject, or a base64-encoded JSON object.", "anyOf": [ { "$ref": "#/components/schemas/CDPLaunchOptions" }, { "$ref": "#/components/schemas/BrowserServerOptions" }, { "type": "string" } ] } }, { "in": "query", "name": "profile", "schema": { "description": "Name of an authenticated profile to hydrate into the browser at launch.\nThe profile's cookies, localStorage and IndexedDB are injected via CDP\nbefore 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.\nAccepts 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" }, "403": { "code": 403, "description": "The request targets a destination that is not allowed.", "message": "HTTP/1.1 403 Forbidden" }, "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": [ "Sessions & Connections" ], "operationId": "session-delete" } }, "/stealth/bql?(/*)": { "post": { "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": "acceptInsecureCerts", "schema": { "description": "Whether to ignore TLS certificate errors (e.g. self-signed or untrusted\nauthorities) so the browser navigates to sites with invalid certificates.", "type": "boolean" } }, { "in": "query", "name": "allowedDomains", "schema": { "description": "Optional per-connection narrowing of the integration's allowed-domain list.\nExtracted from the JSON `allowedDomains` query parameter. Can only narrow the\nintegration's domains, never widen them.", "type": "array", "items": { "type": "string" } } }, { "in": "query", "name": "blockAds", "schema": { "description": "Whether or not to load ad-blocking extensions for the session.\nThis currently uses uBlock-Lite and may cause certain sites\nto not load properly.", "type": "boolean" } }, { "in": "query", "name": "blockAdsInclude", "schema": { "description": "Restrict blockAds to a specific set of uBlock ruleset ids (comma-separated\nlist or JSON array). Only applies when `blockAds` is true. Fewer rulesets\nmeans a faster browser launch under load; omit to load the full default set.", "type": "string" } }, { "in": "query", "name": "blockConsentModals", "schema": { "description": "Whether to automatically block cookie consent modals and popups.", "type": "boolean" } }, { "in": "query", "name": "credentials", "schema": { "$ref": "#/components/schemas/StringRecord", "description": "Optional alias → `op://…` reference map for the integration above. Extracted\nfrom the JSON `credentials` query parameter. References are not secret;\nresolved values are never stored here. Optional — a connection can also pass\nraw `op://…` references straight to Browserless.loadSecret." } }, { "in": "query", "name": "emulationOs", "schema": { "$ref": "#/components/schemas/Platform", "description": "Spoof OS for the session: 'windows', 'macos', or 'linux'. When set, the\nsession runs the full per-platform stealth stack (User-Agent, UA Client\nHints, navigator.platform, GPU, fonts, and media/speech/audio fingerprints)\n— the same stack the /stealth routes use. Omit for the native (Linux) host\nidentity." } }, { "in": "query", "name": "externalProxyServer", "schema": { "description": "External proxy server URL for user-provided proxies.\nFormat: http(s)://[username:password@]host:port\nWhen 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.\nWhen true, actions like typing and clicking will have randomized delays.", "type": "boolean" } }, { "in": "query", "name": "integrationId", "schema": { "description": "Optional 1Password integration id for credential filling on a non-persistent\nconnection. Extracted from the `integrationId` query parameter; the persistent\nsession path carries the same data on session metadata instead.", "type": "string" } }, { "in": "query", "name": "launch", "schema": { "description": "Launch options for the browser, either as a JSON object or a JSON string.\nIncludes options like `headless`, `args`, `defaultViewport`, etc.\nMust be either JSON object, or a base64-encoded JSON object.", "anyOf": [ { "$ref": "#/components/schemas/CDPLaunchOptions" }, { "type": "string" } ] } }, { "in": "query", "name": "profile", "schema": { "description": "Name of an authenticated profile to hydrate into the browser at launch.\nThe profile's cookies, localStorage and IndexedDB are injected via CDP\nbefore your code runs. No-op in builds without a profile subsystem.", "type": "string" } }, { "in": "query", "name": "proxy", "schema": { "$ref": "#/components/schemas/ProxyType", "description": "The type of proxy to use: 'residential' or 'datacenter'." } }, { "in": "query", "name": "proxyCity", "schema": { "description": "The city to use for the proxy.\n\nAvailable cities: https://production-sfo.browserless.io/proxy/cities?token=YOUR_TOKEN\nDocumentation: 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.\n\nSupported codes: US, GB, FR, DE, etc.\nFull 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.\nRecommended when using proxyCountry to ensure websites render content,\ncurrency, 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.\nMaps to specific proxy vendors internally for optimal access to certain websites.\nFormat: \"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.\nWhen 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.\nAccepts 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" }, "403": { "code": 403, "description": "The request targets a destination that is not allowed.", "message": "HTTP/1.1 403 Forbidden" }, "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" ], "operationId": "stealth-bql-execute" }, "get": { "description": "WebSocket endpoint for BrowserQL. Connect to establish a persistent browser\nsession, then send multiple GraphQL operations as JSON messages. The browser\nand page state persist across all messages for the connection duration.\n\nMessages use the same JSON format as the HTTP POST endpoint:\nSend: { \"query\": \"mutation { goto(url: \\\"..\\\") { status } }\", \"variables\": {} }\nReceive: { \"data\": { \"goto\": { \"status\": 200 } } }", "parameters": [ { "in": "query", "name": "acceptInsecureCerts", "schema": { "description": "Whether to ignore TLS certificate errors (e.g. self-signed or untrusted\nauthorities) so the browser navigates to sites with invalid certificates.", "type": "boolean" } }, { "in": "query", "name": "allowedDomains", "schema": { "description": "Optional per-connection narrowing of the integration's allowed-domain list.\nExtracted from the JSON `allowedDomains` query parameter. Can only narrow the\nintegration's domains, never widen them.", "type": "array", "items": { "type": "string" } } }, { "in": "query", "name": "blockAds", "schema": { "description": "Whether or not to load ad-blocking extensions for the session.\nThis currently uses uBlock-Lite and may cause certain sites\nto not load properly.", "type": "boolean" } }, { "in": "query", "name": "blockAdsInclude", "schema": { "description": "Restrict blockAds to a specific set of uBlock ruleset ids (comma-separated\nlist or JSON array). Only applies when `blockAds` is true. Fewer rulesets\nmeans a faster browser launch under load; omit to load the full default set.", "type": "string" } }, { "in": "query", "name": "blockConsentModals", "schema": { "type": "boolean" } }, { "in": "query", "name": "credentials", "schema": { "$ref": "#/components/schemas/StringRecord", "description": "Optional alias → `op://…` reference map for the integration above. Extracted\nfrom the JSON `credentials` query parameter. References are not secret;\nresolved values are never stored here. Optional — a connection can also pass\nraw `op://…` references straight to Browserless.loadSecret." } }, { "in": "query", "name": "emulationOs", "schema": { "$ref": "#/components/schemas/Platform", "description": "Spoof OS for the session: 'windows', 'macos', or 'linux'. When set, the\nsession runs the full per-platform stealth stack (User-Agent, UA Client\nHints, navigator.platform, GPU, fonts, and media/speech/audio fingerprints)\n— the same stack the /stealth routes use. Omit for the native (Linux) host\nidentity." } }, { "in": "query", "name": "externalProxyServer", "schema": { "description": "External proxy server URL for user-provided proxies.\nFormat: http(s)://[username:password@]host:port\nWhen set, routes requests through this proxy instead of built-in residential proxies.", "type": "string" } }, { "in": "query", "name": "humanlike", "schema": { "type": "boolean" } }, { "in": "query", "name": "integrationId", "schema": { "description": "Optional 1Password integration id for credential filling on a non-persistent\nconnection. Extracted from the `integrationId` query parameter; the persistent\nsession path carries the same data on session metadata instead.", "type": "string" } }, { "in": "query", "name": "launch", "schema": { "description": "Launch options for the browser, either as a JSON object or a JSON string.\nIncludes options like `headless`, `args`, `defaultViewport`, etc.\nMust be either JSON object, or a base64-encoded JSON object.", "anyOf": [ { "$ref": "#/components/schemas/CDPLaunchOptions" }, { "type": "string" } ] } }, { "in": "query", "name": "profile", "schema": { "description": "Name of an authenticated profile to hydrate into the browser at launch.\nThe profile's cookies, localStorage and IndexedDB are injected via CDP\nbefore your code runs. No-op in builds without a profile subsystem.", "type": "string" } }, { "in": "query", "name": "proxy", "schema": { "$ref": "#/components/schemas/ProxyType", "description": "The type of proxy to use: 'residential' or 'datacenter'." } }, { "in": "query", "name": "proxyCity", "schema": { "description": "The city to use for the proxy.\n\nAvailable cities: https://production-sfo.browserless.io/proxy/cities?token=YOUR_TOKEN\nDocumentation: 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.\n\nSupported codes: US, GB, FR, DE, etc.\nFull 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.\nRecommended when using proxyCountry to ensure websites render content,\ncurrency, 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.\nMaps to specific proxy vendors internally for optimal access to certain websites.\nFormat: \"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": { "type": "boolean" } }, { "in": "query", "name": "timeout", "schema": { "description": "Override the system-level timeout for this request.\nAccepts 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": { "101": { "description": "Indicates successful WebSocket upgrade." }, "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" }, "403": { "code": 403, "description": "The request targets a destination that is not allowed.", "message": "HTTP/1.1 403 Forbidden" }, "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 WebSocket APIs" ], "operationId": "stealth-bql-connect" } } }, "servers": [ { "url": "https://production-sfo.browserless.io" } ], "tags": [ { "name": "Screenshots & PDFs", "description": "Capture full-page or element screenshots and generate PDFs from web pages. The root `/screenshot` and `/pdf` routes work for most cases. Use browser-specific variants like `/edge/screenshot` when you need a particular engine.", "x-displayName": "Screenshots & PDFs" }, { "name": "Scraping & Content", "description": "Load pages and extract HTML, text, or structured data. `/chromium/content` returns raw HTML. `/chromium/scrape` runs `querySelectorAll` against the rendered DOM and returns matched elements. `/smart-scrape` cascades through multiple extraction strategies automatically.", "x-displayName": "Scraping & Content" }, { "name": "Functions & Downloads", "description": "Run custom JavaScript in a browser context and retrieve the resulting files. Use `/function` to execute a Puppeteer or Playwright script server-side, and `/download` to capture binary assets triggered by in-page actions.", "x-displayName": "Functions & Downloads" }, { "name": "Sessions & Connections", "description": "Create persistent browser sessions, reconnect to running browsers, and query CDP metadata. `/session` spins up a session that outlives a single WebSocket connection. `/reconnect/:id` reattaches to it later.", "x-displayName": "Sessions & Connections" }, { "name": "Crawling", "description": "Launch, monitor, and cancel multi-page crawl jobs. `POST /crawl` starts a crawl, `GET /crawl/:id` polls for progress, and `DELETE /crawl/:id` cancels it.", "x-displayName": "Crawling" }, { "name": "Unblock & Stealth", "description": "Bypass bot detection and anti-scraping measures. `/unblock` handles aggressive anti-bot challenges end-to-end. The BQL stealth variants (`/chromium/bql`, `/chrome/bql`) randomize browser fingerprints for longer-running automation.", "x-displayName": "Unblock & Stealth" }, { "name": "Browser Management", "description": "Inspect running sessions, terminate browsers, and retrieve server metadata. `/active` lists current sessions, `/kill/:id` terminates one, and `/meta` returns server configuration.", "x-displayName": "Browser Management" }, { "name": "Profiles", "description": "Create and manage persistent browser profiles that preserve cookies, localStorage, and IndexedDB across sessions. Capture a logged-in state once with `Browserless.saveProfile`, then rehydrate it on any future session with `?profile=`.", "x-displayName": "Profiles" }, { "name": "Proxy", "description": "Discover available proxy locations and configure residential or datacenter routing for your sessions.\n\n> Residential proxies are only available on Enterprise and Cloud plans.\n\nAdd these parameters to your library or API calls:\n\n- `?proxy=residential` — residential proxy (6 units/MB).\n- `?proxy=datacenter` — datacenter proxy pool (2 units/MB). Cheaper but more easily detected.\n- `?proxyCountry=us` — two-digit ISO country code.\n- `?proxySticky=true` — keep the same IP for the entire session. Recommended for most cases.\n- `?proxyPreset=px_gov01` — website-specific proxy configuration.", "x-displayName": "Proxy" }, { "name": "Integrations", "description": "Connect external services to browser sessions. Currently supports 1Password for injecting stored credentials into a session without exposing secrets in your code.", "x-displayName": "Integrations" }, { "name": "Chrome (licensed build)", "description": "The `/chrome/*` endpoints use the licensed Google Chrome binary, which includes proprietary codec and DRM support. Use these when a site requires Chrome-specific features, video codecs (Twitch, YouTube, Netflix), or enhanced bot detection evasion. For most automation tasks, the `/chromium/*` equivalents work identically.", "x-displayName": "Chrome (licensed build)" }, { "name": "WebSocket APIs", "description": "Connect Puppeteer, Playwright, or raw DevTools Protocol clients over WebSocket. Launch a browser with `wss://` and get back a CDP session for full programmatic control.", "x-displayName": "WebSocket APIs" }, { "name": "CDP Extensions", "description": "Browserless-specific Chrome DevTools Protocol methods you call via `cdp.send()` in Puppeteer or Playwright sessions. These extend the standard CDP with live URLs, captcha solving, session reconnect, profile management, and page identification.\n\n## Usage\n\n```javascript\nconst browser = await puppeteer.connect({ browserWSEndpoint: '...' });\nconst [page] = await browser.pages();\nconst cdp = await page.createCDPSession();\n\n// Example: Get a live URL for debugging\nconst { liveURL } = await cdp.send('Browserless.liveURL', { quality: 75 });\n```\n\n## Browserless.liveURL\n\nReturns a URL that opens a live, interactive view of the current browser session in any browser. Use this for debugging, QA, or human-in-the-loop workflows. The returned URL is temporary and tied to the session's lifetime.\n\nCall via CDP: `cdp.send('Browserless.liveURL', { quality: 75 })`\n\nReturns: `{ liveURL: 'https://...' }`\n\n| Parameter | Type | Description |\n|---|---|---|\n| `quality` | `number` | JPEG quality for the live stream (1-100). Default 75. |\n| `format` | `string` | Image format for the live stream frames. |\n\n## Browserless.closeLiveURL\n\nCloses a previously opened liveURL, freeing server resources. Called automatically when the browser session ends.\n\nCall via CDP: `cdp.send('Browserless.closeLiveURL')`\n\n## Browserless.solveCaptcha\n\nDetects any CAPTCHA challenges on the current page and attempts to solve them using third-party solving services. Supports reCAPTCHA v2/v3, hCaptcha, Cloudflare Turnstile, and more.\n\nCall via CDP: `cdp.send('Browserless.solveCaptcha', { type: 'hcaptcha', wait: true })`\n\nReturns: `{ solved: true, token: '...' }`\n\n| Parameter | Type | Description |\n|---|---|---|\n| `type` | `string` | CAPTCHA type to solve. Omit to auto-detect. |\n| `wait` | `boolean` | Wait for the CAPTCHA to be fully solved before returning. Default true. |\n\n## Browserless.foundCaptcha\n\nScans the current page for known CAPTCHA patterns and returns detection results without solving.\n\nCall via CDP: `cdp.send('Browserless.foundCaptcha')`\n\nReturns: `{ found: true, type: 'hcaptcha' }`\n\n## Browserless.reconnect\n\nReturns a WebSocket URL for reconnecting to the current browser session after disconnecting. The session stays alive on the server for the duration of its TTL.\n\nCall via CDP: `cdp.send('Browserless.reconnect', { timeout: 60000 })`\n\nReturns: `{ browserWSEndpoint: 'wss://...' }`\n\n| Parameter | Type | Description |\n|---|---|---|\n| `timeout` | `number` | How long (ms) to keep the session alive after disconnect. Default 60000. |\n\n## Browserless.saveProfile\n\nCaptures the browser's current state (cookies, localStorage, IndexedDB) and saves it as a named profile. Reuse the profile on future sessions via the `?profile=` query parameter.\n\nCall via CDP: `cdp.send('Browserless.saveProfile', { name: 'my-login' })`\n\nReturns: `{ profileId: '...', name: 'my-login' }`\n\n| Parameter | Type | Description |\n|---|---|---|\n| `name` | `string` | Profile name for retrieval on future sessions. |\n\n## Browserless.refreshProfile\n\nOverwrites an existing profile's saved state with the current browser state. Useful for rotating session tokens without creating a new profile.\n\nCall via CDP: `cdp.send('Browserless.refreshProfile')`\n\n## Browserless.pageIdentifier\n\nReturns a stable identifier for the current browser tab, useful for routing and session management.\n\nCall via CDP: `cdp.send('Browserless.pageIdentifier')`\n\nReturns: `{ id: '...' }`", "x-displayName": "CDP Extensions" } ], "x-tagGroups": [ { "name": "Core APIs", "tags": [ "Screenshots & PDFs", "Scraping & Content", "Functions & Downloads" ] }, { "name": "Browser Control", "tags": [ "Sessions & Connections", "Browser Management", "Crawling" ] }, { "name": "Anti-Bot & Stealth", "tags": [ "Unblock & Stealth", "Proxy" ] }, { "name": "Auth & Profiles", "tags": [ "Profiles", "Integrations" ] }, { "name": "WebSocket / CDP", "tags": [ "WebSocket APIs", "CDP Extensions" ] }, { "name": "Chrome", "tags": [ "Chrome (licensed build)" ] } ], "components": { "schemas": { "FrameAddScriptTagOptions": { "type": "object", "properties": { "url": { "description": "URL of the script to be added.", "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" }, "content": { "description": "Raw CSS content to be injected into the frame.", "type": "string" } }, "additionalProperties": false }, "Credentials": { "type": "object", "properties": { "username": { "type": "string" }, "password": { "type": "string" } }, "additionalProperties": false, "required": [ "password", "username" ] }, "CookieParam": { "description": "Cookie parameter object used to set cookies in the page-level cookies\nAPI.", "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\nthe 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" }, "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\npartitioned cookie is available in. In Firefox, it matches the\nsource origin in the\n{@link https://w3c.github.io/webdriver-bidi/#type-storage-PartitionKey PartitionKey}.", "anyOf": [ { "$ref": "#/components/schemas/CookiePartitionKey" }, { "type": "string" } ] } }, "additionalProperties": false, "required": [ "name", "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\nto the endpoint that set the cookie.\n\nIn 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\nthe topLevelSite.\n\nSupported only in Chrome.", "type": "boolean" } }, "additionalProperties": false, "required": [ "sourceOrigin" ] }, "GoToOptions": { "type": "object", "properties": { "referer": { "description": "If provided, it will take preference over the referer header value set by\n{@link Page.setExtraHTTPHeaderspage.setExtraHTTPHeaders()}.", "type": "string" }, "referrerPolicy": { "description": "If provided, it will take preference over the referer-policy header value\nset by {@link Page.setExtraHTTPHeaderspage.setExtraHTTPHeaders()}.", "type": "string" }, "timeout": { "description": "Maximum wait time in milliseconds. Pass 0 to disable the timeout.\n\nThe default value can be changed by using the\n{@link Page.setDefaultTimeout} or {@link Page.setDefaultNavigationTimeout}\nmethods.", "type": "number" }, "waitUntil": { "description": "When to consider waiting succeeds. Given an array of event strings, waiting\nis considered to be successful after all events have been fired.", "anyOf": [ { "type": "array", "items": { "$ref": "#/components/schemas/PuppeteerLifeCycleEvent" } }, { "enum": [ "domcontentloaded", "load", "networkidle0", "networkidle2" ], "type": "string" } ] }, "signal": { "description": "A signal object that allows you to cancel the call.", "$ref": "#/components/schemas/AbortSignal" } }, "additionalProperties": false }, "PuppeteerLifeCycleEvent": { "enum": [ "domcontentloaded", "load", "networkidle0", "networkidle2" ], "type": "string" }, "AbortSignal": { "type": "object", "properties": { "aborted": { "type": "boolean" }, "onabort": { "anyOf": [ { "type": "object", "additionalProperties": false }, { "type": "null" } ] }, "reason": {} }, "additionalProperties": false, "required": [ "aborted", "onabort", "reason" ] }, "Protocol.Emulation.UserAgentMetadata": { "description": "Used to specify User Agent Client Hints to emulate. See https://wicg.github.io/ua-client-hints\nMissing 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": "#/components/schemas/Protocol.Emulation.UserAgentBrandVersion" } }, "fullVersionList": { "description": "Brands appearing in Sec-CH-UA-Full-Version-List.", "type": "array", "items": { "$ref": "#/components/schemas/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.\nSee 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" ] }, "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" ] }, "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.\nSee {@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" ] }, "CDPLaunchOptions": { "type": "object", "additionalProperties": {}, "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" } } }, "BrowserServerOptions": { "type": "object", "additionalProperties": {}, "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" } } }, "JSONSchema": { "type": "object", "properties": { "code": { "type": "string" }, "context": { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/ContextValue" }, "description": "An object of variables to inject into your Puppeteer function scope. Each key becomes a variable name accessible inside the function body. Use this to pass dynamic values (URLs, selectors, credentials) without hardcoding them in the code string." } }, "additionalProperties": false, "required": [ "code" ] }, "ContextValue": { "anyOf": [ { "type": "array", "items": { "$ref": "#/components/schemas/ContextValue" } }, { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/ContextValue" } }, { "type": [ "null", "string", "number", "boolean" ] } ] }, "PDFMargin": { "type": "object", "properties": { "top": { "type": [ "string", "number" ] }, "bottom": { "type": [ "string", "number" ] }, "left": { "type": [ "string", "number" ] }, "right": { "type": [ "string", "number" ] } }, "additionalProperties": false }, "ScrapeDebugOptions": { "type": "object", "properties": { "console": { "type": "boolean" }, "cookies": { "type": "boolean" }, "html": { "type": "boolean" }, "network": { "type": "boolean" }, "screenshot": { "type": "boolean" } }, "additionalProperties": false }, "ScrapeElementSelector": { "type": "object", "properties": { "selector": { "type": "string" }, "timeout": { "type": "number" } }, "additionalProperties": false, "required": [ "selector" ] }, "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\nsession 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" }, "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\npartitioned cookie is available in. In Firefox, it matches the\nsource origin in the\n{@link https://w3c.github.io/webdriver-bidi/#type-storage-PartitionKey PartitionKey}.", "anyOf": [ { "$ref": "#/components/schemas/CookiePartitionKey" }, { "type": "string" } ] } }, "additionalProperties": false, "required": [ "domain", "expires", "name", "path", "secure", "session", "size", "value" ] }, "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" ] }, "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" }, "clip": { "description": "Specifies the region of the page/element to clip.", "$ref": "#/components/schemas/ScreenshotClip" }, "encoding": { "description": "Encoding of the image.", "enum": [ "base64", "binary" ], "type": "string" }, "captureBeyondViewport": { "description": "Capture the screenshot beyond the viewport.", "type": "boolean" } }, "additionalProperties": false }, "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" ] }, "ProxyType": { "description": "The proxy networks the platform can route through. `residential` uses the\nbuilt-in residential vendors; `datacenter` uses the Geonode datacenter\nnetwork (cheaper, billed at a lower per-MB rate).", "enum": [ "datacenter", "residential" ], "type": "string" }, "UnblockCookie": { "type": "object", "properties": { "name": { "type": "string" }, "value": { "type": "string" }, "domain": { "type": "string" }, "path": { "type": "string" }, "expires": { "type": "number" }, "httpOnly": { "type": "boolean" }, "secure": { "type": "boolean" }, "sameSite": { "type": "string" }, "url": { "type": "string" } }, "additionalProperties": false, "required": [ "domain", "expires", "httpOnly", "name", "path", "sameSite", "secure", "url", "value" ] }, "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" }, "CookieSameSite_2": { "description": "Represents the cookie's 'SameSite' status:\nhttps://tools.ietf.org/html/draft-west-first-party-cookies", "enum": [ "Default", "Lax", "None", "Strict" ], "type": "string" }, "CookiePriority": { "description": "Represents the cookie's 'Priority' status:\nhttps://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\n\"Unset\" allows protocol clients to emulate legacy cookie scope for the scheme.\nThis is a temporary ability and it will be removed in the future.", "enum": [ "NonSecure", "Secure", "Unset" ], "type": "string" }, "ImageFormat": { "enum": [ "jpeg", "png", "webp" ], "type": "string" }, "SearchResponseData": { "type": "object", "properties": { "web": { "type": "array", "items": { "$ref": "#/components/schemas/WebSearchResult" } }, "news": { "type": "array", "items": { "$ref": "#/components/schemas/NewsSearchResult" } }, "images": { "type": "array", "items": { "$ref": "#/components/schemas/ImageSearchResult" } } }, "additionalProperties": false }, "WebSearchResult": { "type": "object", "properties": { "title": { "type": "string" }, "url": { "type": "string" }, "description": { "type": "string" }, "position": { "type": "number" }, "markdown": { "type": "string" }, "html": { "type": "string" }, "links": { "type": "array", "items": { "type": "string" } }, "screenshot": { "type": "string" }, "metadata": { "type": "object", "properties": { "statusCode": { "type": "number" }, "strategy": { "type": "string" }, "error": { "type": "string" } }, "additionalProperties": false, "required": [ "statusCode" ] } }, "additionalProperties": false, "required": [ "description", "title", "url" ] }, "NewsSearchResult": { "type": "object", "properties": { "date": { "type": "string" }, "imageUrl": { "type": "string" }, "title": { "type": "string" }, "url": { "type": "string" }, "description": { "type": "string" }, "position": { "type": "number" }, "markdown": { "type": "string" }, "html": { "type": "string" }, "links": { "type": "array", "items": { "type": "string" } }, "screenshot": { "type": "string" }, "metadata": { "type": "object", "properties": { "statusCode": { "type": "number" }, "strategy": { "type": "string" }, "error": { "type": "string" } }, "additionalProperties": false, "required": [ "statusCode" ] } }, "additionalProperties": false, "required": [ "description", "title", "url" ] }, "ImageSearchResult": { "type": "object", "properties": { "title": { "type": "string" }, "imageUrl": { "type": "string" }, "imageWidth": { "type": "number" }, "imageHeight": { "type": "number" }, "url": { "type": "string" }, "position": { "type": "number" } }, "additionalProperties": false }, "Platform": { "enum": [ "linux", "macos", "windows" ], "type": "string" }, "CrawlStatus": { "enum": [ "cancelled", "completed", "failed", "in-progress" ], "type": "string" }, "CrawlPageResponse": { "type": "object", "properties": { "status": { "$ref": "#/components/schemas/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" }, "CrawlListItem": { "type": "object", "properties": { "id": { "type": "string" }, "url": { "type": "string" }, "status": { "$ref": "#/components/schemas/CrawlStatus" }, "total": { "type": "number" }, "completed": { "type": "number" }, "createdAt": { "type": "string" }, "completedAt": { "type": "string" } }, "additionalProperties": false, "required": [ "completed", "completedAt", "createdAt", "id", "status", "total", "url" ] }, "ProfileResponse": { "description": "Public-facing profile response returned by HTTP routes.\nOmits internal fields like token_hash and storage_key.", "type": "object", "properties": { "id": { "description": "Unique profile identifier.", "type": "string" }, "name": { "description": "User-supplied profile name. Unique per token.", "type": "string" }, "cookieCount": { "description": "Number of cookies captured in the profile.", "type": "number" }, "originCount": { "description": "Number of distinct origins with stored localStorage or IndexedDB.", "type": "number" }, "lastUsedAt": { "description": "ISO timestamp of the last time this profile was applied to a session, or null if never used.", "type": "string" }, "createdAt": { "description": "ISO timestamp of when the profile was created.", "type": "string" }, "updatedAt": { "description": "ISO timestamp of the last metadata change (e.g., rename).", "type": "string" } }, "additionalProperties": false, "required": [ "cookieCount", "createdAt", "id", "lastUsedAt", "name", "originCount", "updatedAt" ] }, "RefreshResponseDiagnostics": { "description": "Per-entry counts of cookies, origins, and IndexedDB items the server\ndropped or truncated before persisting. All zero on a clean refresh.", "type": "object", "properties": { "skippedMalformedCookies": { "description": "Cookies dropped because required fields were missing or wrong type.", "type": "number" }, "skippedPrivateCookies": { "description": "Cookies dropped because their domain pointed at a private/internal host.", "type": "number" }, "skippedMalformedOrigins": { "description": "Origins dropped because they were malformed or non-http(s).", "type": "number" }, "skippedPrivateOrigins": { "description": "Origins dropped because they targeted a private/internal network.", "type": "number" }, "truncatedOrigins": { "description": "Origins dropped because the per-profile cap was exceeded.", "type": "number" }, "skippedMalformedIdbDatabases": { "description": "IndexedDB databases dropped because required fields were missing.", "type": "number" }, "truncatedIdbDatabases": { "description": "IndexedDB databases dropped because the per-origin cap was exceeded.", "type": "number" }, "skippedMalformedIdbStores": { "description": "IndexedDB object-stores dropped because required fields were missing.", "type": "number" }, "truncatedIdbEntries": { "description": "IndexedDB entries dropped because the per-store cap was exceeded.", "type": "number" } }, "additionalProperties": false, "required": [ "skippedMalformedCookies", "skippedMalformedIdbDatabases", "skippedMalformedIdbStores", "skippedMalformedOrigins", "skippedPrivateCookies", "skippedPrivateOrigins", "truncatedIdbDatabases", "truncatedIdbEntries", "truncatedOrigins" ] }, "UploadResponseDiagnostics": { "description": "Per-entry counts of cookies, origins, and IndexedDB items the server\ndropped or truncated before persisting. All zero on a clean upload.", "type": "object", "properties": { "skippedMalformedCookies": { "description": "Cookies dropped because required fields were missing or wrong type.", "type": "number" }, "skippedPrivateCookies": { "description": "Cookies dropped because their domain pointed at a private/internal host.", "type": "number" }, "skippedMalformedOrigins": { "description": "Origins dropped because they were malformed or non-http(s).", "type": "number" }, "skippedPrivateOrigins": { "description": "Origins dropped because they targeted a private/internal network.", "type": "number" }, "truncatedOrigins": { "description": "Origins dropped because the per-profile cap was exceeded.", "type": "number" }, "skippedMalformedIdbDatabases": { "description": "IndexedDB databases dropped because required fields were missing.", "type": "number" }, "truncatedIdbDatabases": { "description": "IndexedDB databases dropped because the per-origin cap was exceeded.", "type": "number" }, "skippedMalformedIdbStores": { "description": "IndexedDB object-stores dropped because required fields were missing.", "type": "number" }, "truncatedIdbEntries": { "description": "IndexedDB entries dropped because the per-store cap was exceeded.", "type": "number" } }, "additionalProperties": false, "required": [ "skippedMalformedCookies", "skippedMalformedIdbDatabases", "skippedMalformedIdbStores", "skippedMalformedOrigins", "skippedPrivateCookies", "skippedPrivateOrigins", "truncatedIdbDatabases", "truncatedIdbEntries", "truncatedOrigins" ] }, "OpAuditLogResponse": { "description": "Public-facing audit-log entry returned by the audit HTTP route. Omits\ntoken_hash — never includes any token material — and carries the credential\nreference plus non-secret target metadata only.", "type": "object", "properties": { "id": { "description": "Unique audit-entry identifier.", "type": "string" }, "integrationId": { "description": "Integration this fill attempt was made through.", "type": "string" }, "profileId": { "description": "Authentication profile the fill targeted, or null.", "type": "string" }, "secretRef": { "description": "The alias or op:// reference requested. Never a resolved value.", "type": "string" }, "targetOrigin": { "description": "Document origin the fill was attempted on, or null.", "type": "string" }, "targetSelector": { "description": "CSS selector supplied by the caller, or null.", "type": "string" }, "targetDescriptor": { "description": "Non-secret descriptor of the focused element, or null.", "type": "string" }, "outcome": { "$ref": "#/components/schemas/OpAuditOutcome", "description": "`success` if the value was filled, otherwise `failure`." }, "errorCode": { "description": "Error code when the outcome is `failure`, otherwise null.", "type": "string" }, "createdAt": { "description": "ISO timestamp of the attempt.", "type": "string" } }, "additionalProperties": false, "required": [ "createdAt", "errorCode", "id", "integrationId", "outcome", "profileId", "secretRef", "targetDescriptor", "targetOrigin", "targetSelector" ] }, "OpAuditOutcome": { "description": "Outcome recorded for a single Browserless.loadSecret attempt.", "enum": [ "failure", "success" ], "type": "string" }, "OpIntegrationKind": { "enum": [ "connect", "service_account" ], "type": "string" }, "OpIntegrationResponse": { "description": "Public-facing integration response returned by HTTP routes.\nOmits internal fields — never includes token_hash or any token material.", "type": "object", "properties": { "id": { "description": "Unique integration identifier.", "type": "string" }, "label": { "description": "User-supplied label. Unique per token.", "type": "string" }, "kind": { "$ref": "#/components/schemas/OpIntegrationKind", "description": "Integration kind: `service_account` (default) or `connect`." }, "allowedDomains": { "description": "Origins this integration is allowed to fill into.", "type": "array", "items": { "type": "string" } }, "connectUrl": { "description": "Connect server URL when kind is `connect`, otherwise null.", "type": "string" }, "expiresAt": { "description": "ISO timestamp after which the integration is treated as expired, or null.", "type": "string" }, "lastResolvedAt": { "description": "ISO timestamp of the last successful secret resolve, or null if never used.", "type": "string" }, "createdAt": { "description": "ISO timestamp of when the integration was created.", "type": "string" }, "updatedAt": { "description": "ISO timestamp of the last metadata change.", "type": "string" } }, "additionalProperties": false, "required": [ "allowedDomains", "connectUrl", "createdAt", "expiresAt", "id", "kind", "label", "lastResolvedAt", "updatedAt" ] }, "AutologinState": { "description": "Lifecycle state of an autologin task.", "enum": [ "failed", "pending", "running", "success" ], "type": "string" }, "AutologinDomainResult": { "type": "object", "properties": { "origin": { "type": "string" }, "status": { "$ref": "#/components/schemas/AutologinDomainStatus" }, "error": { "type": "string" } }, "additionalProperties": false, "required": [ "origin", "status" ] }, "AutologinDomainStatus": { "description": "Per-origin progress/outcome as the agent works through the domain list.\nLive: `pending` (not reached), `active` (currently attempting), `tried`\n(moved past — outcome not yet known). Terminal: `success` | `failed`.", "enum": [ "active", "failed", "pending", "success", "tried" ], "type": "string" }, "StringRecord": { "type": "object", "additionalProperties": false }, "AnyRecord": { "type": "object", "additionalProperties": false } }, "securitySchemes": { "tokenAuth": { "type": "apiKey", "in": "query", "name": "token", "description": "Your Browserless API token. Find it on your [Account dashboard](https://www.browserless.io/account)." } } }, "security": [ { "tokenAuth": [] } ] }