Browserbase SDK

https://github.com/browserbase/sdk-node
Admin
Official Node.js library for the Browserbase API, providing convenient access to Browserbase REST...
Tokens:147,851
Snippets:700
Trust Score:9
License:Apache-2.0
Update:1 week ago
Show doc for...
Tokens:
Raw
### Run an example

Source: https://github.com/browserbase/sdk-node/blob/main/CONTRIBUTING.md

Make the example executable and run it against your API using tsn.

```sh
$ chmod +x examples/<your-example>.ts
# run the example against your api
$ yarn tsn -T examples/<your-example>.ts
```

--------------------------------

### Install from git

Source: https://github.com/browserbase/sdk-node/blob/main/CONTRIBUTING.md

Install the SDK directly from the GitHub repository via npm.

```sh
$ npm install git+ssh://git@github.com:browserbase/sdk-node.git
```

--------------------------------

### retrieve example

Source: https://github.com/browserbase/sdk-node/blob/main/_autodocs/api-reference/projects.md

Example of retrieving a project and logging its name, defaultTimeout, and concurrency.

```typescript
const project = await client.projects.retrieve('proj_123');
console.log(project.name, project.defaultTimeout, project.concurrency);
```

--------------------------------

### list example

Source: https://github.com/browserbase/sdk-node/blob/main/_autodocs/api-reference/projects.md

Example of listing projects and logging each project's id, name, and defaultTimeout.

```typescript
const projects = await client.projects.list();
projects.forEach((p) => console.log(p.id, p.name, p.defaultTimeout));
```

--------------------------------

### Install Browserbase SDK with npm

Source: https://github.com/browserbase/sdk-node/blob/main/README.md

Install the @browserbasehq/sdk package using npm.

```sh
npm install @browserbasehq/sdk
```

--------------------------------

### usage example

Source: https://github.com/browserbase/sdk-node/blob/main/_autodocs/api-reference/projects.md

Example of fetching project usage and logging browser minutes and proxy bytes.

```typescript
const usage = await client.projects.usage('proj_123');
console.log(`browser: ${usage.browserMinutes} min, proxy: ${usage.proxyBytes} bytes`);
```

--------------------------------

### Create and list recording downloads example

Source: https://github.com/browserbase/sdk-node/blob/main/_autodocs/api-reference/sessions.md

Example usage of creating a download request and then listing the download statuses, logging the downloadUrl for completed pages.

```TypeScript
await client.sessions.recording.downloads.create('sess_123');
const { downloads } = await client.sessions.recording.downloads.list('sess_123');
for (const d of downloads) {
  if (d.status === 'COMPLETED') console.log(d.downloadUrl);
}
```

--------------------------------

### Add an example file

Source: https://github.com/browserbase/sdk-node/blob/main/CONTRIBUTING.md

Create a new example file in the examples/ directory. The shebang line enables running with tsn.

```ts
#!/usr/bin/env -S npm run tsn -T
…
```

--------------------------------

### list usage example

Source: https://github.com/browserbase/sdk-node/blob/main/_autodocs/api-reference/sessions.md

Example of listing sessions filtered by status and querying user metadata. The response is an array of sessions, and the example logs each session's id, region, and proxyBytes.

```typescript
const sessions = await client.sessions.list({ status: 'RUNNING', q: 'jobId = "123"' });
sessions.forEach((s) => console.log(s.id, s.region, s.proxyBytes));
```

--------------------------------

### Agents.retrieve usage example

Source: https://github.com/browserbase/sdk-node/blob/main/_autodocs/api-reference/agents.md

Example of retrieving an agent and logging its systemPrompt. Uses the client.agents.retrieve method.

```ts
const agent = await client.agents.retrieve(agentId);
console.log(agent.systemPrompt);
```

--------------------------------

### Agents.update usage example

Source: https://github.com/browserbase/sdk-node/blob/main/_autodocs/api-reference/agents.md

Example of updating an agent's systemPrompt. Uses the client.agents.update method.

```ts
await client.agents.update(agentId, { systemPrompt: 'New instructions' });
```

--------------------------------

### Fetch a page with client.fetchAPI.create

Source: https://github.com/browserbase/sdk-node/blob/main/_autodocs/api-reference/fetch-api.md

Defines the fetchAPI.create method signature and shows two examples: a basic fetch of example.com and a JSON fetch with schema and proxy support. The method posts to /v1/fetch and returns a FetchAPICreateResponse with statusCode, contentType, headers, and content. The basic example logs statusCode, contentType, and content; the JSON example conditionally logs parsed.content.title when content is not a string.

```ts
create(body: FetchAPICreateParams, options?: Core.RequestOptions): Core.APIPromise<FetchAPICreateResponse>
```

```ts
const result = await client.fetchAPI.create({ url: 'https://example.com' });
console.log(result.statusCode, result.contentType, result.content);
```

```ts
const parsed = await client.fetchAPI.create({
  url: 'https://example.com/api/data',
  format: 'json',
  schema: { type: 'object', properties: { title: { type: 'string' } }, required: ['title'] },
  proxies: true,
});
if (typeof parsed.content !== 'string') console.log(parsed.content.title);
```

--------------------------------

### Start the mock server

Source: https://github.com/browserbase/sdk-node/blob/main/CONTRIBUTING.md

Run the mock server script required for most tests.

```sh
$ ./scripts/mock
```

--------------------------------

### Agents.list pagination example

Source: https://github.com/browserbase/sdk-node/blob/main/_autodocs/api-reference/agents.md

Example of manually paginating through agents using the cursor parameter. Loops until nextCursor is null, logging each agent's ID and name.

```ts
let cursor: string | undefined;
do {
  const page = await client.agents.list({ cursor, limit: 20 });
  page.data.forEach((a) => console.log(a.agentId, a.name));
  cursor = page.nextCursor ?? undefined;
} while (cursor);
```

--------------------------------

### Set up the repository with yarn

Source: https://github.com/browserbase/sdk-node/blob/main/CONTRIBUTING.md

Install dependencies and build output files to dist/ using yarn v1.

```sh
$ yarn
$ yarn build
```

--------------------------------

