release: v3.11.1 (#219)

* release: v3.11.1

Add bu-2-0-mini-preview to the v2 supported model types and sync the OpenAPI snapshot.

* fix: include latest API metadata fields

Regenerate all API versions from the latest Cloud main specs, expose browser metadata creation and filtering, and support the new v4 run fields.

* fix: address OpenAPI review feedback

* docs: clarify v2 thinking level support

Author: sauravpanda

RUNBOOK.md

@@ -107,4 +107,4 @@ Follow existing patterns in the codebase. Read before writing.
 - **Python SDK type safety**: All resource methods return Pydantic model instances (via `model_validate()`), NOT dicts.
 - **Structured output**: V2 only. Python auto-converts Pydantic models via `output_schema`. TS uses Zod schemas via `{ schema }` option.
 - **Polling**: `await client.run()` polls `tasks.status()` (lightweight). `for await`/`for step in client.stream()` polls full `tasks.get()` and yields new `TaskStepView` steps.
-- **docs/openapi dir**: `task snapshot:save` calls `task docs:sync` which requires `docs/openapi/` to exist. Create it with `mkdir -p docs/openapi` if missing (e.g., on fresh clone).
+- **Docs OpenAPI dirs**: `task snapshot:save` calls `task docs:sync`, which updates both `docs/openapi/` and the `docs/cloud/openapi/` files consumed by Mintlify. Both directories must exist on a fresh clone.

Taskfile.yml

@@ -358,6 +358,9 @@ tasks:
       - cp snapshots/v2.json docs/openapi/v2.json
       - cp snapshots/v3.json docs/openapi/v3.json
       - cp snapshots/v4.json docs/openapi/v4.json
+      - python3 -m json.tool --indent 4 snapshots/v2.json docs/cloud/openapi/v2.json
+      - python3 -m json.tool --indent 4 snapshots/v3.json docs/cloud/openapi/v3.json
+      - python3 -m json.tool --indent 4 snapshots/v4.json docs/cloud/openapi/v4.json
 
   docs:dev:
     desc: Start Mintlify docs dev server

browser-use-node/package.json

@@ -1,6 +1,6 @@
 {
   "name": "browser-use-sdk",
-  "version": "3.11.0",
+  "version": "3.11.1",
   "description": "Official TypeScript SDK for the Browser Use API",
   "repository": {
     "type": "git",

browser-use-node/src/core/http.ts

@@ -54,7 +54,13 @@ export class HttpClient {
     const url = new URL(`${this.baseUrl}${path}`);
     if (options?.query) {
       for (const [key, value] of Object.entries(options.query)) {
-        if (value !== undefined && value !== null) {
+        if (Array.isArray(value)) {
+          for (const item of value) {
+            if (item !== undefined && item !== null) {
+              url.searchParams.append(key, String(item));
+            }
+          }
+        } else if (value !== undefined && value !== null) {
           url.searchParams.set(key, String(value));
         }
       }

browser-use-node/src/generated/v2/types.ts

@@ -772,6 +772,12 @@ export interface components {
              * @description The ID of the project
              */
             projectId: string;
+            /**
+             * Tracing Disabled
+             * @description Whether third-party LLM tracing is disabled for this project
+             * @default false
+             */
+            tracingDisabled: boolean;
         };
         /**
          * BrowserDownloadFile
@@ -893,6 +899,14 @@ export interface components {
              * @description Presigned URL to download the session recording. Only populated on `GET /api/v2/browsers/{id}`; always `null` in list responses.
              */
             recordingUrl?: string | null;
+            /**
+             * Metadata
+             * @description Caller-supplied labels set when the browser was created.
+             * @default {}
+             */
+            metadata: {
+                [key: string]: string;
+            };
         };
         /**
          * BrowserSessionListResponse
@@ -1010,6 +1024,20 @@ export interface components {
              * @description Presigned URL to download the session recording, if recording was enabled. Only populated on GET /api/v2/browsers/{session_id}: the upload starts when the browser stops, so it is never ready in the stop response.
              */
             recordingUrl?: string | null;
+            /**
+             * Recording Available
+             * @description False when a recording can never appear for this session: recording was disabled, or the browser stopped long enough ago that the upload is not coming. Only ever false from proof, so a failed recording lookup leaves it true. Clients polling for `recordingUrl` must stop when this is false.
+             * @default true
+             */
+            recordingAvailable: boolean;
+            /**
+             * Metadata
+             * @description Caller-supplied labels set when the browser was created.
+             * @default {}
+             */
+            metadata: {
+                [key: string]: string;
+            };
         };
         /**
          * CannotDeleteSkillWhileGeneratingError
@@ -1060,6 +1088,13 @@ export interface components {
              * @default us
              */
             proxyCountryCode: components["schemas"]["ProxyCountryCode"] | null;
+            /**
+             * Metadata
+             * @description Labels for this browser. Up to 10 key-value pairs. Filterable on the browsers list and in the dashboard history.
+             */
+            metadata?: {
+                [key: string]: string;
+            } | null;
             /**
              * Timeout
              * @description The timeout for the session in minutes. All users can use up to 240 minutes (4 hours). Browser sessions are charged $0.02/hour.
@@ -1273,7 +1308,7 @@ export interface components {
             thinking: boolean;
             /**
              * Thinking Level
-             * @description Optional model reasoning depth. Omit this field to preserve the model provider default. Supported values depend on the selected model: most supported Claude models and GPT-5.1+ models support disabled/low/medium/high; Gemini Flash models support all four (disabled maps to Gemini's minimal level); Claude Fable 5, earlier GPT-5 models, Gemini 2.5 Pro, o3/o4, and Grok support low/medium/high; Gemini 3.1 Pro supports low/high; GLM supports disabled/high. Unsupported model/level combinations are rejected. API V2 cannot configure GLM or fixed-budget Claude thinking; use API V3 or V4 for those combinations.
+             * @description Optional model reasoning depth. Omit this field to preserve the provider default. API V2 accepts disabled/low/medium/high for browser-use-llm, browser-use-2.0, gemini-2.5-flash, gemini-3-flash-preview, gemini-3.5-flash, gemini-flash-latest, gemini-flash-lite-latest, gpt-5.5, gpt-5.6-sol, gpt-5.6-terra, gpt-5.6-luna, claude-sonnet-5, claude-opus-4-7, claude-opus-4-8, and claude-opus-5; low/medium/high for gemini-2.5-pro, o3, and o4-mini; low/high for gemini-3-pro-preview and gemini-3.1-pro-preview; and disabled only for claude-sonnet-4-20250514, claude-sonnet-4-5-20250929, and claude-opus-4-5-20251101. For browser-use-llm, browser-use-2.0, Gemini 3 Flash, and Gemini 3.5 Flash, disabled maps to Google's minimal thinking level. For Gemini 2.5 Flash and the gemini-flash-latest variants, disabled maps to a zero thinking budget. bu-2-0-mini-preview does not support configurable thinking, so omit thinkingLevel for that model. Other V2 models reject an explicit level. API V2 cannot configure GLM thinking or enable fixed-budget Claude thinking; use API V3 or V4 for those combinations.
              */
             thinkingLevel?: components["schemas"]["ThinkingLevel"] | null;
             /**
@@ -2377,7 +2412,7 @@ export interface components {
          * SupportedLLMs
          * @enum {string}
          */
-        SupportedLLMs: "browser-use-llm" | "browser-use-2.0" | "gpt-4.1" | "gpt-4.1-mini" | "o4-mini" | "o3" | "gpt-5.5" | "gpt-5.6-sol" | "gpt-5.6-terra" | "gpt-5.6-luna" | "gemini-2.5-flash" | "gemini-2.5-pro" | "gemini-3-pro-preview" | "gemini-3.1-pro-preview" | "gemini-3-flash-preview" | "gemini-3.5-flash" | "gemini-flash-latest" | "gemini-flash-lite-latest" | "claude-sonnet-4-20250514" | "claude-sonnet-4-5-20250929" | "claude-sonnet-5" | "claude-opus-4-5-20251101" | "claude-opus-4-7" | "claude-opus-4-8" | "claude-opus-5" | "glm-5.2" | "minimax-m3" | "llama-4-maverick-17b-128e-instruct" | "claude-3-7-sonnet-20250219";
+        SupportedLLMs: "browser-use-llm" | "browser-use-2.0" | "bu-2-0-mini-preview" | "gpt-4.1" | "gpt-4.1-mini" | "o4-mini" | "o3" | "gpt-5.5" | "gpt-5.6-sol" | "gpt-5.6-terra" | "gpt-5.6-luna" | "gemini-2.5-flash" | "gemini-2.5-pro" | "gemini-3-pro-preview" | "gemini-3.1-pro-preview" | "gemini-3-flash-preview" | "gemini-3.5-flash" | "gemini-flash-latest" | "gemini-flash-lite-latest" | "claude-sonnet-4-20250514" | "claude-sonnet-4-5-20250929" | "claude-sonnet-5" | "claude-opus-4-5-20251101" | "claude-opus-4-7" | "claude-opus-4-8" | "claude-opus-5" | "glm-5.2" | "minimax-m3" | "llama-4-maverick-17b-128e-instruct" | "claude-3-7-sonnet-20250219";
         /**
          * TaskCreatedResponse
          * @description Response model for creating a task
@@ -3971,6 +4006,8 @@ export interface operations {
     list_browser_sessions_browsers_get: {
         parameters: {
             query?: {
+                /** @description Only browsers tagged with every one of these terms. `key` matches any value; `key=value` matches exactly. Repeat the param to require more than one (AND). */
+                metadata?: string[] | null;
                 pageSize?: number;
                 pageNumber?: number;
                 filterBy?: components["schemas"]["BrowserSessionStatus"] | null;

browser-use-node/src/generated/v3/types.ts

@@ -489,6 +489,12 @@ export interface components {
              * @description The ID of the project
              */
             projectId: string;
+            /**
+             * Tracing Disabled
+             * @description Whether third-party LLM tracing is disabled for this project
+             * @default false
+             */
+            tracingDisabled: boolean;
         };
         /**
          * BrowserDownloadFile
@@ -610,6 +616,14 @@ export interface components {
              * @description Presigned URL to download the session recording. Only populated on `GET /api/v2/browsers/{id}`; always `null` in list responses.
              */
             recordingUrl?: string | null;
+            /**
+             * Metadata
+             * @description Caller-supplied labels set when the browser was created.
+             * @default {}
+             */
+            metadata: {
+                [key: string]: string;
+            };
         };
         /**
          * BrowserSessionListResponse
@@ -727,6 +741,20 @@ export interface components {
              * @description Presigned URL to download the session recording, if recording was enabled. Only populated on GET /api/v2/browsers/{session_id}: the upload starts when the browser stops, so it is never ready in the stop response.
              */
             recordingUrl?: string | null;
+            /**
+             * Recording Available
+             * @description False when a recording can never appear for this session: recording was disabled, or the browser stopped long enough ago that the upload is not coming. Only ever false from proof, so a failed recording lookup leaves it true. Clients polling for `recordingUrl` must stop when this is false.
+             * @default true
+             */
+            recordingAvailable: boolean;
+            /**
+             * Metadata
+             * @description Caller-supplied labels set when the browser was created.
+             * @default {}
+             */
+            metadata: {
+                [key: string]: string;
+            };
         };
         /**
          * BuAgentSessionStatus
@@ -778,6 +806,13 @@ export interface components {
              * @default us
              */
             proxyCountryCode: components["schemas"]["ProxyCountryCode"] | null;
+            /**
+             * Metadata
+             * @description Labels for this browser. Up to 10 key-value pairs. Filterable on the browsers list and in the dashboard history.
+             */
+            metadata?: {
+                [key: string]: string;
+            } | null;
             /**
              * Timeout
              * @description The timeout for the session in minutes. All users can use up to 240 minutes (4 hours). Browser sessions are charged $0.02/hour.
@@ -1918,6 +1953,8 @@ export interface operations {
     list_browser_sessions_browsers_get: {
         parameters: {
             query?: {
+                /** @description Only browsers tagged with every one of these terms. `key` matches any value; `key=value` matches exactly. Repeat the param to require more than one (AND). */
+                metadata?: string[] | null;
                 pageSize?: number;
                 pageNumber?: number;
                 filterBy?: components["schemas"]["BrowserSessionStatus"] | null;

browser-use-node/src/generated/v4/types.ts

@@ -671,6 +671,14 @@ export interface components {
              * @description Presigned URL to download the session recording. Only populated on `GET /api/v2/browsers/{id}`; always `null` in list responses.
              */
             recordingUrl?: string | null;
+            /**
+             * Metadata
+             * @description Caller-supplied labels set when the browser was created.
+             * @default {}
+             */
+            metadata: {
+                [key: string]: string;
+            };
         };
         /**
          * BrowserSessionListResponse
@@ -788,6 +796,14 @@ export interface components {
              * @description Presigned URL to download the session recording, if recording was enabled. Only populated on GET /api/v2/browsers/{session_id}: the upload starts when the browser stops, so it is never ready in the stop response.
              */
             recordingUrl?: string | null;
+            /**
+             * Metadata
+             * @description Caller-supplied labels set when the browser was created.
+             * @default {}
+             */
+            metadata: {
+                [key: string]: string;
+            };
         };
         /**
          * CreateBrowserSessionRequest
@@ -838,6 +854,13 @@ export interface components {
              * @default false
              */
             enableRecording: boolean;
+            /**
+             * Metadata
+             * @description Labels for this browser. Up to 10 key-value pairs. Filterable on the browsers list and in the dashboard history.
+             */
+            metadata?: {
+                [key: string]: string;
+            } | null;
         };
         /**
          * CustomProxy
@@ -890,6 +913,23 @@ export interface components {
             /** Detail */
             detail?: components["schemas"]["ValidationError"][];
         };
