feat: browser_pools: add start_url config (KERNEL-1217 PR 2)

Author: stainless-app[bot]

.stats.yml

@@ -1,4 +1,4 @@
 configured_endpoints: 112
-openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/kernel/kernel-b51c72a040c8dfea9c0693de6631feabfffe42922d5feb60b4ac0ee5c83bb8f4.yml
-openapi_spec_hash: 8b671cfe4debe8d9ad7c39ba5b0eaf6d
+openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/kernel/kernel-7d2d29d7598105d50e5118e0bc5ac654361a92cb95555705dbd1d236848e1456.yml
+openapi_spec_hash: 10002eae793e08f81932239bbc72b503
 config_hash: 08d55086449943a8fec212b870061a3f

src/resources/browser-pools.ts

@@ -237,6 +237,15 @@ export namespace BrowserPool {
      */
     proxy_id?: string;
 
+    /**
+     * Optional URL to navigate to when a new browser is warmed into the pool.
+     * Best-effort: failures to navigate do not fail pool fill. Only applied to
+     * newly-warmed browsers — browsers reused via release/acquire keep whatever URL
+     * the previous lease left them on. Accepts any URL Chromium can resolve, including
+     * chrome:// pages.
+     */
+    start_url?: string;
+
     /**
      * If true, launches the browser in stealth mode to reduce detection by anti-bot
      * mechanisms.
@@ -353,6 +362,12 @@ export interface BrowserPoolAcquireResponse {
    */
   proxy_id?: string;
 
+  /**
+   * URL the session was asked to navigate to on creation, if any. Recorded for
+   * debugging — navigation is best-effort and may have failed.
+   */
+  start_url?: string;
+
   /**
    * Session usage metrics.
    */
@@ -430,6 +445,15 @@ export interface BrowserPoolCreateParams {
    */
   proxy_id?: string;
 
+  /**
+   * Optional URL to navigate to when a new browser is warmed into the pool.
+   * Best-effort: failures to navigate do not fail pool fill. Only applied to
+   * newly-warmed browsers — browsers reused via release/acquire keep whatever URL
+   * the previous lease left them on. Accepts any URL Chromium can resolve, including
+   * chrome:// pages.
+   */
+  start_url?: string;
+
   /**
    * If true, launches the browser in stealth mode to reduce detection by anti-bot
    * mechanisms.
@@ -520,6 +544,15 @@ export interface BrowserPoolUpdateParams {
    */
   proxy_id?: string;
 
+  /**
+   * Optional URL to navigate to when a new browser is warmed into the pool.
+   * Best-effort: failures to navigate do not fail pool fill. Only applied to
+   * newly-warmed browsers — browsers reused via release/acquire keep whatever URL
+   * the previous lease left them on. Accepts any URL Chromium can resolve, including
+   * chrome:// pages.
+   */
+  start_url?: string;
+
   /**
    * If true, launches the browser in stealth mode to reduce detection by anti-bot
    * mechanisms.

src/resources/browsers/browsers.ts

@@ -392,6 +392,12 @@ export interface BrowserCreateResponse {
    */
   proxy_id?: string;
 
+  /**
+   * URL the session was asked to navigate to on creation, if any. Recorded for
+   * debugging — navigation is best-effort and may have failed.
+   */
+  start_url?: string;
+
   /**
    * Session usage metrics.
    */
@@ -498,6 +504,12 @@ export interface BrowserRetrieveResponse {
    */
   proxy_id?: string;
 
+  /**
+   * URL the session was asked to navigate to on creation, if any. Recorded for
+   * debugging — navigation is best-effort and may have failed.
+   */
+  start_url?: string;
+
   /**
    * Session usage metrics.
    */
@@ -604,6 +616,12 @@ export interface BrowserUpdateResponse {
    */
   proxy_id?: string;
 
+  /**
+   * URL the session was asked to navigate to on creation, if any. Recorded for
+   * debugging — navigation is best-effort and may have failed.
+   */
+  start_url?: string;
+
   /**
    * Session usage metrics.
    */
@@ -710,6 +728,12 @@ export interface BrowserListResponse {
    */
   proxy_id?: string;
 
+  /**
+   * URL the session was asked to navigate to on creation, if any. Recorded for
+   * debugging — navigation is best-effort and may have failed.
+   */
+  start_url?: string;
+
   /**
    * Session usage metrics.
    */
@@ -805,6 +829,15 @@ export interface BrowserCreateParams {
    */
   proxy_id?: string;
 
+  /**
+   * Optional URL to navigate to immediately after the browser is created.
+   * Best-effort: failures to navigate do not fail browser creation. Any pre-existing
+   * tabs are reduced to a single tab which is then navigated. Accepts any URL
+   * Chromium can resolve, including chrome:// pages. Ignored when reusing an
+   * existing persistent session.
+   */
+  start_url?: string;
+
   /**
    * If true, launches the browser in stealth mode to reduce detection by anti-bot
    * mechanisms.

src/resources/invocations.ts

@@ -501,6 +501,12 @@ export namespace InvocationListBrowsersResponse {
      */
     proxy_id?: string;
 
+    /**
+     * URL the session was asked to navigate to on creation, if any. Recorded for
+     * debugging — navigation is best-effort and may have failed.
+     */
+    start_url?: string;
+
     /**
      * Session usage metrics.
      */

tests/api-resources/browser-pools.test.ts

@@ -36,6 +36,7 @@ describe('resource browserPools', () => {
         save_changes: true,
       },
       proxy_id: 'proxy_id',
+      start_url: 'https://example.com',
       stealth: true,
       timeout_seconds: 60,
       viewport: {
@@ -87,6 +88,7 @@ describe('resource browserPools', () => {
         save_changes: true,
       },
       proxy_id: 'proxy_id',
+      start_url: 'https://example.com',
       stealth: true,
       timeout_seconds: 60,
       viewport: {

tests/api-resources/browsers/browsers.test.ts

@@ -38,6 +38,7 @@ describe('resource browsers', () => {
             save_changes: true,
           },
           proxy_id: 'proxy_id',
+          start_url: 'https://example.com',
           stealth: true,
           timeout_seconds: 10,
           viewport: {