fix: address OpenAPI review feedback

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/src/v2/resources/browsers.ts

@@ -28,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

@@ -27,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);
   }
 

browser-use-node/tests/browsers.test.ts

@@ -24,4 +24,17 @@ describe.each([
       metadata: ["team", "env=test"],
     });
   });
+
+  it("rejects more than 10 metadata entries", () => {
+    const http = { post: vi.fn() };
+    const browsers = new Browsers(http as any);
+    const metadata = Object.fromEntries(
+      Array.from({ length: 11 }, (_, index) => [`key-${index}`, `value-${index}`]),
+    );
+
+    expect(() => browsers.create({ metadata })).toThrow(
+      "metadata supports at most 10 key-value pairs",
+    );
+    expect(http.post).not.toHaveBeenCalled();
+  });
 });

browser-use-python/src/browser_use_sdk/v2/resources/browsers.py

@@ -27,6 +27,9 @@ def _build_create_body(
     enable_recording: bool | None = None,
     **extra: Any,
 ) -> dict[str, Any]:
+    if metadata is not None and len(metadata) > 10:
+        raise ValueError("metadata supports at most 10 key-value pairs")
+
     body: dict[str, Any] = {}
     if profile_id is not None:
         body["profileId"] = profile_id

browser-use-python/src/browser_use_sdk/v3/resources/browsers.py

@@ -16,6 +16,11 @@
     from uuid import UUID
 
 
+def _validate_metadata(metadata: dict[str, str] | None) -> None:
+    if metadata is not None and len(metadata) > 10:
+        raise ValueError("metadata supports at most 10 key-value pairs")
+
+
 class Browsers:
     def __init__(self, http: SyncHttpClient) -> None:
         self._http = http
@@ -35,6 +40,7 @@ def create(
         **extra: Any,
     ) -> BrowserSessionItemView:
         """Create a standalone browser session."""
+        _validate_metadata(metadata)
         body: dict[str, Any] = {}
         if profile_id is not None:
             body["profileId"] = profile_id
@@ -144,6 +150,7 @@ async def create(
         **extra: Any,
     ) -> BrowserSessionItemView:
         """Create a standalone browser session."""
+        _validate_metadata(metadata)
         body: dict[str, Any] = {}
         if profile_id is not None:
             body["profileId"] = profile_id

browser-use-python/tests/test_browsers.py

@@ -51,3 +51,15 @@ def test_browser_metadata_create_and_list(browser_cls: type[Any]) -> None:
         "agentSessionId": None,
         "metadata": ["team", "env=test"],
     }
+
+
+@pytest.mark.parametrize("browser_cls", [V2Browsers, V3Browsers])
+def test_browser_metadata_rejects_more_than_10_entries(browser_cls: type[Any]) -> None:
+    http = FakeHttp()
+    browsers = browser_cls(http)
+    metadata = {f"key-{index}": f"value-{index}" for index in range(11)}
+
+    with pytest.raises(ValueError, match="metadata supports at most 10"):
+        browsers.create(metadata=metadata)
+
+    assert http.calls == []

docs/cloud/openapi/v2.json

@@ -192,7 +192,7 @@
                     "Tasks"
                 ],
                 "summary": "Create Task",
