# StableBrowser API

Pay-per-session browser automation. Launch a real Chromium browser in the cloud, control it with AI-powered actions, and close it when done.

## Workflow

1. **Create a session** — POST /api/sessions ($0.10, x402 payment). Returns a `sessionId`.
2. **Use the session** — call any of the session actions below using SIWX (free, wallet-signed identity).
3. **Close the session** — POST /api/sessions/close when done to avoid leaving orphaned browsers.

All session actions require `sessionId` in the body and SIWX authentication. Only the wallet that created the session can use it.

## Endpoints

### POST /api/sessions — Create session ($0.10)
Starts a new Browserbase browser session. Returns `sessionId`, `debugUrl` (Browserbase live view), and `viewerUrl` (in-app viewer).
Optionally pass an existing `sessionId` to reconnect to a live session rather than starting a fresh one.

### POST /api/sessions/navigate — Navigate to a URL
Go to any URL. Returns the resolved URL and page title after navigation.

### POST /api/sessions/act — AI-powered action
Perform a natural language browser action via Stagehand. Examples:
- "Click the login button"
- "Fill in the email field with user@example.com"
- "Scroll down to the pricing section"
Supports `variables` for safe string interpolation (e.g. "Type %email% into the search box" with `variables: { email: "..." }`).

### POST /api/sessions/extract — Extract structured data
Pull structured data from the current page using a natural language instruction. Examples:
- "Extract all product names and prices"
- "Get the article headline and publication date"
Returns `{ data: ... }` where the shape is inferred from the instruction.

### POST /api/sessions/observe — Find interactive elements
Identify clickable/interactive elements matching a description. Returns a list of elements with selectors, methods, and args — useful for planning multi-step interactions before committing.

### POST /api/sessions/screenshot — Capture screenshot
Returns a base64-encoded PNG of the full current page.

### POST /api/sessions/url — Get current URL
Returns the browser's current URL.

### GET /api/sessions/:sessionId — Get session details
Returns session status, `liveViewUrl` (Browserbase iframe URL), and timestamps.

### POST /api/sessions/close — Close session
Terminates the Browserbase session. Always close sessions when done.

## Example flow

```
// 1. Pay to create session
POST /api/sessions → { sessionId: "abc123", debugUrl: "...", viewerUrl: "..." }

// 2. Navigate
POST /api/sessions/navigate { sessionId: "abc123", url: "https://example.com" }

// 3. Interact
POST /api/sessions/act { sessionId: "abc123", action: "Click the sign up button" }

// 4. Extract results
POST /api/sessions/extract { sessionId: "abc123", instruction: "Get the confirmation message text" }

// 5. Close
POST /api/sessions/close { sessionId: "abc123" }
```

## Notes
- Sessions are owned by the creating wallet; all actions verify ownership.
- Act/extract/observe use Stagehand (AI-powered) and may take a few seconds.
- Navigate/screenshot/url use Playwright directly and are faster.