+        /**
+         * InlineSecretSource
+         * @description A value the caller supplies directly with the run.
+         */
+        InlineSecretSource: {
+            /**
+             * Type
+             * @constant
+             */
+            type: "inline";
+            /**
+             * Value
+             * Format: password
+             * @description The secret itself. Limited to 4096 bytes once encoded for encryption; non-ASCII characters cost more than one byte each.
+             */
+            value: string;
+        };
         /**
          * InsufficientCreditsError
          * @description Error response when there are insufficient credits
@@ -1173,8 +1213,19 @@ export interface components {
             /** Workspaceid */
             workspaceId?: string | null;
             browserSettings?: components["schemas"]["RunBrowserSettings"] | null;
+            /**
+             * Agentmail
+             * @description If true, provisions a persistent temporary email inbox (via AgentMail) for the run workspace. The agent receives the email address in its context and can send, receive, read, and reply to email. Set false to disable AgentMail for this run.
+             * @default false
+             */
+            agentmail: boolean;
             /** Attachedfileids */
             attachedFileIds?: string[] | null;
+            /**
+             * Secretbindings
+             * @description Credentials this run may use without ever seeing them. The agent can ask the server to type a binding by alias on one of its allowed domains; it cannot read the value. Bindings are not persisted past the run.
+             */
+            secretBindings?: components["schemas"]["SecretBinding"][] | null;
             judge?: components["schemas"]["RunJudgeSettings"] | null;
             /** Maxcostusd */
             maxCostUsd?: number | string | null;