-                "description": "Create and start a new task.\n\nYou can either:\n1. Start a new task without a sessionId (auto-creates a session with US proxy by default).\n   Note: Tasks without a sessionId are one-off tasks that automatically close the session\n   upon completion (keep_alive=false). Use sessionSettings to configure the auto-created\n   session (e.g. proxyCountryCode, profileId, screen dimensions).\n2. Start a new task in an existing session (reuse for follow-up tasks or custom configuration)\n\nNote: Without sessionSettings, a US proxy is enabled by default. Providing sessionSettings\noverrides defaults — proxy is only enabled if proxyCountryCode is set. For full control over\nsession configuration (e.g. keep_alive), create a session first via POST /sessions with your\ndesired settings, then pass that sessionId when creating tasks.",
+                "description": "Create and start a new task.\n\nYou can either:\n1. Start a new task without a sessionId (auto-creates a session with US proxy by default).\n   Note: Tasks without a sessionId are one-off tasks that automatically close the session\n   upon completion (keep_alive=false). Use sessionSettings to configure the auto-created\n   session (e.g. proxyCountryCode, profileId, screen dimensions).\n2. Start a new task in an existing session (reuse for follow-up tasks or custom configuration)\n\nNote: Without sessionSettings, a US proxy is enabled by default. Providing sessionSettings\noverrides defaults \u2014 proxy is only enabled if proxyCountryCode is set. For full control over\nsession configuration (e.g. keep_alive), create a session first via POST /sessions with your\ndesired settings, then pass that sessionId when creating tasks.",
                 "operationId": "create_task_tasks_post",
                 "security": [
                     {
@@ -1651,14 +1651,35 @@
                     "Browsers"
                 ],
                 "summary": "List Browser Sessions",
-                "description": "Get paginated list of browser sessions with optional status filtering.",
+                "description": "Get paginated list of browser sessions with optional status filtering.\n\nList responses intentionally omit per-session presigned recording URLs\n(`recording_url` is always `null` here). Each recording URL requires a\nsynchronous boto3 SigV4 signing call (plus an S3 HEAD) that holds the GIL\nand blocks the event loop. With page_size up to the max this CPU-pegs the\nworker and starves the DB pool, cascading into pool exhaustion across the\nfleet. Clients should fetch the recording URL on demand via\n`GET /api/v2/browsers/{id}`, which signs exactly one URL for a single\nsession. Mirrors the v3 sessions list fix (ENG-4904, PR #4621).",
                 "operationId": "list_browser_sessions_browsers_get",
                 "security": [
                     {
                         "APIKeyHeader": []
                     }
                 ],
                 "parameters": [
+                    {
+                        "name": "metadata",
+                        "in": "query",
+                        "required": false,
+                        "schema": {
+                            "anyOf": [
+                                {
+                                    "type": "array",
+                                    "items": {
+                                        "type": "string"
+                                    }
+                                },
+                                {
+                                    "type": "null"
+                                }
+                            ],
+                            "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).",
+                            "title": "Metadata"
+                        },
+                        "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)."
+                    },
                     {
                         "name": "pageSize",
                         "in": "query",
@@ -1697,6 +1718,23 @@
                             ],
                             "title": "Filterby"
                         }
+                    },
+                    {
+                        "name": "agentSessionId",
+                        "in": "query",
+                        "required": false,
+                        "schema": {
+                            "anyOf": [
+                                {
+                                    "type": "string",
+                                    "format": "uuid"
+                                },
+                                {
+                                    "type": "null"
+                                }
+                            ],
+                            "title": "Agentsessionid"
+                        }
                     }
                 ],
                 "responses": {
@@ -3330,6 +3368,12 @@
                         "format": "uuid",
                         "title": "Project ID",
                         "description": "The ID of the project"
+                    },
+                    "tracingDisabled": {
+                        "type": "boolean",
+                        "title": "Tracing Disabled",
+                        "description": "Whether third-party LLM tracing is disabled for this project",
+                        "default": false
                     }
                 },
                 "type": "object",
@@ -3526,7 +3570,16 @@
                             }
                         ],
                         "title": "Recording URL",
-                        "description": "Presigned URL to download the session recording (available after session ends, if recording was enabled)"
+                        "description": "Presigned URL to download the session recording. Only populated on `GET /api/v2/browsers/{id}`; always `null` in list responses."
+                    },
+                    "metadata": {
+                        "additionalProperties": {
+                            "type": "string"
+                        },
+                        "type": "object",
+                        "title": "Metadata",
+                        "description": "Caller-supplied labels set when the browser was created.",
+                        "default": {}
                     }
                 },
                 "type": "object",
@@ -3698,7 +3751,22 @@
                             }
                         ],
                         "title": "Recording URL",
-                        "description": "Presigned URL to download the session recording (available after session ends, if recording was enabled)"
+                        "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."
+                    },
+                    "recordingAvailable": {
+                        "type": "boolean",
+                        "title": "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
+                    },
+                    "metadata": {
+                        "additionalProperties": {
+                            "type": "string"
+                        },
+                        "type": "object",
+                        "title": "Metadata",
+                        "description": "Caller-supplied labels set when the browser was created.",
+                        "default": {}
                     }
                 },
                 "type": "object",
@@ -3775,6 +3843,22 @@
                         "description": "Country code for proxy location. Defaults to US. Set to null to disable proxy.",
                         "default": "us"
                     },
+                    "metadata": {
+                        "anyOf": [
+                            {
+                                "additionalProperties": {
+                                    "type": "string"
+                                },
+                                "maxProperties": 10,
+                                "type": "object"
+                            },
+                            {
+                                "type": "null"
+                            }
+                        ],
+                        "title": "Metadata",
+                        "description": "Labels for this browser. Up to 10 key-value pairs. Filterable on the browsers list and in the dashboard history."
+                    },
                     "timeout": {
                         "type": "integer",
                         "title": "Timeout",
@@ -4165,7 +4249,7 @@
                             }
                         ],
                         "title": "Thinking Level",
-                        "description": "Optional model reasoning depth. Omit this field to preserve the provider default. 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. Other V2 models reject an explicit level. V2 cannot configure GLM thinking or enable fixed-budget Claude thinking."
+                        "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."
                     },
                     "vision": {
                         "anyOf": [
@@ -4183,7 +4267,7 @@
                     },
                     "systemPromptExtension": {
                         "type": "string",
-                        "maxLength": 2000,
+                        "maxLength": 10000,
                         "title": "System Prompt Extension",
                         "description": "Optional extension to the agent system prompt.",
                         "default": ""
@@ -5040,6 +5124,7 @@
                     "cf",
                     "cg",
                     "ch",
+                    "ci",
                     "ck",
                     "cl",
                     "cm",
@@ -6187,6 +6272,7 @@
                 "enum": [
                     "browser-use-llm",
                     "browser-use-2.0",
+                    "bu-2-0-mini-preview",
                     "gpt-4.1",
                     "gpt-4.1-mini",
                     "o4-mini",