### retrieve usage example

Source: https://github.com/browserbase/sdk-node/blob/main/_autodocs/api-reference/sessions.md

Example of retrieving a session by ID. The response may include optional connectUrl, seleniumRemoteUrl, and signingKey fields.

```typescript
const session = await client.sessions.retrieve('sess_123');
if (session.connectUrl) { /* reconnect */ }
```

--------------------------------

### fileFromPath usage example

Source: https://github.com/browserbase/sdk-node/blob/main/_autodocs/api-reference/uploads.md

Shows how to import `fileFromPath` from the SDK and use it to create a `File` from a local extension zip file, which is then passed to `client.extensions.create`. This example is deprecated; prefer `fs.createReadStream` or `toFile`.

```typescript
import { fileFromPath } from '@browserbasehq/sdk';
await client.extensions.create({ file: await fileFromPath('./extension.zip') });
```

--------------------------------

### List secrets example

Source: https://github.com/browserbase/sdk-node/blob/main/_autodocs/api-reference/functions.md

Example of listing secrets for a function with a limit of 20, then logging each secret key.

```typescript
const page = await client.functions.secrets.list('fn_123', { limit: 20 });
page.data.forEach((s) => console.log(s.secretKey));
```

--------------------------------

### Create a reusable agent example

Source: https://github.com/browserbase/sdk-node/blob/main/_autodocs/api-reference/agents.md

Example of creating an agent with a name, system prompt, and result schema. The returned `agentId` is used when creating runs.

```typescript
const { agentId } = await client.agents.create({
  name: 'Research agent',
  systemPrompt: 'Search the web and summarize pricing pages.',
  resultSchema: { type: 'object', properties: { price: { type: 'number' } } },
});
```

--------------------------------

### GET /v1/projects

Source: https://github.com/browserbase/sdk-node/blob/main/_autodocs/endpoints.md

Lists all projects.

```APIDOC
## GET /v1/projects

### Description
Lists all projects.

### Method
GET

### Endpoint
/v1/projects

### Response
#### Success Response (200)
- **ProjectListResponse** - An array of projects.

#### Response Example
[
  {
    "id": "proj_123",
    "name": "My Project"
  }
]
```

--------------------------------

### get<Req, Rsp>(path, opts?)

Source: https://github.com/browserbase/sdk-node/blob/main/_autodocs/api-reference/core.md

Sends a GET request to the specified path with optional request options, returning an APIPromise.

```APIDOC
## get<Req, Rsp>(path, opts?)

### Description
Sends a GET request to the specified path with optional request options, returning an APIPromise.

### Method
GET

### Endpoint
{path}

### Parameters
- **path** (string) - Required - The request path.
- **opts** (PromiseOrValue<RequestOptions<Req>>) - Optional - Request options, can be a promise.

### Response
Returns an APIPromise<Rsp>.
```

--------------------------------

### update usage example

Source: https://github.com/browserbase/sdk-node/blob/main/_autodocs/api-reference/sessions.md

Example of updating a session to request release. The body must include status set to 'REQUEST_RELEASE' to complete the session before timeout and avoid charges.

```typescript
await client.sessions.update('sess_123', { status: 'REQUEST_RELEASE' });
```

--------------------------------

### List all certificates and log IDs

Source: https://github.com/browserbase/sdk-node/blob/main/_autodocs/api-reference/certificates.md

Example of listing all certificates and logging each certificate's ID and project ID.

```typescript
const certs = await client.certificates.list();
certs.forEach((c) => console.log(c.id, c.projectId));
```

--------------------------------

### downloads.list usage example

Source: https://github.com/browserbase/sdk-node/blob/main/_autodocs/api-reference/sessions.md

Fetches the download response for a session and reads the zip bytes into a Buffer using `response.arrayBuffer()`.

```typescript
const resp = await client.sessions.downloads.list('sess_123');
const buf = Buffer.from(await resp.arrayBuffer());
```

--------------------------------

### GET /v1/certificates

Source: https://github.com/browserbase/sdk-node/blob/main/_autodocs/endpoints.md

Lists all certificates.

```APIDOC
## GET /v1/certificates

### Description
Retrieves a list of all certificates.

### Method
GET

### Endpoint
/v1/certificates

### Response
#### Success Response (200)
- **CertificateListResponse** - An array of certificate objects.

#### Response Example
[
  {
    "id": "string",
    "name": "string"
  }
]
```

--------------------------------

### Runs.create — Run an agent

Source: https://github.com/browserbase/sdk-node/blob/main/_autodocs/api-reference/agents.md

Creates a browser agent run via POST `/v1/agents/runs`. The first example shows a simple task with a `resultSchema` override. The second example uses `pauseWhen` and `variables`; when the run status becomes `PAUSED`, the caller should ask for input and then poll `listMessages`.

```ts
create(body: RunCreateParams, options?: Core.RequestOptions): Core.APIPromise<RunCreateResponse>
```

```ts
const run = await client.agents.runs.create({
  task: 'Find the price of the Pro plan on browserbase.com',
  resultSchema: { type: 'object', properties: { price: { type: 'string' } } },
});
```

```ts
const run = await client.agents.runs.create({
  task: 'Log in with the code I will provide',
  pauseWhen: 'you need a verification code',
  variables: { company: { value: 'Acme', description: 'The account name' } },
});
if (run.status === 'PAUSED') { /* ask user for input, then poll listMessages */ }
```

--------------------------------

### retrieve with error handling

Source: https://github.com/browserbase/sdk-node/blob/main/_autodocs/api-reference/projects.md

Example of retrieving a project with try/catch to handle NotFoundError.

```typescript
try {
  const project = await client.projects.retrieve('proj_123');
  console.log(project.ownerId);
} catch (err) {
  if (err instanceof Browserbase.NotFoundError) {
    console.error('project not found — check the ID in Settings');
  }
}
```

--------------------------------

### Retrieve Extension by ID

Source: https://github.com/browserbase/sdk-node/blob/main/_autodocs/api-reference/extensions.md

Example of retrieving an extension by its ID and logging the fileName property.

