Deprecate browserbase project ID (#91)

monadoid · samfinton · web-flow · commit 05f8a76d5c70 · 2026-05-06T21:55:04.000+02:00
Co-authored-by: samfinton &lt;samfinton@samLaptopm5.galaxus.box&gt;
diff --git a/README.md b/README.md
@@ -87,10 +87,8 @@ Python 3.9 or higher.
 
 Set your environment variables (from `examples/.env.example`):
 
-- `STAGEHAND_API_URL`
 - `MODEL_API_KEY`
 - `BROWSERBASE_API_KEY`
-- `BROWSERBASE_PROJECT_ID`
 
 ```bash
 cp examples/.env.example examples/.env
@@ -139,7 +137,6 @@ def main() -> None:
     with Stagehand(
         server="remote",
         browserbase_api_key=os.environ.get("BROWSERBASE_API_KEY"),
-        browserbase_project_id=os.environ.get("BROWSERBASE_PROJECT_ID"),
         model_api_key=os.environ.get("MODEL_API_KEY"),
     ) as client:
         session = client.sessions.start(
@@ -234,7 +231,6 @@ from stagehand import AsyncStagehand
 
 client = AsyncStagehand(
     browserbase_api_key="My Browserbase API Key",
-    browserbase_project_id="My Browserbase Project ID",
     model_api_key="My Model API Key",
 )
 ```
@@ -255,9 +251,11 @@ See this table for the available options:
 | Keyword argument         | Environment variable     | Required | Default value                             |
 | ------------------------ | ------------------------ | -------- | ----------------------------------------- |
 | `browserbase_api_key`    | `BROWSERBASE_API_KEY`    | true     | -                                         |
-| `browserbase_project_id` | `BROWSERBASE_PROJECT_ID` | true     | -                                         |
+| `browserbase_project_id` | -                        | false    | -                                         |
 | `model_api_key`          | `MODEL_API_KEY`          | true     | -                                         |
-| `base_url`               | `STAGEHAND_API_URL`     | false    | `"https://api.stagehand.browserbase.com"` |
+| `base_url`               | `STAGEHAND_API_URL`      | false    | `"https://api.stagehand.browserbase.com"` |
+
+`browserbase_project_id` is deprecated, accepted for backwards compatibility, and ignored. `STAGEHAND_BASE_URL` remains supported as a deprecated fallback when `STAGEHAND_API_URL` is unset.
 
 Keyword arguments take precedence over environment variables.
 
@@ -662,7 +660,7 @@ import httpx
 from stagehand import Stagehand, DefaultHttpxClient
 
 client = Stagehand(
-    # Or use the `STAGEHAND_API_URL` env var
+    # Or use the `STAGEHAND_API_URL` env var, with `STAGEHAND_BASE_URL` as a fallback
     base_url="http://my.test.server.example.com:8083",
     http_client=DefaultHttpxClient(
         proxy="http://my.test.proxy.example.com",
diff --git a/examples/.env.example b/examples/.env.example
@@ -1,4 +1,2 @@
-STAGEHAND_API_URL=https://api.stagehand.browserbase.com
 MODEL_API_KEY=sk-proj-your-llm-api-key-here
 BROWSERBASE_API_KEY=bb_live_your_api_key_here
-BROWSERBASE_PROJECT_ID=your-bb-project-uuid-here
diff --git a/examples/act_example.py b/examples/act_example.py
@@ -10,7 +10,6 @@
 
 Required environment variables:
 - BROWSERBASE_API_KEY: Your Browserbase API key
-- BROWSERBASE_PROJECT_ID: Your Browserbase project ID
 - MODEL_API_KEY: Your OpenAI API key
 """
 
@@ -45,10 +44,9 @@ async def main() -> None:
     load_example_env()
     load_example_env()
     # Create client using environment variables
-    # BROWSERBASE_API_KEY, BROWSERBASE_PROJECT_ID, MODEL_API_KEY
+    # BROWSERBASE_API_KEY and MODEL_API_KEY
     async with AsyncStagehand(
         browserbase_api_key=os.environ.get("BROWSERBASE_API_KEY"),
-        browserbase_project_id=os.environ.get("BROWSERBASE_PROJECT_ID"),
         model_api_key=os.environ.get("MODEL_API_KEY"),
     ) as client:
         # Start a new browser session
diff --git a/examples/agent_execute.py b/examples/agent_execute.py
@@ -3,7 +3,6 @@
 
 Required environment variables:
 - BROWSERBASE_API_KEY
-- BROWSERBASE_PROJECT_ID
 - MODEL_API_KEY
 
 Optional:
diff --git a/examples/byob_example.py b/examples/byob_example.py
@@ -6,7 +6,6 @@
 
 Required environment variables:
 - BROWSERBASE_API_KEY
-- BROWSERBASE_PROJECT_ID
 - MODEL_API_KEY
 
 Usage:
@@ -52,7 +51,6 @@ async def main() -> None:
     load_example_env()
     async with AsyncStagehand(
         browserbase_api_key=os.environ.get("BROWSERBASE_API_KEY"),
-        browserbase_project_id=os.environ.get("BROWSERBASE_PROJECT_ID"),
         model_api_key=os.environ.get("MODEL_API_KEY"),
     ) as client, async_playwright() as playwright:
         browser = await playwright.chromium.launch(headless=True)
diff --git a/examples/env.py b/examples/env.py
@@ -4,10 +4,8 @@
 from pathlib import Path
 
 REQUIRED_KEYS = {
-    "STAGEHAND_API_URL",
     "MODEL_API_KEY",
     "BROWSERBASE_API_KEY",
-    "BROWSERBASE_PROJECT_ID",
 }
 
 
diff --git a/examples/full_example.py b/examples/full_example.py
@@ -12,7 +12,6 @@
 
 Required environment variables:
 - BROWSERBASE_API_KEY: Your Browserbase API key
-- BROWSERBASE_PROJECT_ID: Your Browserbase project ID
 - MODEL_API_KEY: Your OpenAI API key
 """
 
@@ -47,10 +46,9 @@ async def main() -> None:
     load_example_env()
     load_example_env()
     # Create client using environment variables
-    # BROWSERBASE_API_KEY, BROWSERBASE_PROJECT_ID, MODEL_API_KEY
+    # BROWSERBASE_API_KEY and MODEL_API_KEY
     async with AsyncStagehand(
         browserbase_api_key=os.environ.get("BROWSERBASE_API_KEY"),
-        browserbase_project_id=os.environ.get("BROWSERBASE_PROJECT_ID"),
         model_api_key=os.environ.get("MODEL_API_KEY"),
     ) as client:
         # Start a new browser session (returns a session helper bound to a session_id)
diff --git a/examples/local_browser_playwright_example.py b/examples/local_browser_playwright_example.py
@@ -12,10 +12,9 @@
 Environment variables required:
 - MODEL_API_KEY
 - BROWSERBASE_API_KEY (can be any value in local mode)
-- BROWSERBASE_PROJECT_ID (can be any value in local mode)
 
 Optional:
-- STAGEHAND_API_URL (defaults to http://127.0.0.1:3000)
+- STAGEHAND_API_URL or STAGEHAND_BASE_URL (defaults to http://127.0.0.1:3000)
 """
 
 from __future__ import annotations
@@ -82,11 +81,8 @@ def main() -> None:
         sys.exit("Set the MODEL_API_KEY environment variable to run this example.")
 
     bb_api_key = os.environ.get("BROWSERBASE_API_KEY")
-    bb_project_id = os.environ.get("BROWSERBASE_PROJECT_ID")
-    if not bb_api_key or not bb_project_id:
-        sys.exit(
-            "Set BROWSERBASE_API_KEY and BROWSERBASE_PROJECT_ID to run this example."
-        )
+    if not bb_api_key:
+        sys.exit("Set BROWSERBASE_API_KEY to run this example.")
 
     try:
         from playwright.sync_api import sync_playwright  # type: ignore[import-not-found]
@@ -102,7 +98,6 @@ def main() -> None:
     with Stagehand(
         server="local",
         browserbase_api_key=bb_api_key,
-        browserbase_project_id=bb_project_id,
         model_api_key=model_api_key,
         local_ready_timeout_s=30.0,
     ) as client:
diff --git a/examples/local_example.py b/examples/local_example.py
@@ -4,7 +4,6 @@
 
 Required environment variables:
 - BROWSERBASE_API_KEY (can be any value in local mode)
-- BROWSERBASE_PROJECT_ID (can be any value in local mode)
 - MODEL_API_KEY (read by this example and passed explicitly to the client)
 
 
diff --git a/examples/local_server_multiregion_browser_example.py b/examples/local_server_multiregion_browser_example.py
@@ -11,10 +11,9 @@
 Environment variables required:
 - MODEL_API_KEY
 - BROWSERBASE_API_KEY
-- BROWSERBASE_PROJECT_ID
 
 Optional:
-- STAGEHAND_API_URL (defaults to http://127.0.0.1:3000 when server="local")
+- STAGEHAND_API_URL or STAGEHAND_BASE_URL (defaults to http://127.0.0.1:3000 when server="local")
 """
 
 from __future__ import annotations
@@ -53,11 +52,8 @@ def main() -> None:
         sys.exit("Set the MODEL_API_KEY environment variable to run this example.")
 
     bb_api_key = os.environ.get("BROWSERBASE_API_KEY")
-    bb_project_id = os.environ.get("BROWSERBASE_PROJECT_ID")
-    if not bb_api_key or not bb_project_id:
-        sys.exit(
-            "Set BROWSERBASE_API_KEY and BROWSERBASE_PROJECT_ID to run this example."
-        )
+    if not bb_api_key:
+        sys.exit("Set BROWSERBASE_API_KEY to run this example.")
 
     try:
         from playwright.sync_api import sync_playwright  # type: ignore[import-not-found]
@@ -73,7 +69,6 @@ def main() -> None:
     with Stagehand(
         server="local",
         browserbase_api_key=bb_api_key,
-        browserbase_project_id=bb_project_id,
         model_api_key=model_api_key,
         local_ready_timeout_s=30.0,
     ) as client:
diff --git a/examples/logging_example.py b/examples/logging_example.py
@@ -4,7 +4,6 @@
 
 Required environment variables:
 - BROWSERBASE_API_KEY: Your Browserbase API key
-- BROWSERBASE_PROJECT_ID: Your Browserbase project ID
 - MODEL_API_KEY: Your OpenAI API key
 """
 
@@ -23,7 +22,6 @@ async def main() -> None:
     # Create client using environment variables
     async with AsyncStagehand(
         browserbase_api_key=os.environ.get("BROWSERBASE_API_KEY"),
-        browserbase_project_id=os.environ.get("BROWSERBASE_PROJECT_ID"),
         model_api_key=os.environ.get("MODEL_API_KEY"),
     ) as client:
         # Start a new browser session with verbose logging enabled
diff --git a/examples/playwright_page_example.py b/examples/playwright_page_example.py
@@ -10,10 +10,9 @@
 Environment variables required:
 - MODEL_API_KEY
 - BROWSERBASE_API_KEY
-- BROWSERBASE_PROJECT_ID
 
 Optional:
-- STAGEHAND_API_URL (defaults to https://api.stagehand.browserbase.com)
+- STAGEHAND_API_URL or STAGEHAND_BASE_URL (defaults to https://api.stagehand.browserbase.com)
 """
 
 from __future__ import annotations
@@ -52,11 +51,8 @@ def main() -> None:
         sys.exit("Set the MODEL_API_KEY environment variable to run this example.")
 
     bb_api_key = os.environ.get("BROWSERBASE_API_KEY")
-    bb_project_id = os.environ.get("BROWSERBASE_PROJECT_ID")
-    if not bb_api_key or not bb_project_id:
-        sys.exit(
-            "Set BROWSERBASE_API_KEY and BROWSERBASE_PROJECT_ID to run this example."
-        )
+    if not bb_api_key:
+        sys.exit("Set BROWSERBASE_API_KEY to run this example.")
 
     try:
         from playwright.sync_api import sync_playwright  # type: ignore[import-not-found]
@@ -72,7 +68,6 @@ def main() -> None:
     with Stagehand(
         server="remote",
         browserbase_api_key=bb_api_key,
-        browserbase_project_id=bb_project_id,
         model_api_key=model_api_key,
     ) as client:
         print("⏳ Starting Stagehand session...")
diff --git a/examples/pydoll_tab_example.py b/examples/pydoll_tab_example.py
@@ -12,10 +12,9 @@
 Environment variables required:
 - MODEL_API_KEY
 - BROWSERBASE_API_KEY
-- BROWSERBASE_PROJECT_ID
 
 Optional:
-- STAGEHAND_API_URL (defaults to https://api.stagehand.browserbase.com)
+- STAGEHAND_API_URL or STAGEHAND_BASE_URL (defaults to https://api.stagehand.browserbase.com)
 
 Notes:
 - This example requires Python 3.10+ because `pydoll-python` requires Python 3.10+.
@@ -121,9 +120,8 @@ async def main() -> None:
         sys.exit("Set the MODEL_API_KEY environment variable to run this example.")
 
     bb_api_key = os.environ.get("BROWSERBASE_API_KEY")
-    bb_project_id = os.environ.get("BROWSERBASE_PROJECT_ID")
-    if not bb_api_key or not bb_project_id:
-        sys.exit("Set BROWSERBASE_API_KEY and BROWSERBASE_PROJECT_ID to run this example.")
+    if not bb_api_key:
+        sys.exit("Set BROWSERBASE_API_KEY to run this example.")
 
     try:
         from pydoll.browser.chromium import Chrome  # type: ignore[import-not-found]
@@ -138,7 +136,6 @@ async def main() -> None:
     async with AsyncStagehand(
         server="remote",
         browserbase_api_key=bb_api_key,
-        browserbase_project_id=bb_project_id,
         model_api_key=model_api_key,
     ) as client:
         print("⏳ Starting Stagehand session...")
diff --git a/examples/remote_browser_playwright_example.py b/examples/remote_browser_playwright_example.py
@@ -12,10 +12,9 @@
 Environment variables required:
 - MODEL_API_KEY
 - BROWSERBASE_API_KEY
-- BROWSERBASE_PROJECT_ID
 
 Optional:
-- STAGEHAND_API_URL (defaults to https://api.stagehand.browserbase.com)
+- STAGEHAND_API_URL or STAGEHAND_BASE_URL (defaults to https://api.stagehand.browserbase.com)
 """
 
 from __future__ import annotations
@@ -54,11 +53,8 @@ def main() -> None:
         sys.exit("Set the MODEL_API_KEY environment variable to run this example.")
 
     bb_api_key = os.environ.get("BROWSERBASE_API_KEY")
-    bb_project_id = os.environ.get("BROWSERBASE_PROJECT_ID")
-    if not bb_api_key or not bb_project_id:
-        sys.exit(
-            "Set BROWSERBASE_API_KEY and BROWSERBASE_PROJECT_ID to run this example."
-        )
+    if not bb_api_key:
+        sys.exit("Set BROWSERBASE_API_KEY to run this example.")
 
     try:
         from playwright.sync_api import sync_playwright  # type: ignore[import-not-found]
@@ -74,7 +70,6 @@ def main() -> None:
     with Stagehand(
         server="remote",
         browserbase_api_key=bb_api_key,
-        browserbase_project_id=bb_project_id,
         model_api_key=model_api_key,
     ) as client:
         print("⏳ Starting Stagehand session...")
diff --git a/src/stagehand/_client.py b/src/stagehand/_client.py
@@ -132,16 +132,13 @@ def __init__(
 
         This automatically infers the following arguments from their corresponding environment variables if they are not provided:
         - `browserbase_api_key` from `BROWSERBASE_API_KEY`
-        - `browserbase_project_id` from `BROWSERBASE_PROJECT_ID`
 
         `model_api_key` is intentionally not inferred from any AI provider environment variable.
         Pass it explicitly when you want the SDK to send `x-model-api-key` on remote requests or
         to forward `MODEL_API_KEY` to the local SEA child process.
         """
         if browserbase_api_key is None:
             browserbase_api_key = os.environ.get("BROWSERBASE_API_KEY")
-        if browserbase_project_id is None:
-            browserbase_project_id = os.environ.get("BROWSERBASE_PROJECT_ID")
 
         self.browserbase_api_key = browserbase_api_key
         self.browserbase_project_id = browserbase_project_id
@@ -228,7 +225,7 @@ def qs(self) -> Querystring:
     @property
     @override
     def auth_headers(self) -> dict[str, str]:
-        return {**self._bb_api_key_auth, **self._bb_project_id_auth, **self._llm_model_api_key_auth}
+        return {**self._bb_api_key_auth, **self._llm_model_api_key_auth}
 
     ### <CUSTOM CODE HANDWRITTEN BY STAGEHAND TEAM (not codegen)>
     @property
@@ -238,8 +235,7 @@ def _bb_api_key_auth(self) -> dict[str, str]:
 
     @property
     def _bb_project_id_auth(self) -> dict[str, str]:
-        browserbase_project_id = self.browserbase_project_id
-        return {"x-bb-project-id": browserbase_project_id} if browserbase_project_id else {}
+        return {}
 
     @property
     def _llm_model_api_key_auth(self) -> dict[str, str]:
@@ -427,16 +423,13 @@ def __init__(
 
         This automatically infers the following arguments from their corresponding environment variables if they are not provided:
         - `browserbase_api_key` from `BROWSERBASE_API_KEY`
-        - `browserbase_project_id` from `BROWSERBASE_PROJECT_ID`
 
         `model_api_key` is intentionally not inferred from any AI provider environment variable.
         Pass it explicitly when you want the SDK to send `x-model-api-key` on remote requests or
         to forward `MODEL_API_KEY` to the local SEA child process.
         """
         if browserbase_api_key is None:
             browserbase_api_key = os.environ.get("BROWSERBASE_API_KEY")
-        if browserbase_project_id is None:
-            browserbase_project_id = os.environ.get("BROWSERBASE_PROJECT_ID")
 
         self.browserbase_api_key = browserbase_api_key
         self.browserbase_project_id = browserbase_project_id
@@ -523,7 +516,7 @@ def qs(self) -> Querystring:
     @property
     @override
     def auth_headers(self) -> dict[str, str]:
-        return {**self._bb_api_key_auth, **self._bb_project_id_auth, **self._llm_model_api_key_auth}
+        return {**self._bb_api_key_auth, **self._llm_model_api_key_auth}
 
     ### <CUSTOM CODE HANDWRITTEN BY STAGEHAND TEAM (not codegen)>
     @property
@@ -533,8 +526,7 @@ def _bb_api_key_auth(self) -> dict[str, str]:
 
     @property
     def _bb_project_id_auth(self) -> dict[str, str]:
-        browserbase_project_id = self.browserbase_project_id
-        return {"x-bb-project-id": browserbase_project_id} if browserbase_project_id else {}
+        return {}
 
     @property
     def _llm_model_api_key_auth(self) -> dict[str, str]:
diff --git a/src/stagehand/_custom/session.py b/src/stagehand/_custom/session.py
diff --git a/tests/test_client.py b/tests/test_client.py
diff --git a/tests/test_local_server.py b/tests/test_local_server.py

Original file line number	Diff line number	Diff line change
`@@ -4,10 +4,8 @@`
`4`	`4`	`from pathlib import Path`
`5`	`5`
`6`	`6`	`REQUIRED_KEYS = {`
`7`		`- "STAGEHAND_API_URL",`
`8`	`7`	`"MODEL_API_KEY",`
`9`	`8`	`"BROWSERBASE_API_KEY",`
`10`		`- "BROWSERBASE_PROJECT_ID",`
`11`	`9`	`}`
`12`	`10`
`13`	`11`