From 5f49e6020bb74b4c32187ff3d8fc00c305904a62 Mon Sep 17 00:00:00 2001 From: miguel Date: Tue, 15 Sep 2026 15:15:19 -0700 Subject: [PATCH] fix(docs): preserve v3 API reference with a local OpenAPI snapshot --- packages/docs/README.md | 21 + packages/docs/docs.json | 10 +- packages/docs/tests/v3-openapi.test.ts | 100 + packages/docs/v3/openapi.json | 2466 ++++++++++++++++++++++++ 4 files changed, 2592 insertions(+), 5 deletions(-) create mode 100644 packages/docs/tests/v3-openapi.test.ts create mode 100644 packages/docs/v3/openapi.json diff --git a/packages/docs/README.md b/packages/docs/README.md index 2eb230335a..27693badd8 100644 --- a/packages/docs/README.md +++ b/packages/docs/README.md @@ -25,6 +25,27 @@ just check This validates the Mint configuration and OpenAPI definitions, checks links and redirects, and runs the documentation accessibility checks. +## V3 API reference source + +The v3 API reference uses the checked-in `v3/openapi.json`, not a live Stainless URL. +The former source, +`https://app.stainless.com/api/spec/documented/stagehand/openapi.documented.yml`, +returned HTTP 404 and prevented Mint validation from completing. + +The snapshot was recovered on September 15, 2026 from the OpenAPI YAML blocks in the +published `https://docs.stagehand.dev/v3/api-reference/{language}/{page}.md` pages. +All 32 pages (eight endpoints each for Python, Java, Go, and Ruby) were compared. +Their common metadata, operations, and shared components agreed. The snapshot +combines those fragments without changing descriptions, schemas, authentication, +servers, or code samples: eight endpoints, 67 schemas, and two security schemes. +The four language sections retain their existing navigation and generated page paths. + +Treat this as the versioned v3 documentation source. Future spec updates must be +reviewed as content changes, including endpoint titles/URLs, request and response +schemas, authentication, and code samples. Do not replace it with a different +server-generated spec just to make validation pass. Run the docs checks and +`pnpm --filter @browserbasehq/stagehand-docs test:unit` after updates. + ## Publishing Documentation is deployed through the Mintlify GitHub integration after changes reach the diff --git a/packages/docs/docs.json b/packages/docs/docs.json index a60d3d068d..366ec251ba 100644 --- a/packages/docs/docs.json +++ b/packages/docs/docs.json @@ -16,7 +16,7 @@ } }, "api": { - "openapi": "https://app.stainless.com/api/spec/documented/stagehand/openapi.documented.yml" + "openapi": "v3/openapi.json" }, "navigation": { "versions": [ @@ -228,7 +228,7 @@ { "group": "API Reference", "openapi": { - "source": "https://app.stainless.com/api/spec/documented/stagehand/openapi.documented.yml", + "source": "v3/openapi.json", "directory": "v3/api-reference/python" }, "pages": [ @@ -256,7 +256,7 @@ { "group": "API Reference", "openapi": { - "source": "https://app.stainless.com/api/spec/documented/stagehand/openapi.documented.yml", + "source": "v3/openapi.json", "directory": "v3/api-reference/java" }, "pages": [ @@ -284,7 +284,7 @@ { "group": "API Reference", "openapi": { - "source": "https://app.stainless.com/api/spec/documented/stagehand/openapi.documented.yml", + "source": "v3/openapi.json", "directory": "v3/api-reference/go" }, "pages": [ @@ -312,7 +312,7 @@ { "group": "API Reference", "openapi": { - "source": "https://app.stainless.com/api/spec/documented/stagehand/openapi.documented.yml", + "source": "v3/openapi.json", "directory": "v3/api-reference/ruby" }, "pages": [ diff --git a/packages/docs/tests/v3-openapi.test.ts b/packages/docs/tests/v3-openapi.test.ts new file mode 100644 index 0000000000..1733496172 --- /dev/null +++ b/packages/docs/tests/v3-openapi.test.ts @@ -0,0 +1,100 @@ +import { readFileSync } from "node:fs"; +import { describe, expect, it } from "vitest"; + +const config = JSON.parse(readFileSync(new URL("../docs.json", import.meta.url), "utf8")); +const spec = JSON.parse(readFileSync(new URL("../v3/openapi.json", import.meta.url), "utf8")); +const endpoints = [ + ["POST /v1/sessions/start", "Start a new browser session"], + ["POST /v1/sessions/{id}/navigate", "Navigate to a URL"], + ["POST /v1/sessions/{id}/act", "Perform an action"], + ["POST /v1/sessions/{id}/observe", "Observe available actions"], + ["POST /v1/sessions/{id}/extract", "Extract data from the page"], + ["POST /v1/sessions/{id}/agentExecute", "Execute an AI agent"], + ["POST /v1/sessions/{id}/end", "End a browser session"], + ["GET /v1/sessions/{id}/replay", "Replay session metrics"], +]; + +function findReferences(value: unknown): string[] { + if (value === null || typeof value !== "object") return []; + return Object.entries(value).flatMap(([key, entry]) => + key === "$ref" && typeof entry === "string" ? [entry] : findReferences(entry), + ); +} + +describe("v3 API reference", () => { + it("uses the local spec for all four existing API navigation sections", () => { + expect(config.api.openapi).toBe("v3/openapi.json"); + const version = config.navigation.versions.find( + (entry: { version: string }) => entry.version === "v3", + ); + const apiSections = version.dropdowns.filter( + (entry: { dropdown: string }) => entry.dropdown !== "TypeScript", + ); + expect(apiSections.map((entry: { dropdown: string }) => entry.dropdown)).toEqual([ + "Python", + "Java", + "Go", + "Ruby", + ]); + for (const section of apiSections) { + const reference = section.groups.find( + (group: { group: string }) => group.group === "API Reference", + ); + expect(reference.openapi).toEqual({ + source: "v3/openapi.json", + directory: `v3/api-reference/${section.dropdown.toLowerCase()}`, + }); + expect(reference.pages).toEqual(endpoints.map(([endpoint]) => endpoint)); + } + }); + + it.each(endpoints)("preserves the title and code sample languages for %s", (endpoint, title) => { + const [method, path] = endpoint.split(" "); + const operation = spec.paths[path][method.toLowerCase()]; + expect(operation.summary).toBe(title); + expect(operation.description).toBeTruthy(); + expect(operation.responses["200"]).toBeDefined(); + expect(operation["x-codeSamples"].map((sample: { lang: string }) => sample.lang)).toEqual([ + "JavaScript", + "Python", + "Go", + "Java", + "Kotlin", + "Ruby", + "PHP", + "C#", + ]); + for (const sample of operation["x-codeSamples"]) { + expect(sample.source.trim()).not.toBe(""); + } + }); + + it("resolves every schema reference without fetching an external document", () => { + const references = findReferences(spec); + expect(references.length).toBeGreaterThan(0); + for (const reference of references) { + expect(reference).toMatch(/^#\//); + const resolved = reference + .slice(2) + .split("/") + .map((part) => part.replace(/~1/g, "/").replace(/~0/g, "~")) + .reduce((value, key) => value?.[key], spec); + expect(resolved, reference).toBeDefined(); + } + }); + + it("preserves the API server and authentication schemes", () => { + expect(spec.servers).toEqual([{ url: "https://api.stagehand.browserbase.com" }]); + expect(spec.security).toEqual([{ BrowserbaseApiKey: [], BrowserbaseProjectId: [] }]); + expect(spec.components.securitySchemes.BrowserbaseApiKey).toMatchObject({ + type: "apiKey", + in: "header", + name: "x-bb-api-key", + }); + expect(spec.components.securitySchemes.BrowserbaseProjectId).toMatchObject({ + type: "apiKey", + in: "header", + name: "x-bb-project-id", + }); + }); +}); diff --git a/packages/docs/v3/openapi.json b/packages/docs/v3/openapi.json new file mode 100644 index 0000000000..0e1373d1b3 --- /dev/null +++ b/packages/docs/v3/openapi.json @@ -0,0 +1,2466 @@ +{ + "openapi": "3.1.0", + "info": { + "title": "Stagehand API", + "version": "3.1.0", + "description": "Stagehand SDK for AI browser automation [ALPHA]. This API allows clients to\nexecute browser automation tasks remotely on the Browserbase cloud.\nAll endpoints except /sessions/start require an active session ID.\nResponses are streamed using Server-Sent Events (SSE) when the\n`x-stream-response: true` header is provided.\n\nThis SDK is currently ALPHA software and is not production ready!\nPlease try it and give us your feedback, stay tuned for upcoming release announcements!", + "contact": { + "name": "Browserbase", + "url": "https://browserbase.com" + } + }, + "servers": [ + { + "url": "https://api.stagehand.browserbase.com" + } + ], + "security": [ + { + "BrowserbaseApiKey": [], + "BrowserbaseProjectId": [] + } + ], + "paths": { + "/v1/sessions/start": { + "post": { + "summary": "Start a new browser session", + "description": "Creates a new browser session with the specified configuration. Returns a session ID used for all subsequent operations.", + "operationId": "SessionStart", + "parameters": [ + { + "schema": { + "description": "Whether to stream the response via SSE", + "example": "true", + "type": "string", + "enum": ["true", "false"] + }, + "in": "header", + "name": "x-stream-response", + "description": "Whether to stream the response via SSE" + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/SessionStartRequest" + } + } + }, + "required": true + }, + "responses": { + "200": { + "description": "Default Response", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/SessionStartResponse" + } + } + } + } + }, + "x-codeSamples": [ + { + "lang": "JavaScript", + "source": "import Stagehand from 'stagehand-sdk';\n\nconst client = new Stagehand({\n browserbaseAPIKey: process.env['BROWSERBASE_API_KEY'], // This is the default and can be omitted\n browserbaseProjectID: process.env['BROWSERBASE_PROJECT_ID'], // This is the default and can be omitted\n modelAPIKey: process.env['MODEL_API_KEY'], // This is the default and can be omitted\n});\n\nconst response = await client.sessions.start({ modelName: 'openai/gpt-5.4-mini' });\n\nconsole.log(response.data);" + }, + { + "lang": "Python", + "source": "import os\nfrom stagehand import Stagehand\n\nclient = Stagehand(\n browserbase_api_key=os.environ.get(\"BROWSERBASE_API_KEY\"), # This is the default and can be omitted\n browserbase_project_id=os.environ.get(\"BROWSERBASE_PROJECT_ID\"), # This is the default and can be omitted\n model_api_key=os.environ.get(\"MODEL_API_KEY\"), # This is the default and can be omitted\n)\nresponse = client.sessions.start(\n model_name=\"openai/gpt-5.4-mini\",\n)\nprint(response.data)" + }, + { + "lang": "Go", + "source": "package main\n\nimport (\n\t\"context\"\n\t\"fmt\"\n\n\t\"github.com/browserbase/stagehand-go\"\n\t\"github.com/browserbase/stagehand-go/option\"\n)\n\nfunc main() {\n\tclient := stagehand.NewClient(\n\t\toption.WithBrowserbaseAPIKey(\"My Browserbase API Key\"),\n\t\toption.WithBrowserbaseProjectID(\"My Browserbase Project ID\"),\n\t\toption.WithModelAPIKey(\"My Model API Key\"),\n\t)\n\tresponse, err := client.Sessions.Start(context.TODO(), stagehand.SessionStartParams{\n\t\tModelName: \"openai/gpt-5.4-mini\",\n\t})\n\tif err != nil {\n\t\tpanic(err.Error())\n\t}\n\tfmt.Printf(\"%+v\\n\", response.Data)\n}\n" + }, + { + "lang": "Java", + "source": "package com.browserbase.api.example;\n\nimport com.browserbase.api.client.StagehandClient;\nimport com.browserbase.api.client.okhttp.StagehandOkHttpClient;\nimport com.browserbase.api.models.sessions.SessionStartParams;\nimport com.browserbase.api.models.sessions.SessionStartResponse;\n\npublic final class Main {\n private Main() {}\n\n public static void main(String[] args) {\n StagehandClient client = StagehandOkHttpClient.fromEnv();\n\n SessionStartParams params = SessionStartParams.builder()\n .modelName(\"openai/gpt-5.4-mini\")\n .build();\n SessionStartResponse response = client.sessions().start(params);\n }\n}" + }, + { + "lang": "Kotlin", + "source": "package com.browserbase.api.example\n\nimport com.browserbase.api.client.StagehandClient\nimport com.browserbase.api.client.okhttp.StagehandOkHttpClient\nimport com.browserbase.api.models.sessions.SessionStartParams\nimport com.browserbase.api.models.sessions.SessionStartResponse\n\nfun main() {\n val client: StagehandClient = StagehandOkHttpClient.fromEnv()\n\n val params: SessionStartParams = SessionStartParams.builder()\n .modelName(\"openai/gpt-5.4-mini\")\n .build()\n val response: SessionStartResponse = client.sessions().start(params)\n}" + }, + { + "lang": "Ruby", + "source": "require \"stagehand\"\n\nstagehand = Stagehand::Client.new(\n browserbase_api_key: \"My Browserbase API Key\",\n browserbase_project_id: \"My Browserbase Project ID\",\n model_api_key: \"My Model API Key\"\n)\n\nresponse = stagehand.sessions.start(model_name: \"openai/gpt-5.4-mini\")\n\nputs(response)" + }, + { + "lang": "PHP", + "source": "sessions->start(\n modelName: 'openai/gpt-5.4-mini',\n actTimeoutMs: 0,\n browser: [\n 'cdpURL' => 'ws://localhost:9222',\n 'launchOptions' => [\n 'acceptDownloads' => true,\n 'args' => ['string'],\n 'cdpHeaders' => ['foo' => 'string'],\n 'cdpURL' => 'cdpUrl',\n 'chromiumSandbox' => true,\n 'connectTimeoutMs' => 0,\n 'deviceScaleFactor' => 0,\n 'devtools' => true,\n 'downloadsPath' => 'downloadsPath',\n 'executablePath' => 'executablePath',\n 'hasTouch' => true,\n 'headless' => true,\n 'ignoreDefaultArgs' => true,\n 'ignoreHTTPSErrors' => true,\n 'locale' => 'locale',\n 'port' => 0,\n 'preserveUserDataDir' => true,\n 'proxy' => [\n 'server' => 'server',\n 'bypass' => 'bypass',\n 'password' => 'password',\n 'username' => 'username',\n ],\n 'userDataDir' => 'userDataDir',\n 'viewport' => ['height' => 0, 'width' => 0],\n ],\n 'type' => 'local',\n ],\n browserbaseSessionCreateParams: [\n 'browserSettings' => [\n 'advancedStealth' => true,\n 'blockAds' => true,\n 'captchaImageSelector' => 'captchaImageSelector',\n 'captchaInputSelector' => 'captchaInputSelector',\n 'context' => ['id' => 'id', 'persist' => true],\n 'extensionID' => 'extensionId',\n 'fingerprint' => [\n 'browsers' => ['chrome'],\n 'devices' => ['desktop'],\n 'httpVersion' => '1',\n 'locales' => ['string'],\n 'operatingSystems' => ['android'],\n 'screen' => [\n 'maxHeight' => 0, 'maxWidth' => 0, 'minHeight' => 0, 'minWidth' => 0\n ],\n ],\n 'logSession' => true,\n 'os' => 'windows',\n 'recordSession' => true,\n 'solveCaptchas' => true,\n 'verified' => true,\n 'viewport' => ['height' => 0, 'width' => 0],\n ],\n 'extensionID' => 'extensionId',\n 'keepAlive' => true,\n 'projectID' => 'projectId',\n 'proxies' => true,\n 'region' => 'us-west-2',\n 'timeout' => 0,\n 'userMetadata' => ['foo' => 'bar'],\n ],\n browserbaseSessionID: 'browserbaseSessionID',\n domSettleTimeoutMs: 5000,\n experimental: true,\n selfHeal: true,\n systemPrompt: 'systemPrompt',\n verbose: 1,\n waitForCaptchaSolves: true,\n xStreamResponse: 'true',\n );\n\n var_dump($response);\n} catch (APIException $e) {\n echo $e->getMessage();\n}" + }, + { + "lang": "C#", + "source": "using System;\nusing Stagehand;\nusing Stagehand.Models.Sessions;\n\nStagehandClient client = new();\n\nSessionStartParams parameters = new() { ModelName = \"openai/gpt-5.4-mini\" };\n\nvar response = await client.Sessions.Start(parameters);\n\nConsole.WriteLine(response);" + } + ] + } + }, + "/v1/sessions/{id}/navigate": { + "post": { + "summary": "Navigate to a URL", + "description": "Navigates the browser to the specified URL.", + "operationId": "SessionNavigate", + "parameters": [ + { + "schema": { + "description": "Unique session identifier", + "example": "c4dbf3a9-9a58-4b22-8a1c-9f20f9f9e123", + "type": "string" + }, + "in": "path", + "name": "id", + "required": true, + "description": "Unique session identifier" + }, + { + "schema": { + "description": "Whether to stream the response via SSE", + "example": "true", + "type": "string", + "enum": ["true", "false"] + }, + "in": "header", + "name": "x-stream-response", + "description": "Whether to stream the response via SSE" + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/NavigateRequest" + } + } + }, + "required": true + }, + "responses": { + "200": { + "description": "Default Response", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/NavigateResponse" + } + } + } + } + }, + "x-codeSamples": [ + { + "lang": "JavaScript", + "source": "import Stagehand from 'stagehand-sdk';\n\nconst client = new Stagehand({\n browserbaseAPIKey: process.env['BROWSERBASE_API_KEY'], // This is the default and can be omitted\n browserbaseProjectID: process.env['BROWSERBASE_PROJECT_ID'], // This is the default and can be omitted\n modelAPIKey: process.env['MODEL_API_KEY'], // This is the default and can be omitted\n});\n\nconst response = await client.sessions.navigate('c4dbf3a9-9a58-4b22-8a1c-9f20f9f9e123', {\n url: 'https://example.com',\n});\n\nconsole.log(response.data);" + }, + { + "lang": "Python", + "source": "import os\nfrom stagehand import Stagehand\n\nclient = Stagehand(\n browserbase_api_key=os.environ.get(\"BROWSERBASE_API_KEY\"), # This is the default and can be omitted\n browserbase_project_id=os.environ.get(\"BROWSERBASE_PROJECT_ID\"), # This is the default and can be omitted\n model_api_key=os.environ.get(\"MODEL_API_KEY\"), # This is the default and can be omitted\n)\nresponse = client.sessions.navigate(\n id=\"c4dbf3a9-9a58-4b22-8a1c-9f20f9f9e123\",\n url=\"https://example.com\",\n)\nprint(response.data)" + }, + { + "lang": "Go", + "source": "package main\n\nimport (\n\t\"context\"\n\t\"fmt\"\n\n\t\"github.com/browserbase/stagehand-go\"\n\t\"github.com/browserbase/stagehand-go/option\"\n)\n\nfunc main() {\n\tclient := stagehand.NewClient(\n\t\toption.WithBrowserbaseAPIKey(\"My Browserbase API Key\"),\n\t\toption.WithBrowserbaseProjectID(\"My Browserbase Project ID\"),\n\t\toption.WithModelAPIKey(\"My Model API Key\"),\n\t)\n\tresponse, err := client.Sessions.Navigate(\n\t\tcontext.TODO(),\n\t\t\"c4dbf3a9-9a58-4b22-8a1c-9f20f9f9e123\",\n\t\tstagehand.SessionNavigateParams{\n\t\t\tURL: \"https://example.com\",\n\t\t},\n\t)\n\tif err != nil {\n\t\tpanic(err.Error())\n\t}\n\tfmt.Printf(\"%+v\\n\", response.Data)\n}\n" + }, + { + "lang": "Java", + "source": "package com.browserbase.api.example;\n\nimport com.browserbase.api.client.StagehandClient;\nimport com.browserbase.api.client.okhttp.StagehandOkHttpClient;\nimport com.browserbase.api.models.sessions.SessionNavigateParams;\nimport com.browserbase.api.models.sessions.SessionNavigateResponse;\n\npublic final class Main {\n private Main() {}\n\n public static void main(String[] args) {\n StagehandClient client = StagehandOkHttpClient.fromEnv();\n\n SessionNavigateParams params = SessionNavigateParams.builder()\n .id(\"c4dbf3a9-9a58-4b22-8a1c-9f20f9f9e123\")\n .url(\"https://example.com\")\n .build();\n SessionNavigateResponse response = client.sessions().navigate(params);\n }\n}" + }, + { + "lang": "Kotlin", + "source": "package com.browserbase.api.example\n\nimport com.browserbase.api.client.StagehandClient\nimport com.browserbase.api.client.okhttp.StagehandOkHttpClient\nimport com.browserbase.api.models.sessions.SessionNavigateParams\nimport com.browserbase.api.models.sessions.SessionNavigateResponse\n\nfun main() {\n val client: StagehandClient = StagehandOkHttpClient.fromEnv()\n\n val params: SessionNavigateParams = SessionNavigateParams.builder()\n .id(\"c4dbf3a9-9a58-4b22-8a1c-9f20f9f9e123\")\n .url(\"https://example.com\")\n .build()\n val response: SessionNavigateResponse = client.sessions().navigate(params)\n}" + }, + { + "lang": "Ruby", + "source": "require \"stagehand\"\n\nstagehand = Stagehand::Client.new(\n browserbase_api_key: \"My Browserbase API Key\",\n browserbase_project_id: \"My Browserbase Project ID\",\n model_api_key: \"My Model API Key\"\n)\n\nresponse = stagehand.sessions.navigate(\"c4dbf3a9-9a58-4b22-8a1c-9f20f9f9e123\", url: \"https://example.com\")\n\nputs(response)" + }, + { + "lang": "PHP", + "source": "sessions->navigate(\n 'c4dbf3a9-9a58-4b22-8a1c-9f20f9f9e123',\n url: 'https://example.com',\n frameID: 'frameId',\n options: [\n 'referer' => 'referer', 'timeout' => 30000, 'waitUntil' => 'networkidle'\n ],\n streamResponse: true,\n xStreamResponse: 'true',\n );\n\n var_dump($response);\n} catch (APIException $e) {\n echo $e->getMessage();\n}" + }, + { + "lang": "C#", + "source": "using System;\nusing Stagehand;\nusing Stagehand.Models.Sessions;\n\nStagehandClient client = new();\n\nSessionNavigateParams parameters = new()\n{\n ID = \"c4dbf3a9-9a58-4b22-8a1c-9f20f9f9e123\",\n UrlValue = \"https://example.com\",\n};\n\nvar response = await client.Sessions.Navigate(parameters);\n\nConsole.WriteLine(response);" + } + ] + } + }, + "/v1/sessions/{id}/act": { + "post": { + "summary": "Perform an action", + "description": "Executes a browser action using natural language instructions or a predefined Action object.", + "operationId": "SessionAct", + "parameters": [ + { + "schema": { + "description": "Unique session identifier", + "example": "c4dbf3a9-9a58-4b22-8a1c-9f20f9f9e123", + "type": "string" + }, + "in": "path", + "name": "id", + "required": true, + "description": "Unique session identifier" + }, + { + "schema": { + "description": "Whether to stream the response via SSE", + "example": "true", + "type": "string", + "enum": ["true", "false"] + }, + "in": "header", + "name": "x-stream-response", + "description": "Whether to stream the response via SSE" + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ActRequest" + } + } + }, + "required": true + }, + "responses": { + "200": { + "description": "Default Response", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ActResponse" + } + } + } + } + }, + "x-codeSamples": [ + { + "lang": "JavaScript", + "source": "import Stagehand from 'stagehand-sdk';\n\nconst client = new Stagehand({\n browserbaseAPIKey: process.env['BROWSERBASE_API_KEY'], // This is the default and can be omitted\n browserbaseProjectID: process.env['BROWSERBASE_PROJECT_ID'], // This is the default and can be omitted\n modelAPIKey: process.env['MODEL_API_KEY'], // This is the default and can be omitted\n});\n\nconst response = await client.sessions.act('c4dbf3a9-9a58-4b22-8a1c-9f20f9f9e123', {\n input: 'Click the login button',\n});\n\nconsole.log(response.data);" + }, + { + "lang": "Python", + "source": "import os\nfrom stagehand import Stagehand\n\nclient = Stagehand(\n browserbase_api_key=os.environ.get(\"BROWSERBASE_API_KEY\"), # This is the default and can be omitted\n browserbase_project_id=os.environ.get(\"BROWSERBASE_PROJECT_ID\"), # This is the default and can be omitted\n model_api_key=os.environ.get(\"MODEL_API_KEY\"), # This is the default and can be omitted\n)\nfor session in client.sessions.act(\n id=\"c4dbf3a9-9a58-4b22-8a1c-9f20f9f9e123\",\n input=\"Click the login button\",\n):\n print(session)" + }, + { + "lang": "Go", + "source": "package main\n\nimport (\n\t\"context\"\n\t\"fmt\"\n\n\t\"github.com/browserbase/stagehand-go\"\n\t\"github.com/browserbase/stagehand-go/option\"\n)\n\nfunc main() {\n\tclient := stagehand.NewClient(\n\t\toption.WithBrowserbaseAPIKey(\"My Browserbase API Key\"),\n\t\toption.WithBrowserbaseProjectID(\"My Browserbase Project ID\"),\n\t\toption.WithModelAPIKey(\"My Model API Key\"),\n\t)\n\tresponse, err := client.Sessions.Act(\n\t\tcontext.TODO(),\n\t\t\"c4dbf3a9-9a58-4b22-8a1c-9f20f9f9e123\",\n\t\tstagehand.SessionActParams{\n\t\t\tInput: stagehand.SessionActParamsInputUnion{\n\t\t\t\tOfString: stagehand.String(\"Click the login button\"),\n\t\t\t},\n\t\t},\n\t)\n\tif err != nil {\n\t\tpanic(err.Error())\n\t}\n\tfmt.Printf(\"%+v\\n\", response.Data)\n}\n" + }, + { + "lang": "Java", + "source": "package com.browserbase.api.example;\n\nimport com.browserbase.api.client.StagehandClient;\nimport com.browserbase.api.client.okhttp.StagehandOkHttpClient;\nimport com.browserbase.api.models.sessions.SessionActParams;\nimport com.browserbase.api.models.sessions.SessionActResponse;\n\npublic final class Main {\n private Main() {}\n\n public static void main(String[] args) {\n StagehandClient client = StagehandOkHttpClient.fromEnv();\n\n SessionActParams params = SessionActParams.builder()\n .id(\"c4dbf3a9-9a58-4b22-8a1c-9f20f9f9e123\")\n .input(\"Click the login button\")\n .build();\n SessionActResponse response = client.sessions().act(params);\n }\n}" + }, + { + "lang": "Kotlin", + "source": "package com.browserbase.api.example\n\nimport com.browserbase.api.client.StagehandClient\nimport com.browserbase.api.client.okhttp.StagehandOkHttpClient\nimport com.browserbase.api.models.sessions.SessionActParams\nimport com.browserbase.api.models.sessions.SessionActResponse\n\nfun main() {\n val client: StagehandClient = StagehandOkHttpClient.fromEnv()\n\n val params: SessionActParams = SessionActParams.builder()\n .id(\"c4dbf3a9-9a58-4b22-8a1c-9f20f9f9e123\")\n .input(\"Click the login button\")\n .build()\n val response: SessionActResponse = client.sessions().act(params)\n}" + }, + { + "lang": "Ruby", + "source": "require \"stagehand\"\n\nstagehand = Stagehand::Client.new(\n browserbase_api_key: \"My Browserbase API Key\",\n browserbase_project_id: \"My Browserbase Project ID\",\n model_api_key: \"My Model API Key\"\n)\n\nresponse = stagehand.sessions.act(\"c4dbf3a9-9a58-4b22-8a1c-9f20f9f9e123\", input: \"Click the login button\")\n\nputs(response)" + }, + { + "lang": "PHP", + "source": "sessions->act(\n 'c4dbf3a9-9a58-4b22-8a1c-9f20f9f9e123',\n input: 'Click the login button',\n frameID: 'frameId',\n options: [\n 'model' => [\n 'auth' => [\n 'credentials' => [\n 'clientEmail' => 'client_email',\n 'privateKey' => 'private_key',\n 'authProviderX509CertURL' => 'https://example.com',\n 'authUri' => 'https://example.com',\n 'clientID' => 'client_id',\n 'clientX509CertURL' => 'https://example.com',\n 'privateKeyID' => 'private_key_id',\n 'projectID' => 'project_id',\n 'tokenUri' => 'https://example.com',\n 'type' => 'service_account',\n 'universeDomain' => 'universe_domain',\n ],\n 'type' => 'googleServiceAccount',\n 'projectID' => 'projectId',\n 'scopes' => 'string',\n 'universeDomain' => 'universeDomain',\n ],\n 'modelName' => 'openai/gpt-5.4-mini',\n 'provider' => 'vertex',\n 'providerOptions' => [\n 'vertex' => [\n 'location' => 'us-central1',\n 'project' => 'my-gcp-project',\n 'baseURL' => 'https://example.com',\n 'headers' => ['foo' => 'string'],\n ],\n ],\n 'apiKey' => 'sk-some-openai-api-key',\n 'baseURL' => 'https://api.openai.com/v1',\n 'headers' => ['foo' => 'string'],\n ],\n 'timeout' => 30000,\n 'variables' => [\n 'username' => 'john_doe',\n 'password' => [\n 'value' => 'secret123', 'description' => 'The login password'\n ],\n ],\n ],\n xStreamResponse: 'true',\n );\n\n var_dump($response);\n} catch (APIException $e) {\n echo $e->getMessage();\n}" + }, + { + "lang": "C#", + "source": "using System;\nusing Stagehand;\nusing Stagehand.Models.Sessions;\n\nStagehandClient client = new();\n\nSessionActParams parameters = new()\n{\n ID = \"c4dbf3a9-9a58-4b22-8a1c-9f20f9f9e123\",\n Input = \"Click the login button\",\n};\n\nvar response = await client.Sessions.Act(parameters);\n\nConsole.WriteLine(response);" + } + ] + } + }, + "/v1/sessions/{id}/observe": { + "post": { + "summary": "Observe available actions", + "description": "Identifies and returns available actions on the current page that match the given instruction.", + "operationId": "SessionObserve", + "parameters": [ + { + "schema": { + "description": "Unique session identifier", + "example": "c4dbf3a9-9a58-4b22-8a1c-9f20f9f9e123", + "type": "string" + }, + "in": "path", + "name": "id", + "required": true, + "description": "Unique session identifier" + }, + { + "schema": { + "description": "Whether to stream the response via SSE", + "example": "true", + "type": "string", + "enum": ["true", "false"] + }, + "in": "header", + "name": "x-stream-response", + "description": "Whether to stream the response via SSE" + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ObserveRequest" + } + } + }, + "required": true + }, + "responses": { + "200": { + "description": "Default Response", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ObserveResponse" + } + } + } + } + }, + "x-codeSamples": [ + { + "lang": "JavaScript", + "source": "import Stagehand from 'stagehand-sdk';\n\nconst client = new Stagehand({\n browserbaseAPIKey: process.env['BROWSERBASE_API_KEY'], // This is the default and can be omitted\n browserbaseProjectID: process.env['BROWSERBASE_PROJECT_ID'], // This is the default and can be omitted\n modelAPIKey: process.env['MODEL_API_KEY'], // This is the default and can be omitted\n});\n\nconst response = await client.sessions.observe('c4dbf3a9-9a58-4b22-8a1c-9f20f9f9e123');\n\nconsole.log(response.data);" + }, + { + "lang": "Python", + "source": "import os\nfrom stagehand import Stagehand\n\nclient = Stagehand(\n browserbase_api_key=os.environ.get(\"BROWSERBASE_API_KEY\"), # This is the default and can be omitted\n browserbase_project_id=os.environ.get(\"BROWSERBASE_PROJECT_ID\"), # This is the default and can be omitted\n model_api_key=os.environ.get(\"MODEL_API_KEY\"), # This is the default and can be omitted\n)\nfor session in client.sessions.observe(\n id=\"c4dbf3a9-9a58-4b22-8a1c-9f20f9f9e123\",\n):\n print(session)" + }, + { + "lang": "Go", + "source": "package main\n\nimport (\n\t\"context\"\n\t\"fmt\"\n\n\t\"github.com/browserbase/stagehand-go\"\n\t\"github.com/browserbase/stagehand-go/option\"\n)\n\nfunc main() {\n\tclient := stagehand.NewClient(\n\t\toption.WithBrowserbaseAPIKey(\"My Browserbase API Key\"),\n\t\toption.WithBrowserbaseProjectID(\"My Browserbase Project ID\"),\n\t\toption.WithModelAPIKey(\"My Model API Key\"),\n\t)\n\tresponse, err := client.Sessions.Observe(\n\t\tcontext.TODO(),\n\t\t\"c4dbf3a9-9a58-4b22-8a1c-9f20f9f9e123\",\n\t\tstagehand.SessionObserveParams{},\n\t)\n\tif err != nil {\n\t\tpanic(err.Error())\n\t}\n\tfmt.Printf(\"%+v\\n\", response.Data)\n}\n" + }, + { + "lang": "Java", + "source": "package com.browserbase.api.example;\n\nimport com.browserbase.api.client.StagehandClient;\nimport com.browserbase.api.client.okhttp.StagehandOkHttpClient;\nimport com.browserbase.api.models.sessions.SessionObserveParams;\nimport com.browserbase.api.models.sessions.SessionObserveResponse;\n\npublic final class Main {\n private Main() {}\n\n public static void main(String[] args) {\n StagehandClient client = StagehandOkHttpClient.fromEnv();\n\n SessionObserveResponse response = client.sessions().observe(\"c4dbf3a9-9a58-4b22-8a1c-9f20f9f9e123\");\n }\n}" + }, + { + "lang": "Kotlin", + "source": "package com.browserbase.api.example\n\nimport com.browserbase.api.client.StagehandClient\nimport com.browserbase.api.client.okhttp.StagehandOkHttpClient\nimport com.browserbase.api.models.sessions.SessionObserveParams\nimport com.browserbase.api.models.sessions.SessionObserveResponse\n\nfun main() {\n val client: StagehandClient = StagehandOkHttpClient.fromEnv()\n\n val response: SessionObserveResponse = client.sessions().observe(\"c4dbf3a9-9a58-4b22-8a1c-9f20f9f9e123\")\n}" + }, + { + "lang": "Ruby", + "source": "require \"stagehand\"\n\nstagehand = Stagehand::Client.new(\n browserbase_api_key: \"My Browserbase API Key\",\n browserbase_project_id: \"My Browserbase Project ID\",\n model_api_key: \"My Model API Key\"\n)\n\nresponse = stagehand.sessions.observe(\"c4dbf3a9-9a58-4b22-8a1c-9f20f9f9e123\")\n\nputs(response)" + }, + { + "lang": "PHP", + "source": "sessions->observe(\n 'c4dbf3a9-9a58-4b22-8a1c-9f20f9f9e123',\n frameID: 'frameId',\n instruction: 'Find all clickable navigation links',\n options: [\n 'ignoreSelectors' => ['nav', '.cookie-banner', '#sidebar-ads'],\n 'model' => [\n 'auth' => [\n 'credentials' => [\n 'clientEmail' => 'client_email',\n 'privateKey' => 'private_key',\n 'authProviderX509CertURL' => 'https://example.com',\n 'authUri' => 'https://example.com',\n 'clientID' => 'client_id',\n 'clientX509CertURL' => 'https://example.com',\n 'privateKeyID' => 'private_key_id',\n 'projectID' => 'project_id',\n 'tokenUri' => 'https://example.com',\n 'type' => 'service_account',\n 'universeDomain' => 'universe_domain',\n ],\n 'type' => 'googleServiceAccount',\n 'projectID' => 'projectId',\n 'scopes' => 'string',\n 'universeDomain' => 'universeDomain',\n ],\n 'modelName' => 'openai/gpt-5.4-mini',\n 'provider' => 'vertex',\n 'providerOptions' => [\n 'vertex' => [\n 'location' => 'us-central1',\n 'project' => 'my-gcp-project',\n 'baseURL' => 'https://example.com',\n 'headers' => ['foo' => 'string'],\n ],\n ],\n 'apiKey' => 'sk-some-openai-api-key',\n 'baseURL' => 'https://api.openai.com/v1',\n 'headers' => ['foo' => 'string'],\n ],\n 'selector' => 'nav',\n 'timeout' => 30000,\n 'variables' => [\n 'username' => [\n 'value' => 'john@example.com', 'description' => 'The login email'\n ],\n 'rememberMe' => true,\n ],\n ],\n xStreamResponse: 'true',\n );\n\n var_dump($response);\n} catch (APIException $e) {\n echo $e->getMessage();\n}" + }, + { + "lang": "C#", + "source": "using System;\nusing Stagehand;\nusing Stagehand.Models.Sessions;\n\nStagehandClient client = new();\n\nSessionObserveParams parameters = new()\n{\n ID = \"c4dbf3a9-9a58-4b22-8a1c-9f20f9f9e123\"\n};\n\nvar response = await client.Sessions.Observe(parameters);\n\nConsole.WriteLine(response);" + } + ] + } + }, + "/v1/sessions/{id}/extract": { + "post": { + "summary": "Extract data from the page", + "description": "Extracts structured data from the current page using AI-powered analysis.", + "operationId": "SessionExtract", + "parameters": [ + { + "schema": { + "description": "Unique session identifier", + "example": "c4dbf3a9-9a58-4b22-8a1c-9f20f9f9e123", + "type": "string" + }, + "in": "path", + "name": "id", + "required": true, + "description": "Unique session identifier" + }, + { + "schema": { + "description": "Whether to stream the response via SSE", + "example": "true", + "type": "string", + "enum": ["true", "false"] + }, + "in": "header", + "name": "x-stream-response", + "description": "Whether to stream the response via SSE" + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ExtractRequest" + } + } + }, + "required": true + }, + "responses": { + "200": { + "description": "Default Response", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ExtractResponse" + } + } + } + } + }, + "x-codeSamples": [ + { + "lang": "JavaScript", + "source": "import Stagehand from 'stagehand-sdk';\n\nconst client = new Stagehand({\n browserbaseAPIKey: process.env['BROWSERBASE_API_KEY'], // This is the default and can be omitted\n browserbaseProjectID: process.env['BROWSERBASE_PROJECT_ID'], // This is the default and can be omitted\n modelAPIKey: process.env['MODEL_API_KEY'], // This is the default and can be omitted\n});\n\nconst response = await client.sessions.extract('c4dbf3a9-9a58-4b22-8a1c-9f20f9f9e123');\n\nconsole.log(response.data);" + }, + { + "lang": "Python", + "source": "import os\nfrom stagehand import Stagehand\n\nclient = Stagehand(\n browserbase_api_key=os.environ.get(\"BROWSERBASE_API_KEY\"), # This is the default and can be omitted\n browserbase_project_id=os.environ.get(\"BROWSERBASE_PROJECT_ID\"), # This is the default and can be omitted\n model_api_key=os.environ.get(\"MODEL_API_KEY\"), # This is the default and can be omitted\n)\nfor session in client.sessions.extract(\n id=\"c4dbf3a9-9a58-4b22-8a1c-9f20f9f9e123\",\n):\n print(session)" + }, + { + "lang": "Go", + "source": "package main\n\nimport (\n\t\"context\"\n\t\"fmt\"\n\n\t\"github.com/browserbase/stagehand-go\"\n\t\"github.com/browserbase/stagehand-go/option\"\n)\n\nfunc main() {\n\tclient := stagehand.NewClient(\n\t\toption.WithBrowserbaseAPIKey(\"My Browserbase API Key\"),\n\t\toption.WithBrowserbaseProjectID(\"My Browserbase Project ID\"),\n\t\toption.WithModelAPIKey(\"My Model API Key\"),\n\t)\n\tresponse, err := client.Sessions.Extract(\n\t\tcontext.TODO(),\n\t\t\"c4dbf3a9-9a58-4b22-8a1c-9f20f9f9e123\",\n\t\tstagehand.SessionExtractParams{},\n\t)\n\tif err != nil {\n\t\tpanic(err.Error())\n\t}\n\tfmt.Printf(\"%+v\\n\", response.Data)\n}\n" + }, + { + "lang": "Java", + "source": "package com.browserbase.api.example;\n\nimport com.browserbase.api.client.StagehandClient;\nimport com.browserbase.api.client.okhttp.StagehandOkHttpClient;\nimport com.browserbase.api.models.sessions.SessionExtractParams;\nimport com.browserbase.api.models.sessions.SessionExtractResponse;\n\npublic final class Main {\n private Main() {}\n\n public static void main(String[] args) {\n StagehandClient client = StagehandOkHttpClient.fromEnv();\n\n SessionExtractResponse response = client.sessions().extract(\"c4dbf3a9-9a58-4b22-8a1c-9f20f9f9e123\");\n }\n}" + }, + { + "lang": "Kotlin", + "source": "package com.browserbase.api.example\n\nimport com.browserbase.api.client.StagehandClient\nimport com.browserbase.api.client.okhttp.StagehandOkHttpClient\nimport com.browserbase.api.models.sessions.SessionExtractParams\nimport com.browserbase.api.models.sessions.SessionExtractResponse\n\nfun main() {\n val client: StagehandClient = StagehandOkHttpClient.fromEnv()\n\n val response: SessionExtractResponse = client.sessions().extract(\"c4dbf3a9-9a58-4b22-8a1c-9f20f9f9e123\")\n}" + }, + { + "lang": "Ruby", + "source": "require \"stagehand\"\n\nstagehand = Stagehand::Client.new(\n browserbase_api_key: \"My Browserbase API Key\",\n browserbase_project_id: \"My Browserbase Project ID\",\n model_api_key: \"My Model API Key\"\n)\n\nresponse = stagehand.sessions.extract(\"c4dbf3a9-9a58-4b22-8a1c-9f20f9f9e123\")\n\nputs(response)" + }, + { + "lang": "PHP", + "source": "sessions->extract(\n 'c4dbf3a9-9a58-4b22-8a1c-9f20f9f9e123',\n frameID: 'frameId',\n instruction: 'Extract all product names and prices from the page',\n options: [\n 'ignoreSelectors' => ['nav', '.cookie-banner', '#sidebar-ads'],\n 'model' => [\n 'auth' => [\n 'credentials' => [\n 'clientEmail' => 'client_email',\n 'privateKey' => 'private_key',\n 'authProviderX509CertURL' => 'https://example.com',\n 'authUri' => 'https://example.com',\n 'clientID' => 'client_id',\n 'clientX509CertURL' => 'https://example.com',\n 'privateKeyID' => 'private_key_id',\n 'projectID' => 'project_id',\n 'tokenUri' => 'https://example.com',\n 'type' => 'service_account',\n 'universeDomain' => 'universe_domain',\n ],\n 'type' => 'googleServiceAccount',\n 'projectID' => 'projectId',\n 'scopes' => 'string',\n 'universeDomain' => 'universeDomain',\n ],\n 'modelName' => 'openai/gpt-5.4-mini',\n 'provider' => 'vertex',\n 'providerOptions' => [\n 'vertex' => [\n 'location' => 'us-central1',\n 'project' => 'my-gcp-project',\n 'baseURL' => 'https://example.com',\n 'headers' => ['foo' => 'string'],\n ],\n ],\n 'apiKey' => 'sk-some-openai-api-key',\n 'baseURL' => 'https://api.openai.com/v1',\n 'headers' => ['foo' => 'string'],\n ],\n 'screenshot' => false,\n 'selector' => '#main-content',\n 'timeout' => 30000,\n ],\n schema: ['foo' => 'bar'],\n xStreamResponse: 'true',\n );\n\n var_dump($response);\n} catch (APIException $e) {\n echo $e->getMessage();\n}" + }, + { + "lang": "C#", + "source": "using System;\nusing Stagehand;\nusing Stagehand.Models.Sessions;\n\nStagehandClient client = new();\n\nSessionExtractParams parameters = new()\n{\n ID = \"c4dbf3a9-9a58-4b22-8a1c-9f20f9f9e123\"\n};\n\nvar response = await client.Sessions.Extract(parameters);\n\nConsole.WriteLine(response);" + } + ] + } + }, + "/v1/sessions/{id}/agentExecute": { + "post": { + "summary": "Execute an AI agent", + "description": "Runs an autonomous AI agent that can perform complex multi-step browser tasks.", + "operationId": "SessionAgentExecute", + "parameters": [ + { + "schema": { + "description": "Unique session identifier", + "example": "c4dbf3a9-9a58-4b22-8a1c-9f20f9f9e123", + "type": "string" + }, + "in": "path", + "name": "id", + "required": true, + "description": "Unique session identifier" + }, + { + "schema": { + "description": "Whether to stream the response via SSE", + "example": "true", + "type": "string", + "enum": ["true", "false"] + }, + "in": "header", + "name": "x-stream-response", + "description": "Whether to stream the response via SSE" + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/AgentExecuteRequest" + } + } + }, + "required": true + }, + "responses": { + "200": { + "description": "Default Response", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/AgentExecuteResponse" + } + } + } + } + }, + "x-codeSamples": [ + { + "lang": "JavaScript", + "source": "import Stagehand from 'stagehand-sdk';\n\nconst client = new Stagehand({\n browserbaseAPIKey: process.env['BROWSERBASE_API_KEY'], // This is the default and can be omitted\n browserbaseProjectID: process.env['BROWSERBASE_PROJECT_ID'], // This is the default and can be omitted\n modelAPIKey: process.env['MODEL_API_KEY'], // This is the default and can be omitted\n});\n\nconst response = await client.sessions.execute('c4dbf3a9-9a58-4b22-8a1c-9f20f9f9e123', {\n agentConfig: {},\n executeOptions: {\n instruction: \"Log in with username 'demo' and password 'test123', then navigate to settings\",\n },\n});\n\nconsole.log(response.data);" + }, + { + "lang": "Python", + "source": "import os\nfrom stagehand import Stagehand\n\nclient = Stagehand(\n browserbase_api_key=os.environ.get(\"BROWSERBASE_API_KEY\"), # This is the default and can be omitted\n browserbase_project_id=os.environ.get(\"BROWSERBASE_PROJECT_ID\"), # This is the default and can be omitted\n model_api_key=os.environ.get(\"MODEL_API_KEY\"), # This is the default and can be omitted\n)\nfor session in client.sessions.execute(\n id=\"c4dbf3a9-9a58-4b22-8a1c-9f20f9f9e123\",\n agent_config={},\n execute_options={\n \"instruction\": \"Log in with username 'demo' and password 'test123', then navigate to settings\"\n },\n):\n print(session)" + }, + { + "lang": "Go", + "source": "package main\n\nimport (\n\t\"context\"\n\t\"fmt\"\n\n\t\"github.com/browserbase/stagehand-go\"\n\t\"github.com/browserbase/stagehand-go/option\"\n)\n\nfunc main() {\n\tclient := stagehand.NewClient(\n\t\toption.WithBrowserbaseAPIKey(\"My Browserbase API Key\"),\n\t\toption.WithBrowserbaseProjectID(\"My Browserbase Project ID\"),\n\t\toption.WithModelAPIKey(\"My Model API Key\"),\n\t)\n\tresponse, err := client.Sessions.Execute(\n\t\tcontext.TODO(),\n\t\t\"c4dbf3a9-9a58-4b22-8a1c-9f20f9f9e123\",\n\t\tstagehand.SessionExecuteParams{\n\t\t\tAgentConfig: stagehand.SessionExecuteParamsAgentConfig{},\n\t\t\tExecuteOptions: stagehand.SessionExecuteParamsExecuteOptions{\n\t\t\t\tInstruction: \"Log in with username 'demo' and password 'test123', then navigate to settings\",\n\t\t\t},\n\t\t},\n\t)\n\tif err != nil {\n\t\tpanic(err.Error())\n\t}\n\tfmt.Printf(\"%+v\\n\", response.Data)\n}\n" + }, + { + "lang": "Java", + "source": "package com.browserbase.api.example;\n\nimport com.browserbase.api.client.StagehandClient;\nimport com.browserbase.api.client.okhttp.StagehandOkHttpClient;\nimport com.browserbase.api.models.sessions.SessionExecuteParams;\nimport com.browserbase.api.models.sessions.SessionExecuteResponse;\n\npublic final class Main {\n private Main() {}\n\n public static void main(String[] args) {\n StagehandClient client = StagehandOkHttpClient.fromEnv();\n\n SessionExecuteParams params = SessionExecuteParams.builder()\n .id(\"c4dbf3a9-9a58-4b22-8a1c-9f20f9f9e123\")\n .agentConfig(SessionExecuteParams.AgentConfig.builder().build())\n .executeOptions(SessionExecuteParams.ExecuteOptions.builder()\n .instruction(\"Log in with username 'demo' and password 'test123', then navigate to settings\")\n .build())\n .build();\n SessionExecuteResponse response = client.sessions().execute(params);\n }\n}" + }, + { + "lang": "Kotlin", + "source": "package com.browserbase.api.example\n\nimport com.browserbase.api.client.StagehandClient\nimport com.browserbase.api.client.okhttp.StagehandOkHttpClient\nimport com.browserbase.api.models.sessions.SessionExecuteParams\nimport com.browserbase.api.models.sessions.SessionExecuteResponse\n\nfun main() {\n val client: StagehandClient = StagehandOkHttpClient.fromEnv()\n\n val params: SessionExecuteParams = SessionExecuteParams.builder()\n .id(\"c4dbf3a9-9a58-4b22-8a1c-9f20f9f9e123\")\n .agentConfig(SessionExecuteParams.AgentConfig.builder().build())\n .executeOptions(SessionExecuteParams.ExecuteOptions.builder()\n .instruction(\"Log in with username 'demo' and password 'test123', then navigate to settings\")\n .build())\n .build()\n val response: SessionExecuteResponse = client.sessions().execute(params)\n}" + }, + { + "lang": "Ruby", + "source": "require \"stagehand\"\n\nstagehand = Stagehand::Client.new(\n browserbase_api_key: \"My Browserbase API Key\",\n browserbase_project_id: \"My Browserbase Project ID\",\n model_api_key: \"My Model API Key\"\n)\n\nresponse = stagehand.sessions.execute(\n \"c4dbf3a9-9a58-4b22-8a1c-9f20f9f9e123\",\n agent_config: {},\n execute_options: {instruction: \"Log in with username 'demo' and password 'test123', then navigate to settings\"}\n)\n\nputs(response)" + }, + { + "lang": "PHP", + "source": "sessions->execute(\n 'c4dbf3a9-9a58-4b22-8a1c-9f20f9f9e123',\n agentConfig: [\n 'cua' => true,\n 'executionModel' => [\n 'auth' => [\n 'credentials' => [\n 'clientEmail' => 'client_email',\n 'privateKey' => 'private_key',\n 'authProviderX509CertURL' => 'https://example.com',\n 'authUri' => 'https://example.com',\n 'clientID' => 'client_id',\n 'clientX509CertURL' => 'https://example.com',\n 'privateKeyID' => 'private_key_id',\n 'projectID' => 'project_id',\n 'tokenUri' => 'https://example.com',\n 'type' => 'service_account',\n 'universeDomain' => 'universe_domain',\n ],\n 'type' => 'googleServiceAccount',\n 'projectID' => 'projectId',\n 'scopes' => 'string',\n 'universeDomain' => 'universeDomain',\n ],\n 'modelName' => 'openai/gpt-5.4-mini',\n 'provider' => 'vertex',\n 'providerOptions' => [\n 'vertex' => [\n 'location' => 'us-central1',\n 'project' => 'my-gcp-project',\n 'baseURL' => 'https://example.com',\n 'headers' => ['foo' => 'string'],\n ],\n ],\n 'apiKey' => 'sk-some-openai-api-key',\n 'baseURL' => 'https://api.openai.com/v1',\n 'headers' => ['foo' => 'string'],\n ],\n 'mode' => 'cua',\n 'model' => [\n 'auth' => [\n 'credentials' => [\n 'clientEmail' => 'client_email',\n 'privateKey' => 'private_key',\n 'authProviderX509CertURL' => 'https://example.com',\n 'authUri' => 'https://example.com',\n 'clientID' => 'client_id',\n 'clientX509CertURL' => 'https://example.com',\n 'privateKeyID' => 'private_key_id',\n 'projectID' => 'project_id',\n 'tokenUri' => 'https://example.com',\n 'type' => 'service_account',\n 'universeDomain' => 'universe_domain',\n ],\n 'type' => 'googleServiceAccount',\n 'projectID' => 'projectId',\n 'scopes' => 'string',\n 'universeDomain' => 'universeDomain',\n ],\n 'modelName' => 'openai/gpt-5.4-mini',\n 'provider' => 'vertex',\n 'providerOptions' => [\n 'vertex' => [\n 'location' => 'us-central1',\n 'project' => 'my-gcp-project',\n 'baseURL' => 'https://example.com',\n 'headers' => ['foo' => 'string'],\n ],\n ],\n 'apiKey' => 'sk-some-openai-api-key',\n 'baseURL' => 'https://api.openai.com/v1',\n 'headers' => ['foo' => 'string'],\n ],\n 'provider' => 'openai',\n 'systemPrompt' => 'systemPrompt',\n ],\n executeOptions: [\n 'instruction' => 'Log in with username \\'demo\\' and password \\'test123\\', then navigate to settings',\n 'highlightCursor' => true,\n 'maxSteps' => 20,\n 'toolTimeout' => 30000,\n 'useSearch' => true,\n 'variables' => ['foo' => 'string'],\n ],\n frameID: 'frameId',\n shouldCache: true,\n xStreamResponse: 'true',\n );\n\n var_dump($response);\n} catch (APIException $e) {\n echo $e->getMessage();\n}" + }, + { + "lang": "C#", + "source": "using System;\nusing System.Collections.Generic;\nusing Stagehand;\nusing Stagehand.Models.Sessions;\n\nStagehandClient client = new();\n\nSessionExecuteParams parameters = new()\n{\n ID = \"c4dbf3a9-9a58-4b22-8a1c-9f20f9f9e123\",\n AgentConfig = new()\n {\n Cua = true,\n ExecutionModel = new ExecutionModelVertexModelConfigObject()\n {\n Auth = new()\n {\n Credentials = new()\n {\n ClientEmail = \"client_email\",\n PrivateKey = \"private_key\",\n AuthProviderX509CertUrl = \"https://example.com\",\n AuthUri = \"https://example.com\",\n ClientID = \"client_id\",\n ClientX509CertUrl = \"https://example.com\",\n PrivateKeyID = \"private_key_id\",\n ProjectID = \"project_id\",\n TokenUri = \"https://example.com\",\n Type = ExecutionModelVertexModelConfigObjectAuthCredentialsType.ServiceAccount,\n UniverseDomain = \"universe_domain\",\n },\n ProjectID = \"projectId\",\n Scopes = \"string\",\n UniverseDomain = \"universeDomain\",\n },\n ModelName = \"openai/gpt-5.4-mini\",\n ProviderOptions = new(\n new ExecutionModelVertexModelConfigObjectProviderOptionsVertex()\n {\n Location = \"us-central1\",\n Project = \"my-gcp-project\",\n BaseUrl = \"https://example.com\",\n Headers = new Dictionary()\n {\n { \"foo\", \"string\" }\n },\n }\n ),\n ApiKey = \"sk-some-openai-api-key\",\n BaseUrl = \"https://api.openai.com/v1\",\n Headers = new Dictionary() { { \"foo\", \"string\" } },\n },\n Mode = Mode.Cua,\n Model = new AgentConfigModelVertexModelConfigObject()\n {\n Auth = new()\n {\n Credentials = new()\n {\n ClientEmail = \"client_email\",\n PrivateKey = \"private_key\",\n AuthProviderX509CertUrl = \"https://example.com\",\n AuthUri = \"https://example.com\",\n ClientID = \"client_id\",\n ClientX509CertUrl = \"https://example.com\",\n PrivateKeyID = \"private_key_id\",\n ProjectID = \"project_id\",\n TokenUri = \"https://example.com\",\n Type = AgentConfigModelVertexModelConfigObjectAuthCredentialsType.ServiceAccount,\n UniverseDomain = \"universe_domain\",\n },\n ProjectID = \"projectId\",\n Scopes = \"string\",\n UniverseDomain = \"universeDomain\",\n },\n ModelName = \"openai/gpt-5.4-mini\",\n ProviderOptions = new(\n new AgentConfigModelVertexModelConfigObjectProviderOptionsVertex(\n\n )\n {\n Location = \"us-central1\",\n Project = \"my-gcp-project\",\n BaseUrl = \"https://example.com\",\n Headers = new Dictionary()\n {\n { \"foo\", \"string\" }\n },\n }\n ),\n ApiKey = \"sk-some-openai-api-key\",\n BaseUrl = \"https://api.openai.com/v1\",\n Headers = new Dictionary() { { \"foo\", \"string\" } },\n },\n Provider = AgentConfigProvider.OpenAI,\n SystemPrompt = \"systemPrompt\",\n },\n ExecuteOptions = new()\n {\n Instruction = \"Log in with username 'demo' and password 'test123', then navigate to settings\",\n HighlightCursor = true,\n MaxSteps = 20,\n ToolTimeout = 30000,\n UseSearch = true,\n Variables = new Dictionary()\n {\n { \"foo\", \"string\" }\n },\n },\n};\n\nvar response = await client.Sessions.Execute(parameters);\n\nConsole.WriteLine(response);" + } + ] + } + }, + "/v1/sessions/{id}/end": { + "post": { + "summary": "End a browser session", + "description": "Terminates the browser session and releases all associated resources.", + "operationId": "SessionEnd", + "parameters": [ + { + "schema": { + "description": "Unique session identifier", + "example": "c4dbf3a9-9a58-4b22-8a1c-9f20f9f9e123", + "type": "string" + }, + "in": "path", + "name": "id", + "required": true, + "description": "Unique session identifier" + }, + { + "schema": { + "description": "Whether to stream the response via SSE", + "example": "true", + "type": "string", + "enum": ["true", "false"] + }, + "in": "header", + "name": "x-stream-response", + "description": "Whether to stream the response via SSE" + } + ], + "responses": { + "200": { + "description": "Default Response", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/SessionEndResponse" + } + } + } + } + }, + "x-codeSamples": [ + { + "lang": "JavaScript", + "source": "import Stagehand from 'stagehand-sdk';\n\nconst client = new Stagehand({\n browserbaseAPIKey: process.env['BROWSERBASE_API_KEY'], // This is the default and can be omitted\n browserbaseProjectID: process.env['BROWSERBASE_PROJECT_ID'], // This is the default and can be omitted\n modelAPIKey: process.env['MODEL_API_KEY'], // This is the default and can be omitted\n});\n\nconst response = await client.sessions.end('c4dbf3a9-9a58-4b22-8a1c-9f20f9f9e123');\n\nconsole.log(response.success);" + }, + { + "lang": "Python", + "source": "import os\nfrom stagehand import Stagehand\n\nclient = Stagehand(\n browserbase_api_key=os.environ.get(\"BROWSERBASE_API_KEY\"), # This is the default and can be omitted\n browserbase_project_id=os.environ.get(\"BROWSERBASE_PROJECT_ID\"), # This is the default and can be omitted\n model_api_key=os.environ.get(\"MODEL_API_KEY\"), # This is the default and can be omitted\n)\nresponse = client.sessions.end(\n id=\"c4dbf3a9-9a58-4b22-8a1c-9f20f9f9e123\",\n)\nprint(response.success)" + }, + { + "lang": "Go", + "source": "package main\n\nimport (\n\t\"context\"\n\t\"fmt\"\n\n\t\"github.com/browserbase/stagehand-go\"\n\t\"github.com/browserbase/stagehand-go/option\"\n)\n\nfunc main() {\n\tclient := stagehand.NewClient(\n\t\toption.WithBrowserbaseAPIKey(\"My Browserbase API Key\"),\n\t\toption.WithBrowserbaseProjectID(\"My Browserbase Project ID\"),\n\t\toption.WithModelAPIKey(\"My Model API Key\"),\n\t)\n\tresponse, err := client.Sessions.End(\n\t\tcontext.TODO(),\n\t\t\"c4dbf3a9-9a58-4b22-8a1c-9f20f9f9e123\",\n\t\tstagehand.SessionEndParams{},\n\t)\n\tif err != nil {\n\t\tpanic(err.Error())\n\t}\n\tfmt.Printf(\"%+v\\n\", response.Success)\n}\n" + }, + { + "lang": "Java", + "source": "package com.browserbase.api.example;\n\nimport com.browserbase.api.client.StagehandClient;\nimport com.browserbase.api.client.okhttp.StagehandOkHttpClient;\nimport com.browserbase.api.models.sessions.SessionEndParams;\nimport com.browserbase.api.models.sessions.SessionEndResponse;\n\npublic final class Main {\n private Main() {}\n\n public static void main(String[] args) {\n StagehandClient client = StagehandOkHttpClient.fromEnv();\n\n SessionEndResponse response = client.sessions().end(\"c4dbf3a9-9a58-4b22-8a1c-9f20f9f9e123\");\n }\n}" + }, + { + "lang": "Kotlin", + "source": "package com.browserbase.api.example\n\nimport com.browserbase.api.client.StagehandClient\nimport com.browserbase.api.client.okhttp.StagehandOkHttpClient\nimport com.browserbase.api.models.sessions.SessionEndParams\nimport com.browserbase.api.models.sessions.SessionEndResponse\n\nfun main() {\n val client: StagehandClient = StagehandOkHttpClient.fromEnv()\n\n val response: SessionEndResponse = client.sessions().end(\"c4dbf3a9-9a58-4b22-8a1c-9f20f9f9e123\")\n}" + }, + { + "lang": "Ruby", + "source": "require \"stagehand\"\n\nstagehand = Stagehand::Client.new(\n browserbase_api_key: \"My Browserbase API Key\",\n browserbase_project_id: \"My Browserbase Project ID\",\n model_api_key: \"My Model API Key\"\n)\n\nresponse = stagehand.sessions.end_(\"c4dbf3a9-9a58-4b22-8a1c-9f20f9f9e123\")\n\nputs(response)" + }, + { + "lang": "PHP", + "source": "sessions->end(\n 'c4dbf3a9-9a58-4b22-8a1c-9f20f9f9e123', xStreamResponse: 'true'\n );\n\n var_dump($response);\n} catch (APIException $e) {\n echo $e->getMessage();\n}" + }, + { + "lang": "C#", + "source": "using System;\nusing Stagehand;\nusing Stagehand.Models.Sessions;\n\nStagehandClient client = new();\n\nSessionEndParams parameters = new()\n{\n ID = \"c4dbf3a9-9a58-4b22-8a1c-9f20f9f9e123\"\n};\n\nvar response = await client.Sessions.End(parameters);\n\nConsole.WriteLine(response);" + } + ] + } + }, + "/v1/sessions/{id}/replay": { + "get": { + "summary": "Replay session metrics", + "description": "Retrieves replay metrics for a session.", + "operationId": "SessionReplay", + "parameters": [ + { + "schema": { + "description": "Unique session identifier", + "example": "c4dbf3a9-9a58-4b22-8a1c-9f20f9f9e123", + "type": "string" + }, + "in": "path", + "name": "id", + "required": true, + "description": "Unique session identifier" + }, + { + "schema": { + "description": "Whether to stream the response via SSE", + "example": "true", + "type": "string", + "enum": ["true", "false"] + }, + "in": "header", + "name": "x-stream-response", + "description": "Whether to stream the response via SSE" + } + ], + "responses": { + "200": { + "description": "Default Response", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ReplayResponse" + } + } + } + } + }, + "x-codeSamples": [ + { + "lang": "JavaScript", + "source": "import Stagehand from 'stagehand-sdk';\n\nconst client = new Stagehand({\n browserbaseAPIKey: process.env['BROWSERBASE_API_KEY'], // This is the default and can be omitted\n browserbaseProjectID: process.env['BROWSERBASE_PROJECT_ID'], // This is the default and can be omitted\n modelAPIKey: process.env['MODEL_API_KEY'], // This is the default and can be omitted\n});\n\nconst response = await client.sessions.replay('c4dbf3a9-9a58-4b22-8a1c-9f20f9f9e123');\n\nconsole.log(response.data);" + }, + { + "lang": "Python", + "source": "import os\nfrom stagehand import Stagehand\n\nclient = Stagehand(\n browserbase_api_key=os.environ.get(\"BROWSERBASE_API_KEY\"), # This is the default and can be omitted\n browserbase_project_id=os.environ.get(\"BROWSERBASE_PROJECT_ID\"), # This is the default and can be omitted\n model_api_key=os.environ.get(\"MODEL_API_KEY\"), # This is the default and can be omitted\n)\nresponse = client.sessions.replay(\n id=\"c4dbf3a9-9a58-4b22-8a1c-9f20f9f9e123\",\n)\nprint(response.data)" + }, + { + "lang": "Go", + "source": "package main\n\nimport (\n\t\"context\"\n\t\"fmt\"\n\n\t\"github.com/browserbase/stagehand-go\"\n\t\"github.com/browserbase/stagehand-go/option\"\n)\n\nfunc main() {\n\tclient := stagehand.NewClient(\n\t\toption.WithBrowserbaseAPIKey(\"My Browserbase API Key\"),\n\t\toption.WithBrowserbaseProjectID(\"My Browserbase Project ID\"),\n\t\toption.WithModelAPIKey(\"My Model API Key\"),\n\t)\n\tresponse, err := client.Sessions.Replay(\n\t\tcontext.TODO(),\n\t\t\"c4dbf3a9-9a58-4b22-8a1c-9f20f9f9e123\",\n\t\tstagehand.SessionReplayParams{},\n\t)\n\tif err != nil {\n\t\tpanic(err.Error())\n\t}\n\tfmt.Printf(\"%+v\\n\", response.Data)\n}\n" + }, + { + "lang": "Java", + "source": "package com.browserbase.api.example;\n\nimport com.browserbase.api.client.StagehandClient;\nimport com.browserbase.api.client.okhttp.StagehandOkHttpClient;\nimport com.browserbase.api.models.sessions.SessionReplayParams;\nimport com.browserbase.api.models.sessions.SessionReplayResponse;\n\npublic final class Main {\n private Main() {}\n\n public static void main(String[] args) {\n StagehandClient client = StagehandOkHttpClient.fromEnv();\n\n SessionReplayResponse response = client.sessions().replay(\"c4dbf3a9-9a58-4b22-8a1c-9f20f9f9e123\");\n }\n}" + }, + { + "lang": "Kotlin", + "source": "package com.browserbase.api.example\n\nimport com.browserbase.api.client.StagehandClient\nimport com.browserbase.api.client.okhttp.StagehandOkHttpClient\nimport com.browserbase.api.models.sessions.SessionReplayParams\nimport com.browserbase.api.models.sessions.SessionReplayResponse\n\nfun main() {\n val client: StagehandClient = StagehandOkHttpClient.fromEnv()\n\n val response: SessionReplayResponse = client.sessions().replay(\"c4dbf3a9-9a58-4b22-8a1c-9f20f9f9e123\")\n}" + }, + { + "lang": "Ruby", + "source": "require \"stagehand\"\n\nstagehand = Stagehand::Client.new(\n browserbase_api_key: \"My Browserbase API Key\",\n browserbase_project_id: \"My Browserbase Project ID\",\n model_api_key: \"My Model API Key\"\n)\n\nresponse = stagehand.sessions.replay(\"c4dbf3a9-9a58-4b22-8a1c-9f20f9f9e123\")\n\nputs(response)" + }, + { + "lang": "PHP", + "source": "sessions->replay(\n 'c4dbf3a9-9a58-4b22-8a1c-9f20f9f9e123', xStreamResponse: 'true'\n );\n\n var_dump($response);\n} catch (APIException $e) {\n echo $e->getMessage();\n}" + }, + { + "lang": "C#", + "source": "using System;\nusing Stagehand;\nusing Stagehand.Models.Sessions;\n\nStagehandClient client = new();\n\nSessionReplayParams parameters = new()\n{\n ID = \"c4dbf3a9-9a58-4b22-8a1c-9f20f9f9e123\"\n};\n\nvar response = await client.Sessions.Replay(parameters);\n\nConsole.WriteLine(response);" + } + ] + } + } + }, + "components": { + "schemas": { + "SessionStartRequest": { + "type": "object", + "properties": { + "modelName": { + "description": "Model name to use for AI operations", + "example": "openai/gpt-5.4-mini", + "type": "string" + }, + "domSettleTimeoutMs": { + "description": "Timeout in ms to wait for DOM to settle", + "example": 5000, + "type": "number" + }, + "verbose": { + "description": "Logging verbosity level (0=quiet, 1=normal, 2=debug)", + "example": 1, + "type": "number", + "enum": [0, 1, 2] + }, + "systemPrompt": { + "description": "Custom system prompt for AI operations", + "type": "string" + }, + "browserbaseSessionCreateParams": { + "$ref": "#/components/schemas/BrowserbaseSessionCreateParams" + }, + "browser": { + "$ref": "#/components/schemas/BrowserConfig" + }, + "selfHeal": { + "description": "Enable self-healing for failed actions", + "example": true, + "type": "boolean" + }, + "browserbaseSessionID": { + "description": "Existing Browserbase session ID to resume", + "type": "string" + }, + "experimental": { + "type": "boolean" + }, + "waitForCaptchaSolves": { + "description": "Wait for captcha solves (deprecated, v2 only)", + "type": "boolean" + }, + "actTimeoutMs": { + "description": "Timeout in ms for act operations (deprecated, v2 only)", + "type": "number" + } + }, + "required": ["modelName"] + }, + "SessionStartResponse": { + "type": "object", + "properties": { + "success": { + "description": "Indicates whether the request was successful", + "type": "boolean" + }, + "data": { + "$ref": "#/components/schemas/SessionStartResultOutput" + } + }, + "required": ["success", "data"], + "additionalProperties": false + }, + "BrowserbaseSessionCreateParams": { + "type": "object", + "properties": { + "projectId": { + "deprecated": true, + "description": "Deprecated. Browserbase API keys are now project-scoped, so this field is no longer required.", + "type": "string" + }, + "browserSettings": { + "$ref": "#/components/schemas/BrowserbaseBrowserSettings" + }, + "extensionId": { + "type": "string" + }, + "keepAlive": { + "type": "boolean" + }, + "proxies": { + "anyOf": [ + { + "type": "boolean" + }, + { + "type": "array", + "items": { + "$ref": "#/components/schemas/ProxyConfig" + } + } + ] + }, + "region": { + "$ref": "#/components/schemas/BrowserbaseRegion" + }, + "timeout": { + "type": "number" + }, + "userMetadata": { + "type": "object", + "propertyNames": { + "type": "string" + }, + "additionalProperties": {} + } + } + }, + "BrowserConfig": { + "type": "object", + "properties": { + "type": { + "description": "Browser type to use", + "example": "local", + "type": "string", + "enum": ["local", "browserbase"] + }, + "cdpUrl": { + "description": "Chrome DevTools Protocol URL for connecting to existing browser", + "example": "ws://localhost:9222", + "type": "string" + }, + "launchOptions": { + "$ref": "#/components/schemas/LocalBrowserLaunchOptions" + } + } + }, + "SessionStartResultOutput": { + "type": "object", + "properties": { + "sessionId": { + "description": "Unique Browserbase session identifier", + "example": "c4dbf3a9-9a58-4b22-8a1c-9f20f9f9e123", + "type": "string" + }, + "cdpUrl": { + "description": "CDP WebSocket URL for connecting to the Browserbase cloud browser (present when available)", + "example": "wss://connect.browserbase.com/?signingKey=abc123", + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ] + }, + "available": { + "type": "boolean" + } + }, + "required": ["sessionId", "available"], + "additionalProperties": false + }, + "BrowserbaseBrowserSettings": { + "type": "object", + "properties": { + "advancedStealth": { + "type": "boolean" + }, + "blockAds": { + "type": "boolean" + }, + "captchaImageSelector": { + "type": "string" + }, + "captchaInputSelector": { + "type": "string" + }, + "context": { + "$ref": "#/components/schemas/BrowserbaseContext" + }, + "extensionId": { + "type": "string" + }, + "fingerprint": { + "$ref": "#/components/schemas/BrowserbaseFingerprint" + }, + "logSession": { + "type": "boolean" + }, + "os": { + "type": "string", + "enum": ["windows", "mac", "linux", "mobile", "tablet"] + }, + "recordSession": { + "type": "boolean" + }, + "solveCaptchas": { + "type": "boolean" + }, + "verified": { + "type": "boolean" + }, + "viewport": { + "$ref": "#/components/schemas/BrowserbaseViewport" + } + } + }, + "ProxyConfig": { + "oneOf": [ + { + "$ref": "#/components/schemas/BrowserbaseProxyConfig" + }, + { + "$ref": "#/components/schemas/ExternalProxyConfig" + } + ], + "type": "object", + "discriminator": { + "propertyName": "type", + "mapping": { + "browserbase": { + "$ref": "#/components/schemas/BrowserbaseProxyConfig" + }, + "external": { + "$ref": "#/components/schemas/ExternalProxyConfig" + } + } + } + }, + "BrowserbaseRegion": { + "type": "string", + "enum": ["us-west-2", "us-east-1", "eu-central-1", "ap-southeast-1"] + }, + "LocalBrowserLaunchOptions": { + "type": "object", + "properties": { + "args": { + "type": "array", + "items": { + "type": "string" + } + }, + "executablePath": { + "type": "string" + }, + "port": { + "type": "number" + }, + "userDataDir": { + "type": "string" + }, + "preserveUserDataDir": { + "type": "boolean" + }, + "headless": { + "type": "boolean" + }, + "devtools": { + "type": "boolean" + }, + "chromiumSandbox": { + "type": "boolean" + }, + "ignoreDefaultArgs": { + "anyOf": [ + { + "type": "boolean" + }, + { + "type": "array", + "items": { + "type": "string" + } + } + ] + }, + "proxy": { + "type": "object", + "properties": { + "server": { + "type": "string" + }, + "bypass": { + "type": "string" + }, + "username": { + "type": "string" + }, + "password": { + "type": "string" + } + }, + "required": ["server"] + }, + "locale": { + "type": "string" + }, + "viewport": { + "type": "object", + "properties": { + "width": { + "type": "number" + }, + "height": { + "type": "number" + } + }, + "required": ["width", "height"] + }, + "deviceScaleFactor": { + "type": "number" + }, + "hasTouch": { + "type": "boolean" + }, + "ignoreHTTPSErrors": { + "type": "boolean" + }, + "cdpUrl": { + "type": "string" + }, + "cdpHeaders": { + "type": "object", + "propertyNames": { + "type": "string" + }, + "additionalProperties": { + "type": "string" + } + }, + "connectTimeoutMs": { + "type": "number" + }, + "downloadsPath": { + "type": "string" + }, + "acceptDownloads": { + "type": "boolean" + } + }, + "additionalProperties": false + }, + "BrowserbaseContext": { + "type": "object", + "properties": { + "id": { + "type": "string" + }, + "persist": { + "type": "boolean" + } + }, + "required": ["id"] + }, + "BrowserbaseFingerprint": { + "type": "object", + "properties": { + "browsers": { + "type": "array", + "items": { + "type": "string", + "enum": ["chrome", "edge", "firefox", "safari"] + } + }, + "devices": { + "type": "array", + "items": { + "type": "string", + "enum": ["desktop", "mobile"] + } + }, + "httpVersion": { + "type": "string", + "enum": ["1", "2"] + }, + "locales": { + "type": "array", + "items": { + "type": "string" + } + }, + "operatingSystems": { + "type": "array", + "items": { + "type": "string", + "enum": ["android", "ios", "linux", "macos", "windows"] + } + }, + "screen": { + "$ref": "#/components/schemas/BrowserbaseFingerprintScreen" + } + } + }, + "BrowserbaseViewport": { + "type": "object", + "properties": { + "width": { + "type": "number" + }, + "height": { + "type": "number" + } + } + }, + "BrowserbaseProxyConfig": { + "type": "object", + "properties": { + "type": { + "type": "string", + "const": "browserbase" + }, + "domainPattern": { + "type": "string" + }, + "geolocation": { + "$ref": "#/components/schemas/BrowserbaseProxyGeolocation" + } + }, + "required": ["type"] + }, + "ExternalProxyConfig": { + "type": "object", + "properties": { + "type": { + "type": "string", + "const": "external" + }, + "server": { + "type": "string" + }, + "domainPattern": { + "type": "string" + }, + "username": { + "type": "string" + }, + "password": { + "type": "string" + } + }, + "required": ["type", "server"] + }, + "BrowserbaseFingerprintScreen": { + "type": "object", + "properties": { + "maxHeight": { + "type": "number" + }, + "maxWidth": { + "type": "number" + }, + "minHeight": { + "type": "number" + }, + "minWidth": { + "type": "number" + } + } + }, + "BrowserbaseProxyGeolocation": { + "type": "object", + "properties": { + "country": { + "type": "string" + }, + "city": { + "type": "string" + }, + "state": { + "type": "string" + } + }, + "required": ["country"] + }, + "NavigateRequest": { + "type": "object", + "properties": { + "url": { + "description": "URL to navigate to", + "example": "https://example.com", + "type": "string" + }, + "options": { + "$ref": "#/components/schemas/NavigateOptions" + }, + "frameId": { + "description": "Target frame ID for the navigation", + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ] + }, + "streamResponse": { + "description": "Whether to stream the response via SSE", + "example": true, + "type": "boolean" + } + }, + "required": ["url"] + }, + "NavigateResponse": { + "type": "object", + "properties": { + "success": { + "description": "Indicates whether the request was successful", + "type": "boolean" + }, + "data": { + "$ref": "#/components/schemas/NavigateResultOutput" + } + }, + "required": ["success", "data"], + "additionalProperties": false + }, + "NavigateOptions": { + "type": "object", + "properties": { + "referer": { + "description": "Referer header to send with the request", + "type": "string" + }, + "timeout": { + "description": "Timeout in ms for the navigation", + "example": 30000, + "type": "number" + }, + "waitUntil": { + "description": "When to consider navigation complete", + "example": "networkidle", + "type": "string", + "enum": ["load", "domcontentloaded", "networkidle"] + } + } + }, + "NavigateResultOutput": { + "type": "object", + "properties": { + "result": { + "description": "Navigation response (Playwright Response object or null)", + "anyOf": [ + {}, + { + "type": "null" + } + ], + "x-stainless-any": true + }, + "actionId": { + "description": "Action ID for tracking", + "type": "string" + } + }, + "required": ["result"], + "additionalProperties": false + }, + "ActRequest": { + "type": "object", + "properties": { + "input": { + "description": "Natural language instruction or Action object", + "example": "Click the login button", + "anyOf": [ + { + "type": "string" + }, + { + "$ref": "#/components/schemas/Action" + } + ] + }, + "options": { + "$ref": "#/components/schemas/ActOptions" + }, + "frameId": { + "description": "Target frame ID for the action", + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ] + }, + "streamResponse": { + "description": "Whether to stream the response via SSE", + "example": true, + "type": "boolean" + } + }, + "required": ["input"] + }, + "ActResponse": { + "type": "object", + "properties": { + "success": { + "description": "Indicates whether the request was successful", + "type": "boolean" + }, + "data": { + "$ref": "#/components/schemas/ActResultOutput" + } + }, + "required": ["success", "data"], + "additionalProperties": false + }, + "Action": { + "description": "Action object returned by observe and used by act", + "type": "object", + "properties": { + "selector": { + "description": "CSS selector or XPath for the element", + "example": "[data-testid='submit-button']", + "type": "string" + }, + "description": { + "description": "Human-readable description of the action", + "example": "Click the submit button", + "type": "string" + }, + "backendNodeId": { + "description": "Backend node ID for the element", + "type": "number" + }, + "method": { + "description": "The method to execute (click, fill, etc.)", + "example": "click", + "type": "string" + }, + "arguments": { + "description": "Arguments to pass to the method", + "example": ["Hello World"], + "type": "array", + "items": { + "type": "string" + } + } + }, + "required": ["selector", "description"] + }, + "ActOptions": { + "type": "object", + "properties": { + "model": { + "description": "Model configuration object or model name string (e.g., 'openai/gpt-5-nano')", + "anyOf": [ + { + "$ref": "#/components/schemas/ModelConfig" + }, + { + "type": "string" + } + ] + }, + "variables": { + "$ref": "#/components/schemas/Variables", + "description": "Variables to substitute in the action instruction. Accepts flat primitives or { value, description? } objects.", + "example": { + "username": "john_doe", + "password": { + "value": "secret123", + "description": "The login password" + } + } + }, + "timeout": { + "description": "Timeout in ms for the action", + "example": 30000, + "type": "number" + } + } + }, + "ActResultOutput": { + "type": "object", + "properties": { + "result": { + "$ref": "#/components/schemas/ActResultDataOutput" + }, + "actionId": { + "description": "Action ID for tracking", + "type": "string" + } + }, + "required": ["result"], + "additionalProperties": false + }, + "ModelConfig": { + "$ref": "#/components/schemas/ModelConfigObject" + }, + "Variables": { + "type": "object", + "propertyNames": { + "type": "string" + }, + "additionalProperties": { + "$ref": "#/components/schemas/VariableValue" + } + }, + "ActResultDataOutput": { + "type": "object", + "properties": { + "success": { + "description": "Whether the action completed successfully", + "example": true, + "type": "boolean" + }, + "message": { + "description": "Human-readable result message", + "example": "Successfully clicked the login button", + "type": "string" + }, + "actionDescription": { + "description": "Description of the action that was performed", + "example": "Clicked button with text 'Login'", + "type": "string" + }, + "actions": { + "description": "List of actions that were executed", + "type": "array", + "items": { + "$ref": "#/components/schemas/ActionOutput" + } + } + }, + "required": ["success", "message", "actionDescription", "actions"], + "additionalProperties": false + }, + "ModelConfigObject": { + "anyOf": [ + { + "$ref": "#/components/schemas/VertexModelConfigObject" + }, + { + "$ref": "#/components/schemas/AzureModelConfigObject" + }, + { + "$ref": "#/components/schemas/GenericModelConfigObject" + } + ] + }, + "VariableValue": { + "anyOf": [ + { + "$ref": "#/components/schemas/VariablePrimitive" + }, + { + "type": "object", + "properties": { + "value": { + "$ref": "#/components/schemas/VariablePrimitive" + }, + "description": { + "type": "string" + } + }, + "required": ["value"], + "additionalProperties": false + } + ] + }, + "ActionOutput": { + "description": "Action object returned by observe and used by act", + "type": "object", + "properties": { + "selector": { + "description": "CSS selector or XPath for the element", + "example": "[data-testid='submit-button']", + "type": "string" + }, + "description": { + "description": "Human-readable description of the action", + "example": "Click the submit button", + "type": "string" + }, + "backendNodeId": { + "description": "Backend node ID for the element", + "type": "number" + }, + "method": { + "description": "The method to execute (click, fill, etc.)", + "example": "click", + "type": "string" + }, + "arguments": { + "description": "Arguments to pass to the method", + "example": ["Hello World"], + "type": "array", + "items": { + "type": "string" + } + } + }, + "required": ["selector", "description"], + "additionalProperties": false + }, + "VertexModelConfigObject": { + "type": "object", + "properties": { + "modelName": { + "description": "Model name string with provider prefix (e.g., 'openai/gpt-5-nano')", + "example": "openai/gpt-5.4-mini", + "type": "string" + }, + "apiKey": { + "description": "API key for the model provider", + "example": "sk-some-openai-api-key", + "type": "string" + }, + "baseURL": { + "description": "Base URL for the model provider", + "example": "https://api.openai.com/v1", + "type": "string", + "format": "uri" + }, + "headers": { + "description": "Custom headers sent with every request to the model provider", + "type": "object", + "propertyNames": { + "type": "string" + }, + "additionalProperties": { + "type": "string" + } + }, + "provider": { + "description": "Vertex AI model provider", + "type": "string", + "const": "vertex" + }, + "auth": { + "$ref": "#/components/schemas/GoogleServiceAccountAuth", + "description": "Vertex provider authentication configuration" + }, + "providerOptions": { + "$ref": "#/components/schemas/VertexModelProviderOptions", + "description": "Vertex provider-specific model configuration" + } + }, + "required": ["modelName", "provider", "auth", "providerOptions"], + "additionalProperties": false + }, + "AzureModelConfigObject": { + "anyOf": [ + { + "$ref": "#/components/schemas/AzureEntraModelConfigObject" + }, + { + "$ref": "#/components/schemas/AzureApiKeyModelConfigObject" + } + ] + }, + "GenericModelConfigObject": { + "type": "object", + "properties": { + "modelName": { + "description": "Model name string with provider prefix (e.g., 'openai/gpt-5-nano')", + "example": "openai/gpt-5.4-mini", + "type": "string" + }, + "apiKey": { + "description": "API key for the model provider", + "example": "sk-some-openai-api-key", + "type": "string" + }, + "baseURL": { + "description": "Base URL for the model provider", + "example": "https://api.openai.com/v1", + "type": "string", + "format": "uri" + }, + "headers": { + "description": "Custom headers sent with every request to the model provider", + "type": "object", + "propertyNames": { + "type": "string" + }, + "additionalProperties": { + "type": "string" + } + }, + "openaiEndpointFormat": { + "description": "Wire format used by an OpenAI-compatible endpoint. Defaults to the Responses API; use chat for Chat Completions-only endpoints.", + "example": "chat", + "type": "string", + "enum": ["responses", "chat"] + }, + "provider": { + "description": "AI provider for the model (or provide a baseURL endpoint instead)", + "example": "openai", + "type": "string", + "enum": ["openai", "anthropic", "google", "microsoft", "bedrock"] + } + }, + "required": ["modelName"], + "additionalProperties": false + }, + "VariablePrimitive": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "number" + }, + { + "type": "boolean" + } + ] + }, + "GoogleServiceAccountAuth": { + "type": "object", + "properties": { + "type": { + "description": "Use inline Google Cloud service account credentials for provider authentication", + "type": "string", + "const": "googleServiceAccount" + }, + "credentials": { + "$ref": "#/components/schemas/GoogleServiceAccountCredentials", + "description": "Google Cloud service account credentials" + }, + "scopes": { + "description": "Google auth scopes for the desired API request", + "anyOf": [ + { + "type": "string" + }, + { + "type": "array", + "items": { + "type": "string" + } + } + ] + }, + "projectId": { + "description": "Google Cloud project ID used by google-auth-library", + "type": "string" + }, + "universeDomain": { + "description": "Google Cloud universe domain", + "type": "string" + } + }, + "required": ["type", "credentials"], + "additionalProperties": false + }, + "VertexModelProviderOptions": { + "type": "object", + "properties": { + "vertex": { + "$ref": "#/components/schemas/VertexProviderOptions", + "description": "Vertex AI provider-specific settings" + } + }, + "required": ["vertex"], + "additionalProperties": false + }, + "AzureEntraModelConfigObject": { + "type": "object", + "properties": { + "modelName": { + "description": "Model name string with provider prefix (e.g., 'openai/gpt-5-nano')", + "example": "openai/gpt-5.4-mini", + "type": "string" + }, + "baseURL": { + "description": "Base URL for the model provider", + "example": "https://api.openai.com/v1", + "type": "string", + "format": "uri" + }, + "headers": { + "description": "Custom headers sent with every request to the model provider", + "type": "object", + "propertyNames": { + "type": "string" + }, + "additionalProperties": { + "type": "string" + } + }, + "provider": { + "description": "Azure OpenAI model provider", + "type": "string", + "const": "azure" + }, + "providerOptions": { + "$ref": "#/components/schemas/AzureModelProviderOptions", + "description": "Azure provider-specific model configuration" + }, + "auth": { + "$ref": "#/components/schemas/AzureEntraIdAuth", + "description": "Azure provider authentication configuration" + } + }, + "required": ["modelName", "provider", "providerOptions", "auth"], + "additionalProperties": false + }, + "AzureApiKeyModelConfigObject": { + "type": "object", + "properties": { + "modelName": { + "description": "Model name string with provider prefix (e.g., 'openai/gpt-5-nano')", + "example": "openai/gpt-5.4-mini", + "type": "string" + }, + "apiKey": { + "description": "API key for the model provider", + "example": "sk-some-openai-api-key", + "type": "string" + }, + "baseURL": { + "description": "Base URL for the model provider", + "example": "https://api.openai.com/v1", + "type": "string", + "format": "uri" + }, + "headers": { + "description": "Custom headers sent with every request to the model provider", + "type": "object", + "propertyNames": { + "type": "string" + }, + "additionalProperties": { + "type": "string" + } + }, + "provider": { + "description": "Azure OpenAI model provider", + "type": "string", + "const": "azure" + }, + "providerOptions": { + "$ref": "#/components/schemas/AzureModelProviderOptions", + "description": "Azure provider-specific model configuration" + } + }, + "required": ["modelName", "provider", "providerOptions"], + "additionalProperties": false + }, + "GoogleServiceAccountCredentials": { + "type": "object", + "properties": { + "type": { + "type": "string", + "const": "service_account" + }, + "project_id": { + "type": "string" + }, + "private_key_id": { + "type": "string" + }, + "private_key": { + "type": "string" + }, + "client_email": { + "type": "string" + }, + "client_id": { + "type": "string" + }, + "auth_uri": { + "type": "string", + "format": "uri" + }, + "token_uri": { + "type": "string", + "format": "uri" + }, + "auth_provider_x509_cert_url": { + "type": "string", + "format": "uri" + }, + "client_x509_cert_url": { + "type": "string", + "format": "uri" + }, + "universe_domain": { + "type": "string" + } + }, + "required": ["private_key", "client_email"], + "additionalProperties": false + }, + "VertexProviderOptions": { + "type": "object", + "properties": { + "project": { + "description": "Google Cloud project ID for Vertex AI models", + "example": "my-gcp-project", + "type": "string" + }, + "location": { + "description": "Google Cloud location for Vertex AI models", + "example": "us-central1", + "type": "string" + }, + "baseURL": { + "description": "Base URL for the Vertex AI provider", + "type": "string", + "format": "uri" + }, + "headers": { + "description": "Custom headers sent with every request to the Vertex AI provider", + "type": "object", + "propertyNames": { + "type": "string" + }, + "additionalProperties": { + "type": "string" + } + } + }, + "required": ["project", "location"], + "additionalProperties": false + }, + "AzureModelProviderOptions": { + "type": "object", + "properties": { + "azure": { + "$ref": "#/components/schemas/AzureProviderOptions", + "description": "Azure OpenAI provider-specific settings" + } + }, + "required": ["azure"], + "additionalProperties": false + }, + "AzureEntraIdAuth": { + "type": "object", + "properties": { + "type": { + "description": "Use a Microsoft Entra ID bearer token for authentication", + "type": "string", + "const": "azureEntraId" + }, + "token": { + "description": "Microsoft Entra ID bearer token for Azure OpenAI", + "type": "string", + "minLength": 1 + } + }, + "required": ["type", "token"], + "additionalProperties": false + }, + "AzureProviderOptions": { + "type": "object", + "properties": { + "resourceName": { + "description": "Azure OpenAI resource name", + "example": "my-azure-openai-resource", + "type": "string" + }, + "baseURL": { + "description": "Base URL for the Azure OpenAI provider", + "type": "string", + "format": "uri" + }, + "apiVersion": { + "description": "Azure OpenAI API version", + "example": "2024-10-01-preview", + "type": "string" + }, + "useDeploymentBasedUrls": { + "description": "Whether to use deployment-based Azure OpenAI URLs", + "type": "boolean" + }, + "headers": { + "description": "Custom headers sent with every request to the Azure OpenAI provider", + "type": "object", + "propertyNames": { + "type": "string" + }, + "additionalProperties": { + "type": "string" + } + } + }, + "additionalProperties": false + }, + "ObserveRequest": { + "type": "object", + "properties": { + "instruction": { + "description": "Natural language instruction for what actions to find", + "example": "Find all clickable navigation links", + "type": "string" + }, + "options": { + "$ref": "#/components/schemas/ObserveOptions" + }, + "frameId": { + "description": "Target frame ID for the observation", + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ] + }, + "streamResponse": { + "description": "Whether to stream the response via SSE", + "example": true, + "type": "boolean" + } + } + }, + "ObserveResponse": { + "type": "object", + "properties": { + "success": { + "description": "Indicates whether the request was successful", + "type": "boolean" + }, + "data": { + "$ref": "#/components/schemas/ObserveResultOutput" + } + }, + "required": ["success", "data"], + "additionalProperties": false + }, + "ObserveOptions": { + "type": "object", + "properties": { + "model": { + "description": "Model configuration object or model name string (e.g., 'openai/gpt-5-nano')", + "anyOf": [ + { + "$ref": "#/components/schemas/ModelConfig" + }, + { + "type": "string" + } + ] + }, + "variables": { + "$ref": "#/components/schemas/Variables", + "description": "Variables whose names are exposed to the model so observe() returns %variableName% placeholders in suggested action arguments instead of literal values. Accepts flat primitives or { value, description? } objects.", + "example": { + "username": { + "value": "john@example.com", + "description": "The login email" + }, + "rememberMe": true + } + }, + "timeout": { + "description": "Timeout in ms for the observation", + "example": 30000, + "type": "number" + }, + "selector": { + "description": "CSS selector to scope observation to a specific element", + "example": "nav", + "type": "string" + }, + "ignoreSelectors": { + "description": "Selectors for elements and subtrees that should be excluded from observation", + "example": ["nav", ".cookie-banner", "#sidebar-ads"], + "type": "array", + "items": { + "type": "string" + } + } + } + }, + "ObserveResultOutput": { + "type": "object", + "properties": { + "result": { + "type": "array", + "items": { + "$ref": "#/components/schemas/ActionOutput" + } + }, + "actionId": { + "description": "Action ID for tracking", + "type": "string" + } + }, + "required": ["result"], + "additionalProperties": false + }, + "ExtractRequest": { + "type": "object", + "properties": { + "instruction": { + "description": "Natural language instruction for what to extract", + "example": "Extract all product names and prices from the page", + "type": "string" + }, + "schema": { + "description": "JSON Schema defining the structure of data to extract", + "type": "object", + "propertyNames": { + "type": "string" + }, + "additionalProperties": {} + }, + "options": { + "$ref": "#/components/schemas/ExtractOptions" + }, + "frameId": { + "description": "Target frame ID for the extraction", + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ] + }, + "streamResponse": { + "description": "Whether to stream the response via SSE", + "example": true, + "type": "boolean" + } + } + }, + "ExtractResponse": { + "type": "object", + "properties": { + "success": { + "description": "Indicates whether the request was successful", + "type": "boolean" + }, + "data": { + "$ref": "#/components/schemas/ExtractResultOutput" + } + }, + "required": ["success", "data"], + "additionalProperties": false + }, + "ExtractOptions": { + "type": "object", + "properties": { + "model": { + "description": "Model configuration object or model name string (e.g., 'openai/gpt-5-nano')", + "anyOf": [ + { + "$ref": "#/components/schemas/ModelConfig" + }, + { + "type": "string" + } + ] + }, + "timeout": { + "description": "Timeout in ms for the extraction", + "example": 30000, + "type": "number" + }, + "selector": { + "description": "CSS selector to scope extraction to a specific element", + "example": "#main-content", + "type": "string" + }, + "ignoreSelectors": { + "description": "Selectors for elements and subtrees that should be excluded from extraction", + "example": ["nav", ".cookie-banner", "#sidebar-ads"], + "type": "array", + "items": { + "type": "string" + } + }, + "screenshot": { + "description": "When true, include a screenshot of the current viewport in the extraction LLM call. Defaults to false.", + "example": false, + "type": "boolean" + } + } + }, + "ExtractResultOutput": { + "type": "object", + "properties": { + "result": { + "description": "Extracted data matching the requested schema", + "x-stainless-any": true + }, + "actionId": { + "description": "Action ID for tracking", + "type": "string" + } + }, + "required": ["result"], + "additionalProperties": false + }, + "AgentExecuteRequest": { + "type": "object", + "properties": { + "agentConfig": { + "$ref": "#/components/schemas/AgentConfig" + }, + "executeOptions": { + "$ref": "#/components/schemas/AgentExecuteOptions" + }, + "frameId": { + "description": "Target frame ID for the agent", + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ] + }, + "streamResponse": { + "description": "Whether to stream the response via SSE", + "example": true, + "type": "boolean" + }, + "shouldCache": { + "description": "If true, the server captures a cache entry and returns it to the client", + "type": "boolean" + } + }, + "required": ["agentConfig", "executeOptions"] + }, + "AgentExecuteResponse": { + "type": "object", + "properties": { + "success": { + "description": "Indicates whether the request was successful", + "type": "boolean" + }, + "data": { + "$ref": "#/components/schemas/AgentExecuteResultOutput" + } + }, + "required": ["success", "data"], + "additionalProperties": false + }, + "AgentConfig": { + "type": "object", + "properties": { + "provider": { + "description": "AI provider for the agent (legacy, use model: openai/gpt-5-nano instead)", + "example": "openai", + "type": "string", + "enum": ["openai", "anthropic", "google", "microsoft", "bedrock"] + }, + "model": { + "description": "Model configuration object or model name string (e.g., 'openai/gpt-5-nano')", + "anyOf": [ + { + "$ref": "#/components/schemas/ModelConfig" + }, + { + "type": "string" + } + ] + }, + "systemPrompt": { + "description": "Custom system prompt for the agent", + "type": "string" + }, + "cua": { + "description": "Deprecated. Use mode: 'cua' instead. If both are provided, mode takes precedence.", + "example": true, + "type": "boolean" + }, + "mode": { + "description": "Tool mode for the agent (dom, hybrid, cua). If set, overrides cua.", + "example": "cua", + "type": "string", + "enum": ["dom", "hybrid", "cua"] + }, + "executionModel": { + "description": "Model configuration object or model name string (e.g., 'openai/gpt-5-nano') for tool execution (observe/act calls within agent tools). If not specified, inherits from the main model configuration.", + "anyOf": [ + { + "$ref": "#/components/schemas/ModelConfig" + }, + { + "type": "string" + } + ] + } + } + }, + "AgentExecuteOptions": { + "type": "object", + "properties": { + "instruction": { + "description": "Natural language instruction for the agent", + "example": "Log in with username 'demo' and password 'test123', then navigate to settings", + "type": "string" + }, + "maxSteps": { + "description": "Maximum number of steps the agent can take", + "example": 20, + "type": "number" + }, + "highlightCursor": { + "description": "Whether to visually highlight the cursor during execution", + "example": true, + "type": "boolean" + }, + "useSearch": { + "description": "Whether to enable the web search tool powered by Browserbase Search API", + "example": true, + "type": "boolean" + }, + "toolTimeout": { + "description": "Timeout in milliseconds for each agent tool call", + "example": 30000, + "type": "number" + }, + "variables": { + "$ref": "#/components/schemas/Variables", + "description": "Variables available to the agent via %variableName% syntax in supported tools" + } + }, + "required": ["instruction"] + }, + "AgentExecuteResultOutput": { + "type": "object", + "properties": { + "result": { + "$ref": "#/components/schemas/AgentResultDataOutput" + }, + "cacheEntry": { + "$ref": "#/components/schemas/AgentCacheEntryOutput" + } + }, + "required": ["result"], + "additionalProperties": false + }, + "AgentResultDataOutput": { + "type": "object", + "properties": { + "success": { + "description": "Whether the agent completed successfully", + "example": true, + "type": "boolean" + }, + "message": { + "description": "Summary of what the agent accomplished", + "example": "Successfully logged in and navigated to dashboard", + "type": "string" + }, + "actions": { + "type": "array", + "items": { + "$ref": "#/components/schemas/AgentAction" + } + }, + "completed": { + "description": "Whether the agent finished its task", + "example": true, + "type": "boolean" + }, + "metadata": { + "type": "object", + "propertyNames": { + "type": "string" + }, + "additionalProperties": {} + }, + "usage": { + "$ref": "#/components/schemas/AgentUsageOutput" + } + }, + "required": ["success", "message", "actions", "completed"], + "additionalProperties": false + }, + "AgentCacheEntryOutput": { + "type": "object", + "properties": { + "cacheKey": { + "description": "Opaque cache identifier computed from instruction, URL, options, and config", + "type": "string" + }, + "entry": { + "description": "Serialized cache entry that can be written to disk" + } + }, + "required": ["cacheKey", "entry"], + "additionalProperties": false + }, + "AgentAction": { + "type": "object", + "properties": { + "type": { + "description": "Type of action taken", + "example": "click", + "type": "string" + }, + "reasoning": { + "description": "Agent's reasoning for taking this action", + "type": "string" + }, + "taskCompleted": { + "type": "boolean" + }, + "action": { + "type": "string" + }, + "timeMs": { + "description": "Time taken for this action in ms", + "type": "number" + }, + "pageText": { + "type": "string" + }, + "pageUrl": { + "type": "string" + }, + "instruction": { + "type": "string" + } + }, + "required": ["type"], + "additionalProperties": {} + }, + "AgentUsageOutput": { + "type": "object", + "properties": { + "input_tokens": { + "example": 1500, + "type": "number" + }, + "output_tokens": { + "example": 250, + "type": "number" + }, + "reasoning_tokens": { + "type": "number" + }, + "cached_input_tokens": { + "type": "number" + }, + "inference_time_ms": { + "example": 2500, + "type": "number" + } + }, + "required": ["input_tokens", "output_tokens", "inference_time_ms"], + "additionalProperties": false + }, + "SessionEndResponse": { + "type": "object", + "properties": { + "success": { + "description": "Indicates whether the request was successful", + "type": "boolean" + } + }, + "required": ["success"], + "additionalProperties": false + }, + "ReplayResponse": { + "type": "object", + "properties": { + "success": { + "description": "Indicates whether the request was successful", + "type": "boolean" + }, + "data": { + "$ref": "#/components/schemas/ReplayResultOutput" + } + }, + "required": ["success", "data"], + "additionalProperties": false + }, + "ReplayResultOutput": { + "type": "object", + "properties": { + "pages": { + "type": "array", + "items": { + "$ref": "#/components/schemas/ReplayPageOutput" + } + }, + "clientLanguage": { + "type": "string" + } + }, + "required": ["pages"], + "additionalProperties": false + }, + "ReplayPageOutput": { + "type": "object", + "properties": { + "url": { + "type": "string" + }, + "timestamp": { + "type": "number" + }, + "duration": { + "type": "number" + }, + "actions": { + "type": "array", + "items": { + "$ref": "#/components/schemas/ReplayActionOutput" + } + } + }, + "required": ["url", "timestamp", "duration", "actions"], + "additionalProperties": false + }, + "ReplayActionOutput": { + "type": "object", + "properties": { + "method": { + "type": "string" + }, + "parameters": { + "type": "object", + "propertyNames": { + "type": "string" + }, + "additionalProperties": {} + }, + "result": { + "type": "object", + "propertyNames": { + "type": "string" + }, + "additionalProperties": {} + }, + "timestamp": { + "type": "number" + }, + "endTime": { + "type": "number" + }, + "tokenUsage": { + "$ref": "#/components/schemas/TokenUsageOutput" + } + }, + "required": ["method", "parameters", "result", "timestamp"], + "additionalProperties": false + }, + "TokenUsageOutput": { + "type": "object", + "properties": { + "inputTokens": { + "type": "number" + }, + "outputTokens": { + "type": "number" + }, + "timeMs": { + "type": "number" + }, + "cost": { + "type": "number" + } + }, + "additionalProperties": false + } + }, + "securitySchemes": { + "BrowserbaseApiKey": { + "type": "apiKey", + "in": "header", + "name": "x-bb-api-key", + "description": "Browserbase API key for authentication" + }, + "BrowserbaseProjectId": { + "type": "apiKey", + "in": "header", + "name": "x-bb-project-id", + "description": "Deprecated. Browserbase API keys are now project-scoped, so this header is no longer required." + } + } + } +}