```typescript
const ext = await client.extensions.retrieve('ext_123');
console.log(ext.fileName);
```

--------------------------------

### Create a session with advanced options and withResponse

Source: https://github.com/browserbase/sdk-node/blob/main/_autodocs/api-reference/sessions.md

Creates a session with browser settings, proxies, api_timeout, and keepAlive, using withResponse() to get the raw response. Includes error handling with Browserbase.APIError.

```typescript
const { data: session, response } = await client.sessions
  .create({
    browserSettings: { viewport: { width: 1280, height: 720 }, logSession: false },
    proxies: [{ type: 'browserbase', geolocation: { country: 'US', state: 'CA', city: 'Los Angeles' } }],
    api_timeout: 300, // 5 minutes
    keepAlive: true,
  }, { maxRetries: 5, timeout: 10_000 })
  .withResponse(); // catch with .catch(err => err instanceof Browserbase.APIError)
```

--------------------------------

### Create a context and log its encryption details

Source: https://github.com/browserbase/sdk-node/blob/main/_autodocs/api-reference/contexts.md

Example of creating a context with a user-defined name and logging the returned ID, public key, and cipher algorithm. The name is trimmed and must be unique among active contexts in the project (case-insensitive).

```ts
const ctx = await client.contexts.create({ name: 'logged-in-state' });
console.log(ctx.id, ctx.publicKey, ctx.cipherAlgorithm);
```

--------------------------------

### GET /v1/sessions/{id}/recording/downloads

Source: https://github.com/browserbase/sdk-node/blob/main/api.md

Lists downloads for a session recording. Returns a DownloadListResponse object.

```APIDOC
## GET /v1/sessions/{id}/recording/downloads

### Description
Lists downloads for a session recording.

### Method
GET

### Endpoint
/v1/sessions/{id}/recording/downloads

### Parameters
#### Path Parameters
- **id** (string) - Required - The ID of the session.

### Response
#### Success Response (200)
- **DownloadListResponse** (object) - A list of downloads.

### Response Example
{
  "data": []
}
```

--------------------------------

### GET /v1/projects/{id}/usage

Source: https://github.com/browserbase/sdk-node/blob/main/_autodocs/endpoints.md

Retrieves usage information for a specific project.

```APIDOC
## GET /v1/projects/{id}/usage

### Description
Retrieves usage information for a specific project.

### Method
GET

### Endpoint
/v1/projects/{id}/usage

### Parameters
#### Path Parameters
- **id** (string) - Required - The project ID.

### Response
#### Success Response (200)
- **ProjectUsage** - Usage details for the project.

#### Response Example
{
  "creditsUsed": 100,
  "creditsLimit": 1000
}
```

--------------------------------

### Retrieve a certificate and handle not found

Source: https://github.com/browserbase/sdk-node/blob/main/_autodocs/api-reference/certificates.md

Example of retrieving a certificate by ID and logging its updatedAt. Catches Browserbase.NotFoundError to log 'certificate not found'.

```typescript
try {
  const cert = await client.certificates.retrieve('cert_123');
  console.log(cert.updatedAt);
} catch (err) {
  if (err instanceof Browserbase.NotFoundError) console.error('certificate not found');
}
```

--------------------------------

### GET /v1/projects/{id}

Source: https://github.com/browserbase/sdk-node/blob/main/_autodocs/endpoints.md

Retrieves a project by its ID. Returns a 404 error if the project is unknown.

```APIDOC
## GET /v1/projects/{id}

### Description
Retrieves a project by its ID. Returns a 404 error if the project is unknown.

### Method
GET

### Endpoint
/v1/projects/{id}

### Parameters
#### Path Parameters
- **id** (string) - Required - The project ID.

### Response
#### Success Response (200)
- **Project** - The project object.

#### Response Example
{
  "id": "proj_123",
  "name": "My Project"
}
```

--------------------------------

### GET /v1/sessions/{id}/downloads

Source: https://github.com/browserbase/sdk-node/blob/main/api.md

Lists downloads for a session. Returns a Response object.

```APIDOC
## GET /v1/sessions/{id}/downloads

### Description
Lists downloads for a session.

### Method
GET

### Endpoint
/v1/sessions/{id}/downloads

### Parameters
#### Path Parameters
- **id** (string) - Required - The ID of the session.

### Response
#### Success Response (200)
- **Response** (object) - The downloads list.

### Response Example
{
  "data": []
}
```

--------------------------------

### Upload Extension from File Stream

Source: https://github.com/browserbase/sdk-node/blob/main/_autodocs/api-reference/extensions.md

Example of uploading an extension using a file stream from the filesystem. The resulting extension object contains id, fileName, and projectId.

```typescript
import fs from 'fs';
const ext = await client.extensions.create({ file: fs.createReadStream('./extension.zip') });
console.log(ext.id, ext.fileName, ext.projectId);
```

--------------------------------

### logs.list usage example

Source: https://github.com/browserbase/sdk-node/blob/main/_autodocs/api-reference/sessions.md

Retrieves session logs and filters for entries where the method is `Page.navigate`.

```typescript
const logs = await client.sessions.logs.list('sess_123');
logs.filter((l) => l.method === 'Page.navigate');
```

--------------------------------

### Upload certificate using fs.createReadStream

Source: https://github.com/browserbase/sdk-node/blob/main/_autodocs/api-reference/certificates.md

Example of uploading a certificate file from the filesystem using fs.createReadStream. Logs the certificate ID and project ID after creation.

```typescript
import fs from 'fs';
const cert = await client.certificates.create({ file: fs.createReadStream('/path/to/cert.pem') });
console.log(cert.id, cert.projectId);
```

--------------------------------

### Upload certificate from buffer with error handling

Source: https://github.com/browserbase/sdk-node/blob/main/_autodocs/api-reference/certificates.md

Example of uploading a certificate from a Buffer using toFile, with error handling that catches Browserbase.APIError and logs the status and error message.

```typescript
import Browserbase, { toFile } from '@browserbasehq/sdk';
const cert = await new Browserbase().certificates.create({
  file: await toFile(Buffer.from('-----BEGIN CERTIFICATE-----...'), 'cert.pem'),
}).catch((err) => {
  if (err instanceof Browserbase.APIError) {
    console.error(`upload failed: ${err.status} ${err.error ?? err.message}`);
  }
  throw err;
});
```

