STG-1808: Deprecate browserbase project ID (#38)

monadoid · samfinton · web-flow · commit 1bb5d8accd86 · 2026-05-06T21:55:04.000+02:00
* Deprecate browserbase project ID

* Fix CI formatting

---------

Co-authored-by: samfinton &lt;samfinton@samLaptopm5.galaxus.box&gt;
diff --git a/README.md b/README.md
@@ -115,10 +115,8 @@ Multiregion support: see `stagehand-java-example/src/main/java/com/stagehand/api
 
 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
@@ -258,8 +256,8 @@ Configure the client using system properties or environment variables:
 import com.browserbase.api.client.StagehandClient;
 import com.browserbase.api.client.okhttp.StagehandOkHttpClient;
 
-// Configures using the `stagehand.browserbaseApiKey`, `stagehand.browserbaseProjectId`, `stagehand.modelApiKey` and `stagehand.baseUrl` system properties
-// Or configures using the `BROWSERBASE_API_KEY`, `BROWSERBASE_PROJECT_ID`, `MODEL_API_KEY` and `STAGEHAND_API_URL` environment variables
+// Configures using the `stagehand.browserbaseApiKey`, `stagehand.modelApiKey` and `stagehand.baseUrl` system properties
+// Or configures using the `BROWSERBASE_API_KEY`, `MODEL_API_KEY` and `STAGEHAND_API_URL` environment variables
 StagehandClient client = StagehandOkHttpClient.fromEnv();
 ```
 
@@ -271,7 +269,6 @@ import com.browserbase.api.client.okhttp.StagehandOkHttpClient;
 
 StagehandClient client = StagehandOkHttpClient.builder()
     .browserbaseApiKey("My Browserbase API Key")
-    .browserbaseProjectId("My Browserbase Project ID")
     .modelApiKey("My Model API Key")
     .build();
 ```
@@ -283,8 +280,8 @@ import com.browserbase.api.client.StagehandClient;
 import com.browserbase.api.client.okhttp.StagehandOkHttpClient;
 
 StagehandClient client = StagehandOkHttpClient.builder()
-    // Configures using the `stagehand.browserbaseApiKey`, `stagehand.browserbaseProjectId`, `stagehand.modelApiKey` and `stagehand.baseUrl` system properties
-    // Or configures using the `BROWSERBASE_API_KEY`, `BROWSERBASE_PROJECT_ID`, `MODEL_API_KEY` and `STAGEHAND_API_URL` environment variables
+    // Configures using the `stagehand.browserbaseApiKey`, `stagehand.modelApiKey` and `stagehand.baseUrl` system properties
+    // Or configures using the `BROWSERBASE_API_KEY`, `MODEL_API_KEY` and `STAGEHAND_API_URL` environment variables
     .fromEnv()
     .browserbaseApiKey("My Browserbase API Key")
     .build();
@@ -295,9 +292,10 @@ See this table for the available options:
 | Setter                 | System property                  | Environment variable     | Required | Default value                             |
 | ---------------------- | -------------------------------- | ------------------------ | -------- | ----------------------------------------- |
 | `browserbaseApiKey`    | `stagehand.browserbaseApiKey`    | `BROWSERBASE_API_KEY`    | true     | -                                         |
-| `browserbaseProjectId` | `stagehand.browserbaseProjectId` | `BROWSERBASE_PROJECT_ID` | false    | -                                         |
 | `modelApiKey`          | `stagehand.modelApiKey`          | `MODEL_API_KEY`          | true     | -                                         |
-| `baseUrl`              | `stagehand.baseUrl`              | `STAGEHAND_API_URL`     | true     | `"https://api.stagehand.browserbase.com"` |
+| `baseUrl`              | `stagehand.baseUrl`              | `STAGEHAND_API_URL`      | false    | `"https://api.stagehand.browserbase.com"` |
+
+`browserbaseProjectId` is deprecated, accepted for backwards compatibility, and ignored. `STAGEHAND_BASE_URL` remains supported as a deprecated fallback when `STAGEHAND_API_URL` is unset.
 
 System properties take precedence over environment variables.
 
@@ -345,8 +343,8 @@ import com.browserbase.api.models.sessions.SessionActParams;
 import com.browserbase.api.models.sessions.SessionActResponse;
 import java.util.concurrent.CompletableFuture;
 
-// Configures using the `stagehand.browserbaseApiKey`, `stagehand.browserbaseProjectId`, `stagehand.modelApiKey` and `stagehand.baseUrl` system properties
-// Or configures using the `BROWSERBASE_API_KEY`, `BROWSERBASE_PROJECT_ID`, `MODEL_API_KEY` and `STAGEHAND_API_URL` environment variables
+// Configures using the `stagehand.browserbaseApiKey`, `stagehand.modelApiKey` and `stagehand.baseUrl` system properties
+// Or configures using the `BROWSERBASE_API_KEY`, `MODEL_API_KEY` and `STAGEHAND_API_URL` environment variables
 StagehandClient client = StagehandOkHttpClient.fromEnv();
 
 SessionActParams params = SessionActParams.builder()
@@ -365,8 +363,8 @@ import com.browserbase.api.models.sessions.SessionActParams;
 import com.browserbase.api.models.sessions.SessionActResponse;
 import java.util.concurrent.CompletableFuture;
 
-// Configures using the `stagehand.browserbaseApiKey`, `stagehand.browserbaseProjectId`, `stagehand.modelApiKey` and `stagehand.baseUrl` system properties
-// Or configures using the `BROWSERBASE_API_KEY`, `BROWSERBASE_PROJECT_ID`, `MODEL_API_KEY` and `STAGEHAND_API_URL` environment variables
+// Configures using the `stagehand.browserbaseApiKey`, `stagehand.modelApiKey` and `stagehand.baseUrl` system properties
+// Or configures using the `BROWSERBASE_API_KEY`, `MODEL_API_KEY` and `STAGEHAND_API_URL` environment variables
 StagehandClientAsync client = StagehandOkHttpClientAsync.fromEnv();
 
 SessionActParams params = SessionActParams.builder()
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/stagehand-java-client-okhttp/src/main/kotlin/com/browserbase/api/client/okhttp/OkHttpClient.kt b/stagehand-java-client-okhttp/src/main/kotlin/com/browserbase/api/client/okhttp/OkHttpClient.kt
@@ -103,7 +103,6 @@ internal constructor(@JvmSynthetic internal val okHttpClient: okhttp3.OkHttpClie
             clientBuilder.addNetworkInterceptor(
                 HttpLoggingInterceptor().setLevel(logLevel).apply {
                     redactHeader("x-bb-api-key")
-                    redactHeader("x-bb-project-id")
                     redactHeader("x-model-api-key")
                 }
             )
diff --git a/stagehand-java-core/src/main/kotlin/com/browserbase/api/core/ClientOptions.kt b/stagehand-java-core/src/main/kotlin/com/browserbase/api/core/ClientOptions.kt
@@ -327,7 +327,7 @@ private constructor(
 
         /**
          * Deprecated. Browserbase API keys are now project-scoped, so this value is no longer
-         * required.
+         * required. Accepted for backwards compatibility; it is ignored.
          */
         fun browserbaseProjectId(browserbaseProjectId: String?) = apply {
             this.browserbaseProjectId = browserbaseProjectId
@@ -430,12 +430,11 @@ private constructor(
          *
          * See this table for the available options:
          *
-         * |Setter                |System property                 |Environment variable    |Required|Default value                            |
-         * |----------------------|--------------------------------|------------------------|--------|-----------------------------------------|
-         * |`browserbaseApiKey`   |`stagehand.browserbaseApiKey`   |`BROWSERBASE_API_KEY`   |true    |-                                        |
-         * |`browserbaseProjectId`|`stagehand.browserbaseProjectId`|`BROWSERBASE_PROJECT_ID`|false   |-                                        |
-         * |`modelApiKey`         |`stagehand.modelApiKey`         |`MODEL_API_KEY`         |true    |-                                        |
-         * |`baseUrl`             |`stagehand.baseUrl`             |`STAGEHAND_API_URL`     |true    |`"https://api.stagehand.browserbase.com"`|
+         * |Setter             |System property              |Environment variable |Required|Default value                            |
+         * |-------------------|-----------------------------|---------------------|--------|-----------------------------------------|
+         * |`browserbaseApiKey`|`stagehand.browserbaseApiKey`|`BROWSERBASE_API_KEY`|true    |-                                        |
+         * |`modelApiKey`      |`stagehand.modelApiKey`      |`MODEL_API_KEY`      |true    |-                                        |
+         * |`baseUrl`          |`stagehand.baseUrl`          |`STAGEHAND_API_URL`  |false   |`"https://api.stagehand.browserbase.com"`|
          *
          * System properties take precedence over environment variables.
          */
@@ -448,9 +447,6 @@ private constructor(
                 ?.let { baseUrl(it) }
             (System.getProperty("stagehand.browserbaseApiKey") ?: getEnv("BROWSERBASE_API_KEY"))
                 ?.let { browserbaseApiKey(it) }
-            (System.getProperty("stagehand.browserbaseProjectId")
-                    ?: getEnv("BROWSERBASE_PROJECT_ID"))
-                ?.let { browserbaseProjectId(it) }
             (System.getProperty("stagehand.modelApiKey") ?: getEnv("MODEL_API_KEY"))?.let {
                 modelApiKey(it)
             }
@@ -520,11 +516,6 @@ private constructor(
                     headers.replace("x-bb-api-key", it)
                 }
             }
-            browserbaseProjectId?.let {
-                if (!it.isEmpty()) {
-                    headers.replace("x-bb-project-id", it)
-                }
-            }
             modelApiKey.let {
                 if (!it.isEmpty()) {
                     headers.replace("x-model-api-key", it)
diff --git a/stagehand-java-core/src/test/kotlin/com/browserbase/api/core/ClientOptionsTest.kt b/stagehand-java-core/src/test/kotlin/com/browserbase/api/core/ClientOptionsTest.kt
@@ -47,6 +47,19 @@ internal class ClientOptionsTest {
             .containsExactly("another My Browserbase API Key")
     }
 
+    @Test
+    fun browserbaseProjectId_isNoOp() {
+        val clientOptions =
+            ClientOptions.builder()
+                .httpClient(httpClient)
+                .browserbaseApiKey("My Browserbase API Key")
+                .browserbaseProjectId("My Browserbase Project ID")
+                .modelApiKey("My Model API Key")
+                .build()
+
+        assertThat(clientOptions.headers.values("x-bb-project-id")).isEmpty()
+    }
+
     @Test
     fun fromEnv_prefersStagehandApiUrl() {
         val env =
diff --git a/stagehand-java-example/src/main/java/com/stagehand/api/example/Env.java b/stagehand-java-example/src/main/java/com/stagehand/api/example/Env.java
@@ -7,7 +7,7 @@
 
 final class Env {
     private static final String[] REQUIRED_KEYS = {
-        "STAGEHAND_API_URL", "MODEL_API_KEY", "BROWSERBASE_API_KEY", "BROWSERBASE_PROJECT_ID",
+        "MODEL_API_KEY", "BROWSERBASE_API_KEY",
     };
 
     private Env() {}
@@ -34,15 +34,17 @@ static void load() {
                     case "BROWSERBASE_API_KEY":
                         System.setProperty("stagehand.browserbaseApiKey", value);
                         break;
-                    case "BROWSERBASE_PROJECT_ID":
-                        System.setProperty("stagehand.browserbaseProjectId", value);
-                        break;
                     case "MODEL_API_KEY":
                         System.setProperty("stagehand.modelApiKey", value);
                         break;
                     case "STAGEHAND_API_URL":
                         System.setProperty("stagehand.baseUrl", value);
                         break;
+                    case "STAGEHAND_BASE_URL":
+                        if (System.getProperty("stagehand.baseUrl") == null) {
+                            System.setProperty("stagehand.baseUrl", value);
+                        }
+                        break;
                     default:
                         break;
                 }
@@ -67,8 +69,6 @@ private static String mapKey(String key) {
         switch (key) {
             case "BROWSERBASE_API_KEY":
                 return "stagehand.browserbaseApiKey";
-            case "BROWSERBASE_PROJECT_ID":
-                return "stagehand.browserbaseProjectId";
             case "MODEL_API_KEY":
                 return "stagehand.modelApiKey";
             case "STAGEHAND_API_URL":
diff --git a/stagehand-java-example/src/main/java/com/stagehand/api/example/LocalServerMultiregionBrowserExample.java b/stagehand-java-example/src/main/java/com/stagehand/api/example/LocalServerMultiregionBrowserExample.java
@@ -33,9 +33,8 @@
  *
  * Required environment variables:
  * - BROWSERBASE_API_KEY: Your Browserbase API key
- * - BROWSERBASE_PROJECT_ID: Your Browserbase project ID
  * - MODEL_API_KEY: Your OpenAI API key
- * - STAGEHAND_API_URL: Local Stagehand server base URL
+ * Optional: STAGEHAND_API_URL or STAGEHAND_BASE_URL for a local Stagehand server base URL
  */
 public class LocalServerMultiregionBrowserExample {
     public static void main(String[] args) {
@@ -49,7 +48,6 @@ public static void main(String[] args) {
                                 .type(SessionStartParams.Browser.Type.BROWSERBASE)
                                 .build())
                         .browserbaseSessionCreateParams(SessionStartParams.BrowserbaseSessionCreateParams.builder()
-                                .projectId(System.getProperty("stagehand.browserbaseProjectId"))
                                 .region(SessionStartParams.BrowserbaseSessionCreateParams.Region.EU_CENTRAL_1)
                                 .build())
                         .build());
diff --git a/stagehand-java-example/src/main/java/com/stagehand/api/example/Main.java b/stagehand-java-example/src/main/java/com/stagehand/api/example/Main.java
@@ -24,14 +24,13 @@
  *
  * Required environment variables:
  * - BROWSERBASE_API_KEY: Your Browserbase API key
- * - BROWSERBASE_PROJECT_ID: Your Browserbase project ID
  * - MODEL_API_KEY: Your OpenAI API key
  */
 public class Main {
     public static void main(String[] args) {
         Env.load();
         // Create client using environment variables
-        // BROWSERBASE_API_KEY, BROWSERBASE_PROJECT_ID, MODEL_API_KEY
+        // BROWSERBASE_API_KEY and MODEL_API_KEY
         StagehandClient client = StagehandOkHttpClient.builder().fromEnv().build();
 
         // Start a new browser session
diff --git a/stagehand-java-example/src/main/java/com/stagehand/api/example/RemoteBrowserPlaywrightExample.java b/stagehand-java-example/src/main/java/com/stagehand/api/example/RemoteBrowserPlaywrightExample.java
@@ -33,14 +33,13 @@
  *
  * Required environment variables:
  * - BROWSERBASE_API_KEY: Your Browserbase API key
- * - BROWSERBASE_PROJECT_ID: Your Browserbase project ID
  * - MODEL_API_KEY: Your OpenAI API key
  */
 public class RemoteBrowserPlaywrightExample {
     public static void main(String[] args) {
         Env.load();
         // Create client using environment variables
-        // BROWSERBASE_API_KEY, BROWSERBASE_PROJECT_ID, MODEL_API_KEY
+        // BROWSERBASE_API_KEY and MODEL_API_KEY
         StagehandClient client = StagehandOkHttpClient.builder().fromEnv().build();
 
         // Start a new remote Browserbase session (Playwright)
@@ -50,9 +49,6 @@ public static void main(String[] args) {
                         .browser(SessionStartParams.Browser.builder()
                                 .type(SessionStartParams.Browser.Type.BROWSERBASE)
                                 .build())
-                        .browserbaseSessionCreateParams(SessionStartParams.BrowserbaseSessionCreateParams.builder()
-                                .projectId(System.getProperty("stagehand.browserbaseProjectId"))
-                                .build())
                         .build());
 
         String sessionId = startResponse.data().sessionId();

Original file line number	Diff line number	Diff line change
`@@ -103,7 +103,6 @@ internal constructor(@JvmSynthetic internal val okHttpClient: okhttp3.OkHttpClie`
`103`	`103`	`clientBuilder.addNetworkInterceptor(`
`104`	`104`	`HttpLoggingInterceptor().setLevel(logLevel).apply {`
`105`	`105`	`redactHeader("x-bb-api-key")`
`106`		`- redactHeader("x-bb-project-id")`
`107`	`106`	`redactHeader("x-model-api-key")`
`108`	`107`	`}`
`109`	`108`	`)`