@@ -1332,6 +1383,31 @@ export interface components {
              */
             updatedAt: string;
         };
+        /**
+         * SecretBinding
+         * @description One credential this run may have typed into a browser field.
+         *
+         *     The value never reaches the agent. It is encrypted at rest, kept out of the
+         *     worker payload, and typed straight into the focused field by the server when
+         *     the agent asks for the alias by name — and only while the page it is typing
+         *     into is on one of `allowedDomains`.
+         *
+         *     Run-scoped: bindings die with the run, so a follow-up run that needs the same
+         *     credential must send it again.
+         */
+        SecretBinding: {
+            /**
+             * Alias
+             * @description Name the agent refers to this secret by, e.g. "github_password".
+             */
+            alias: string;
+            source: components["schemas"]["InlineSecretSource"];
+            /**
+             * Alloweddomains
+             * @description Hosts the secret may be typed into, e.g. ["github.com"]. A host covers its subdomains. Bare hostnames only — no scheme, port, path, or wildcard.
+             */
+            allowedDomains: string[];
+        };
         /**
          * SessionInfo
          * @description Lightweight metadata for one V4 session (its most recent run).
@@ -2660,6 +2736,8 @@ export interface operations {
     list_browser_sessions_browsers_get: {
         parameters: {
             query?: {
+                /** @description Only browsers tagged with every one of these terms. `key` matches any value; `key=value` matches exactly. Repeat the param to require more than one (AND). */
+                metadata?: string[] | null;
                 pageSize?: number;
                 pageNumber?: number;
                 filterBy?: components["schemas"]["BrowserSessionStatus"] | null;