--------------------------------

### GET /v1/contexts/{id}

Source: https://github.com/browserbase/sdk-node/blob/main/_autodocs/endpoints.md

Retrieves a context by its ID. Returns a 404 error if not found.

```APIDOC
## GET /v1/contexts/{id}

### Description
Fetches details of a specific context using its unique identifier.

### Method
GET

### Endpoint
/v1/contexts/{id}

### Parameters
#### Path Parameters
- **id** (string) - Required - The unique identifier of the context.

### Response
#### Success Response (200)
- **Context** - The context object.

#### Response Example
{
  "id": "string",
  "name": "string"
}

#### Error Response (404)
- Returned when the context ID is unknown.
```

--------------------------------

### downloads.list method signature

Source: https://github.com/browserbase/sdk-node/blob/main/_autodocs/api-reference/sessions.md

Signature for `Sessions.Downloads.list`. It sends a GET request to `/v1/sessions/${id}/downloads` with `Accept: application/zip` and `__binaryResponse: true`, returning a raw fetch `Response` instead of parsed JSON.

```typescript
list(id: string, options?: Core.RequestOptions): Core.APIPromise<Response>
```

--------------------------------

### GET /v1/sessions/${id}/recording/downloads

Source: https://github.com/browserbase/sdk-node/blob/main/_autodocs/api-reference/sessions.md

Returns per-page download status with a short-lived signed downloadUrl for completed pages on standard projects.

```APIDOC
## GET /v1/sessions/${id}/recording/downloads

### Description
Returns per-page download status with a short-lived signed downloadUrl for completed pages on standard projects.

### Method
GET

### Endpoint
`/v1/sessions/${id}/recording/downloads`

### Parameters
#### Path Parameters
- **id** (string) - Required - The session ID.

### Request Example
```ts
const { downloads } = await client.sessions.recording.downloads.list('sess_123');
```

### Response
#### Success Response (200)
Returns an object with a `downloads` array of `RecordingDownload` objects.

#### Response Example
```json
{
  "downloads": [
    {
      "pageId": "0",
      "status": "COMPLETED",
      "completedAt": "2023-01-01T00:00:00Z",
      "downloadUrl": "https://cdn.example.com/..."
    }
  ]
}
```
```

--------------------------------

### GET /v1/webhooks

Source: https://github.com/browserbase/sdk-node/blob/main/_autodocs/endpoints.md

Lists all webhooks, newest first. Supports cursor-based pagination with optional cursor and limit query parameters.

```APIDOC
## GET /v1/webhooks

### Description
Lists all webhooks, newest first. Supports cursor-based pagination with optional cursor and limit query parameters.

### Method
GET

### Endpoint
/v1/webhooks

### Parameters
#### Query Parameters
- **cursor** (string) - Optional - Pagination cursor.
- **limit** (integer) - Optional - Maximum number of items to return.

### Response
#### Success Response (200)
- **data** (array) - List of webhook objects.
- **nextCursor** (string) - Cursor for the next page, if any.

#### Response Example
{
  "data": [
    {
      "id": "wh_123",
      "endpoint": "https://example.com/webhook",
      "eventTypes": ["session.created"]
    }
  ],
  "nextCursor": "cursor_abc"
}
```

--------------------------------

### Instantiate Browserbase client with env vars and custom options

Source: https://github.com/browserbase/sdk-node/blob/main/_autodocs/api-reference/browserbase.md

Shows how to create a client using environment variables or explicit options like timeout, maxRetries, and custom headers.

```typescript
import Browserbase from '@browserbasehq/sdk';

const client = new Browserbase(); // uses BROWSERBASE_API_KEY and BROWSERBASE_BASE_URL env vars

// explicit, with custom defaults
const client2 = new Browserbase({
  apiKey: process.env['BROWSERBASE_API_KEY']!,
  baseURL: 'https://api.browserbase.com',
  timeout: 20_000,
  maxRetries: 0,
  defaultHeaders: { 'X-My-Header': 'value' },
  defaultQuery: { projectId: 'proj_123' },
});
```

--------------------------------

### getPublicKey — Get a Keypair

Source: https://github.com/browserbase/sdk-node/blob/main/_autodocs/api-reference/secrets.md

Retrieves the project's public key and keypair ID for encrypting secret values.

```APIDOC
## GET /v1/secrets/keypair

### Description
Retrieves the project's public key and keypair ID for encrypting secret values.

### Method
GET

### Endpoint
/v1/secrets/keypair

### Response
#### Success Response (200)
- **id** (string) - Identifier of the keypair the public key was minted from. Pass back when creating a secret.
- **publicKey** (string) - The project's HPKE public encryption key, base64-encoded.

#### Response Example
```json
{
  "id": "kp_123",
  "publicKey": "base64EncodedPublicKey"
}
```
```

--------------------------------

### debug usage example

Source: https://github.com/browserbase/sdk-node/blob/main/_autodocs/api-reference/sessions.md

Calls `client.sessions.debug` with a session ID and `expiresIn` of 3600 seconds, then logs the `debuggerUrl` from the returned live URLs.

```typescript
const live = await client.sessions.debug('sess_123', { expiresIn: 3600 });
console.log(live.debuggerUrl);
```

--------------------------------

### Detach secret example

Source: https://github.com/browserbase/sdk-node/blob/main/_autodocs/api-reference/functions.md

Example of detaching a secret from a function using its ID and the secret ID.

```typescript
await client.functions.secrets.detach('fn_123', 'sec_456');
```

--------------------------------

### Attach secret example

Source: https://github.com/browserbase/sdk-node/blob/main/_autodocs/api-reference/functions.md

Example of attaching a secret to a function using its ID and the secret ID.

```typescript
await client.functions.secrets.attach('fn_123', { secretId: 'sec_456' });
```

--------------------------------

### Retrieve a context by ID

Source: https://github.com/browserbase/sdk-node/blob/main/_autodocs/api-reference/contexts.md

