Open-source Python library for AI browser agents, plus Browser Use Cloud: stealth browsers and a hosted agent API.
Python ai-agentsai-toolsbrowser-agentbrowser-automationbrowser-usecdpcloud-browsercomputer-useheadless-browserllmmcpplaywrightpythonremote-browserstealth-browserweb-automationweb-scraping
docs(cloud): add API v4 skill reference
MagMueller295a57d9579b
diff --git a/skills/cloud/SKILL.md b/skills/cloud/SKILL.mdindex d96b53777..01dfea136 100644--- a/skills/cloud/SKILL.md+++ b/skills/cloud/SKILL.md@@ -3,7 +3,7 @@ name: clouddescription: >Documentation reference for using Browser Use Cloud — the hosted APIand 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 orTypeScript), X-Browser-Use-API-Key authentication, cloud sessions,browser profiles, profile sync, CDP WebSocket connections, stealthbrowsers, 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.mdnew file mode 100644index 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.jsondiff --git a/skills/cloud/references/quickstart.md b/skills/cloud/references/quickstart.mdindex 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.pyindex 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 reimport subprocessimport sysfrom 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')