{"openapi":"3.1.0","info":{"title":"StableBrowser","description":"Pay-per-session browser automation. Create a real browser session ($0.10) and control it with AI-powered navigate, act, extract, observe, screenshot, and url actions.","version":"1.0.0","x-guidance":"# StableBrowser API\n\nPay-per-session browser automation. Launch a real Chromium browser in the cloud, control it with AI-powered actions, and close it when done.\n\n## Workflow\n\n1. **Create a session** — POST /api/sessions ($0.10, x402 payment). Returns a `sessionId`.\n2. **Use the session** — call any of the session actions below using SIWX (free, wallet-signed identity).\n3. **Close the session** — POST /api/sessions/close when done to avoid leaving orphaned browsers.\n\nAll session actions require `sessionId` in the body and SIWX authentication. Only the wallet that created the session can use it.\n\n## Endpoints\n\n### POST /api/sessions — Create session ($0.10)\nStarts a new Browserbase browser session. Returns `sessionId`, `debugUrl` (Browserbase live view), and `viewerUrl` (in-app viewer).\nOptionally pass an existing `sessionId` to reconnect to a live session rather than starting a fresh one.\n\n### POST /api/sessions/navigate — Navigate to a URL\nGo to any URL. Returns the resolved URL and page title after navigation.\n\n### POST /api/sessions/act — AI-powered action\nPerform a natural language browser action via Stagehand. Examples:\n- \"Click the login button\"\n- \"Fill in the email field with user@example.com\"\n- \"Scroll down to the pricing section\"\nSupports `variables` for safe string interpolation (e.g. \"Type %email% into the search box\" with `variables: { email: \"...\" }`).\n\n### POST /api/sessions/extract — Extract structured data\nPull structured data from the current page using a natural language instruction. Examples:\n- \"Extract all product names and prices\"\n- \"Get the article headline and publication date\"\nReturns `{ data: ... }` where the shape is inferred from the instruction.\n\n### POST /api/sessions/observe — Find interactive elements\nIdentify clickable/interactive elements matching a description. Returns a list of elements with selectors, methods, and args — useful for planning multi-step interactions before committing.\n\n### POST /api/sessions/screenshot — Capture screenshot\nReturns a base64-encoded PNG of the full current page.\n\n### POST /api/sessions/url — Get current URL\nReturns the browser's current URL.\n\n### GET /api/sessions/:sessionId — Get session details\nReturns session status, `liveViewUrl` (Browserbase iframe URL), and timestamps.\n\n### POST /api/sessions/close — Close session\nTerminates the Browserbase session. Always close sessions when done.\n\n## Example flow\n\n```\n// 1. Pay to create session\nPOST /api/sessions → { sessionId: \"abc123\", debugUrl: \"...\", viewerUrl: \"...\" }\n\n// 2. Navigate\nPOST /api/sessions/navigate { sessionId: \"abc123\", url: \"https://example.com\" }\n\n// 3. Interact\nPOST /api/sessions/act { sessionId: \"abc123\", action: \"Click the sign up button\" }\n\n// 4. Extract results\nPOST /api/sessions/extract { sessionId: \"abc123\", instruction: \"Get the confirmation message text\" }\n\n// 5. Close\nPOST /api/sessions/close { sessionId: \"abc123\" }\n```\n\n## Notes\n- Sessions are owned by the creating wallet; all actions verify ownership.\n- Act/extract/observe use Stagehand (AI-powered) and may take a few seconds.\n- Navigate/screenshot/url use Playwright directly and are faster.\n","guidance":"# StableBrowser API\n\nPay-per-session browser automation. Launch a real Chromium browser in the cloud, control it with AI-powered actions, and close it when done.\n\n## Workflow\n\n1. **Create a session** — POST /api/sessions ($0.10, x402 payment). Returns a `sessionId`.\n2. **Use the session** — call any of the session actions below using SIWX (free, wallet-signed identity).\n3. **Close the session** — POST /api/sessions/close when done to avoid leaving orphaned browsers.\n\nAll session actions require `sessionId` in the body and SIWX authentication. Only the wallet that created the session can use it.\n\n## Endpoints\n\n### POST /api/sessions — Create session ($0.10)\nStarts a new Browserbase browser session. Returns `sessionId`, `debugUrl` (Browserbase live view), and `viewerUrl` (in-app viewer).\nOptionally pass an existing `sessionId` to reconnect to a live session rather than starting a fresh one.\n\n### POST /api/sessions/navigate — Navigate to a URL\nGo to any URL. Returns the resolved URL and page title after navigation.\n\n### POST /api/sessions/act — AI-powered action\nPerform a natural language browser action via Stagehand. Examples:\n- \"Click the login button\"\n- \"Fill in the email field with user@example.com\"\n- \"Scroll down to the pricing section\"\nSupports `variables` for safe string interpolation (e.g. \"Type %email% into the search box\" with `variables: { email: \"...\" }`).\n\n### POST /api/sessions/extract — Extract structured data\nPull structured data from the current page using a natural language instruction. Examples:\n- \"Extract all product names and prices\"\n- \"Get the article headline and publication date\"\nReturns `{ data: ... }` where the shape is inferred from the instruction.\n\n### POST /api/sessions/observe — Find interactive elements\nIdentify clickable/interactive elements matching a description. Returns a list of elements with selectors, methods, and args — useful for planning multi-step interactions before committing.\n\n### POST /api/sessions/screenshot — Capture screenshot\nReturns a base64-encoded PNG of the full current page.\n\n### POST /api/sessions/url — Get current URL\nReturns the browser's current URL.\n\n### GET /api/sessions/:sessionId — Get session details\nReturns session status, `liveViewUrl` (Browserbase iframe URL), and timestamps.\n\n### POST /api/sessions/close — Close session\nTerminates the Browserbase session. Always close sessions when done.\n\n## Example flow\n\n```\n// 1. Pay to create session\nPOST /api/sessions → { sessionId: \"abc123\", debugUrl: \"...\", viewerUrl: \"...\" }\n\n// 2. Navigate\nPOST /api/sessions/navigate { sessionId: \"abc123\", url: \"https://example.com\" }\n\n// 3. Interact\nPOST /api/sessions/act { sessionId: \"abc123\", action: \"Click the sign up button\" }\n\n// 4. Extract results\nPOST /api/sessions/extract { sessionId: \"abc123\", instruction: \"Get the confirmation message text\" }\n\n// 5. Close\nPOST /api/sessions/close { sessionId: \"abc123\" }\n```\n\n## Notes\n- Sessions are owned by the creating wallet; all actions verify ownership.\n- Act/extract/observe use Stagehand (AI-powered) and may take a few seconds.\n- Navigate/screenshot/url use Playwright directly and are faster.\n"},"servers":[{"url":"https://stablebrowser.vercel.app"}],"tags":[{"name":"Session Act"},{"name":"Session Close"},{"name":"Session Extract"},{"name":"Session Get"},{"name":"Session Navigate"},{"name":"Session Observe"},{"name":"Session Screenshot"},{"name":"Session Url"},{"name":"Sessions"}],"paths":{"/api/sessions/:sessionId":{"get":{"operationId":"session-get","summary":"Get session details. Only the owner wallet can retrieve this.","tags":["Session Get"],"security":[{"siwx":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"sessionId":{"type":"string"},"status":{"type":"string","enum":["active","closed"]},"liveViewUrl":{"anyOf":[{"type":"string"},{"type":"null"}]},"createdAt":{"type":"string"},"closedAt":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["sessionId","status","liveViewUrl","createdAt","closedAt"],"additionalProperties":false}}}},"402":{"description":"Authentication Required"}}}},"/api/sessions/navigate":{"post":{"operationId":"session-navigate","summary":"Navigate the browser to a URL. Session must be active and owned by the caller.","tags":["Session Navigate"],"security":[{"siwx":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"sessionId":{"type":"string","description":"Session ID returned from POST /api/sessions"},"url":{"type":"string","description":"The URL to navigate to"}},"required":["sessionId","url"]}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"url":{"type":"string","description":"Current page URL after navigation"},"title":{"type":"string","description":"Page title after navigation"}},"required":["url","title"],"additionalProperties":false}}}},"402":{"description":"Authentication Required"}}}},"/api/sessions/screenshot":{"post":{"operationId":"session-screenshot","summary":"Capture a full-page screenshot of the current browser state. Returns a base64-encoded PNG.","tags":["Session Screenshot"],"security":[{"siwx":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"sessionId":{"type":"string","description":"Session ID returned from POST /api/sessions"},"name":{"description":"The name of the screenshot","type":"string"}},"required":["sessionId"]}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"screenshot":{"type":"string","description":"Base64-encoded PNG screenshot"},"mimeType":{"type":"string","const":"image/png"}},"required":["screenshot","mimeType"],"additionalProperties":false}}}},"402":{"description":"Authentication Required"}}}},"/api/sessions/url":{"post":{"operationId":"session-url","summary":"Return the current page URL of the browser session.","tags":["Session Url"],"security":[{"siwx":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"sessionId":{"type":"string","description":"Session ID returned from POST /api/sessions"}},"required":["sessionId"]}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"url":{"type":"string","description":"Current page URL"}},"required":["url"],"additionalProperties":false}}}},"402":{"description":"Authentication Required"}}}},"/api/sessions":{"post":{"operationId":"sessions","summary":"Create a new browser session ($0.10). Optionally pass sessionId to resume an existing Browserbase session. Returns sessionId (Browserbase session ID) to use for all subsequent calls.","tags":["Sessions"],"x-payment-info":{"price":{"mode":"fixed","currency":"USD","amount":"0.10"},"protocols":[{"x402":{}}]},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"sessionId":{"description":"Optional session ID to use/reuse. If not provided or invalid, a new session is created.","type":"string"}}}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"sessionId":{"type":"string","description":"Browserbase session ID — use this in all subsequent calls"},"debugUrl":{"description":"Browserbase live debugger URL (fullscreen view of the browser)","type":"string"},"viewerUrl":{"description":"StableBrowser viewer page — sign in with your wallet to watch the session","type":"string"},"createdAt":{"type":"string"}},"required":["sessionId","createdAt"],"additionalProperties":false}}}},"402":{"description":"Payment Required"}}}},"/api/sessions/close":{"post":{"operationId":"session-close","summary":"Close a browser session. Only the wallet that created the session can close it.","tags":["Session Close"],"security":[{"siwx":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"sessionId":{"type":"string","description":"Session ID returned from POST /api/sessions"}},"required":["sessionId"]}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"sessionId":{"type":"string"},"status":{"type":"string","const":"closed"},"closedAt":{"type":"string"}},"required":["sessionId","status","closedAt"],"additionalProperties":false}}}},"402":{"description":"Authentication Required"}}}},"/api/sessions/act":{"post":{"operationId":"session-act","summary":"Perform an AI-powered action on the page. Describe what to do in plain English, e.g. 'Click the login button' or 'Fill in the email field with user@example.com'.","tags":["Session Act"],"security":[{"siwx":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"sessionId":{"type":"string","description":"Session ID returned from POST /api/sessions"},"action":{"type":"string","description":"The action to perform. Should be as atomic and specific as possible, i.e. 'Click the sign in button' or 'Type 'hello' into the search input'."},"variables":{"description":"Variables used in the action template. ONLY use variables if you're dealing with sensitive data or dynamic content. When using variables, you MUST have the variable key in the action template. ie: {\"action\": \"Fill in the password\", \"variables\": {\"password\": \"123456\"}}","type":"object","propertyNames":{"type":"string"},"additionalProperties":{}}},"required":["sessionId","action"]}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"message":{"type":"string"}},"required":["success"],"additionalProperties":false}}}},"402":{"description":"Authentication Required"}}}},"/api/sessions/extract":{"post":{"operationId":"session-extract","summary":"Extract structured data from the current page using an AI instruction. Be specific about what to extract, e.g. 'Extract all product names and prices from the listing page'.","tags":["Session Extract"],"security":[{"siwx":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"sessionId":{"type":"string","description":"Session ID returned from POST /api/sessions"},"instruction":{"type":"string","description":"The specific instruction for what information to extract from the current page. Be as detailed and specific as possible about what you want to extract. For example: 'Extract all product names and prices from the listing page'. The more specific your instruction, the better the extraction results will be."}},"required":["sessionId","instruction"]}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"Extracted structured data"}},"required":["data"],"additionalProperties":false}}}},"402":{"description":"Authentication Required"}}}},"/api/sessions/observe":{"post":{"operationId":"session-observe","summary":"Find interactive elements on the page. Be specific, e.g. 'Find the red login button in the top right corner'.","tags":["Session Observe"],"security":[{"siwx":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"sessionId":{"type":"string","description":"Session ID returned from POST /api/sessions"},"instruction":{"type":"string","description":"Detailed instruction for what specific elements or components to observe on the web page. This instruction must be extremely specific and descriptive. For example: 'Find the red login button in the top right corner', 'Locate the search input field with placeholder text', or 'Identify all clickable product cards on the page'. The more specific and detailed your instruction, the better the observation results will be. Avoid generic instructions like 'find buttons' or 'see elements'. Instead, describe the visual characteristics, location, text content, or functionality of the elements you want to observe. This tool is designed to help you identify interactive elements that you can later use with the act tool for performing actions like clicking, typing, or form submission."}},"required":["sessionId","instruction"]}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"elements":{"type":"array","items":{"type":"object","properties":{"description":{"type":"string"},"selector":{"type":"string"},"method":{"type":"string"},"args":{"type":"array","items":{"type":"string"}}},"required":["description"],"additionalProperties":false},"description":"Interactive elements matching the instruction"}},"required":["elements"],"additionalProperties":false}}}},"402":{"description":"Authentication Required"}}}}},"components":{"securitySchemes":{"siwx":{"type":"apiKey","in":"header","name":"SIGN-IN-WITH-X"}}}}