browser-use-node/src/v2/resources/browsers.ts

@@ -10,6 +10,7 @@ type UpdateBrowserSessionRequest = components["schemas"]["UpdateBrowserSessionRe
 type BrowserDownloadListResponse = components["schemas"]["BrowserDownloadListResponse"];
 
 export interface BrowserListParams {
+  metadata?: string[];
   pageSize?: number;
   pageNumber?: number;
   filterBy?: string;
@@ -27,6 +28,9 @@ export class Browsers {
 
   /** Create a new browser session. */
   create(body: CreateBrowserBody = {}): Promise<BrowserSessionItemView> {
+    if (body.metadata && Object.keys(body.metadata).length > 10) {
+      throw new RangeError("metadata supports at most 10 key-value pairs");
+    }
     if (body.proxyCountryCode) {
       body = { ...body, proxyCountryCode: body.proxyCountryCode.toLowerCase() as any };
     }

browser-use-node/src/v3/resources/browsers.ts

@@ -9,6 +9,7 @@ type UpdateBrowserSessionRequest = components["schemas"]["UpdateBrowserSessionRe
 type BrowserDownloadListResponse = components["schemas"]["BrowserDownloadListResponse"];
 
 export interface BrowserListParams {
+  metadata?: string[];
   pageSize?: number;
   pageNumber?: number;
   filterBy?: string;
@@ -26,6 +27,9 @@ export class Browsers {
 
   /** Create a standalone browser session. */
   create(body: Partial<CreateBrowserSessionRequest> = {}): Promise<BrowserSessionItemView> {
+    if (body.metadata && Object.keys(body.metadata).length > 10) {
+      throw new RangeError("metadata supports at most 10 key-value pairs");
+    }
     return this.http.post<BrowserSessionItemView>("/browsers", body);
   }