{ "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." } } } }