Example of retrieving a context by its ID. The returned context object contains metadata such as creation and update timestamps.

```ts
const ctx = await client.contexts.retrieve('ctx_123');
```

--------------------------------

### new Browserbase(options)

Source: https://github.com/browserbase/sdk-node/blob/main/_autodocs/api-reference/browserbase.md

Creates a new Browserbase client instance. The constructor accepts optional configuration options for API key, base URL, timeout, retries, and more. If no API key is provided and the BROWSERBASE_API_KEY environment variable is missing, it throws a BrowserbaseError.

```APIDOC
## new Browserbase(options)

### Description
Creates a new Browserbase client instance. The constructor accepts optional configuration options for API key, base URL, timeout, retries, and more. If no API key is provided and the BROWSERBASE_API_KEY environment variable is missing, it throws a BrowserbaseError.

### Method
Constructor

### Endpoint
`new Browserbase(options?)`

### Parameters
#### Constructor Options
- **apiKey** (string) - Optional - Your Browserbase API Key. Defaults to `process.env['BROWSERBASE_API_KEY']`. If not provided and the environment variable is missing, the constructor throws a `BrowserbaseError`.
- **baseURL** (string | null | undefined) - Optional - Override the default base URL for the API. Defaults to `process.env['BROWSERBASE_BASE_URL']` or `https://api.browserbase.com`.
- **timeout** (number) - Optional - Max milliseconds to wait for a response before timing out a single request. Defaults to `60000` ms.
- **httpAgent** (Agent) - Optional - HTTP agent used to manage HTTP(S) connections. In Node.js it forces the legacy `node-fetch` transport so the agent is honored.
- **fetch** (Core.Fetch) - Optional - Custom fetch function implementation: `(url: RequestInfo, init?: RequestInit) => Promise<Response>`. Defaults to `globalThis.fetch` (fallback `node-fetch`).
- **maxRetries** (number) - Optional - Max number of automatic retries for temporary failures (network errors, 5XX, 408/409/429). Defaults to `2`.
- **defaultHeaders** (Core.Headers) - Optional - Default headers for every request. Can be removed per-request by setting the header to `null`/`undefined` in request options. `Core.Headers = Record<string, string | null | undefined>`.
- **defaultQuery** (Core.DefaultQuery) - Optional - Default query params for every request. Can be removed per-request by passing `undefined`. `Core.DefaultQuery = Record<string, string | undefined>`.

### Request Example
```ts
import Browserbase from '@browserbasehq/sdk';

const client = new Browserbase(); // uses BROWSERBASE_API_KEY and BROWSERBASE_BASE_URL env vars

// explicit, with custom defaults
const client2 = new Browserbase({
  apiKey: process.env['BROWSERBASE_API_KEY']!,
  baseURL: 'https://api.browserbase.com',
  timeout: 20_000,
  maxRetries: 0,
  defaultHeaders: { 'X-My-Header': 'value' },
  defaultQuery: { projectId: 'proj_123' },
});
```

### Response
#### Success Response
Returns a `Browserbase` instance.

#### Error Handling
If `apiKey` is `undefined` after env-var resolution, throws a `BrowserbaseError` with the message: `"The BROWSERBASE_API_KEY environment variable is missing or empty; either provide it, or instantiate the Browserbase client with an apiKey option, like new Browserbase({ apiKey: 'My API Key' })."`

#### Error Example
```ts
import Browserbase, { BrowserbaseError } from '@browserbasehq/sdk';

try {
  const client = new Browserbase({ apiKey: undefined, baseURL: undefined });
} catch (err) {
  if (err instanceof BrowserbaseError) {
    console.error(err.message); // "The BROWSERBASE_API_KEY environment variable is missing or empty..."
  }
}
```
```

--------------------------------

### Create a Browserbase session in JavaScript

Source: https://github.com/browserbase/sdk-node/blob/main/README.md

Initializes the Browserbase client with an API key (defaults to BROWSERBASE_API_KEY environment variable) and creates a session with a project ID.

```js
import Browserbase from '@browserbasehq/sdk';

const client = new Browserbase({
  apiKey: process.env['BROWSERBASE_API_KEY'], // This is the default and can be omitted
});

const session = await client.sessions.create({ projectId: 'your_project_id' });
```

--------------------------------

### Upload Extension from File Object with Error Handling

Source: https://github.com/browserbase/sdk-node/blob/main/_autodocs/api-reference/extensions.md

Example of uploading an extension using a File object, catching APIError to log the failure status. The returned extension ID is then used to create a session.

```typescript
import Browserbase from '@browserbasehq/sdk';
const ext = await client.extensions.create({
  file: new File([zipBytes], 'ext.zip', { type: 'application/zip' }),
}).catch((err) => {
  if (err instanceof Browserbase.APIError) console.error(`upload failed (${err.status})`);
  throw err;
});
const session = await client.sessions.create({ extensionId: ext.id });
```

--------------------------------

### toFile usage with Buffer and certificates.create

Source: https://github.com/browserbase/sdk-node/blob/main/_autodocs/api-reference/uploads.md

Shows how to import toFile and use it to convert a Buffer into a File, then pass it to client.certificates.create.

```typescript
import Browserbase, { toFile } from '@browserbasehq/sdk';

const file = await toFile(Buffer.from('my bytes'), 'file.txt');
await client.certificates.create({ file });
```

--------------------------------

### Create a session with minimal parameters

Source: https://github.com/browserbase/sdk-node/blob/main/_autodocs/api-reference/sessions.md

Creates a session with only a projectId, then logs the connectUrl, id, and status. The status is expected to be 'RUNNING'.

```typescript
import Browserbase from '@browserbasehq/sdk';
const client = new Browserbase();

const session = await client.sessions.create({ projectId: 'proj_123' });
console.log(session.connectUrl, session.id, session.status); // 'RUNNING'
```

--------------------------------

### Create Session Upload: client.sessions.uploads.create

Source: https://github.com/browserbase/sdk-node/blob/main/_autodocs/api-reference/sessions.md

Creates a session upload by sending a multipart/form-data POST request to /v1/sessions/${id}/uploads. The body requires a file as an Uploadable, and the response contains a message string. The example uses toFile to convert a Buffer into an uploadable file.

```typescript
create(id: string, body: UploadCreateParams, options?: Core.RequestOptions): Core.APIPromise<UploadCreateResponse>
```

```typescript
import { toFile } from '@browserbasehq/sdk';

