Add configurable API URLs to the SDKs

[monadoid]

before

Endpoint routing relied on environment variables, and STAGEHAND_API_URL was not consumed by the SDK.

// BROWSERBASE_BASE_URL=https://api.dev.browserbase.com
// STAGEHAND_API_URL=https://api.stagehand.dev.browserbase.com

const browser = await browserbase.launch({ apiKey });
const stagehand = await Stagehand.create({ browser });

after

Both endpoints are configured explicitly:

// No endpoint environment variables.

const browser = await browserbase.launch({
  apiKey,
  baseUrl: "https://api.dev.browserbase.com",
});

const stagehand = await Stagehand.create({
  browser,
  apiUrl: "https://api.stagehand.dev.browserbase.com",
});

The same options are available in Python and Go, with production defaults.

test plan

• TypeScript, protocol, and extension tests and builds
• Python tests, lint, and typecheck
• Go tests, vet, and example build
• Live dev Model Gateway extraction

[changeset-bot]

⚠️ No Changeset found

Latest commit: 9a0da08

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

[cubic-dev-ai]

All reported issues were addressed across 37 files

<sub>Reply with feedback, questions, or to request a fix.

Re-trigger cubic</sub>

[cubic-dev-ai]

All reported issues were addressed across 18 files (changes from recent commits).

<sub>Reply with feedback, questions, or to request a fix.

Re-trigger cubic</sub>

[cubic-dev-ai]

1 issue found across 8 files (changes from recent commits).

Confidence score: 3/5

• In packages/protocol/schemas.ts, the apiUrl refine currently allows URLs with query strings/fragments, so later raw /v1 concatenation can generate invalid gateway endpoints and cause request failures at runtime — tighten validation to service-origin URLs only (or normalize/sanitize before appending /v1).

Prompt for AI agents (unresolved issues)

Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.


<file name="packages/protocol/schemas.ts">

<violation number="1" location="packages/protocol/schemas.ts:1556">
P2: Some accepted `apiUrl` values still produce broken gateway endpoints, because query strings/fragments pass this refine and `/v1` is appended as raw text later. Suggest constraining `apiUrl` to a service-origin form (no query/hash) in this validator.</violation>
</file>

<sub>Tip: Review your code locally with the cubic CLI to iterate faster.

Re-trigger cubic</sub>

[cubic-dev-ai]

P2: Some accepted apiUrl values still produce broken gateway endpoints, because query strings/fragments pass this refine and /v1 is appended as raw text later. Suggest constraining apiUrl to a service-origin form (no query/hash) in this validator.

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At packages/protocol/schemas.ts, line 1556:

<comment>Some accepted `apiUrl` values still produce broken gateway endpoints, because query strings/fragments pass this refine and `/v1` is appended as raw text later. Suggest constraining `apiUrl` to a service-origin form (no query/hash) in this validator.</comment>

<file context>
@@ -1551,10 +1551,16 @@ export const StagehandInitParamsSchema = z
-    }),
+    apiUrl: z
+      .url()
+      .refine((value) => !new URL(value).pathname.replace(/\/+$/, "").endsWith("/v1"), {
+        message: "Stagehand apiUrl must be a service origin without /v1",
+      })
</file context>

Suggested change

	.refine((value) => !new URL(value).pathname.replace(/\/+$/, "").endsWith("/v1"), {
	message: "Stagehand apiUrl must be a service origin without /v1",
	})
	.refine((value) => {
	const url = new URL(value);
	const pathname = url.pathname.replace(/\/+$/, "");
	return !pathname.endsWith("/v1") && url.search === "" && url.hash === "";
	}, {
	message: "Stagehand apiUrl must be a service origin without /v1, query params, or hash fragments",
	})