release: 3.20.0

Author: stainless-app[bot]

.release-please-manifest.json

@@ -1,3 +1,3 @@
 {
-  ".": "3.19.3"
+  ".": "3.20.0"
 }

.stats.yml

@@ -1,4 +1,4 @@
 configured_endpoints: 8
-openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/browserbase%2Fstagehand-b969ce378479c79ee64c05127c0ed6c6ce2edbee017ecd037242fb618a5ebc9f.yml
-openapi_spec_hash: a24aabaa5214effb679808b7f2be0ad4
-config_hash: a962ae71493deb11a1c903256fb25386
+openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/browserbase/stagehand-6f6bfb81d092f30a5e2005328c97d61b9ea36132bb19e9e79e55294b9534ce20.yml
+openapi_spec_hash: f3fc1e3688a38dc2c28f7178f7d534e5
+config_hash: 1fb12ae9b478488bc1e56bfbdc210b01

CHANGELOG.md

@@ -1,5 +1,37 @@
 # Changelog
 
+## 3.20.0 (2026-05-06)
+
+Full Changelog: [v3.19.3...v3.20.0](https://github.com/browserbase/stagehand-java/compare/v3.19.3...v3.20.0)
+
+### Features
+
+* [feat]: add `ignoreSelectors` to `extract()` ([ab25ab1](https://github.com/browserbase/stagehand-java/commit/ab25ab1c249cb689ea39cb2e3970927d616ddefd))
+* [STG-1798] feat: support Browserbase verified sessions ([59ee151](https://github.com/browserbase/stagehand-java/commit/59ee1516eb17d6b8474b12d2722ff4627fa2557c))
+* [STG-1808] Deprecate Browserbase project ID ([4700262](https://github.com/browserbase/stagehand-java/commit/47002629082ee0a602b2b4739be7b7b605337040))
+* Bedrock auth passthrough ([7d5037a](https://github.com/browserbase/stagehand-java/commit/7d5037abacedbee829f0fe238565ed81c211eba9))
+* **client:** more robust error parsing ([c7d063a](https://github.com/browserbase/stagehand-java/commit/c7d063aa513f6b62ca7e95d0031a5018516a114f))
+* **client:** support proxy authentication ([7572751](https://github.com/browserbase/stagehand-java/commit/7572751215d53839a93f8d0fc1dd303994813aca))
+* remove experimental requirement on agent variables ([#2079](https://github.com/browserbase/stagehand-java/issues/2079)) ([1a0a44c](https://github.com/browserbase/stagehand-java/commit/1a0a44c9d3d95f32df91a72ee3d1f42c7634aa6e))
+* Revert "[STG-1573] Add providerOptions for extensible model auth ([#1822](https://github.com/browserbase/stagehand-java/issues/1822))" ([c337e61](https://github.com/browserbase/stagehand-java/commit/c337e61dd9b2cc366bceec0e7119874acdc3b069))
+* support setting headers via env ([ab67768](https://github.com/browserbase/stagehand-java/commit/ab677681d664219c7f006c72b49b723922280a26))
+
+
+### Performance Improvements
+
+* **client:** create one json mapper ([5f27b6b](https://github.com/browserbase/stagehand-java/commit/5f27b6bdce009ea88970dea1ce52cd1d29169c98))
+
+
+### Chores
+
+* remove duplicated dokka setup ([25bb04d](https://github.com/browserbase/stagehand-java/commit/25bb04d02c26e2929adf6b2e1ea0d37b2843880f))
+
+
+### Documentation
+
+* clarify forwards compat behavior ([0463c65](https://github.com/browserbase/stagehand-java/commit/0463c65a44d0b165f9a6f850d0096cb6af207b97))
+* remove bad semicolon ([b3e9df1](https://github.com/browserbase/stagehand-java/commit/b3e9df1d14045e2a4ebc18bb16b75453856e6311))
+
 ## 3.19.3 (2026-04-03)
 
 Full Changelog: [v3.18.0...v3.19.3](https://github.com/browserbase/stagehand-java/compare/v3.18.0...v3.19.3)

README.md

@@ -2,8 +2,8 @@
 
 <!-- x-release-please-start-version -->
 
-[![Maven Central](https://img.shields.io/maven-central/v/com.browserbase.api/stagehand-java)](https://central.sonatype.com/artifact/com.browserbase.api/stagehand-java/3.19.3)
-[![javadoc](https://javadoc.io/badge2/com.browserbase.api/stagehand-java/3.19.3/javadoc.svg)](https://javadoc.io/doc/com.browserbase.api/stagehand-java/3.19.3)
+[![Maven Central](https://img.shields.io/maven-central/v/com.browserbase.api/stagehand-java)](https://central.sonatype.com/artifact/com.browserbase.api/stagehand-java/3.20.0)
+[![javadoc](https://javadoc.io/badge2/com.browserbase.api/stagehand-java/3.20.0/javadoc.svg)](https://javadoc.io/doc/com.browserbase.api/stagehand-java/3.20.0)
 
 <!-- x-release-please-end -->
 
@@ -85,7 +85,7 @@ Most existing browser automation tools either require you to write low-level cod
 ### Gradle
 
 ```kotlin
-implementation("com.browserbase.api:stagehand-java:3.19.3")
+implementation("com.browserbase.api:stagehand-java:3.20.0")
 ```
 
 ### Maven
@@ -94,7 +94,7 @@ implementation("com.browserbase.api:stagehand-java:3.19.3")
 <dependency>
   <groupId>com.browserbase.api</groupId>
   <artifactId>stagehand-java</artifactId>
-  <version>3.19.3</version>
+  <version>3.20.0</version>
 </dependency>
 ```
 
@@ -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_BASE_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_BASE_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` | true     | -                                         |
 | `modelApiKey`          | `stagehand.modelApiKey`          | `MODEL_API_KEY`          | true     | -                                         |
-| `baseUrl`              | `stagehand.baseUrl`              | `STAGEHAND_BASE_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_BASE_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_BASE_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()
@@ -432,7 +430,7 @@ client.async().sessions().actStreaming(params)
     .subscribe(chunk -> {
         System.out.println(chunk);
     })
-    .onCompleteFuture();
+    .onCompleteFuture()
     .whenComplete((unused, error) -> {
         if (error != null) {
             System.out.println("Something went wrong!");
@@ -636,6 +634,21 @@ StagehandClient client = StagehandOkHttpClient.builder()
     .build();
 ```
 
+If the proxy responds with `407 Proxy Authentication Required`, supply credentials by also configuring `proxyAuthenticator`:
+
+```java
+import com.browserbase.api.client.StagehandClient;
+import com.browserbase.api.client.okhttp.StagehandOkHttpClient;
+import com.browserbase.api.core.http.ProxyAuthenticator;
+
+StagehandClient client = StagehandOkHttpClient.builder()
+    .fromEnv()
+    .proxy(...)
+    // Or a custom implementation of `ProxyAuthenticator`.
+    .proxyAuthenticator(ProxyAuthenticator.basic("username", "password"))
+    .build();
+```
+
 ### Connection pooling
 
 To customize the underlying OkHttp connection pool, configure the client using the `maxIdleConnections` and `keepAliveDuration` methods:
@@ -873,7 +886,9 @@ In rare cases, the API may return a response that doesn't match the expected typ
 
 By default, the SDK will not throw an exception in this case. It will throw [`StagehandInvalidDataException`](stagehand-java-core/src/main/kotlin/com/browserbase/api/errors/StagehandInvalidDataException.kt) only if you directly access the property.
 
-If you would prefer to check that the response is completely well-typed upfront, then either call `validate()`:
+Validating the response is _not_ forwards compatible with new types from the API for existing fields.
+
+If you would still prefer to check that the response is completely well-typed upfront, then either call `validate()`:
 
 ```java
 import com.browserbase.api.models.sessions.SessionActResponse;

build.gradle.kts

@@ -8,7 +8,7 @@ repositories {
 
 allprojects {
     group = "com.browserbase.api"
-    version = "3.19.3" // x-release-please-version
+    version = "3.20.0" // x-release-please-version
 }
 
 subprojects {
@@ -21,7 +21,6 @@ subprojects {
         group = "Verification"
         description = "Verifies all source files are formatted."
     }
-    apply(plugin = "org.jetbrains.dokka")
 }
 
 subprojects {

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