const { message } = await client.sessions.uploads.create('sess_123', {
  file: await toFile(Buffer.from('hello world'), 'hello.txt'),
});
```

--------------------------------

### Configure timeout globally and per-request

Source: https://github.com/browserbase/sdk-node/blob/main/README.md

Shows how to set the timeout option to override the default 1-minute request timeout. The example sets a 20-second default and a 5-second per-request timeout. On timeout, an APIConnectionTimeoutError is thrown.

```ts
// Configure the default for all requests:
const client = new Browserbase({
  timeout: 20 * 1000, // 20 seconds (default is 1 minute)
});

// Override per-request:
await client.sessions.create({ projectId: 'your_project_id' }, {
  timeout: 5 * 1000,
});
```

--------------------------------

### retrieve method signature for getting a certificate

Source: https://github.com/browserbase/sdk-node/blob/main/_autodocs/api-reference/certificates.md

Signature for the retrieve method that fetches a certificate by ID via GET /v1/certificates/${id}. Returns a promise of Certificate and throws NotFoundError for unknown IDs.

```typescript
retrieve(id: string, options?: Core.RequestOptions): Core.APIPromise<Certificate>
```

--------------------------------

### Access raw Response data with asResponse() and withResponse()

Source: https://github.com/browserbase/sdk-node/blob/main/README.md

Use .asResponse() to get the raw fetch Response, and .withResponse() to get both parsed data and raw Response. Useful for accessing headers or statusText.

```TypeScript
const client = new Browserbase();

const response = await client.sessions.create({ projectId: 'your_project_id' }).asResponse();
console.log(response.headers.get('X-My-Header'));
console.log(response.statusText); // access the underlying Response object

const { data: session, response: raw } = await client.sessions
  .create({ projectId: 'your_project_id' })
  .withResponse();
console.log(raw.headers.get('X-My-Header'));
console.log(session);
```

--------------------------------

### Configure Browserbase client with custom options

Source: https://github.com/browserbase/sdk-node/blob/main/_autodocs/configuration.md

Creates a Browserbase client with client-wide configuration including API key from environment variable, base URL, timeout, max retries, default headers, default query parameters, and a custom fetch function that logs the URL.

```TypeScript
// Client-wide configuration
const client = new Browserbase({
  apiKey: process.env['BROWSERBASE_API_KEY']!,
  baseURL: process.env['BROWSERBASE_BASE_URL'] ?? 'https://api.browserbase.com',
  timeout: 30_000,
  maxRetries: 3,
  defaultHeaders: { 'X-Custom': 'yes' },
  defaultQuery: { projectId: 'proj_123' },
  fetch: async (url, init) => { console.log(url); return fetch(url, init); },
});
```

--------------------------------

### GET /v1/agents

Source: https://github.com/browserbase/sdk-node/blob/main/api.md

Lists all agents. Returns an AgentListResponse.

```APIDOC
## GET /v1/agents

### Description
Lists all agents.

### Method
GET

### Endpoint
/v1/agents

### Parameters
#### Query Parameters
- **params** (object) - Optional - Query parameters for filtering or pagination.

### Response
#### Success Response (200)
- **AgentListResponse** (object) - A list of agents.

#### Response Example
```json
{
  "data": []
}
```
```

--------------------------------

### Delete Extension by ID

Source: https://github.com/browserbase/sdk-node/blob/main/_autodocs/api-reference/extensions.md

Example of deleting an extension by its ID.

```typescript
await client.extensions.delete('ext_123');
```

--------------------------------

### GET /v1/sessions

Source: https://github.com/browserbase/sdk-node/blob/main/api.md

Lists all sessions. Returns a SessionListResponse object.

```APIDOC
## GET /v1/sessions

### Description
Lists all sessions.

### Method
GET

### Endpoint
/v1/sessions

### Parameters
#### Query Parameters
- **params** (object) - Optional - List parameters.

### Response
#### Success Response (200)
- **SessionListResponse** (object) - A list of sessions.

### Response Example
{
  "data": []
}
```

--------------------------------

### GET /v1/sessions/{id}/logs

Source: https://github.com/browserbase/sdk-node/blob/main/_autodocs/endpoints.md

Retrieves the logs for a specific session.

```APIDOC
## GET /v1/sessions/{id}/logs

### Description
Retrieves the logs for a specific session.

### Method
GET

### Endpoint
/v1/sessions/{id}/logs

### Parameters
#### Path Parameters
- **id** (string) - Required - The unique identifier of the session.

### Response
#### Success Response (200)
- **LogListResponse** (array) - An array of `SessionLog` objects.

```

--------------------------------

### GET /v1/secrets/keypair

Source: https://github.com/browserbase/sdk-node/blob/main/_autodocs/endpoints.md

Retrieves the public keypair used for secret encryption.

```APIDOC
## GET /v1/secrets/keypair

### Description
Retrieves the public keypair used for secret encryption.

### Method
GET

### Endpoint
/v1/secrets/keypair

### Response
#### Success Response (200)
- **SecretsKeypair** - Object containing `id` and `publicKey`.

#### Response Example
{
  "id": "kp_123",
  "publicKey": "public_key_string"
}
```

--------------------------------

### ClientOptions

Source: https://github.com/browserbase/sdk-node/blob/main/_autodocs/configuration.md

Configuration options for the Browserbase SDK client constructor. These options control authentication, network behavior, retries, and custom fetch implementations.

```APIDOC
## ClientOptions

### Description
Configuration options for the Browserbase SDK client constructor. These options control authentication, network behavior, retries, and custom fetch implementations.

### Fields

