Migrating from Browserless

// before
const browser = await puppeteer.connect({
  browserWSEndpoint: 'wss://production-sfo.browserless.io?token=BROWSERLESS_TOKEN',
});

// after
const browser = await puppeteer.connect({
  browserWSEndpoint: 'wss://gw.flatbrowser.com?token=flat_live_YOUR_KEY',
});

• Your token goes in ?token= as before (or Authorization: Bearer). Create one in the dashboard.
• Playwright users: keep chromium.connectOverCDP(). If you used chromium.connect() against /chromium/playwright, switch to connectOverCDP — see connect URLs.
• Concurrency: Browserless queues extra connections; we answer 429 with Retry-After unless you pass queueTimeout (up to 60 s), which makes the gateway wait for a free slot like Browserless does.

Parameters and body keys we accept but do not act on are listed, by name only, in the X-Flatbrowser-Ignored-Params response header — on the REST response, and on the WebSocket handshake response for CDP connections. Log it once during your migration.

curl -si -X POST 'https://gw.flatbrowser.com/screenshot?blockAds=true' \
  -H 'Authorization: Bearer flat_live_YOUR_KEY' -H 'Content-Type: application/json' \
  -d '{"url":"https://example.com","options":{"type":"jpeg","quality":80}}' -o shot.jpg
# HTTP/1.1 200 OK
# Content-Type: image/jpeg
# X-Flatbrowser-Ignored-Params: blockAds

HTTP discovery

These apply to WebSocket connect URLs, POST /v1/sessions and the REST actions. A parameter that is not in this table is refused with 400 unsupported_param — far more often a typo of a meaningful parameter than a harmless extra.

The Browserless-style paths take Browserless request bodies and answer like Browserless. The native /v1/* endpoints keep their own flat bodies (see the REST reference).

Request body keys on the Browserless-style paths

1. Swap the endpoint and token.
2. Remove profile, stealth and other rejected parameters; move login state to Playwright storageState or saved cookies.
3. If you used Browserless’s proxies, pass your own proxy with proxy= (plus proxyCountry and proxyLocaleMatch=true if you want the locale to match).
4. Handle 429 with Retry-After, or add queueTimeout.
5. Run your suite once and check X-Flatbrowser-Ignored-Params.