Quickstart

1. Your key

Sign up or go to API keys and create one. The secret starts with bf_live_ and is shown exactly once — we only store its hash.

2. Point the SDK at browserfarm

Base URL: https://api.dev.thebrowserfarm.com

pnpm add @browserbasehq/sdk playwright-core

import Browserbase from "@browserbasehq/sdk";
import { chromium } from "playwright-core";

const bb = new Browserbase({
  apiKey: process.env.BROWSERFARM_API_KEY, // bf_live_… (from /keys),
  baseURL: "https://api.dev.thebrowserfarm.com",   // <- the only line you change
});

const session = await bb.sessions.create({
  projectId: process.env.BROWSERFARM_PROJECT_ID ?? "default",
});

// connectUrl is wss://<api host>/<id>/cdp?signingKey=<bfsk_…> on the
// public API (ws:// in local dev). Pass the URL through unchanged.
const browser = await chromium.connectOverCDP(session.connectUrl);
const page = (browser.contexts()[0] ?? (await browser.newContext())).pages()[0]
  ?? await browser.newPage();

await page.goto("https://example.com");
console.log(await page.title());

await browser.close();
// Closing the last CDP connection ends the session (keepAlive defaults to
// false). The explicit release is idempotent and also covers a session you
// created with keepAlive: true or never connected to.
await bb.sessions.update(session.id, {
  projectId: process.env.BROWSERFARM_PROJECT_ID ?? "default",
  status: "REQUEST_RELEASE",
});

3. Or hit the REST API directly

Send the key as X-BB-API-Key or Authorization: Bearer. If both are present, X-BB-API-Key wins.

curl -X POST https://api.dev.thebrowserfarm.com/v1/sessions \
  -H "X-BB-API-Key: $BROWSERFARM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"projectId":"default"}'

Device flow

An agent that cannot paste a key can ask for one instead: it calls POST /api/device/code and shows you a code. Approve that code on /device, and the agent receives a normal API key the next time it polls — shown to the agent once, revocable from API keys. Codes expire after 10 minutes. See API docs.

Limits

One limit is enforced: concurrent browsers per account, 10 unless the account says otherwise (Usage after you sign in). Past the cap, session creation returns HTTP 429 with a Retry-After header. There is no other rate limit. Sessions are ephemeral — nothing persists between them, so log in inside each session.