- **apiKey** (string) - Optional - API key. The constructor throws if neither this nor the BROWSERBASE_API_KEY environment variable is present. Defaults to the BROWSERBASE_API_KEY environment variable.
- **baseURL** (string | null) - Optional - Base URL override, e.g. "https://api.example.com/v2/". Defaults to the BROWSERBASE_BASE_URL environment variable or "https://api.browserbase.com".
- **timeout** (number) - Optional - Max wait (ms) for a response per request; must be a non-negative integer. Defaults to 60000 ms. Timeouts retry by default.
- **httpAgent** (Agent) - Optional - Node HTTP(S) agent. In modern Node this forces the legacy node-fetch transport so the agent is honored. Defaults to the runtime default agent.
- **fetch** (Core.Fetch) - Optional - Custom fetch implementation (url, init?) => Promise<Response>; useful for logging/middleware. Defaults to globalThis.fetch with a node-fetch fallback.
- **maxRetries** (number) - Optional - Max automatic retries for network errors / 408 / 409 / 429 / >=500. Must be a non-negative integer. Defaults to 2.
- **defaultHeaders** (Core.Headers) - Optional - Headers merged into every request; can be removed per-request by setting the header to null/undefined.
- **defaultQuery** (Core.DefaultQuery) - Optional - Query params merged into every request; removed per-request by passing undefined.

### Validation
- `timeout` and `maxRetries` are validated by `validatePositiveInteger` (must be integers ≥ 0) in the `APIClient` constructor; violations throw `BrowserbaseError`.
```

--------------------------------

### GET /v1/secrets

Source: https://github.com/browserbase/sdk-node/blob/main/_autodocs/endpoints.md

Lists all secrets with optional pagination and date filters.

```APIDOC
## GET /v1/secrets

### Description
Lists all secrets with optional pagination and date filters.

### Method
GET

### Endpoint
/v1/secrets

### Parameters
#### Query Parameters
- **cursor** (string) - Optional - Pagination cursor.
- **limit** (integer) - Optional - Maximum number of items to return.
- **startAt** (string) - Optional - Start date/time filter.
- **endAt** (string) - Optional - End date/time filter.

### Response
#### Success Response (200)
- **SecretListResponse** - List of secrets.

#### Response Example
{
  "secrets": []
}
```

--------------------------------

### Run tests

Source: https://github.com/browserbase/sdk-node/blob/main/CONTRIBUTING.md

Execute the test suite with yarn.

```sh
$ yarn run test
```

--------------------------------

### Import web shims (shims/web)

Source: https://github.com/browserbase/sdk-node/blob/main/_autodocs/api-reference/shims.md

Forces the web-standard shim set, which expects global `fetch`, `FormData`, `Blob`, etc. to be provided. Use this for browsers, Deno, Bun, Cloudflare Workers, or Vercel Edge Runtime. The import must appear before importing the SDK.

```typescript
import '@browserbasehq/sdk/shims/web'; // web-standard fetch; expects globals to be provided
import Browserbase from '@browserbasehq/sdk';
```

--------------------------------

### retrieve — Get an Extension

Source: https://github.com/browserbase/sdk-node/blob/main/_autodocs/api-reference/extensions.md

Retrieves details of a specific extension by its ID.

```APIDOC
## GET /v1/extensions/{id}

### Description
Retrieves an Extension object by its ID.

### Method
GET

### Endpoint
/v1/extensions/${id}

### Parameters
#### Path Parameters
- **id** (string) - Required - Extension ID.

### Request Example
```ts
const ext = await client.extensions.retrieve('ext_123');
```

### Response
#### Success Response (200)
- **id** (string) - Extension ID.
- **createdAt** (string) - Creation timestamp.
- **fileName** (string) - Original file name.
- **projectId** (string) - Project ID linked to the extension.
- **updatedAt** (string) - Last update timestamp.

#### Response Example
```json
{
  "id": "ext_123",
  "createdAt": "2024-01-01T00:00:00Z",
  "fileName": "extension.zip",
  "projectId": "proj_123",
  "updatedAt": "2024-01-01T00:00:00Z"
}
```

### Error Handling
Throws NotFoundError (404) for unknown IDs.
```

--------------------------------

### Link a local copy of the repo

Source: https://github.com/browserbase/sdk-node/blob/main/CONTRIBUTING.md

Clone the repository and link it locally using yarn or pnpm.

```sh
# Clone
$ git clone https://www.github.com/browserbase/sdk-node
$ cd sdk-node

# With yarn
$ yarn link
$ cd ../my-package
$ yarn link @browserbasehq/sdk

# With pnpm
$ pnpm link --global
$ cd ../my-package
$ pnpm link --global @browserbasehq/sdk
```

--------------------------------

### POST /v1/sessions/{id}/recording/downloads

Source: https://github.com/browserbase/sdk-node/blob/main/_autodocs/endpoints.md

Creates a download request for the session's recording. The response contains download statuses, all initially PENDING.

```APIDOC
## POST /v1/sessions/{id}/recording/downloads

### Description
Creates a download request for the session's recording.

### Method
POST

### Endpoint
/v1/sessions/{id}/recording/downloads

### Parameters
#### Path Parameters
- **id** (string) - Required - The unique identifier of the session.

### Response
#### Success Response (200)
- **DownloadCreateResponse** (object) - Contains download statuses, all initially `PENDING`.

```

--------------------------------

### Delete a context by ID

Source: https://github.com/browserbase/sdk-node/blob/main/_autodocs/api-reference/contexts.md

Example of deleting a context by its ID. The promise resolves to void.

```ts
await client.contexts.delete('ctx_123');
```

--------------------------------

### POST /v1/contexts

Source: https://github.com/browserbase/sdk-node/blob/main/_autodocs/endpoints.md

Creates a new context with optional name and project ID.

```APIDOC
## POST /v1/contexts

### Description
Creates a new context with optional name and project ID.

### Method
POST

### Endpoint
/v1/contexts

### Parameters
#### Request Body
- **name** (string) - Optional - The name of the context.
- **projectId** (string) - Optional - The ID of the project.

### Request Example
{
  "name": "string",
  "projectId": "string"
}

### Response
#### Success Response (200)
- **ContextCreateResponse** - The created context object with ID and encryption parameters.

