{ "customSiteTitle": "Browserless Documentation", "info": { "title": "Browserless", "version": "2.56.7", "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/api-reference/cdp-extensions) that expose Browserless-specific commands like `liveURL`, `solveCaptcha`, and `reconnect`. 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/start) 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": "Ruleset IDs to load when `blockAds` is enabled, as CSV or JSON-array text.", "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.\nOnly applies to the residential network; the datacenter pool ignores it.\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. Off by default.", "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": { "status": { "type": "number" }, "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." }, "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": "Ruleset IDs to load when `blockAds` is enabled, as CSV or JSON-array text.", "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.\nOnly applies to the residential network; the datacenter pool ignores it.\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. Off by default.", "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": { "status": { "type": "number" }, "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." }, "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": "blockAdsInclude", "schema": { "description": "Ruleset IDs to load when `blockAds` is enabled, as CSV or JSON-array text.", "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": "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.\nOnly applies to the residential network; the datacenter pool ignores it.\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. Off by default.", "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": "blockAdsInclude", "schema": { "description": "Ruleset IDs to load when `blockAds` is enabled, as CSV or JSON-array text.", "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": "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.\nOnly applies to the residential network; the datacenter pool ignores it.\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. Off by default.", "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": "blockAdsInclude", "schema": { "description": "Ruleset IDs to load when `blockAds` is enabled, as CSV or JSON-array text.", "type": "string" } }, { "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.\nOnly applies to the residential network; the datacenter pool ignores it.\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. Off by default.", "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": "blockAdsInclude", "schema": { "description": "Ruleset IDs to load when `blockAds` is enabled, as CSV or JSON-array text.", "type": "string" } }, { "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.\nOnly applies to the residential network; the datacenter pool ignores it.\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. Off by default.", "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": "emulationOs", "schema": { "$ref": "#/components/schemas/Platform", "description": "OS to emulate: `windows`/`macos`/`linux`/`android`. Omitted → native Linux\nwith no device profile; an explicit `linux` still gets one." } }, { "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.\nOnly applies to the residential network; the datacenter pool ignores it.\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. Off by default.", "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- `rawText` – DOM text with script, style, and noscript elements removed and whitespace collapsed; PDF targets return extracted text\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", "rawText", "screenshot" ], "type": "string" } }, "actions": { "description": "Browser actions to run in order before the final page is captured. The\nsupported action types are `wait`, `click`, `write`, `scroll`, `scrape`,\nand `executeJavascript`. A maximum of 20 actions is allowed. Detailed,\nindex-aware validation is performed by the route so the generated schema\nintentionally leaves each array entry permissive.\n\n- `wait` accepts exactly one of `milliseconds` or `selector`\n- `click` accepts a non-empty `selector`\n- `write` accepts a non-empty `selector` and string `text`\n- `scroll` optionally accepts a `selector`\n- `scrape` captures the current page URL and HTML\n- `executeJavascript` accepts a non-empty `script` up to 10,000 characters\n\n`wait`, `click`, `write`, `scroll`, and `executeJavascript` may include a\npositive `timeout` of at most 30,000 milliseconds (default 10,000).\nEvery action and the final page settle share the request timeout budget.\n\nAn empty array is accepted as a no-op. Use a trailing newline in\n`write.text` to submit a form. Screenshots and PDFs are requested through\ntop-level `formats` and capture the final page after all actions run.", "maxItems": 20, "type": "array", "items": {} }, "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" }, "onlyMainContent": { "description": "For HTML webpages, extract the main article content, removing navigation,\nheaders, footers, sidebars and other boilerplate from DOM-derived outputs.\nParsed JSON and PDF content are unchanged. Unlike Firecrawl, this defaults\nto false; when enabled, the HTML format contains the extracted HTML.", "default": false, "type": "boolean" }, "includeTags": { "description": "CSS selectors to keep in HTML webpage outputs. Malformed entries are\nignored; if no selector matches, unfiltered content is returned. Mutually\nexclusive with excludeTags and onlyMainContent.", "maxItems": 100, "type": "array", "items": { "type": "string" } }, "excludeTags": { "description": "CSS selectors to remove from HTML webpage outputs. Malformed entries are\nignored. Mutually exclusive with includeTags.", "maxItems": 100, "type": "array", "items": { "type": "string" } }, "headers": { "description": "Custom request headers sent to the target. host, authorization,\nproxy-authorization, cookie, set-cookie, x-forwarded-for, x-real-ip, and\nforwarded are removed.", "type": "object", "additionalProperties": { "type": "string" } }, "waitFor": { "description": "Milliseconds to wait after page load. Clamped to [0, 30000]; positive\nvalues force a browser strategy.", "default": 0, "type": "number" }, "strategyCache": { "description": "Whether to use and update the remembered winning strategy for this host.\nDefaults to `true`. Set to `false` to bypass both reads and writes for this\nrequest.", "default": true, "type": "boolean" } }, "type": "object", "required": [ "url" ], "example": { "url": "https://docs.browserless.io/" } }, "example": { "url": "string", "formats": [ "html", "links", "screenshot" ], "proxy": "datacenter", "actions": [ { "type": "click", "selector": "button[data-accept-cookies]" }, { "type": "wait", "selector": "main[data-ready]", "timeout": 10000 }, { "type": "scroll", "selector": "#featured-product" }, { "type": "scrape" } ] } } } }, "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 is extracted text for PDF targets, a string for HTML content, or a parsed object for JSON. Will be null if the scrape was unsuccessful.", "anyOf": [ { "$ref": "#/components/schemas/AnyRecord" }, { "type": "string" } ] }, "contentType": { "description": "The content type returned by the target, or null if the scrape was unsuccessful or unavailable. JSON content is parsed into an object; PDF content is extracted into text.", "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\n`formats`. On a successful scrape this is the scraped page; on a captcha /\nanti-bot failure (`ok:false`) it is a best-effort debug capture of the\nblocking page. Null otherwise.", "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. For PDF targets, this is extracted page text joined with blank lines.", "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" } }, "actions": { "description": "Values captured by `scrape` and `executeJavascript` actions, or null when\nactions were omitted, empty, or the scrape failed.", "type": "object", "properties": { "scrapes": { "type": "array", "items": { "type": "object", "properties": { "url": { "type": "string" }, "html": { "type": "string" } }, "additionalProperties": false, "required": [ "html", "url" ] } }, "javascriptReturns": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string" }, "value": { "type": "string", "nullable": true } }, "additionalProperties": false, "required": [ "type", "value" ] } } }, "additionalProperties": false, "required": [ "javascriptReturns", "scrapes" ], "nullable": true }, "rawText": { "description": "DOM text with scripts/styles removed and whitespace collapsed, or extracted PDF text.", "type": "string" }, "metadata": { "description": "Page metadata on success, or null when scraping fails.", "type": "object", "properties": { "title": { "type": "string" }, "description": { "type": "string" }, "language": { "type": "string" }, "sourceURL": { "type": "string" }, "statusCode": { "type": "number" } }, "additionalProperties": false, "required": [ "description", "language", "sourceURL", "statusCode", "title" ] } }, "additionalProperties": false, "required": [ "actions", "attempted", "content", "contentType", "headers", "links", "markdown", "message", "metadata", "ok", "pdf", "rawText", "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.\nOnly applies to the residential network; the datacenter pool ignores it.\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. Off by default.", "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" }, "errorCode": { "$ref": "#/components/schemas/SearchFailureCode" }, "unresponsiveEngines": { "type": "array", "items": { "$ref": "#/components/schemas/UnresponsiveEngine" } } }, "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 }, "SearchFailureCode": { "enum": [ "no_results", "upstream_timeout", "upstream_unavailable" ], "type": "string" }, "UnresponsiveEngine": { "type": "object", "properties": { "engine": { "type": "string" }, "reason": { "$ref": "#/components/schemas/UnresponsiveEngineReason" } }, "additionalProperties": false, "required": [ "engine", "reason" ] }, "UnresponsiveEngineReason": { "enum": [ "access_denied", "captcha", "rate_limited", "timeout", "unknown" ], "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": "/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.\nOnly applies to the residential network; the datacenter pool ignores it.\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. Off by default.", "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": "blockAdsInclude", "schema": { "description": "Ruleset IDs to load when `blockAds` is enabled, as CSV or JSON-array text.", "type": "string" } }, { "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.\nOnly applies to the residential network; the datacenter pool ignores it.\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. Off by default.", "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": "blockAdsInclude", "schema": { "description": "Ruleset IDs to load when `blockAds` is enabled, as CSV or JSON-array text.", "type": "string" } }, { "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.\nOnly applies to the residential network; the datacenter pool ignores it.\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. Off by default.", "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": "blockAdsInclude", "schema": { "description": "Ruleset IDs to load when `blockAds` is enabled, as CSV or JSON-array text.", "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": "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.\nOnly applies to the residential network; the datacenter pool ignores it.\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. Off by default.", "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": "blockAdsInclude", "schema": { "description": "Ruleset IDs to load when `blockAds` is enabled, as CSV or JSON-array text.", "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": "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.\nOnly applies to the residential network; the datacenter pool ignores it.\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. Off by default.", "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": "blockAdsInclude", "schema": { "description": "Ruleset IDs to load when `blockAds` is enabled, as CSV or JSON-array text.", "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": "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.\nOnly applies to the residential network; the datacenter pool ignores it.\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. Off by default.", "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": "blockAdsInclude", "schema": { "description": "Ruleset IDs to load when `blockAds` is enabled, as CSV or JSON-array text.", "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": "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.\nOnly applies to the residential network; the datacenter pool ignores it.\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. Off by default.", "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": "blockAdsInclude", "schema": { "description": "Ruleset IDs to load when `blockAds` is enabled, as CSV or JSON-array text.", "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": "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.\nOnly applies to the residential network; the datacenter pool ignores it.\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. Off by default.", "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": "blockAdsInclude", "schema": { "description": "Ruleset IDs to load when `blockAds` is enabled, as CSV or JSON-array text.", "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": "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.\nOnly applies to the residential network; the datacenter pool ignores it.\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. Off by default.", "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": "blockAdsInclude", "schema": { "description": "Ruleset IDs to load when `blockAds` is enabled, as CSV or JSON-array text.", "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.\nOnly applies to the residential network; the datacenter pool ignores it.\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. Off by default.", "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.", "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. Hosted Cloud accepts\n0 as the plan's maximum retention and rejects values above that maximum.", "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" }, "blockAdsInclude": { "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" }, "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" } }, "label": { "description": "An optional, caller-supplied label for the session. Stored on the session\nrecord for the caller's own bookkeeping; does not affect behavior.", "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": "blockAdsInclude", "schema": { "description": "Ruleset IDs to load when `blockAds` is enabled, as CSV or JSON-array text.", "type": "string" } }, { "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/*", "tags": [ "Browser Management" ], "operationId": "kill-0-9-a-z-a-z" } }, "/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. When browser ownership enforcement\nis enabled, 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 owned by the authenticated account (or, for keys not yet mapped to an account, the 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": "Ruleset IDs to load when `blockAds` is enabled, as CSV or JSON-array text.", "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": "emulationOs", "schema": { "$ref": "#/components/schemas/Platform", "description": "OS to emulate: `windows`/`macos`/`linux`/`android`. Omitted → native Linux\nwith no device profile; an explicit `linux` still gets one." } }, { "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.\nOnly applies to the residential network; the datacenter pool ignores it.\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. Off by default.", "enum": [ "0", "1", "false", "true" ], "type": "string" } }, { "in": "query", "name": "replay", "schema": { "description": "Records the unblock session for replay (rrweb) and uploads on cleanup, reusing the\nBQL pipeline. Connection-level flag via `?replay=true`. Defaults to false.", "type": "boolean" } }, { "in": "query", "name": "solveCaptchas", "schema": { "description": "With `browserWSEndpoint`, persists captcha-solving on the kept-alive session so\nreconnects auto-solve. Connection-level flag via `?solveCaptchas=true`. Defaults 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 true, browserless proceeds when \"awaited\" events fail or timeout\n(goto, waitForSelector, and more).", "type": "boolean" }, "url": { "description": "The URL of the site you want to unblock.", "type": "string" }, "browserWSEndpoint": { "description": "Whether or not to keep the underlying browser alive and around for\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": "How long to keep the browser alive for re-connection when browserWSEndpoint\nis requested. Maximum of 30000 (30 seconds).", "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": "Time the browser stays alive until shutdown; zero when browserWSEndpoint: false.\nLimit is 60000 (60 seconds).", "type": "number" }, "screenshot": { "description": "A base64 encoded JPEG of the of the final site page.", "type": "string" }, "solved": { "description": "Whether a detected anti-bot challenge was successfully solved during the unblock.\nFalse when none was present or a present one could not be solved.", "type": "boolean" } }, "additionalProperties": false, "required": [ "browserWSEndpoint", "content", "cookies", "screenshot", "solved", "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": "blockAdsInclude", "schema": { "description": "Ruleset IDs to load when `blockAds` is enabled, as CSV or JSON-array text.", "type": "string" } }, { "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\nor your plan's session limit, whichever comes first. Free sessions are capped at\ntwo minutes; higher-tier plans retain the 10-minute maximum.\n\n**Note:** This endpoint is also available at: `/management/profile` for backwards compatibility.", "parameters": [ { "in": "query", "name": "emulationOs", "schema": { "$ref": "#/components/schemas/Platform", "description": "OS persona to preserve while authoring the profile." } }, { "in": "query", "name": "timeout", "schema": { "description": "Maximum duration of the temporary profile-creation session, in\nmilliseconds. The effective duration is capped by the smaller of 10\nminutes and your plan's session limit.", "type": "number" } } ], "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" }, "delete": { "description": "Removes selected sites and their cookies, localStorage and IndexedDB from a saved profile.\n\n**Note:** This endpoint is also available at: `/management/profile` for backwards compatibility.", "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "properties": { "name": { "type": "string" }, "domains": { "description": "Exact sites to remove, without cascading to subdomains.", "type": "array", "items": { "type": "string" } } }, "type": "object", "required": [ "domains", "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" }, "captureSettings": { "$ref": "#/components/schemas/ProfileCaptureSettings", "description": "Capture inputs the CLI used, or null for profiles not created by the CLI. The UI\nderives no capture flag from these; it uses any non-empty object to stamp the CLI\nbadge and show a read-only summary, and reads `browser`/`profile` specifically to\ndecide whether its refresh command needs placeholders for them. The CLI reads the\nrest itself and decides the exclusion behaviour from `excludeDomains`." }, "domainAuth": { "description": "Per-domain auth status + expiry for the saved logins in this profile, with\nstatus classified at read time (valid / expiring_soon / expired / unknown).\nEmpty for profiles saved before this feature, until their next capture,\nupload, or refresh. Never contains a cookie value.", "type": "array", "items": { "$ref": "#/components/schemas/ProfileDomainAuth" } }, "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": [ "captureSettings", "cookieCount", "createdAt", "domainAuth", "id", "lastUsedAt", "name", "originCount", "updatedAt" ], "definitions": { "ProfileCaptureSettings": { "description": "Capture inputs the CLI ran with, so a later `profile refresh` can replay them\nwithout flags. Null for the CDP saveProfile path and any future non-CLI creator.\nNever holds the token, and omits server/region because a stale stored region\nis a guaranteed 404.", "type": "object", "properties": { "browser": { "description": "Raw `--browser` value.", "type": "string" }, "profile": { "description": "Raw `--profile` value (source profile directory or display name).", "type": "string" }, "excludeDomains": { "description": "Effective merged exclusion list. `[]` is meaningful — \"captured with no\nexclusions\" — and distinct from absent, which means \"unknown\".", "type": "array", "items": { "type": "string" } }, "onlyDomains": { "description": "Normalized `--only-domain` hostnames, deduped and capped — not merged with local config.", "type": "array", "items": { "type": "string" } }, "keepDomains": { "description": "Normalized `--keep-domain` hostnames, same normalization, no merge.", "type": "array", "items": { "type": "string" } }, "autoFit": { "description": "Whether `--auto-fit` was used.", "type": "boolean" }, "passwordStore": { "description": "Raw `--password-store` value. Linux only.", "type": "string" }, "cliVersion": { "description": "CLI version that produced these settings, for drift diagnosis.", "type": "string" } }, "additionalProperties": false }, "ProfileDomainAuth": { "description": "Response shape: the stored snapshot plus its read-time status.", "type": "object", "properties": { "domain": { "type": "string" }, "status": { "$ref": "#/components/schemas/DomainAuthStatus" }, "expiresAt": { "type": "string" } }, "additionalProperties": false, "required": [ "domain", "expiresAt", "status" ] }, "DomainAuthStatus": { "description": "Per-domain auth status, computed at read time from a stored absolute expiry.", "enum": [ "expired", "expiring_soon", "unknown", "valid" ], "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": "/profile", "tags": [ "Profiles" ] } }, "/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.\n\n**Note:** This endpoint is also available at: `/management/profiles` 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": "blockAdsInclude", "schema": { "description": "Ruleset IDs to load when `blockAds` is enabled, as CSV or JSON-array text.", "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": "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" }, "captureSettings": { "$ref": "#/components/schemas/ProfileCaptureSettings", "description": "Capture inputs the CLI used, or null for profiles not created by the CLI. The UI\nderives no capture flag from these; it uses any non-empty object to stamp the CLI\nbadge and show a read-only summary, and reads `browser`/`profile` specifically to\ndecide whether its refresh command needs placeholders for them. The CLI reads the\nrest itself and decides the exclusion behaviour from `excludeDomains`." }, "domainAuth": { "description": "Per-domain auth status + expiry for the saved logins in this profile, with\nstatus classified at read time (valid / expiring_soon / expired / unknown).\nEmpty for profiles saved before this feature, until their next capture,\nupload, or refresh. Never contains a cookie value.", "type": "array", "items": { "$ref": "#/components/schemas/ProfileDomainAuth" } }, "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": [ "captureSettings", "cookieCount", "createdAt", "domainAuth", "id", "lastUsedAt", "name", "originCount", "updatedAt" ] }, "ProfileCaptureSettings": { "description": "Capture inputs the CLI ran with, so a later `profile refresh` can replay them\nwithout flags. Null for the CDP saveProfile path and any future non-CLI creator.\nNever holds the token, and omits server/region because a stale stored region\nis a guaranteed 404.", "type": "object", "properties": { "browser": { "description": "Raw `--browser` value.", "type": "string" }, "profile": { "description": "Raw `--profile` value (source profile directory or display name).", "type": "string" }, "excludeDomains": { "description": "Effective merged exclusion list. `[]` is meaningful — \"captured with no\nexclusions\" — and distinct from absent, which means \"unknown\".", "type": "array", "items": { "type": "string" } }, "onlyDomains": { "description": "Normalized `--only-domain` hostnames, deduped and capped — not merged with local config.", "type": "array", "items": { "type": "string" } }, "keepDomains": { "description": "Normalized `--keep-domain` hostnames, same normalization, no merge.", "type": "array", "items": { "type": "string" } }, "autoFit": { "description": "Whether `--auto-fit` was used.", "type": "boolean" }, "passwordStore": { "description": "Raw `--password-store` value. Linux only.", "type": "string" }, "cliVersion": { "description": "CLI version that produced these settings, for drift diagnosis.", "type": "string" } }, "additionalProperties": false }, "ProfileDomainAuth": { "description": "Response shape: the stored snapshot plus its read-time status.", "type": "object", "properties": { "domain": { "type": "string" }, "status": { "$ref": "#/components/schemas/DomainAuthStatus" }, "expiresAt": { "type": "string" } }, "additionalProperties": false, "required": [ "domain", "expiresAt", "status" ] }, "DomainAuthStatus": { "description": "Per-domain auth status, computed at read time from a stored absolute expiry.", "enum": [ "expired", "expiring_soon", "unknown", "valid" ], "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": "/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.\n\n**Note:** This endpoint is also available at: `/management/profile/*` for backwards compatibility.", "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.\n\n**Note:** This endpoint is also available at: `/management/profile/*` for backwards compatibility.", "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" }, "captureSettings": { "$ref": "#/components/schemas/ProfileCaptureSettings", "description": "Capture inputs the CLI used, or null for profiles not created by the CLI. The UI\nderives no capture flag from these; it uses any non-empty object to stamp the CLI\nbadge and show a read-only summary, and reads `browser`/`profile` specifically to\ndecide whether its refresh command needs placeholders for them. The CLI reads the\nrest itself and decides the exclusion behaviour from `excludeDomains`." }, "domainAuth": { "description": "Per-domain auth status + expiry for the saved logins in this profile, with\nstatus classified at read time (valid / expiring_soon / expired / unknown).\nEmpty for profiles saved before this feature, until their next capture,\nupload, or refresh. Never contains a cookie value.", "type": "array", "items": { "$ref": "#/components/schemas/ProfileDomainAuth" } }, "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": [ "captureSettings", "cookieCount", "createdAt", "domainAuth", "id", "lastUsedAt", "name", "originCount", "updatedAt" ], "definitions": { "ProfileCaptureSettings": { "description": "Capture inputs the CLI ran with, so a later `profile refresh` can replay them\nwithout flags. Null for the CDP saveProfile path and any future non-CLI creator.\nNever holds the token, and omits server/region because a stale stored region\nis a guaranteed 404.", "type": "object", "properties": { "browser": { "description": "Raw `--browser` value.", "type": "string" }, "profile": { "description": "Raw `--profile` value (source profile directory or display name).", "type": "string" }, "excludeDomains": { "description": "Effective merged exclusion list. `[]` is meaningful — \"captured with no\nexclusions\" — and distinct from absent, which means \"unknown\".", "type": "array", "items": { "type": "string" } }, "onlyDomains": { "description": "Normalized `--only-domain` hostnames, deduped and capped — not merged with local config.", "type": "array", "items": { "type": "string" } }, "keepDomains": { "description": "Normalized `--keep-domain` hostnames, same normalization, no merge.", "type": "array", "items": { "type": "string" } }, "autoFit": { "description": "Whether `--auto-fit` was used.", "type": "boolean" }, "passwordStore": { "description": "Raw `--password-store` value. Linux only.", "type": "string" }, "cliVersion": { "description": "CLI version that produced these settings, for drift diagnosis.", "type": "string" } }, "additionalProperties": false }, "ProfileDomainAuth": { "description": "Response shape: the stored snapshot plus its read-time status.", "type": "object", "properties": { "domain": { "type": "string" }, "status": { "$ref": "#/components/schemas/DomainAuthStatus" }, "expiresAt": { "type": "string" } }, "additionalProperties": false, "required": [ "domain", "expiresAt", "status" ] }, "DomainAuthStatus": { "description": "Per-domain auth status, computed at read time from a stored absolute expiry.", "enum": [ "expired", "expiring_soon", "unknown", "valid" ], "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": "/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.\n\n**Note:** This endpoint is also available at: `/management/profile/*` for backwards compatibility.", "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" }, "captureSettings": { "$ref": "#/components/schemas/ProfileCaptureSettings", "description": "Capture inputs the CLI used, or null for profiles not created by the CLI. The UI\nderives no capture flag from these; it uses any non-empty object to stamp the CLI\nbadge and show a read-only summary, and reads `browser`/`profile` specifically to\ndecide whether its refresh command needs placeholders for them. The CLI reads the\nrest itself and decides the exclusion behaviour from `excludeDomains`." }, "domainAuth": { "description": "Per-domain auth status + expiry for the saved logins in this profile, with\nstatus classified at read time (valid / expiring_soon / expired / unknown).\nEmpty for profiles saved before this feature, until their next capture,\nupload, or refresh. Never contains a cookie value.", "type": "array", "items": { "$ref": "#/components/schemas/ProfileDomainAuth" } }, "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": [ "captureSettings", "cookieCount", "createdAt", "domainAuth", "id", "lastUsedAt", "name", "originCount", "updatedAt" ], "definitions": { "ProfileCaptureSettings": { "description": "Capture inputs the CLI ran with, so a later `profile refresh` can replay them\nwithout flags. Null for the CDP saveProfile path and any future non-CLI creator.\nNever holds the token, and omits server/region because a stale stored region\nis a guaranteed 404.", "type": "object", "properties": { "browser": { "description": "Raw `--browser` value.", "type": "string" }, "profile": { "description": "Raw `--profile` value (source profile directory or display name).", "type": "string" }, "excludeDomains": { "description": "Effective merged exclusion list. `[]` is meaningful — \"captured with no\nexclusions\" — and distinct from absent, which means \"unknown\".", "type": "array", "items": { "type": "string" } }, "onlyDomains": { "description": "Normalized `--only-domain` hostnames, deduped and capped — not merged with local config.", "type": "array", "items": { "type": "string" } }, "keepDomains": { "description": "Normalized `--keep-domain` hostnames, same normalization, no merge.", "type": "array", "items": { "type": "string" } }, "autoFit": { "description": "Whether `--auto-fit` was used.", "type": "boolean" }, "passwordStore": { "description": "Raw `--password-store` value. Linux only.", "type": "string" }, "cliVersion": { "description": "CLI version that produced these settings, for drift diagnosis.", "type": "string" } }, "additionalProperties": false }, "ProfileDomainAuth": { "description": "Response shape: the stored snapshot plus its read-time status.", "type": "object", "properties": { "domain": { "type": "string" }, "status": { "$ref": "#/components/schemas/DomainAuthStatus" }, "expiresAt": { "type": "string" } }, "additionalProperties": false, "required": [ "domain", "expiresAt", "status" ] }, "DomainAuthStatus": { "description": "Per-domain auth status, computed at read time from a stored absolute expiry.", "enum": [ "expired", "expiring_soon", "unknown", "valid" ], "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": "/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`." }, "captureSettings": { "$ref": "#/components/schemas/RefreshCaptureSettingsPayload", "description": "Capture inputs this refresh ran with. Omit the key to leave the stored settings\nuntouched — which is what an older CLI does. An object that survives validation\nREPLACES the stored one wholesale — it is not a patch, so a partial payload drops\nthe members it omits.\n\nAn object that validates down to nothing — `{}`, or one carrying only\n`onlyDomains: []` / `keepDomains: []` — is treated as if the key were omitted:\n200, stored settings untouched. `excludeDomains: []` is the deliberate exception:\nit survives, so the payload DOES replace the stored object and drops every member\nit omits. It records \"captured with no exclusions\", which a later flagless refresh\nreplays instead of re-reading the refreshing machine's own config." } }, "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" }, "captureSettings": { "$ref": "#/components/schemas/ProfileCaptureSettings", "description": "Capture inputs the CLI used, or null for profiles not created by the CLI. The UI\nderives no capture flag from these; it uses any non-empty object to stamp the CLI\nbadge and show a read-only summary, and reads `browser`/`profile` specifically to\ndecide whether its refresh command needs placeholders for them. The CLI reads the\nrest itself and decides the exclusion behaviour from `excludeDomains`." }, "domainAuth": { "description": "Per-domain auth status + expiry for the saved logins in this profile, with\nstatus classified at read time (valid / expiring_soon / expired / unknown).\nEmpty for profiles saved before this feature, until their next capture,\nupload, or refresh. Never contains a cookie value.", "type": "array", "items": { "$ref": "#/components/schemas/ProfileDomainAuth" } }, "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": [ "captureSettings", "cookieCount", "createdAt", "diagnostics", "domainAuth", "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" }, "skippedMalformedLocalStorageEntries": { "description": "localStorage entries dropped because names or values were not strings.", "type": "number" }, "skippedMalformedIdbIndexes": { "description": "IndexedDB indexes dropped because required fields were malformed.", "type": "number" } }, "additionalProperties": false, "required": [ "skippedMalformedCookies", "skippedMalformedIdbDatabases", "skippedMalformedIdbIndexes", "skippedMalformedIdbStores", "skippedMalformedLocalStorageEntries", "skippedMalformedOrigins", "skippedPrivateCookies", "skippedPrivateOrigins", "truncatedIdbDatabases", "truncatedIdbEntries", "truncatedOrigins" ] }, "ProfileCaptureSettings": { "description": "Capture inputs the CLI ran with, so a later `profile refresh` can replay them\nwithout flags. Null for the CDP saveProfile path and any future non-CLI creator.\nNever holds the token, and omits server/region because a stale stored region\nis a guaranteed 404.", "type": "object", "properties": { "browser": { "description": "Raw `--browser` value.", "type": "string" }, "profile": { "description": "Raw `--profile` value (source profile directory or display name).", "type": "string" }, "excludeDomains": { "description": "Effective merged exclusion list. `[]` is meaningful — \"captured with no\nexclusions\" — and distinct from absent, which means \"unknown\".", "type": "array", "items": { "type": "string" } }, "onlyDomains": { "description": "Normalized `--only-domain` hostnames, deduped and capped — not merged with local config.", "type": "array", "items": { "type": "string" } }, "keepDomains": { "description": "Normalized `--keep-domain` hostnames, same normalization, no merge.", "type": "array", "items": { "type": "string" } }, "autoFit": { "description": "Whether `--auto-fit` was used.", "type": "boolean" }, "passwordStore": { "description": "Raw `--password-store` value. Linux only.", "type": "string" }, "cliVersion": { "description": "CLI version that produced these settings, for drift diagnosis.", "type": "string" } }, "additionalProperties": false }, "ProfileDomainAuth": { "description": "Response shape: the stored snapshot plus its read-time status.", "type": "object", "properties": { "domain": { "type": "string" }, "status": { "$ref": "#/components/schemas/DomainAuthStatus" }, "expiresAt": { "type": "string" } }, "additionalProperties": false, "required": [ "domain", "expiresAt", "status" ] }, "DomainAuthStatus": { "description": "Per-domain auth status, computed at read time from a stored absolute expiry.", "enum": [ "expired", "expiring_soon", "unknown", "valid" ], "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": "/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)." }, "captureSettings": { "$ref": "#/components/schemas/UploadCaptureSettingsPayload", "description": "Capture inputs the CLI ran with, stored so a later `browserless profile refresh`\ncan replay them without flags. Optional — an older CLI omits it. This route is a\nstrict create, so there is nothing to preserve: the profile is created with these\nsettings, or with none.\n\nAn object that validates down to nothing — `{}`, or one carrying only\n`onlyDomains: []` / `keepDomains: []` — is stored as `null`, the same as omitting\nthe key. `excludeDomains: []` is the deliberate exception: it survives and records\n\"captured with no exclusions\", which a later flagless refresh replays instead of\nre-reading the refreshing machine's own config." } }, "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" }, "captureSettings": { "$ref": "#/components/schemas/ProfileCaptureSettings", "description": "Capture inputs the CLI used, or null for profiles not created by the CLI. The UI\nderives no capture flag from these; it uses any non-empty object to stamp the CLI\nbadge and show a read-only summary, and reads `browser`/`profile` specifically to\ndecide whether its refresh command needs placeholders for them. The CLI reads the\nrest itself and decides the exclusion behaviour from `excludeDomains`." }, "domainAuth": { "description": "Per-domain auth status + expiry for the saved logins in this profile, with\nstatus classified at read time (valid / expiring_soon / expired / unknown).\nEmpty for profiles saved before this feature, until their next capture,\nupload, or refresh. Never contains a cookie value.", "type": "array", "items": { "$ref": "#/components/schemas/ProfileDomainAuth" } }, "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": [ "captureSettings", "cookieCount", "createdAt", "diagnostics", "domainAuth", "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" }, "skippedMalformedLocalStorageEntries": { "description": "localStorage entries dropped because names or values were not strings.", "type": "number" }, "skippedMalformedIdbIndexes": { "description": "IndexedDB indexes dropped because required fields were malformed.", "type": "number" } }, "additionalProperties": false, "required": [ "skippedMalformedCookies", "skippedMalformedIdbDatabases", "skippedMalformedIdbIndexes", "skippedMalformedIdbStores", "skippedMalformedLocalStorageEntries", "skippedMalformedOrigins", "skippedPrivateCookies", "skippedPrivateOrigins", "truncatedIdbDatabases", "truncatedIdbEntries", "truncatedOrigins" ] }, "ProfileCaptureSettings": { "description": "Capture inputs the CLI ran with, so a later `profile refresh` can replay them\nwithout flags. Null for the CDP saveProfile path and any future non-CLI creator.\nNever holds the token, and omits server/region because a stale stored region\nis a guaranteed 404.", "type": "object", "properties": { "browser": { "description": "Raw `--browser` value.", "type": "string" }, "profile": { "description": "Raw `--profile` value (source profile directory or display name).", "type": "string" }, "excludeDomains": { "description": "Effective merged exclusion list. `[]` is meaningful — \"captured with no\nexclusions\" — and distinct from absent, which means \"unknown\".", "type": "array", "items": { "type": "string" } }, "onlyDomains": { "description": "Normalized `--only-domain` hostnames, deduped and capped — not merged with local config.", "type": "array", "items": { "type": "string" } }, "keepDomains": { "description": "Normalized `--keep-domain` hostnames, same normalization, no merge.", "type": "array", "items": { "type": "string" } }, "autoFit": { "description": "Whether `--auto-fit` was used.", "type": "boolean" }, "passwordStore": { "description": "Raw `--password-store` value. Linux only.", "type": "string" }, "cliVersion": { "description": "CLI version that produced these settings, for drift diagnosis.", "type": "string" } }, "additionalProperties": false }, "ProfileDomainAuth": { "description": "Response shape: the stored snapshot plus its read-time status.", "type": "object", "properties": { "domain": { "type": "string" }, "status": { "$ref": "#/components/schemas/DomainAuthStatus" }, "expiresAt": { "type": "string" } }, "additionalProperties": false, "required": [ "domain", "expiresAt", "status" ] }, "DomainAuthStatus": { "description": "Per-domain auth status, computed at read time from a stored absolute expiry.", "enum": [ "expired", "expiring_soon", "unknown", "valid" ], "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": "/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.\n\n**Note:** This endpoint is also available at: `/management/integrations/onepassword` for backwards compatibility.", "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.\n\n**Note:** This endpoint is also available at: `/management/integrations/onepassword` 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": "blockAdsInclude", "schema": { "description": "Ruleset IDs to load when `blockAds` is enabled, as CSV or JSON-array text.", "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": "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.\n\n**Note:** This endpoint is also available at: `/management/integrations/onepassword/*` for backwards compatibility.", "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.\n\n**Note:** This endpoint is also available at: `/management/integrations/onepassword/*` for backwards compatibility.", "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 activity for a single 1Password integration owned\nby the token, newest first. One entry per Browserless.loadSecret or\nsaveSecret attempt: outcome, error code, the credential reference, and\nnon-secret target metadata. Secret values are 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.\n\n**Note:** This endpoint is also available at: `/management/integrations/onepassword/*/audit` 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": "blockAdsInclude", "schema": { "description": "Ruleset IDs to load when `blockAds` is enabled, as CSV or JSON-array text.", "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": "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 credential operation used.", "type": "string" }, "profileId": { "description": "Authentication profile associated with the operation, 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 filled, `saved` if created, otherwise `failure`." }, "errorCode": { "description": "Error code when the outcome is `failure`, otherwise null.", "type": "string" }, "createdAt": { "description": "ISO timestamp of the operation.", "type": "string" } }, "additionalProperties": false, "required": [ "createdAt", "errorCode", "id", "integrationId", "outcome", "profileId", "secretRef", "targetDescriptor", "targetOrigin", "targetSelector" ] }, "OpAuditOutcome": { "description": "Outcome recorded for a Browserless.loadSecret or saveSecret attempt.", "enum": [ "failure", "saved", "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.", "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "properties": { "name": { "description": "Name to save the resulting profile under. Unique per token.", "type": "string" }, "integrationId": { "description": "Registered 1Password integration id.", "type": "string" }, "recover": { "description": "Refresh an existing owned profile instead of creating a new one.", "type": "boolean" }, "allowedDomains": { "description": "Optional subset of the integration's allowed domains.", "type": "array", "items": { "type": "string" } }, "emailOtp": { "type": "array", "items": { "type": "object", "properties": { "origin": { "type": "string" }, "vault": { "type": "string" }, "item": { "type": "string" } }, "additionalProperties": false, "required": [ "item", "origin", "vault" ] } }, "proxy": { "description": "Optional proxy for the browser session the agent logs in through. Omitted\n→ the run goes direct, so it never bills proxy traffic implicitly.", "type": "object", "properties": { "type": { "enum": [ "datacenter", "residential" ], "type": "string" }, "sticky": { "type": "boolean" }, "country": { "type": "string" }, "city": { "type": "string" }, "state": { "type": "string" }, "preset": { "type": "string" } }, "additionalProperties": false }, "attemptId": { "description": "Optional profile-setup funnel correlation UUID.", "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 account (or token, for keys not yet mapped to an account) —\nreturns 404 for unknown ids or another account'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" }, "errorCode": { "type": "string" }, "reason": { "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": "blockAdsInclude", "schema": { "description": "Ruleset IDs to load when `blockAds` is enabled, as CSV or JSON-array text.", "type": "string" } }, { "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": "profileName", "schema": { "description": "Recovery only: restrict choices to this tenant-owned saved artifact.", "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" ] } }, "inboxCandidates": { "type": "array", "items": { "$ref": "#/components/schemas/InboxCandidate" } } }, "additionalProperties": false, "required": [ "domains", "inboxCandidates", "integrationId" ], "definitions": { "InboxCandidate": { "type": "object", "properties": { "vault": { "type": "string" }, "item": { "type": "string" }, "label": { "type": "string" } }, "additionalProperties": false, "required": [ "item", "label", "vault" ] } }, "$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": "blockAdsInclude", "schema": { "description": "Ruleset IDs to load when `blockAds` is enabled, as CSV or JSON-array text.", "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": "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.\nOnly applies to the residential network; the datacenter pool ignores it.\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. Off by default.", "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": "blockAdsInclude", "schema": { "description": "Ruleset IDs to load when `blockAds` is enabled, as CSV or JSON-array text.", "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": "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.\nOnly applies to the residential network; the datacenter pool ignores it.\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. Off by default.", "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": "blockAdsInclude", "schema": { "description": "Ruleset IDs to load when `blockAds` is enabled, as CSV or JSON-array text.", "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/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.\nOnly applies to the residential network; the datacenter pool ignores it.\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. Off by default.", "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": "blockAdsInclude", "schema": { "description": "Ruleset IDs to load when `blockAds` is enabled, as CSV or JSON-array text.", "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": "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.\nOnly applies to the residential network; the datacenter pool ignores it.\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. Off by default.", "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": "blockAdsInclude", "schema": { "description": "Ruleset IDs to load when `blockAds` is enabled, as CSV or JSON-array text.", "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/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.\nOnly applies to the residential network; the datacenter pool ignores it.\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. Off by default.", "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": "blockAdsInclude", "schema": { "description": "Ruleset IDs to load when `blockAds` is enabled, as CSV or JSON-array text.", "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.", "additionalProperties": false, "type": "object", "properties": { "args": { "type": "array", "items": { "type": "string" } }, "chromiumSandbox": { "type": "boolean" }, "devtools": { "type": "boolean" }, "downloadsPath": { "type": "string" }, "env": { "description": "Environment for the browser process. Honored by both puppeteer.launch and\nplaywright.launchServer. Set server-side to give the session its own TMPDIR\n(see generateScratchDir); a caller-supplied value is merged under it, since\na session must not be able to point its scratch back at the shared temp dir.\n\nThat merge happens on the object handed to `launch` only. It is kept off\nthe session's stored `launchOptions`, which /sessions serves verbatim.", "$ref": "#/components/schemas/Record" }, "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.\nOnly applies to the residential network; the datacenter pool ignores it.\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. Off by default.", "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": "blockAdsInclude", "schema": { "description": "Ruleset IDs to load when `blockAds` is enabled, as CSV or JSON-array text.", "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/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.\nOnly applies to the residential network; the datacenter pool ignores it.\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. Off by default.", "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": "Websocket 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.\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": "blockAdsInclude", "schema": { "description": "Ruleset IDs to load when `blockAds` is enabled, as CSV or JSON-array text.", "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": "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.\nOnly applies to the residential network; the datacenter pool ignores it.\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. Off by default.", "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": "blockAdsInclude", "schema": { "description": "Ruleset IDs to load when `blockAds` is enabled, as CSV or JSON-array text.", "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" }, { "$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.\nOnly applies to the residential network; the datacenter pool ignores it.\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. Off by default.", "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.\nOnly applies to the residential network; the datacenter pool ignores it.\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. Off by default.", "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": "blockAdsInclude", "schema": { "description": "Ruleset IDs to load when `blockAds` is enabled, as CSV or JSON-array text.", "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": "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.\nOnly applies to the residential network; the datacenter pool ignores it.\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. Off by default.", "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": "blockAdsInclude", "schema": { "description": "Ruleset IDs to load when `blockAds` is enabled, as CSV or JSON-array text.", "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": "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.\nOnly applies to the residential network; the datacenter pool ignores it.\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. Off by default.", "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": "blockAdsInclude", "schema": { "description": "Ruleset IDs to load when `blockAds` is enabled, as CSV or JSON-array text.", "type": "string" } }, { "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.\nOnly applies to the residential network; the datacenter pool ignores it.\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. Off by default.", "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).\nselectors. Debugging information is available by sending in the appropriate\nflags in the \"debugOpts\" property. Responds with an array of JSON objects.", "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": "Ruleset IDs to load when `blockAds` is enabled, as CSV or JSON-array text.", "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.\nOnly applies to the residential network; the datacenter pool ignores it.\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. Off by default.", "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": { "addScriptTag": { "type": "array", "items": { "$ref": "#/components/schemas/FrameAddScriptTagOptions" } }, "addStyleTag": { "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 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": { "type": "object", "properties": { "console": { "type": "boolean" }, "cookies": { "type": "boolean" }, "html": { "type": "boolean" }, "network": { "type": "boolean" }, "screenshot": { "type": "boolean" } }, "additionalProperties": false }, "elements": { "type": "array", "items": { "$ref": "#/components/schemas/ScrapeElementSelector" } }, "emulateMediaType": { "type": "string" }, "gotoOptions": { "description": "The supported subset of puppeteer's goto options: `waitUntil` (mapped onto\nbap-ts's set — an array reduces to its first entry), `timeout` (clamped to\nthe route ceiling), and `referer`. Other puppeteer goto fields are not\nforwarded.", "type": "object", "properties": { "timeout": { "type": "number" }, "waitUntil": { "anyOf": [ { "type": "array", "items": { "$ref": "#/components/schemas/PuppeteerLifeCycleEvent" } }, { "enum": [ "domcontentloaded", "load", "networkidle0", "networkidle2" ], "type": "string" } ] }, "referer": { "type": "string" } }, "additionalProperties": false }, "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": { "status": { "type": "number" }, "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." }, "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": { "$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": { "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": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/ScrapeGroupResult" } }, "debug": { "type": "object", "properties": { "console": { "type": "array", "items": { "type": "string" } }, "cookies": { "type": "array", "items": { "$ref": "#/components/schemas/Cookie" } }, "html": { "type": "string" }, "network": { "type": "object", "properties": { "inbound": { "type": "array", "items": { "$ref": "#/components/schemas/InboundResponse" } }, "outbound": { "type": "array", "items": { "$ref": "#/components/schemas/OutboundRequest" } } }, "additionalProperties": false, "required": [ "inbound", "outbound" ] }, "screenshot": { "type": "string" } }, "additionalProperties": false, "required": [ "console", "cookies", "html", "network", "screenshot" ] } }, "additionalProperties": false, "required": [ "data", "debug" ], "definitions": { "ScrapeGroupResult": { "type": "object", "properties": { "results": { "type": "array", "items": { "$ref": "#/components/schemas/ScrapeElementResult" } }, "selector": { "type": "string" } }, "additionalProperties": false, "required": [ "results", "selector" ] }, "ScrapeElementResult": { "type": "object", "properties": { "attributes": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "value": { "type": "string" } }, "additionalProperties": false, "required": [ "name", "value" ] } }, "height": { "type": "number" }, "html": { "type": "string" }, "left": { "type": "number" }, "text": { "type": "string" }, "top": { "type": "number" }, "width": { "type": "number" } }, "additionalProperties": false, "required": [ "attributes", "height", "html", "left", "text", "top", "width" ] }, "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": { "$ref": "#/components/schemas/CookieSameSite_2", "description": "Cookie SameSite type." }, "priority": { "$ref": "#/components/schemas/CookiePriority", "description": "Cookie Priority. Supported only in Chrome." }, "sourceScheme": { "$ref": "#/components/schemas/CookieSourceScheme", "description": "Cookie source scheme type. Supported only in Chrome." }, "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" ] }, "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" }, "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" ] }, "InboundResponse": { "type": "object", "properties": { "headers": { "$ref": "#/components/schemas/StringRecord" }, "status": { "type": "number" }, "url": { "type": "string" } }, "additionalProperties": false, "required": [ "headers", "status", "url" ] }, "Record": { "type": "object", "additionalProperties": false }, "OutboundRequest": { "type": "object", "properties": { "headers": { "$ref": "#/components/schemas/StringRecord" }, "method": { "type": "string" }, "url": { "type": "string" } }, "additionalProperties": false, "required": [ "headers", "method", "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": "/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": "blockAdsInclude", "schema": { "description": "Ruleset IDs to load when `blockAds` is enabled, as CSV or JSON-array text.", "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": "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.\nOnly applies to the residential network; the datacenter pool ignores it.\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. Off by default.", "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": "blockAdsInclude", "schema": { "description": "Ruleset IDs to load when `blockAds` is enabled, as CSV or JSON-array text.", "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": "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.\nOnly applies to the residential network; the datacenter pool ignores it.\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. Off by default.", "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": "blockAdsInclude", "schema": { "description": "Ruleset IDs to load when `blockAds` is enabled, as CSV or JSON-array text.", "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": "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.\nOnly applies to the residential network; the datacenter pool ignores it.\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. Off by default.", "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": "blockAdsInclude", "schema": { "description": "Ruleset IDs to load when `blockAds` is enabled, as CSV or JSON-array text.", "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.\nOnly applies to the residential network; the datacenter pool ignores it.\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. Off by default.", "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": "Ruleset IDs to load when `blockAds` is enabled, as CSV or JSON-array text.", "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": "emulationOs", "schema": { "$ref": "#/components/schemas/Platform", "description": "OS to emulate: `windows`/`macos`/`linux`/`android`. Omitted → native Linux\nwith no device profile; an explicit `linux` still gets one." } }, { "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.\nOnly applies to the residential network; the datacenter pool ignores it.\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. Off by default.", "enum": [ "0", "1", "false", "true" ], "type": "string" } }, { "in": "query", "name": "replay", "schema": { "description": "Records the unblock session for replay (rrweb) and uploads on cleanup, reusing the\nBQL pipeline. Connection-level flag via `?replay=true`. Defaults to false.", "type": "boolean" } }, { "in": "query", "name": "solveCaptchas", "schema": { "description": "With `browserWSEndpoint`, persists captcha-solving on the kept-alive session so\nreconnects auto-solve. Connection-level flag via `?solveCaptchas=true`. Defaults 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 true, browserless proceeds when \"awaited\" events fail or timeout\n(goto, waitForSelector, and more).", "type": "boolean" }, "url": { "description": "The URL of the site you want to unblock.", "type": "string" }, "browserWSEndpoint": { "description": "Whether or not to keep the underlying browser alive and around for\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": "How long to keep the browser alive for re-connection when browserWSEndpoint\nis requested. Maximum of 30000 (30 seconds).", "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": "Time the browser stays alive until shutdown; zero when browserWSEndpoint: false.\nLimit is 60000 (60 seconds).", "type": "number" }, "screenshot": { "description": "A base64 encoded JPEG of the of the final site page.", "type": "string" }, "solved": { "description": "Whether a detected anti-bot challenge was successfully solved during the unblock.\nFalse when none was present or a present one could not be solved.", "type": "boolean" } }, "additionalProperties": false, "required": [ "browserWSEndpoint", "content", "cookies", "screenshot", "solved", "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": "blockAdsInclude", "schema": { "description": "Ruleset IDs to load when `blockAds` is enabled, as CSV or JSON-array text.", "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": "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.\nOnly applies to the residential network; the datacenter pool ignores it.\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. Off by default.", "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": "blockAdsInclude", "schema": { "description": "Ruleset IDs to load when `blockAds` is enabled, as CSV or JSON-array text.", "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/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.\nOnly applies to the residential network; the datacenter pool ignores it.\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. Off by default.", "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": "blockAdsInclude", "schema": { "description": "Ruleset IDs to load when `blockAds` is enabled, as CSV or JSON-array text.", "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": "deviceScaleFactor", "schema": { "description": "Device pixel ratio for the desktop screen above (allowed: 1 or 1.25).\nOmit to default to the seeded/profile scale. Ignored for emulationOs=android.", "type": "number" } }, { "in": "query", "name": "deviceSlot", "schema": { "description": "Pin this session to one of your identity's N stable device slots (0-based,\ndefault N=8). Each slot is one virtual machine: its GPU, screen, cores, memory\nand OS version stay fixed across sessions, so traffic spreads over N machines\ninstead of clustering on one. Requires a desktop emulationOs.", "type": "number" } }, { "in": "query", "name": "emulatedDevice", "schema": { "description": "Device model for mobile personas (emulationOs=android), e.g. \"pixel-8\",\n\"galaxy-s23\". Omit to auto-pick a device seeded per session (stable per\nidentity, spread across the fleet); an unknown slug does the same.", "type": "string" } }, { "in": "query", "name": "emulationOs", "schema": { "$ref": "#/components/schemas/Platform", "description": "Spoof OS for full per-platform stealth: windows | macos | linux | android." } }, { "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.\nOnly applies to the residential network; the datacenter pool ignores it.\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. Off by default.", "enum": [ "0", "1", "false", "true" ], "type": "string" } }, { "in": "query", "name": "record", "schema": { "type": "boolean" } }, { "in": "query", "name": "replay", "schema": { "type": "boolean" } }, { "in": "query", "name": "screen", "schema": { "description": "Desktop screen resolution as WIDTHxHEIGHT (e.g. '1920x1080'). Sets the\nreported screen.*, window size and (with deviceScaleFactor) DPR for a\ndesktop persona. Omit to auto-pick a screen seeded per session (stable per\nidentity, spread across the fleet). Ignored for emulationOs=android.", "type": "string" } }, { "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": "blockAdsInclude", "schema": { "description": "Ruleset IDs to load when `blockAds` is enabled, as CSV or JSON-array text.", "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": "deviceScaleFactor", "schema": { "description": "Device pixel ratio for the desktop screen above (allowed: 1 or 1.25).\nOmit to default to the seeded/profile scale. Ignored for emulationOs=android.", "type": "number" } }, { "in": "query", "name": "deviceSlot", "schema": { "description": "Pin this session to one of your identity's N stable device slots (0-based,\ndefault N=8). Each slot is one virtual machine: its GPU, screen, cores, memory\nand OS version stay fixed across sessions, so traffic spreads over N machines\ninstead of clustering on one. Requires a desktop emulationOs.", "type": "number" } }, { "in": "query", "name": "emulatedDevice", "schema": { "description": "Device model for mobile personas (emulationOs=android), e.g. \"pixel-8\",\n\"galaxy-s23\". Omit to auto-pick a device seeded per session (stable per\nidentity, spread across the fleet); an unknown slug does the same.", "type": "string" } }, { "in": "query", "name": "emulationOs", "schema": { "$ref": "#/components/schemas/Platform", "description": "Spoof OS for full per-platform stealth: windows | macos | linux | android." } }, { "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.\nOnly applies to the residential network; the datacenter pool ignores it.\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. Off by default.", "enum": [ "0", "1", "false", "true" ], "type": "string" } }, { "in": "query", "name": "record", "schema": { "type": "boolean" } }, { "in": "query", "name": "replay", "schema": { "type": "boolean" } }, { "in": "query", "name": "screen", "schema": { "description": "Desktop screen resolution as WIDTHxHEIGHT (e.g. '1920x1080'). Sets the\nreported screen.*, window size and (with deviceScaleFactor) DPR for a\ndesktop persona. Omit to auto-pick a screen seeded per session (stable per\nidentity, spread across the fleet). Ignored for emulationOs=android.", "type": "string" } }, { "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": "blockAdsInclude", "schema": { "description": "Ruleset IDs to load when `blockAds` is enabled, as CSV or JSON-array text.", "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": "deviceScaleFactor", "schema": { "description": "Device pixel ratio for the desktop screen above (allowed: 1 or 1.25).\nOmit to default to the seeded/profile scale. Ignored for emulationOs=android.", "type": "number" } }, { "in": "query", "name": "deviceSlot", "schema": { "description": "Pin this session to one of your identity's N stable device slots (0-based,\ndefault N=8). Each slot is one virtual machine: its GPU, screen, cores, memory\nand OS version stay fixed across sessions, so traffic spreads over N machines\ninstead of clustering on one. Requires a desktop emulationOs.", "type": "number" } }, { "in": "query", "name": "emulatedDevice", "schema": { "description": "Device model for mobile personas (emulationOs=android), e.g. \"pixel-8\",\n\"galaxy-s23\". Omit to auto-pick a device seeded per session (stable per\nidentity, spread across the fleet); an unknown slug does the same.", "type": "string" } }, { "in": "query", "name": "emulationOs", "schema": { "$ref": "#/components/schemas/Platform", "description": "Spoof OS for full per-platform stealth: windows | macos | linux | android." } }, { "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.\nOnly applies to the residential network; the datacenter pool ignores it.\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. Off by default.", "enum": [ "0", "1", "false", "true" ], "type": "string" } }, { "in": "query", "name": "record", "schema": { "type": "boolean" } }, { "in": "query", "name": "replay", "schema": { "type": "boolean" } }, { "in": "query", "name": "screen", "schema": { "description": "Desktop screen resolution as WIDTHxHEIGHT (e.g. '1920x1080'). Sets the\nreported screen.*, window size and (with deviceScaleFactor) DPR for a\ndesktop persona. Omit to auto-pick a screen seeded per session (stable per\nidentity, spread across the fleet). Ignored for emulationOs=android.", "type": "string" } }, { "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": "Websocket 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" ] } }, "/agent/run": { "get": { "description": "List the caller's agent runs, newest first, with cursor pagination.", "parameters": [ { "in": "query", "name": "cursor", "schema": { "description": "Opaque pagination cursor from a previous response.", "type": "string" } }, { "in": "query", "name": "limit", "schema": { "description": "Page size, 1-100.", "type": "number" } }, { "in": "query", "name": "status", "schema": { "description": "Filter by run status.", "type": "string" } }, { "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.\nOnly applies to the residential network; the datacenter pool ignores it.\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. Off by default.", "enum": [ "0", "1", "false", "true" ], "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": "/agent/run", "tags": [ "Agent" ], "operationId": "agent-run-get-2" }, "post": { "description": "Start an asynchronous AI agent run: a managed agent drives a real browser against a natural-language task and returns a structured JSON result. Returns a run ID to poll via GET /agent/run/{id}.", "parameters": [ { "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.\nOnly applies to the residential network; the datacenter pool ignores it.\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. Off by default.", "enum": [ "0", "1", "false", "true" ], "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "query": { "description": "Natural-language task for the agent. Minimum 10 characters.", "type": "string" }, "timeout": { "description": "Per-turn timeout in ms, clamped to [10000, 900000] (15-min hard cap).", "type": "number" }, "webhook": { "description": "Optional webhook POSTed the result envelope on terminal states.", "type": "object", "properties": { "url": { "type": "string" }, "events": { "type": "array", "items": { "enum": [ "failed", "succeeded" ], "type": "string" } } }, "additionalProperties": false, "required": [ "url" ] }, "responseSchema": { "description": "Best-effort JSON schema for the agent's final answer.", "type": "object", "properties": {}, "additionalProperties": true }, "maxSteps": { "description": "Soft cap on browser tool calls. Default 60, hard cap 90.", "type": "number" }, "allowedDomains": { "description": "Navigation allowlist.", "type": "array", "items": { "type": "string" } }, "startUrl": { "description": "First navigation target.", "type": "string" }, "proxy": { "description": "Route browsing through a residential or datacenter proxy. Best-effort like\nthe other hints below: injected into the agent's prompt, not enforced.", "enum": [ "datacenter", "residential" ], "type": "string" }, "proxyCountry": { "description": "Two-letter country code for the proxy exit (e.g. `US`).", "type": "string" }, "stealth": { "description": "Ask the agent to use stealth / anti-bot-detection mode.", "type": "boolean" }, "solveCaptchas": { "description": "Ask the agent to solve CAPTCHAs it encounters.", "type": "boolean" }, "profile": { "description": "Name of a saved authentication profile to reuse.", "type": "string" }, "replay": { "description": "Opt in to recording the run as a session replay, listed in the account\ndashboard. Enforced on the worker-owned session, not suggested to the model.\nRuns falling back to an MCP-owned session are not recorded.", "type": "boolean" }, "formats": { "description": "Page captures to return with the result, taken from the agent's current\ntab when the run ends. Omit for none.", "type": "array", "items": { "enum": [ "html", "links", "markdown", "screenshot" ], "type": "string" } } }, "type": "object", "required": [ "query" ] } } } }, "responses": { "200": { "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "status": { "type": "string" } }, "additionalProperties": false, "required": [ "id", "status" ], "$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": "/agent/run", "tags": [ "Agent" ], "operationId": "agent-run-post-3" } }, "/agent/run/*": { "delete": { "description": "Cancel a pending/running agent run (→ stopped, aborting the in-flight turn) or delete a terminal one.", "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": "/agent/run/*", "tags": [ "Agent" ], "operationId": "agent-run" }, "get": { "description": "Poll an agent run: its status, the latest turn result and streamed step rationales, and the full turn transcript.", "parameters": [ { "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.\nOnly applies to the residential network; the datacenter pool ignores it.\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. Off by default.", "enum": [ "0", "1", "false", "true" ], "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": "/agent/run/*", "tags": [ "Agent" ], "operationId": "agent-run-get-1" } }, "/agent/run/*/continue": { "post": { "description": "Continue a multi-turn agent run with a follow-up task. Not enabled in v1.", "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "properties": { "query": { "description": "Follow-up task for the next turn.", "type": "string" } }, "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": "/agent/run/*/continue", "tags": [ "Agent" ] } }, "/browser/*/live": { "post": { "description": "Creates a view-only live URL for a currently-running browser, identified by\nbrowserId. Hosted authenticated Cloud plans, including Free, can use this\nroute. Explicitly disabled and unlicensed deployments remain ineligible.", "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/*/live", "tags": [ "Browser Management" ] } }, "/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": "Ruleset IDs to load when `blockAds` is enabled, as CSV or JSON-array text.", "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": "deviceScaleFactor", "schema": { "description": "Device pixel ratio for the desktop screen above (allowed: 1 or 1.25).\nOmit to default to the seeded/profile scale. Ignored for emulationOs=android.", "type": "number" } }, { "in": "query", "name": "deviceSlot", "schema": { "description": "Pin this session to one of your identity's N stable device slots (0-based,\ndefault N=8). Each slot is one virtual machine: its GPU, screen, cores, memory\nand OS version stay fixed across sessions, so traffic spreads over N machines\ninstead of clustering on one. Requires a desktop emulationOs.", "type": "number" } }, { "in": "query", "name": "emulatedDevice", "schema": { "description": "Device model for the mobile persona (emulationOs=android): a device slug such\nas 'pixel-8', 'pixel-8-pro', 'galaxy-s23', 'galaxy-s23-ultra'. Drives the\nUA-CH model/version, viewport/DPR, touch points, cores, memory and GPU string.\nOmit to auto-pick a device seeded per session (stable per identity, spread\nacross the fleet; an unknown slug does the same). Requires emulationOs=android\non a stealth request — sent otherwise, the request is rejected with 400.", "type": "string" } }, { "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.\nOnly applies to the residential network; the datacenter pool ignores it.\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. Off by default.", "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": "screen", "schema": { "description": "Desktop screen resolution as WIDTHxHEIGHT (e.g. '1920x1080'). Sets the\nreported screen.*, window size and (with deviceScaleFactor) DPR for a\ndesktop persona. Omit to auto-pick a screen seeded per session (stable per\nidentity, spread across the fleet). Ignored for emulationOs=android.", "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": { "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": "Ruleset IDs to load when `blockAds` is enabled, as CSV or JSON-array text.", "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": "deviceScaleFactor", "schema": { "description": "Device pixel ratio for the desktop screen above (allowed: 1 or 1.25).\nOmit to default to the seeded/profile scale. Ignored for emulationOs=android.", "type": "number" } }, { "in": "query", "name": "deviceSlot", "schema": { "description": "Pin this session to one of your identity's N stable device slots (0-based,\ndefault N=8). Each slot is one virtual machine: its GPU, screen, cores, memory\nand OS version stay fixed across sessions, so traffic spreads over N machines\ninstead of clustering on one. Requires a desktop emulationOs.", "type": "number" } }, { "in": "query", "name": "emulatedDevice", "schema": { "description": "Device model for the mobile persona (emulationOs=android): a device slug such\nas 'pixel-8', 'pixel-8-pro', 'galaxy-s23', 'galaxy-s23-ultra'. Drives the\nUA-CH model/version, viewport/DPR, touch points, cores, memory and GPU string.\nOmit to auto-pick a device seeded per session (stable per identity, spread\nacross the fleet; an unknown slug does the same). Requires emulationOs=android\non a stealth request — sent otherwise, the request is rejected with 400.", "type": "string" } }, { "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.\nOnly applies to the residential network; the datacenter pool ignores it.\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. Off by default.", "enum": [ "0", "1", "false", "true" ], "type": "string" } }, { "in": "query", "name": "replay", "schema": { "type": "boolean" } }, { "in": "query", "name": "screen", "schema": { "description": "Desktop screen resolution as WIDTHxHEIGHT (e.g. '1920x1080'). Sets the\nreported screen.*, window size and (with deviceScaleFactor) DPR for a\ndesktop persona. Omit to auto-pick a screen seeded per session (stable per\nidentity, spread across the fleet). Ignored for emulationOs=android.", "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": "/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": "blockAdsInclude", "schema": { "description": "Ruleset IDs to load when `blockAds` is enabled, as CSV or JSON-array text.", "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": "deviceScaleFactor", "schema": { "description": "Device pixel ratio for the desktop screen above (allowed: 1 or 1.25).\nOmit to default to the seeded/profile scale. Ignored for emulationOs=android.", "type": "number" } }, { "in": "query", "name": "deviceSlot", "schema": { "description": "Pin this session to one of your identity's N stable device slots (0-based,\ndefault N=8). Each slot is one virtual machine: its GPU, screen, cores, memory\nand OS version stay fixed across sessions, so traffic spreads over N machines\ninstead of clustering on one. Requires a desktop emulationOs.", "type": "number" } }, { "in": "query", "name": "emulatedDevice", "schema": { "description": "Device model for mobile personas (emulationOs=android), e.g. \"pixel-8\",\n\"galaxy-s23\". Omit to auto-pick a device seeded per session (stable per\nidentity, spread across the fleet); an unknown slug does the same.", "type": "string" } }, { "in": "query", "name": "emulationOs", "schema": { "$ref": "#/components/schemas/Platform", "description": "Spoof OS for full per-platform stealth: windows | macos | linux | android." } }, { "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.\nOnly applies to the residential network; the datacenter pool ignores it.\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. Off by default.", "enum": [ "0", "1", "false", "true" ], "type": "string" } }, { "in": "query", "name": "record", "schema": { "type": "boolean" } }, { "in": "query", "name": "replay", "schema": { "type": "boolean" } }, { "in": "query", "name": "screen", "schema": { "description": "Desktop screen resolution as WIDTHxHEIGHT (e.g. '1920x1080'). Sets the\nreported screen.*, window size and (with deviceScaleFactor) DPR for a\ndesktop persona. Omit to auto-pick a screen seeded per session (stable per\nidentity, spread across the fleet). Ignored for emulationOs=android.", "type": "string" } }, { "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": [ "Agent" ] } }, "/chromium/agent/capabilities": { "get": { "description": "Returns the versioned capabilities declared by the Chromium agent route.\nSupply the intended route query parameters so authentication and plan checks\ncan reject unsupported combinations before a browser is allocated.", "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": "Ruleset IDs to load when `blockAds` is enabled, as CSV or JSON-array text.", "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": "deviceScaleFactor", "schema": { "description": "Device pixel ratio for the desktop screen above (allowed: 1 or 1.25).\nOmit to default to the seeded/profile scale. Ignored for emulationOs=android.", "type": "number" } }, { "in": "query", "name": "deviceSlot", "schema": { "description": "Pin this session to one of your identity's N stable device slots (0-based,\ndefault N=8). Each slot is one virtual machine: its GPU, screen, cores, memory\nand OS version stay fixed across sessions, so traffic spreads over N machines\ninstead of clustering on one. Requires a desktop emulationOs.", "type": "number" } }, { "in": "query", "name": "emulatedDevice", "schema": { "description": "Device model for mobile personas (emulationOs=android), e.g. \"pixel-8\",\n\"galaxy-s23\". Omit to auto-pick a device seeded per session (stable per\nidentity, spread across the fleet); an unknown slug does the same.", "type": "string" } }, { "in": "query", "name": "emulationOs", "schema": { "$ref": "#/components/schemas/Platform", "description": "Spoof OS for full per-platform stealth: windows | macos | linux | android." } }, { "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.\nOnly applies to the residential network; the datacenter pool ignores it.\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. Off by default.", "enum": [ "0", "1", "false", "true" ], "type": "string" } }, { "in": "query", "name": "record", "schema": { "type": "boolean" } }, { "in": "query", "name": "replay", "schema": { "type": "boolean" } }, { "in": "query", "name": "screen", "schema": { "description": "Desktop screen resolution as WIDTHxHEIGHT (e.g. '1920x1080'). Sets the\nreported screen.*, window size and (with deviceScaleFactor) DPR for a\ndesktop persona. Omit to auto-pick a screen seeded per session (stable per\nidentity, spread across the fleet). Ignored for emulationOs=android.", "type": "string" } }, { "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": { "200": { "content": { "application/json": { "schema": { "type": "object", "properties": { "version": { "type": "number", "const": 1, "default": 1 }, "route": { "type": "string", "const": "/chromium/agent" }, "capabilities": { "type": "object", "properties": { "vision": { "type": "object", "properties": { "available": { "type": "boolean", "const": true, "default": true }, "primitives": { "type": "array", "items": [ { "type": "string", "const": "screenshot" }, { "type": "string", "const": "viewport" } ], "minItems": 2, "maxItems": 2, "default": [ "screenshot", "viewport" ] }, "availableAt": { "type": "array", "items": [ { "type": "string", "const": "/chromium/agent" } ], "minItems": 1, "maxItems": 1 } }, "additionalProperties": false, "required": [ "available", "availableAt", "primitives" ] }, "os-spoofing": { "type": "object", "properties": { "available": { "type": "boolean", "const": true, "default": true }, "queryParameters": { "type": "array", "items": [ { "type": "string", "const": "emulationOs" } ], "minItems": 1, "maxItems": 1, "default": [ "emulationOs" ] }, "availableAt": { "type": "array", "items": [ { "type": "string", "const": "/chromium/agent" }, { "type": "string", "const": "/stealth/bql" } ], "minItems": 2, "maxItems": 2 } }, "additionalProperties": false, "required": [ "available", "availableAt", "queryParameters" ] }, "datacenter-proxy": { "type": "object", "properties": { "available": { "type": "boolean", "const": true, "default": true }, "queryParameters": { "type": "array", "items": [ { "type": "string", "const": "proxy" } ], "minItems": 1, "maxItems": 1, "default": [ "proxy" ] }, "values": { "type": "array", "items": [ { "type": "string", "const": "datacenter" } ], "minItems": 1, "maxItems": 1, "default": [ "datacenter" ] }, "availableAt": { "type": "array", "items": [ { "type": "string", "const": "/chromium/agent" }, { "type": "string", "const": "/stealth/bql" } ], "minItems": 2, "maxItems": 2 } }, "additionalProperties": false, "required": [ "available", "availableAt", "queryParameters", "values" ] }, "secret-capture": { "type": "object", "properties": { "available": { "type": "boolean", "const": true, "default": true }, "primitives": { "type": "array", "items": [ { "type": "string", "const": "loadSecret" }, { "type": "string", "const": "clearSecrets" }, { "type": "string", "const": "goto" }, { "type": "string", "const": "screenshot" } ], "minItems": 4, "maxItems": 4, "default": [ "loadSecret", "clearSecrets", "goto", "screenshot" ] }, "ordering": { "type": "string", "const": "Run screenshots before loadSecret, or run clearSecrets or a top-frame navigation before capturing.", "default": "Run screenshots before loadSecret, or run clearSecrets or a top-frame navigation before capturing." }, "availableAt": { "type": "array", "items": [ { "type": "string", "const": "/chromium/agent" } ], "minItems": 1, "maxItems": 1 } }, "additionalProperties": false, "required": [ "available", "availableAt", "ordering", "primitives" ] } }, "additionalProperties": false, "required": [ "datacenter-proxy", "os-spoofing", "secret-capture", "vision" ] } }, "additionalProperties": false, "required": [ "capabilities", "route", "version" ], "$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/agent/capabilities", "tags": [ "Management REST APIs", "Browser REST 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": "Ruleset IDs to load when `blockAds` is enabled, as CSV or JSON-array text.", "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": "deviceScaleFactor", "schema": { "description": "Device pixel ratio for the desktop screen above (allowed: 1 or 1.25).\nOmit to default to the seeded/profile scale. Ignored for emulationOs=android.", "type": "number" } }, { "in": "query", "name": "deviceSlot", "schema": { "description": "Pin this session to one of your identity's N stable device slots (0-based,\ndefault N=8). Each slot is one virtual machine: its GPU, screen, cores, memory\nand OS version stay fixed across sessions, so traffic spreads over N machines\ninstead of clustering on one. Requires a desktop emulationOs.", "type": "number" } }, { "in": "query", "name": "emulatedDevice", "schema": { "description": "Device model for the mobile persona (emulationOs=android): a device slug such\nas 'pixel-8', 'pixel-8-pro', 'galaxy-s23', 'galaxy-s23-ultra'. Drives the\nUA-CH model/version, viewport/DPR, touch points, cores, memory and GPU string.\nOmit to auto-pick a device seeded per session (stable per identity, spread\nacross the fleet; an unknown slug does the same). Requires emulationOs=android\non a stealth request — sent otherwise, the request is rejected with 400.", "type": "string" } }, { "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.\nOnly applies to the residential network; the datacenter pool ignores it.\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. Off by default.", "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": "screen", "schema": { "description": "Desktop screen resolution as WIDTHxHEIGHT (e.g. '1920x1080'). Sets the\nreported screen.*, window size and (with deviceScaleFactor) DPR for a\ndesktop persona. Omit to auto-pick a screen seeded per session (stable per\nidentity, spread across the fleet). Ignored for emulationOs=android.", "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": { "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": [ "BQL Execution" ], "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": "Ruleset IDs to load when `blockAds` is enabled, as CSV or JSON-array text.", "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": "deviceScaleFactor", "schema": { "description": "Device pixel ratio for the desktop screen above (allowed: 1 or 1.25).\nOmit to default to the seeded/profile scale. Ignored for emulationOs=android.", "type": "number" } }, { "in": "query", "name": "deviceSlot", "schema": { "description": "Pin this session to one of your identity's N stable device slots (0-based,\ndefault N=8). Each slot is one virtual machine: its GPU, screen, cores, memory\nand OS version stay fixed across sessions, so traffic spreads over N machines\ninstead of clustering on one. Requires a desktop emulationOs.", "type": "number" } }, { "in": "query", "name": "emulatedDevice", "schema": { "description": "Device model for the mobile persona (emulationOs=android): a device slug such\nas 'pixel-8', 'pixel-8-pro', 'galaxy-s23', 'galaxy-s23-ultra'. Drives the\nUA-CH model/version, viewport/DPR, touch points, cores, memory and GPU string.\nOmit to auto-pick a device seeded per session (stable per identity, spread\nacross the fleet; an unknown slug does the same). Requires emulationOs=android\non a stealth request — sent otherwise, the request is rejected with 400.", "type": "string" } }, { "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.\nOnly applies to the residential network; the datacenter pool ignores it.\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. Off by default.", "enum": [ "0", "1", "false", "true" ], "type": "string" } }, { "in": "query", "name": "replay", "schema": { "type": "boolean" } }, { "in": "query", "name": "screen", "schema": { "description": "Desktop screen resolution as WIDTHxHEIGHT (e.g. '1920x1080'). Sets the\nreported screen.*, window size and (with deviceScaleFactor) DPR for a\ndesktop persona. Omit to auto-pick a screen seeded per session (stable per\nidentity, spread across the fleet). Ignored for emulationOs=android.", "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/bql?(/*)", "tags": [ "BQL Execution" ], "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.\nOnly applies to the residential network; the datacenter pool ignores it.\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. Off by default.", "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": [ "CDP & DevTools Connections" ] } }, "/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": "blockAdsInclude", "schema": { "description": "Ruleset IDs to load when `blockAds` is enabled, as CSV or JSON-array text.", "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" }, { "$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.\nOnly applies to the residential network; the datacenter pool ignores it.\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. Off by default.", "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": [ "CDP & DevTools Connections" ] } }, "/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": "blockAdsInclude", "schema": { "description": "Ruleset IDs to load when `blockAds` is enabled, as CSV or JSON-array text.", "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": "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.\nOnly applies to the residential network; the datacenter pool ignores it.\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. Off by default.", "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": [ "CDP & DevTools Connections" ] } }, "/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": "blockAdsInclude", "schema": { "description": "Ruleset IDs to load when `blockAds` is enabled, as CSV or JSON-array text.", "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": "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.\nOnly applies to the residential network; the datacenter pool ignores it.\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. Off by default.", "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": [ "CDP & DevTools Connections" ] } }, "/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": "blockAdsInclude", "schema": { "description": "Ruleset IDs to load when `blockAds` is enabled, as CSV or JSON-array text.", "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": "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.\nOnly applies to the residential network; the datacenter pool ignores it.\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. Off by default.", "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": [ "CDP & DevTools Connections" ] } }, "/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" ] } }, "/profile/*/download": { "get": { "description": "Downloads the captured authentication state for a specific profile.\nThe profile name is the URL-encoded path segment before \"/download\".\nReturns 404 if no profile with that name exists for this token.\n\n**Note:** This endpoint is also available at: `/profile/.*/download` for backwards compatibility.", "parameters": [], "requestBody": { "content": {} }, "responses": { "200": { "content": { "application/json": { "schema": { "type": "object", "properties": { "cookies": { "type": "array", "items": { "$ref": "#/components/schemas/ProfileCookie" } }, "origins": { "type": "array", "items": { "$ref": "#/components/schemas/DownloadProfileOriginStorage" } } }, "additionalProperties": false, "required": [ "cookies", "origins" ], "definitions": { "ProfileCookie": { "type": "object", "properties": { "name": { "type": "string" }, "value": { "type": "string" }, "domain": { "type": "string" }, "path": { "type": "string" }, "expires": { "type": "number" }, "size": { "type": "number" }, "httpOnly": { "type": "boolean" }, "secure": { "type": "boolean" }, "session": { "type": "boolean" }, "sameSite": { "enum": [ "Lax", "None", "Strict" ], "type": "string" }, "sourceScheme": { "enum": [ "NonSecure", "Secure", "Unset" ], "type": "string" }, "sourcePort": { "type": "number" } }, "additionalProperties": false, "required": [ "domain", "expires", "httpOnly", "name", "path", "secure", "session", "size", "value" ] }, "DownloadProfileOriginStorage": { "type": "object", "properties": { "origin": { "type": "string" }, "localStorage": { "$ref": "#/components/schemas/DownloadProfileLocalStorage" }, "indexedDBs": { "type": "array", "items": { "$ref": "#/components/schemas/DownloadProfileIndexedDB" } } }, "additionalProperties": false, "required": [ "localStorage", "origin" ] }, "DownloadProfileLocalStorage": { "type": "object", "additionalProperties": { "type": "string" } }, "DownloadProfileIndexedDB": { "type": "object", "properties": { "name": { "type": "string" }, "version": { "type": "number" }, "objectStores": { "type": "array", "items": { "$ref": "#/components/schemas/DownloadProfileIndexedDBObjectStore" } } }, "additionalProperties": false, "required": [ "name", "objectStores", "version" ] }, "DownloadProfileIndexedDBObjectStore": { "type": "object", "properties": { "name": { "type": "string" }, "keyPath": { "anyOf": [ { "$ref": "#/components/schemas/DownloadProfileNullableKeyPath" }, { "type": "null" } ] }, "autoIncrement": { "type": "boolean" }, "entries": { "type": "array", "items": { "$ref": "#/components/schemas/ProfileIndexedDBEntry" } }, "indexes": { "type": "array", "items": { "$ref": "#/components/schemas/DownloadProfileIndexedDBIndex" } } }, "additionalProperties": false, "required": [ "autoIncrement", "entries", "indexes", "keyPath", "name" ] }, "DownloadProfileNullableKeyPath": { "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "string" } ] }, "ProfileIndexedDBEntry": { "type": "object", "properties": { "key": {}, "value": {} }, "additionalProperties": false, "required": [ "key", "value" ] }, "DownloadProfileIndexedDBIndex": { "type": "object", "properties": { "name": { "type": "string" }, "keyPath": { "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "string" } ] }, "unique": { "type": "boolean" }, "multiEntry": { "type": "boolean" } }, "additionalProperties": false, "required": [ "keyPath", "multiEntry", "name", "unique" ] } }, "$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/*/download", "tags": [ "Management REST APIs" ] } }, "/scrape": { "post": { "description": "A JSON-based API that returns text, html, and meta-data from a given list of\nselectors. Debugging information is available by sending in the appropriate\nflags in the \"debugOpts\" property. Responds with an array of JSON objects.\n\n**Note:** This endpoint is also available at: `/chromium/scrape` for backwards compatibility.", "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": "Ruleset IDs to load when `blockAds` is enabled, as CSV or JSON-array text.", "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.\nOnly applies to the residential network; the datacenter pool ignores it.\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. Off by default.", "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": { "addScriptTag": { "type": "array", "items": { "$ref": "#/components/schemas/FrameAddScriptTagOptions" } }, "addStyleTag": { "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 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": { "type": "object", "properties": { "console": { "type": "boolean" }, "cookies": { "type": "boolean" }, "html": { "type": "boolean" }, "network": { "type": "boolean" }, "screenshot": { "type": "boolean" } }, "additionalProperties": false }, "elements": { "type": "array", "items": { "$ref": "#/components/schemas/ScrapeElementSelector" } }, "emulateMediaType": { "type": "string" }, "gotoOptions": { "description": "The supported subset of puppeteer's goto options: `waitUntil` (mapped onto\nbap-ts's set — an array reduces to its first entry), `timeout` (clamped to\nthe route ceiling), and `referer`. Other puppeteer goto fields are not\nforwarded.", "type": "object", "properties": { "timeout": { "type": "number" }, "waitUntil": { "anyOf": [ { "type": "array", "items": { "$ref": "#/components/schemas/PuppeteerLifeCycleEvent" } }, { "enum": [ "domcontentloaded", "load", "networkidle0", "networkidle2" ], "type": "string" } ] }, "referer": { "type": "string" } }, "additionalProperties": false }, "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": { "status": { "type": "number" }, "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." }, "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": { "$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": { "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" ] } } } }, "responses": { "200": { "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/ScrapeGroupResult" } }, "debug": { "type": "object", "properties": { "console": { "type": "array", "items": { "type": "string" } }, "cookies": { "type": "array", "items": { "$ref": "#/components/schemas/Cookie" } }, "html": { "type": "string" }, "network": { "type": "object", "properties": { "inbound": { "type": "array", "items": { "$ref": "#/components/schemas/InboundResponse" } }, "outbound": { "type": "array", "items": { "$ref": "#/components/schemas/OutboundRequest" } } }, "additionalProperties": false, "required": [ "inbound", "outbound" ] }, "screenshot": { "type": "string" } }, "additionalProperties": false, "required": [ "console", "cookies", "html", "network", "screenshot" ] } }, "additionalProperties": false, "required": [ "data", "debug" ], "definitions": { "ScrapeGroupResult": { "type": "object", "properties": { "results": { "type": "array", "items": { "$ref": "#/components/schemas/ScrapeElementResult" } }, "selector": { "type": "string" } }, "additionalProperties": false, "required": [ "results", "selector" ] }, "ScrapeElementResult": { "type": "object", "properties": { "attributes": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "value": { "type": "string" } }, "additionalProperties": false, "required": [ "name", "value" ] } }, "height": { "type": "number" }, "html": { "type": "string" }, "left": { "type": "number" }, "text": { "type": "string" }, "top": { "type": "number" }, "width": { "type": "number" } }, "additionalProperties": false, "required": [ "attributes", "height", "html", "left", "text", "top", "width" ] }, "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": { "$ref": "#/components/schemas/CookieSameSite_2", "description": "Cookie SameSite type." }, "priority": { "$ref": "#/components/schemas/CookiePriority", "description": "Cookie Priority. Supported only in Chrome." }, "sourceScheme": { "$ref": "#/components/schemas/CookieSourceScheme", "description": "Cookie source scheme type. Supported only in Chrome." }, "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" ] }, "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" }, "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" ] }, "InboundResponse": { "type": "object", "properties": { "headers": { "$ref": "#/components/schemas/StringRecord" }, "status": { "type": "number" }, "url": { "type": "string" } }, "additionalProperties": false, "required": [ "headers", "status", "url" ] }, "Record": { "type": "object", "additionalProperties": false }, "OutboundRequest": { "type": "object", "properties": { "headers": { "$ref": "#/components/schemas/StringRecord" }, "method": { "type": "string" }, "url": { "type": "string" } }, "additionalProperties": false, "required": [ "headers", "method", "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": "/scrape", "tags": [ "Scraping & Content" ] } }, "/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": "blockAdsInclude", "schema": { "description": "Ruleset IDs to load when `blockAds` is enabled, as CSV or JSON-array text.", "type": "string" } }, { "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" } }, "/skills": { "get": { "description": "Returns the browser-automation skills known for a site: tuned, site-specific\nrecipes an agent should follow instead of planning its own steps.\n\"domain\" is required; \"task\" narrows the result to a single skill slug.\nReturns an empty array when no skill is known for the domain.", "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": "blockAdsInclude", "schema": { "description": "Ruleset IDs to load when `blockAds` is enabled, as CSV or JSON-array text.", "type": "string" } }, { "in": "query", "name": "domain", "schema": { "description": "Hostname to look skills up for, e.g. \"airbnb.com\". A scheme, port or\n\"www.\" prefix is accepted and normalized away.", "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": "task", "schema": { "description": "Optional skill slug, e.g. \"search-listings\". Omit to get every skill\nknown for the domain.", "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.\nOnly applies to the residential network; the datacenter pool ignores it.\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. Off by default.", "enum": [ "0", "1", "false", "true" ], "type": "string" } } ], "requestBody": { "content": {} }, "responses": { "200": { "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/SkillResponse" }, "definitions": { "SkillResponse": { "description": "The public shape: no `source`, which carries token_hash / sessionId.", "type": "object", "properties": { "id": { "type": "string" }, "domain": { "type": "string" }, "task": { "type": "string" }, "title": { "type": "string" }, "skill_md": { "type": "string" }, "version": { "type": "number" }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } }, "additionalProperties": false, "required": [ "created_at", "domain", "id", "skill_md", "task", "title", "updated_at", "version" ] } }, "$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": "/skills", "tags": [ "Platform / Skills" ] } }, "/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": "Ruleset IDs to load when `blockAds` is enabled, as CSV or JSON-array text.", "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": "deviceScaleFactor", "schema": { "description": "Device pixel ratio for the desktop screen above (allowed: 1 or 1.25).\nOmit to default to the seeded/profile scale. Ignored for emulationOs=android.", "type": "number" } }, { "in": "query", "name": "deviceSlot", "schema": { "description": "Pin this session to one of your identity's N stable device slots (0-based,\ndefault N=8). Each slot is one virtual machine: its GPU, screen, cores, memory\nand OS version stay fixed across sessions, so traffic spreads over N machines\ninstead of clustering on one. Requires a desktop emulationOs.", "type": "number" } }, { "in": "query", "name": "emulatedDevice", "schema": { "description": "Device model for the mobile persona (emulationOs=android): a device slug such\nas 'pixel-8', 'pixel-8-pro', 'galaxy-s23', 'galaxy-s23-ultra'. Drives the\nUA-CH model/version, viewport/DPR, touch points, cores, memory and GPU string.\nOmit to auto-pick a device seeded per session (stable per identity, spread\nacross the fleet; an unknown slug does the same). Requires emulationOs=android\non a stealth request — sent otherwise, the request is rejected with 400.", "type": "string" } }, { "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.\nOnly applies to the residential network; the datacenter pool ignores it.\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. Off by default.", "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": "screen", "schema": { "description": "Desktop screen resolution as WIDTHxHEIGHT (e.g. '1920x1080'). Sets the\nreported screen.*, window size and (with deviceScaleFactor) DPR for a\ndesktop persona. Omit to auto-pick a screen seeded per session (stable per\nidentity, spread across the fleet). Ignored for emulationOs=android.", "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": { "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": [ "BQL Execution" ], "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": "Ruleset IDs to load when `blockAds` is enabled, as CSV or JSON-array text.", "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": "deviceScaleFactor", "schema": { "description": "Device pixel ratio for the desktop screen above (allowed: 1 or 1.25).\nOmit to default to the seeded/profile scale. Ignored for emulationOs=android.", "type": "number" } }, { "in": "query", "name": "deviceSlot", "schema": { "description": "Pin this session to one of your identity's N stable device slots (0-based,\ndefault N=8). Each slot is one virtual machine: its GPU, screen, cores, memory\nand OS version stay fixed across sessions, so traffic spreads over N machines\ninstead of clustering on one. Requires a desktop emulationOs.", "type": "number" } }, { "in": "query", "name": "emulatedDevice", "schema": { "description": "Device model for the mobile persona (emulationOs=android): a device slug such\nas 'pixel-8', 'pixel-8-pro', 'galaxy-s23', 'galaxy-s23-ultra'. Drives the\nUA-CH model/version, viewport/DPR, touch points, cores, memory and GPU string.\nOmit to auto-pick a device seeded per session (stable per identity, spread\nacross the fleet; an unknown slug does the same). Requires emulationOs=android\non a stealth request — sent otherwise, the request is rejected with 400.", "type": "string" } }, { "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.\nOnly applies to the residential network; the datacenter pool ignores it.\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. Off by default.", "enum": [ "0", "1", "false", "true" ], "type": "string" } }, { "in": "query", "name": "replay", "schema": { "type": "boolean" } }, { "in": "query", "name": "screen", "schema": { "description": "Desktop screen resolution as WIDTHxHEIGHT (e.g. '1920x1080'). Sets the\nreported screen.*, window size and (with deviceScaleFactor) DPR for a\ndesktop persona. Omit to auto-pick a screen seeded per session (stable per\nidentity, spread across the fleet). Ignored for emulationOs=android.", "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": "/stealth/bql?(/*)", "tags": [ "BQL Execution" ], "operationId": "stealth-bql-connect" } } }, "servers": [ { "url": "https://production-sfo.browserless.io" } ], "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" }, "env": { "description": "Environment for the browser process. Honored by both puppeteer.launch and\nplaywright.launchServer. Set server-side to give the session its own TMPDIR\n(see generateScratchDir); a caller-supplied value is merged under it, since\na session must not be able to point its scratch back at the shared temp dir.\n\nThat merge happens on the object handed to `launch` only. It is kept off\nthe session's stored `launchOptions`, which /sessions serves verbatim.", "$ref": "#/components/schemas/Record" }, "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" } } }, "Record": { "type": "object", "additionalProperties": false }, "JSONSchema": { "type": "object", "properties": { "code": { "type": "string" }, "context": { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/ContextValue" } } }, "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" }, "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" }, "ScrapeGroupResult": { "type": "object", "properties": { "results": { "type": "array", "items": { "$ref": "#/components/schemas/ScrapeElementResult" } }, "selector": { "type": "string" } }, "additionalProperties": false, "required": [ "results", "selector" ] }, "ScrapeElementResult": { "type": "object", "properties": { "attributes": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "value": { "type": "string" } }, "additionalProperties": false, "required": [ "name", "value" ] } }, "height": { "type": "number" }, "html": { "type": "string" }, "left": { "type": "number" }, "text": { "type": "string" }, "top": { "type": "number" }, "width": { "type": "number" } }, "additionalProperties": false, "required": [ "attributes", "height", "html", "left", "text", "top", "width" ] }, "InboundResponse": { "type": "object", "properties": { "headers": { "$ref": "#/components/schemas/StringRecord" }, "status": { "type": "number" }, "url": { "type": "string" } }, "additionalProperties": false, "required": [ "headers", "status", "url" ] }, "OutboundRequest": { "type": "object", "properties": { "headers": { "$ref": "#/components/schemas/StringRecord" }, "method": { "type": "string" }, "url": { "type": "string" } }, "additionalProperties": false, "required": [ "headers", "method", "url" ] }, "Platform": { "enum": [ "android", "linux", "macos", "windows" ], "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" }, "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 }, "SearchFailureCode": { "enum": [ "no_results", "upstream_timeout", "upstream_unavailable" ], "type": "string" }, "UnresponsiveEngine": { "type": "object", "properties": { "engine": { "type": "string" }, "reason": { "$ref": "#/components/schemas/UnresponsiveEngineReason" } }, "additionalProperties": false, "required": [ "engine", "reason" ] }, "UnresponsiveEngineReason": { "enum": [ "access_denied", "captcha", "rate_limited", "timeout", "unknown" ], "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" ] }, "SkillResponse": { "description": "The public shape: no `source`, which carries token_hash / sessionId.", "type": "object", "properties": { "id": { "type": "string" }, "domain": { "type": "string" }, "task": { "type": "string" }, "title": { "type": "string" }, "skill_md": { "type": "string" }, "version": { "type": "number" }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } }, "additionalProperties": false, "required": [ "created_at", "domain", "id", "skill_md", "task", "title", "updated_at", "version" ] }, "ProfileCaptureSettings": { "description": "Capture inputs the CLI ran with, so a later `profile refresh` can replay them\nwithout flags. Null for the CDP saveProfile path and any future non-CLI creator.\nNever holds the token, and omits server/region because a stale stored region\nis a guaranteed 404.", "type": "object", "properties": { "browser": { "description": "Raw `--browser` value.", "type": "string" }, "profile": { "description": "Raw `--profile` value (source profile directory or display name).", "type": "string" }, "excludeDomains": { "description": "Effective merged exclusion list. `[]` is meaningful — \"captured with no\nexclusions\" — and distinct from absent, which means \"unknown\".", "type": "array", "items": { "type": "string" } }, "onlyDomains": { "description": "Normalized `--only-domain` hostnames, deduped and capped — not merged with local config.", "type": "array", "items": { "type": "string" } }, "keepDomains": { "description": "Normalized `--keep-domain` hostnames, same normalization, no merge.", "type": "array", "items": { "type": "string" } }, "autoFit": { "description": "Whether `--auto-fit` was used.", "type": "boolean" }, "passwordStore": { "description": "Raw `--password-store` value. Linux only.", "type": "string" }, "cliVersion": { "description": "CLI version that produced these settings, for drift diagnosis.", "type": "string" } }, "additionalProperties": false }, "ProfileDomainAuth": { "description": "Response shape: the stored snapshot plus its read-time status.", "type": "object", "properties": { "domain": { "type": "string" }, "status": { "$ref": "#/components/schemas/DomainAuthStatus" }, "expiresAt": { "type": "string" } }, "additionalProperties": false, "required": [ "domain", "expiresAt", "status" ] }, "DomainAuthStatus": { "description": "Per-domain auth status, computed at read time from a stored absolute expiry.", "enum": [ "expired", "expiring_soon", "unknown", "valid" ], "type": "string" }, "ProfileCookie": { "type": "object", "properties": { "name": { "type": "string" }, "value": { "type": "string" }, "domain": { "type": "string" }, "path": { "type": "string" }, "expires": { "type": "number" }, "size": { "type": "number" }, "httpOnly": { "type": "boolean" }, "secure": { "type": "boolean" }, "session": { "type": "boolean" }, "sameSite": { "enum": [ "Lax", "None", "Strict" ], "type": "string" }, "sourceScheme": { "enum": [ "NonSecure", "Secure", "Unset" ], "type": "string" }, "sourcePort": { "type": "number" } }, "additionalProperties": false, "required": [ "domain", "expires", "httpOnly", "name", "path", "secure", "session", "size", "value" ] }, "DownloadProfileOriginStorage": { "type": "object", "properties": { "origin": { "type": "string" }, "localStorage": { "$ref": "#/components/schemas/DownloadProfileLocalStorage" }, "indexedDBs": { "type": "array", "items": { "$ref": "#/components/schemas/DownloadProfileIndexedDB" } } }, "additionalProperties": false, "required": [ "localStorage", "origin" ] }, "DownloadProfileLocalStorage": { "type": "object", "additionalProperties": { "type": "string" } }, "DownloadProfileIndexedDB": { "type": "object", "properties": { "name": { "type": "string" }, "version": { "type": "number" }, "objectStores": { "type": "array", "items": { "$ref": "#/components/schemas/DownloadProfileIndexedDBObjectStore" } } }, "additionalProperties": false, "required": [ "name", "objectStores", "version" ] }, "DownloadProfileIndexedDBObjectStore": { "type": "object", "properties": { "name": { "type": "string" }, "keyPath": { "anyOf": [ { "$ref": "#/components/schemas/DownloadProfileNullableKeyPath" }, { "type": "null" } ] }, "autoIncrement": { "type": "boolean" }, "entries": { "type": "array", "items": { "$ref": "#/components/schemas/ProfileIndexedDBEntry" } }, "indexes": { "type": "array", "items": { "$ref": "#/components/schemas/DownloadProfileIndexedDBIndex" } } }, "additionalProperties": false, "required": [ "autoIncrement", "entries", "indexes", "keyPath", "name" ] }, "DownloadProfileNullableKeyPath": { "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "string" } ] }, "ProfileIndexedDBEntry": { "type": "object", "properties": { "key": {}, "value": {} }, "additionalProperties": false, "required": [ "key", "value" ] }, "DownloadProfileIndexedDBIndex": { "type": "object", "properties": { "name": { "type": "string" }, "keyPath": { "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "string" } ] }, "unique": { "type": "boolean" }, "multiEntry": { "type": "boolean" } }, "additionalProperties": false, "required": [ "keyPath", "multiEntry", "name", "unique" ] }, "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" }, "captureSettings": { "$ref": "#/components/schemas/ProfileCaptureSettings", "description": "Capture inputs the CLI used, or null for profiles not created by the CLI. The UI\nderives no capture flag from these; it uses any non-empty object to stamp the CLI\nbadge and show a read-only summary, and reads `browser`/`profile` specifically to\ndecide whether its refresh command needs placeholders for them. The CLI reads the\nrest itself and decides the exclusion behaviour from `excludeDomains`." }, "domainAuth": { "description": "Per-domain auth status + expiry for the saved logins in this profile, with\nstatus classified at read time (valid / expiring_soon / expired / unknown).\nEmpty for profiles saved before this feature, until their next capture,\nupload, or refresh. Never contains a cookie value.", "type": "array", "items": { "$ref": "#/components/schemas/ProfileDomainAuth" } }, "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": [ "captureSettings", "cookieCount", "createdAt", "domainAuth", "id", "lastUsedAt", "name", "originCount", "updatedAt" ] }, "RefreshCaptureSettingsPayload": { "description": "Declared locally, not imported, so the generator emits a flat definition —\nmust stay field-for-field equal to `ProfileCaptureSettings` in\n`../../profiles/types.ts`. `profile.http.spec.ts` pins it two ways: an\n`Exact<>` type assertion, and a key-set check against the generated\n`*.body.json` — the artifact that actually decides whether a request 400s.\nAll-optional so a partial payload cannot 400, and non-nullable because the\ngenerator drops the null. Nested definitions get\n`additionalProperties: false`, so **adding a member here is an\nenterprise-first deploy, every time.**", "type": "object", "properties": { "browser": { "description": "Raw `--browser` value.", "type": "string" }, "profile": { "description": "Raw `--profile` value.", "type": "string" }, "excludeDomains": { "description": "Effective merged exclusion list, not just the `--exclude-domain` flags.", "type": "array", "items": { "type": "string" } }, "onlyDomains": { "description": "Normalized `--only-domain` hostnames, deduped and capped — not merged with local config.", "type": "array", "items": { "type": "string" } }, "keepDomains": { "description": "Normalized `--keep-domain` hostnames, same normalization, no merge.", "type": "array", "items": { "type": "string" } }, "autoFit": { "description": "Whether `--auto-fit` was used.", "type": "boolean" }, "passwordStore": { "description": "Raw `--password-store` value. Linux only.", "type": "string" }, "cliVersion": { "description": "CLI version that produced these settings.", "type": "string" } }, "additionalProperties": false }, "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" }, "skippedMalformedLocalStorageEntries": { "description": "localStorage entries dropped because names or values were not strings.", "type": "number" }, "skippedMalformedIdbIndexes": { "description": "IndexedDB indexes dropped because required fields were malformed.", "type": "number" } }, "additionalProperties": false, "required": [ "skippedMalformedCookies", "skippedMalformedIdbDatabases", "skippedMalformedIdbIndexes", "skippedMalformedIdbStores", "skippedMalformedLocalStorageEntries", "skippedMalformedOrigins", "skippedPrivateCookies", "skippedPrivateOrigins", "truncatedIdbDatabases", "truncatedIdbEntries", "truncatedOrigins" ] }, "UploadCaptureSettingsPayload": { "description": "Declared locally, not imported, so the generator emits a flat definition —\nmust stay field-for-field equal to `ProfileCaptureSettings` in\n`../../profiles/types.ts`. `profile.http.spec.ts` pins it two ways: an\n`Exact<>` type assertion, and a key-set check against the generated\n`*.body.json` — the artifact that actually decides whether a request 400s.\nAll-optional so a partial payload cannot 400, and non-nullable because the\ngenerator drops the null. Nested definitions get\n`additionalProperties: false`, so **adding a member here is an\nenterprise-first deploy, every time.**", "type": "object", "properties": { "browser": { "description": "Raw `--browser` value.", "type": "string" }, "profile": { "description": "Raw `--profile` value.", "type": "string" }, "excludeDomains": { "description": "Effective merged exclusion list, not just the `--exclude-domain` flags.", "type": "array", "items": { "type": "string" } }, "onlyDomains": { "description": "Normalized `--only-domain` hostnames, deduped and capped — not merged with local config.", "type": "array", "items": { "type": "string" } }, "keepDomains": { "description": "Normalized `--keep-domain` hostnames, same normalization, no merge.", "type": "array", "items": { "type": "string" } }, "autoFit": { "description": "Whether `--auto-fit` was used.", "type": "boolean" }, "passwordStore": { "description": "Raw `--password-store` value. Linux only.", "type": "string" }, "cliVersion": { "description": "CLI version that produced these settings.", "type": "string" } }, "additionalProperties": false }, "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" }, "skippedMalformedLocalStorageEntries": { "description": "localStorage entries dropped because names or values were not strings.", "type": "number" }, "skippedMalformedIdbIndexes": { "description": "IndexedDB indexes dropped because required fields were malformed.", "type": "number" } }, "additionalProperties": false, "required": [ "skippedMalformedCookies", "skippedMalformedIdbDatabases", "skippedMalformedIdbIndexes", "skippedMalformedIdbStores", "skippedMalformedLocalStorageEntries", "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 credential operation used.", "type": "string" }, "profileId": { "description": "Authentication profile associated with the operation, 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 filled, `saved` if created, otherwise `failure`." }, "errorCode": { "description": "Error code when the outcome is `failure`, otherwise null.", "type": "string" }, "createdAt": { "description": "ISO timestamp of the operation.", "type": "string" } }, "additionalProperties": false, "required": [ "createdAt", "errorCode", "id", "integrationId", "outcome", "profileId", "secretRef", "targetDescriptor", "targetOrigin", "targetSelector" ] }, "OpAuditOutcome": { "description": "Outcome recorded for a Browserless.loadSecret or saveSecret attempt.", "enum": [ "failure", "saved", "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" ] }, "InboxCandidate": { "type": "object", "properties": { "vault": { "type": "string" }, "item": { "type": "string" }, "label": { "type": "string" } }, "additionalProperties": false, "required": [ "item", "label", "vault" ] }, "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" }, "errorCode": { "type": "string" }, "reason": { "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": [] } ], "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 stealth toggle (`/stealth`, `/chromium/stealth`, `/chrome/stealth`) randomizes 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": "Agent", "description": "Run autonomous browser agents. `POST /agent/run` starts an asynchronous run and returns an id to poll via `GET /agent/run/:id`; `POST /agent/run/:id/continue` sends it a follow-up task (not enabled in v1). `/chromium/agent` connects over WebSocket for a persistent, JSON-RPC-driven agentic browser session instead.", "x-displayName": "Agent" }, { "name": "BQL Execution", "description": "Run BrowserQL (BQL) queries over REST, or connect over WebSocket for a persistent BQL session. `/chromium/bql` runs standard BQL; `/stealth/bql` adds fingerprint randomization for bot-detection-sensitive automation.", "x-displayName": "BQL Execution" }, { "name": "CDP & DevTools Connections", "description": "Low-level WebSocket connections for CDP tooling: the hosted-agent CLI chat (`/chromium/cli`), reconnecting to an existing stealth session, attaching to an already-running Chromium process, and the underlying connections `/function` uses internally.", "x-displayName": "CDP & DevTools Connections" }, { "name": "Platform / Skills", "description": "Site-specific browser-automation skills: tuned recipes an agent should follow for a given domain instead of planning its own steps.", "x-displayName": "Platform / Skills" } ], "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", "Agent", "BQL Execution", "CDP & DevTools Connections" ] }, { "name": "Chrome", "tags": [ "Chrome (licensed build)" ] }, { "name": "Platform", "tags": [ "Platform / Skills" ] } ] }