Skip to content

Open-source Python library for AI browser agents, plus Browser Use Cloud: stealth browsers and a hosted agent API.

docs(cloud): add API v4 skill reference

MagMueller295a57d9579b
diff --git a/skills/cloud/SKILL.md b/skills/cloud/SKILL.md
index d96b53777..01dfea136 100644
--- a/skills/cloud/SKILL.md
+++ b/skills/cloud/SKILL.md
@@ -3,7 +3,7 @@ name: cloud
description: >
Documentation reference for using Browser Use Cloud — the hosted API
and SDK for browser automation. Use this skill whenever the user needs
- help with the Cloud REST API (v2 or v3), browser-use-sdk (Python or
+ help with the Cloud REST API (v2, v3, or v4), browser-use-sdk (Python or
TypeScript), X-Browser-Use-API-Key authentication, cloud sessions,
browser profiles, profile sync, CDP WebSocket connections, stealth
browsers, residential proxies, CAPTCHA handling, webhooks, workspaces,
@@ -25,7 +25,8 @@ Read the relevant file based on what the user needs.
| Topic | Read |
|-------|------|
-| Setup, first task, pricing, FAQ | `references/quickstart.md` |
+| Current v4 setup, first run, sessions, workspaces, browsers | `references/api-v4.md` |
+| Legacy v2 setup, pricing, FAQ | `references/quickstart.md` |
| v2 REST API: all 30 endpoints, cURL examples, schemas | `references/api-v2.md` |
| v3 BU Agent API: sessions, messages, files, workspaces | `references/api-v3.md` |
| Sessions, profiles, auth strategies, 1Password | `references/sessions.md` |
@@ -43,13 +44,17 @@ Read the relevant file based on what the user needs.
## Critical Notes
-- Cloud API base URL: `https://api.browser-use.com/api/v2/` (v2) or `https://api.browser-use.com/api/v3` (v3)
+- Use v4 for new hosted-agent integrations. Keep v2 or v3 only when maintaining an existing integration or using a resource not yet wrapped by the v4 SDK.
+- Cloud API base URL: `https://api.browser-use.com/api/v2/` (v2), `https://api.browser-use.com/api/v3` (v3), or `https://api.browser-use.com/api/v4` (v4)
- Auth header: `X-Browser-Use-API-Key: <key>`
- Get API key: https://cloud.browser-use.com/new-api-key
- Set env var: `BROWSER_USE_API_KEY=<key>`
- Cloud SDK: `uv pip install browser-use-sdk` (Python) or `npm install browser-use-sdk` (TypeScript)
- Python v2: `from browser_use_sdk import AsyncBrowserUse`
- Python v3: `from browser_use_sdk.v3 import AsyncBrowserUse`
+- Python v4: `from browser_use_sdk.v4 import BrowserUse` or `AsyncBrowserUse`
- TypeScript v2: `import { BrowserUse } from "browser-use-sdk"`
- TypeScript v3: `import { BrowserUse } from "browser-use-sdk/v3"`
+- TypeScript v4: `import { BrowserUse } from "browser-use-sdk/v4"`
+- Browser management is available at the v4 REST `/browsers` resource, but its SDK wrapper still uses the explicit v3 namespace. Always stop a browser explicitly; closing CDP does not stop billing.
- CDP WebSocket: `wss://connect.browser-use.com?apiKey=KEY&proxyCountryCode=us`
diff --git a/skills/cloud/references/api-v4.md b/skills/cloud/references/api-v4.md
new file mode 100644
index 000000000..64180974f
--- /dev/null
+++ b/skills/cloud/references/api-v4.md
@@ -0,0 +1,134 @@
+# API v4: Hosted Agent Runs
+
+Use v4 for new hosted-agent integrations. A **run** is one agent turn, a
+**session** is the conversation shared by follow-up runs, and a **workspace**
+is the persistent filesystem that can be reused across sessions.
+
+- REST base: `https://api.browser-use.com/api/v4`
+- Auth header: `X-Browser-Use-API-Key: <key>`
+- Python: `from browser_use_sdk.v4 import BrowserUse`
+- TypeScript: `import { BrowserUse } from "browser-use-sdk/v4"`
+
+## First Run
+
+### Python
+
+```python
+from browser_use_sdk.v4 import BrowserUse
+
+with BrowserUse() as client:
+ created = client.runs.create("Find the top Hacker News story")
+ run = client.runs.wait_for_completion(created.id)
+ print(run.result)
+```
+
+### TypeScript
+
+```typescript
+import { BrowserUse } from "browser-use-sdk/v4";
+
+const client = new BrowserUse();
+const created = await client.runs.create({
+ task: "Find the top Hacker News story",
+});
+const run = await client.runs.waitForCompletion(created.id);
+console.log(run.result);
+```
+
+### REST
+
+Create the run, poll the lightweight status route, then fetch the full result
+only after the status is `completed`, `failed`, or `cancelled`:
+
+```bash
+curl -X POST https://api.browser-use.com/api/v4/runs \
+ -H "X-Browser-Use-API-Key: $BROWSER_USE_API_KEY" \
+ -H "Content-Type: application/json" \
+ -d '{"task":"Find the top Hacker News story"}'
+
+curl https://api.browser-use.com/api/v4/runs/RUN_ID/status \
+ -H "X-Browser-Use-API-Key: $BROWSER_USE_API_KEY"
+
+curl https://api.browser-use.com/api/v4/runs/RUN_ID \
+ -H "X-Browser-Use-API-Key: $BROWSER_USE_API_KEY"
+```
+
+Do not repeatedly poll the full run resource. The SDK wait helpers use the
+status route and fetch the full run once at the end.
+
+## Sessions and Follow-ups
+
+Every new run implicitly creates a session. Reuse its session ID to continue
+the same conversation:
+
+```python
+from browser_use_sdk.v4 import BrowserUse
+
+with BrowserUse() as client:
+ first = client.runs.create("Open Hacker News")
+ client.runs.wait_for_completion(first.id)
+
+ follow_up = client.runs.create(
+ "Now summarize the top story",
+ session_id=first.session_id,
+ )
+ result = client.runs.wait_for_completion(follow_up.id)
+```
+
+For a busy session, queue a next turn with
+`client.sessions.send_message(session_id, text)`. Pass `interrupt=True` only
+when the active run should be cancelled so the new message can start. The REST
+equivalent is `POST /sessions/{session_id}/queue` with `text` and optional
+`interrupt`.
+
+## Workspaces and Files
+
+A workspace persists files independently of a session. Upload a local file,
+then attach its returned file ID to a run:
+
+```python
+from browser_use_sdk.v4 import BrowserUse
+
+with BrowserUse() as client:
+ workspace = client.workspaces.create(name="research")
+ uploaded = client.workspaces.upload(workspace.id, "people.csv")
+
+ run = client.runs.create(
+ "Read the CSV and save a report",
+ workspace_id=workspace.id,
+ attached_file_ids=[uploaded[0].id],
+ )
+```
+
+Attachments are run-scoped. Reusing a workspace does not automatically attach
+every file in it. List generated files with `client.workspaces.files(workspace.id)`;
+presigned download URLs expire after 60 seconds, so request them immediately
+before downloading.
+
+## Direct Browser Control
+
+The v4 REST API can create a browser for direct CDP control:
+
+1. `POST /browsers` returns the browser `id` (its session ID) and `cdpUrl`.
+2. Connect Browser Use, Playwright, Puppeteer, or Selenium to `cdpUrl`.
+3. `PATCH /browsers/{session_id}` with `{"action":"stop"}` stops the browser;
+ replace `session_id` with the returned `id`.
+
+Closing a CDP client does not stop the cloud browser or its billing. The
+browser-management SDK wrapper currently uses the explicit v3 namespace; use
+`browser_use_sdk.v3` or `browser-use-sdk/v3` for that resource, or call the v4
+REST endpoint directly.
+
+## Resource Map
+
+| Resource | Common operations |
+|----------|-------------------|
+| Runs | create, list, get, status, events, cancel, attachments |
+| Sessions | list, get, queue messages, inspect/remove queued messages, purge |
+| Workspaces | create, get, update, archive, size, upload/list/delete files |
+| Browsers (REST) | create, inspect, stop |
+
+For the complete current contract, use:
+
+- Docs: https://docs.browser-use.com/cloud/api-v4
+- OpenAPI: https://docs.browser-use.com/cloud/openapi/v4.json
diff --git a/skills/cloud/references/quickstart.md b/skills/cloud/references/quickstart.md
index 69a322af4..2f6c0c6a3 100644
--- a/skills/cloud/references/quickstart.md
+++ b/skills/cloud/references/quickstart.md
@@ -1,5 +1,9 @@
# Cloud Quickstart, Pricing & FAQ
+> This page keeps the v2 quickstart for existing integrations. For a new
+> hosted-agent integration, use [API v4](api-v4.md). V4 is the current API and
+> SDK path.
+
## Table of Contents
- [Overview](#overview)
- [Setup](#setup)
diff --git a/tests/ci/test_browser_use_skill_install_docs.py b/tests/ci/test_browser_use_skill_install_docs.py
index 41da21a81..754e991ef 100644
--- a/tests/ci/test_browser_use_skill_install_docs.py
+++ b/tests/ci/test_browser_use_skill_install_docs.py
@@ -1,4 +1,5 @@
import os
+import re
import subprocess
import sys
from pathlib import Path
@@ -57,6 +58,16 @@ def test_docs_install_browser_use_skill_from_package_alias():
assert 'raw.githubusercontent.com/browser-use/browser-harness/main/SKILL.md' not in readme
+def test_cloud_v4_reference_scopes_workspace_file_listing():
+ api_v4 = (ROOT / 'skills' / 'cloud' / 'references' / 'api-v4.md').read_text(encoding='utf-8')
+
+ assert 'client.workspaces.files(workspace.id)' in api_v4
+ assert 'client.workspaces.files()' not in api_v4
+ python_examples = re.findall(r'```python\n(.*?)```', api_v4, flags=re.DOTALL)
+ assert python_examples
+ assert all('BrowserUse' in example for example in python_examples if 'client.' in example)
+
+
def test_browser_use_cli_installs_browser_harness_package_skill(tmp_path):
bin_dir = _fake_browser_harness_tools(tmp_path, '---\nname: browser-harness\n---\n\n# Browser Harness\n')