#### Response Example
{
  "id": "string",
  "encryptionParams": {}
}
```

--------------------------------

### GET /v1/sessions/{id}/replays

Source: https://github.com/browserbase/sdk-node/blob/main/api.md

Retrieves replays for a session. Returns a ReplayRetrieveResponse object.

```APIDOC
## GET /v1/sessions/{id}/replays

### Description
Retrieves replays for a session.

### Method
GET

### Endpoint
/v1/sessions/{id}/replays

### Parameters
#### Path Parameters
- **id** (string) - Required - The ID of the session.

### Response
#### Success Response (200)
- **ReplayRetrieveResponse** (object) - The replay data.

### Response Example
{
  "id": "replay_123"
}
```

--------------------------------

### GET /v1/sessions/{id}/recording

Source: https://github.com/browserbase/sdk-node/blob/main/api.md

Retrieves the recording for a session. Returns a RecordingRetrieveResponse object.

```APIDOC
## GET /v1/sessions/{id}/recording

### Description
Retrieves the recording for a session.

### Method
GET

### Endpoint
/v1/sessions/{id}/recording

### Parameters
#### Path Parameters
- **id** (string) - Required - The ID of the session.

### Response
#### Success Response (200)
- **RecordingRetrieveResponse** (object) - The recording data.

### Response Example
{
  "id": "rec_123"
}
```

--------------------------------

### GET /v1/certificates

Source: https://github.com/browserbase/sdk-node/blob/main/api.md

Lists all certificates. This method is called as client.certificates.list() and returns a CertificateListResponse object.

```APIDOC
## GET /v1/certificates

### Description
Lists all certificates.

### Method
GET

### Endpoint
/v1/certificates

### Response
#### Success Response (200)
- **CertificateListResponse** (object) - A list of certificates.

#### Response Example
```json
{
  "data": [
    {
      "id": "cert_123",
      "name": "My Certificate"
    }
  ]
}
```
```

--------------------------------

### GET /v1/sessions/{id}/recording

Source: https://github.com/browserbase/sdk-node/blob/main/_autodocs/endpoints.md

Retrieves the recording data for a session. This endpoint is deprecated.

```APIDOC
## GET /v1/sessions/{id}/recording

### Description
Retrieves the recording data for a session. This endpoint is deprecated.

### Method
GET

### Endpoint
/v1/sessions/{id}/recording

### Parameters
#### Path Parameters
- **id** (string) - Required - The unique identifier of the session.

### Response
#### Success Response (200)
- **RecordingRetrieveResponse** (object) - Contains an array of rrweb events.

```

--------------------------------

### Browserbase constructor signature

Source: https://github.com/browserbase/sdk-node/blob/main/_autodocs/api-reference/browserbase.md

The constructor accepts ClientOptions with defaults from environment variables.

```typescript
constructor({
  baseURL = Core.readEnv('BROWSERBASE_BASE_URL'),
  apiKey = Core.readEnv('BROWSERBASE_API_KEY'),
  ...opts
}: ClientOptions = {})
```

--------------------------------

### GET /v1/extensions/{id}

Source: https://github.com/browserbase/sdk-node/blob/main/_autodocs/endpoints.md

Retrieves an extension by its ID. Returns a 404 error if not found.

```APIDOC
## GET /v1/extensions/{id}

### Description
Fetches details of a specific extension using its unique identifier.

### Method
GET

### Endpoint
/v1/extensions/{id}

### Parameters
#### Path Parameters
- **id** (string) - Required - The unique identifier of the extension.

### Response
#### Success Response (200)
- **Extension** - The extension object.

#### Response Example
{
  "id": "string",
  "name": "string"
}

#### Error Response (404)
- Returned when the extension ID is unknown.
```

--------------------------------

### Update a context by ID

Source: https://github.com/browserbase/sdk-node/blob/main/_autodocs/api-reference/contexts.md

Example of updating a context by its ID. The method is deprecated and does not accept a body.

```ts
const ctx = await client.contexts.update('ctx_123');
```

--------------------------------

### Create MP4 recording download

Source: https://github.com/browserbase/sdk-node/blob/main/_autodocs/api-reference/sessions.md

Requests one downloadable MP4 per recorded page. Assembly is asynchronous and every page returns as PENDING. Re-posting re-enqueues all pages.

```TypeScript
create(id: string, options?: Core.RequestOptions): Core.APIPromise<DownloadCreateResponse>
```

--------------------------------

### GET /v1/secrets/{id}

Source: https://github.com/browserbase/sdk-node/blob/main/_autodocs/endpoints.md

Retrieves a secret by its ID. Returns a 404 error if the secret is unknown.

```APIDOC
## GET /v1/secrets/{id}

### Description
Retrieves a secret by its ID. Returns a 404 error if the secret is unknown.

### Method
GET

### Endpoint
/v1/secrets/{id}

### Parameters
#### Path Parameters
- **id** (string) - Required - The secret ID.

### Response
#### Success Response (200)
- **Secret** - The secret object.

#### Response Example
{
  "id": "secret_123",
  "key": "my_secret"
}
```

--------------------------------

### Agents.list signatures

Source: https://github.com/browserbase/sdk-node/blob/main/_autodocs/api-reference/agents.md

Two overloaded TypeScript signatures for listing agents. Calls GET /v1/agents.

```ts
list(query?: AgentListParams, options?: Core.RequestOptions): Core.APIPromise<AgentListResponse>;
list(options?: Core.RequestOptions): Core.APIPromise<AgentListResponse>;
```

--------------------------------

### Delete a certificate and log confirmation

Source: https://github.com/browserbase/sdk-node/blob/main/_autodocs/api-reference/certificates.md

Example of deleting a certificate by ID and logging 'deleted' after the operation completes.

```typescript
await client.certificates.delete('cert_123');
console.log('deleted');
```

--------------------------------

### list method signature for listing certificates

Source: https://github.com/browserbase/sdk-node/blob/main/_autodocs/api-reference/certificates.md

Signature for the list method that returns an array of certificates via GET /v1/certificates.

```typescript
list(options?: Core.RequestOptions): Core.APIPromise<CertificateListResponse>
```
Tokens:
Raw