> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.nativeport.ai/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.nativeport.ai/_mcp/server.

# Browserbase

Fronts the **session** surface of [Browserbase](https://www.browserbase.com) at `https://api.browserbase.com`: session creation, updates to a live session, and session detail reads. The path following `/browserbase/` is relayed upstream, restricted to those session actions:

```
GET|POST /browserbase/<api path>   → https://api.browserbase.com/<api path>
```

Admission is default-deny against a fixed allowlist. The session actions listed below are the only paths that pass; everything else — projects, contexts, extensions, plus the `GET /v1/sessions` list — draws a `404` until the endpoint concerned is added to the allowlist. Mounted methods: `GET`, `POST`.

## Common paths

| Path                                 | Purpose                  |
| ------------------------------------ | ------------------------ |
| `POST /browserbase/v1/sessions`      | Create a session         |
| `POST /browserbase/v1/sessions/{id}` | Update a running session |
| `GET /browserbase/v1/sessions/{id}`  | Session details          |

## Credential handling

* **`X-BB-API-Key` is injected**; a client-supplied value is overwritten.
* **`Authorization` is dropped** before the request goes upstream — your gateway token is meaningless to Browserbase.

On session creation, `projectId` may be omitted — the API key already tells Browserbase which project — so the gateway adds nothing to the body. Passing `projectId` explicitly is still fine when a particular project must be targeted.

## WebSocket / browser automation

**WebSocket sessions are not proxied** — only plain HTTP passes through the gateway.

The browser automation itself runs over a WebSocket: the session response carries a `connectUrl` for it. So create the session **via** the gateway, then point your Playwright/Puppeteer client straight at that session-scoped `connectUrl`:

1. Call `POST /browserbase/v1/sessions` via the gateway.
2. Attach your automation client straight to the returned `connectUrl`.

As before, the master key never lands on the client.

## Example

```bash
curl -X POST "$GATEWAY/browserbase/v1/sessions" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{}'
```

Responses arrive as Browserbase's JSON, untouched. Field-level request and response detail lives in [Browserbase's API reference](https://docs.browserbase.com/reference/api/overview); the gateway modifies neither.