Skip to content

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

split cloud API reference into v2 and v3, add REST-first coverage

ShawnPana607c6c814e09
diff --git a/skills/browser-use-docs/SKILL.md b/skills/browser-use-docs/SKILL.md
index c52c46fd8..52956e90d 100644
--- a/skills/browser-use-docs/SKILL.md
+++ b/skills/browser-use-docs/SKILL.md
@@ -38,7 +38,8 @@ Read the relevant reference file based on what the user needs.
| Topic | Read |
|-------|------|
| Setup, first task, pricing, FAQ | `references/cloud/quickstart.md` |
-| REST endpoints (v2), SDK methods, v3, schemas | `references/cloud/api.md` |
+| v2 REST API: all 30 endpoints, cURL examples, schemas | `references/cloud/api-v2.md` |
+| v3 BU Agent API: sessions, messages, files, workspaces | `references/cloud/api-v3.md` |
| Sessions, profiles, auth strategies, 1Password | `references/cloud/sessions.md` |
| CDP direct access, Playwright/Puppeteer/Selenium | `references/cloud/browser-api.md` |
| Proxies, webhooks, workspaces, skills, MCP, live view | `references/cloud/features.md` |
diff --git a/skills/browser-use-docs/references/cloud/api-v2.md b/skills/browser-use-docs/references/cloud/api-v2.md
new file mode 100644
index 000000000..107cd367e
--- /dev/null
+++ b/skills/browser-use-docs/references/cloud/api-v2.md
@@ -0,0 +1,321 @@
+# Cloud API v2 (Stable)
+
+Full-featured REST API for tasks, sessions, browsers, profiles, skills, and marketplace.
+
+## Table of Contents
+- [Authentication](#authentication)
+- [Common cURL Examples](#common-curl-examples)
+- [Tasks](#tasks)
+- [Sessions](#sessions)
+- [Browsers (CDP)](#browsers-cdp)
+- [Files](#files)
+- [Profiles](#profiles)
+- [Skills](#skills)
+- [Marketplace](#marketplace)
+- [Billing](#billing)
+- [Pagination](#pagination)
+- [Enums](#enums)
+- [Response Schemas](#response-schemas)
+
+---
+
+## Authentication
+
+- **Header:** `X-Browser-Use-API-Key: <your-key>`
+- **Base URL:** `https://api.browser-use.com/api/v2`
+- **Get key:** https://cloud.browser-use.com/new-api-key
+
+All endpoints require the `X-Browser-Use-API-Key` header.
+
+## Common cURL Examples
+
+### Create a task
+
+```bash
+curl -X POST https://api.browser-use.com/api/v2/tasks \
+ -H "X-Browser-Use-API-Key: $BROWSER_USE_API_KEY" \
+ -H "Content-Type: application/json" \
+ -d '{"task": "Find the top Hacker News post and return title and URL"}'
+```
+
+Response: `{"id": "<task-id>", "sessionId": "<session-id>"}`
+
+### Poll task status
+
+```bash
+curl https://api.browser-use.com/api/v2/tasks/<task-id>/status \
+ -H "X-Browser-Use-API-Key: $BROWSER_USE_API_KEY"
+```
+
+### Get session live URL
+
+```bash
+curl https://api.browser-use.com/api/v2/sessions/<session-id> \
+ -H "X-Browser-Use-API-Key: $BROWSER_USE_API_KEY"
+```
+
+Response includes `liveUrl` — open it to watch the agent work.
+
+### Create a CDP browser
+
+```bash
+curl -X POST https://api.browser-use.com/api/v2/browsers \
+ -H "X-Browser-Use-API-Key: $BROWSER_USE_API_KEY" \
+ -H "Content-Type: application/json" \
+ -d '{"proxyCountryCode": "us", "timeout": 30}'
+```
+
+Response includes `cdpUrl` (WebSocket) and `liveUrl`.
+
+### Stop a session
+
+```bash
+curl -X PATCH https://api.browser-use.com/api/v2/sessions/<session-id> \
+ -H "X-Browser-Use-API-Key: $BROWSER_USE_API_KEY" \
+ -H "Content-Type: application/json" \
+ -d '{"action": "stop"}'
+```
+
+### Upload a file to a session
+
+```bash
+# 1. Get presigned URL
+curl -X POST https://api.browser-use.com/api/v2/files/sessions/<session-id>/presigned-url \
+ -H "X-Browser-Use-API-Key: $BROWSER_USE_API_KEY" \
+ -H "Content-Type: application/json" \
+ -d '{"fileName": "input.pdf", "contentType": "application/pdf", "sizeBytes": 102400}'
+
+# 2. Upload via PUT to the returned URL
+curl -X PUT "<presigned-url>" \
+ -H "Content-Type: application/pdf" \
+ --data-binary @input.pdf
+```
+
+Presigned URLs expire after **120 seconds**. Max file size: **10 MB**.
+
+---
+
+## Tasks
+
+**GET /tasks** — Paginated list with filtering.
+Query: `pageSize?`, `pageNumber?`, `sessionId?` (uuid), `filterBy?` (TaskStatus), `after?` (datetime), `before?` (datetime)
+Response: `{ items: TaskItemView[], totalItems, pageNumber, pageSize }`
+
+**POST /tasks** — Create and run a task. Auto-creates session or uses existing.
+
+| Param | Type | Required | Description |
+|-------|------|----------|-------------|
+| task | string | **yes** | Task prompt (1-50,000 chars) |
+| llm | SupportedLLMs | no | Model (default: browser-use-llm) |
+| startUrl | string | no | Initial URL (saves steps) |
+| maxSteps | integer | no | Max agent steps (default: 100) |
+| structuredOutput | string | no | JSON schema string |
+| sessionId | uuid | no | Run in existing session |
+| metadata | object | no | Key-value metadata (string values) |
+| secrets | object | no | Domain-scoped credentials (string values) |
+| allowedDomains | string[] | no | Restrict navigation |
+| opVaultId | string | no | 1Password vault ID |
+| highlightElements | boolean | no | Highlight interactive elements |
+| flashMode | boolean | no | Fast mode (skip evaluation/thinking) |
+| thinking | boolean | no | Extended reasoning |
+| vision | boolean\|"auto" | no | Screenshot mode |
+| systemPromptExtension | string | no | Append to system prompt |
+| judge | boolean | no | Enable quality judge |
+| skillIds | string[] | no | Skills to use during task |
+
+Response (202): `{ id: uuid, sessionId: uuid }`
+Errors: 400 (session busy/stopped), 404 (session not found), 422 (validation), 429 (rate limit)
+
+**GET /tasks/{task_id}** — Detailed task info with steps and output files.
+Response: TaskView
+
+**GET /tasks/{task_id}/status** — Poll task status (lighter than full GET).
+Response: `{ status: TaskStatus }`
+
+**PATCH /tasks/{task_id}** — Control task execution.
+Body: `{ action: TaskUpdateAction }` — `stop`, `pause`, `resume`, or `stop_task_and_session`
+Response: TaskView. Errors: 404, 422.
+
+**GET /tasks/{task_id}/logs** — Download URL for execution logs.
+Response: `{ downloadUrl: string }`. Errors: 404, 500.
+
+---
+
+## Sessions
+
+**GET /sessions** — Paginated list.
+Query: `pageSize?`, `pageNumber?`, `filterBy?` (SessionStatus)
+
+**POST /sessions** — Create a session.
+Body: `{ profileId?: uuid, proxyCountryCode?: string, startUrl?: string }`
+Response (201): SessionItemView. Errors: 404 (profile not found), 429 (too many concurrent).
+
+**GET /sessions/{id}** — Session details with tasks and share URL.
+Response: SessionView
+
+**PATCH /sessions/{id}** — Stop session and all running tasks.
+Body: `{ action: "stop" }`. Errors: 404, 422.
+
+**POST /sessions/{id}/purge** — Purge session data.
+Response: 200.
+
+**GET /sessions/{id}/public-share** — Get share info.
+Response: ShareView. Errors: 404.
+
+**POST /sessions/{id}/public-share** — Create or return existing share.
+Response (201): ShareView.
+
+**DELETE /sessions/{id}/public-share** — Remove share.
+Response: 204.
+
+---
+
+## Browsers (CDP)
+
+**POST /browsers** — Create a CDP browser session.
+
+| Param | Type | Required | Description |
+|-------|------|----------|-------------|
+| profileId | uuid | no | Browser profile |
+| proxyCountryCode | string | no | Residential proxy (195+ countries) |
+| timeout | integer | no | Session timeout in minutes (max 240) |
+| browserScreenWidth | integer | no | Browser width in pixels |
+| browserScreenHeight | integer | no | Browser height in pixels |
+| customProxy | object | no | `{ host, port, username?, password? }` (HTTP or SOCKS5) |
+
+**Pricing:** $0.05/hour. Billed upfront, proportional refund on stop. Ceil to nearest minute (min 1 min). Free: 15 min max. Paid: 4 hours max.
+
+Response (201): BrowserSessionItemView (includes `cdpUrl` and `liveUrl`).
+Errors: 403 (timeout exceeded for free), 404 (profile not found), 429 (too many concurrent).
+
+**GET /browsers/{id}** — Browser session details.
+
+**PATCH /browsers/{id}** — Stop browser (unused time refunded).
+Body: `{ action: "stop" }`
+
+---
+
+## Files
+
+**POST /files/sessions/{id}/presigned-url** — Get upload URL for session files.
+Body: `{ fileName: string, contentType: UploadContentType, sizeBytes: integer }`
+Response: `{ url: string, method: "POST", fields: {}, fileName: string, expiresIn: integer }`
+Errors: 400 (unsupported type), 404, 500.
+
+**POST /files/browsers/{id}/presigned-url** — Same for browser sessions.
+
+**GET /files/tasks/{task_id}/output-files/{file_id}** — Download URL for task output.
+Response: `{ id: uuid, fileName: string, downloadUrl: string }`
+Errors: 404, 500.
+
+**Upload flow:** Get presigned URL → PUT file with Content-Type header → URL expires in 120s → Max 10 MB.
+
+---
+
+## Profiles
+
+**GET /profiles** — Paginated list. Query: `pageSize?`, `pageNumber?`
+
+**POST /profiles** — Create profile (persistent cookies/localStorage between tasks).
+Body: `{ name?: string }`. Response (201): ProfileView. Error: 402 (subscription needed).
+
+**GET /profiles/{id}** — Profile details.
+
+**DELETE /profiles/{id}** — Permanently delete. Response: 204.
+
+**PATCH /profiles/{id}** — Update name. Body: `{ name?: string }`
+
+---
+
+## Skills
+
+**POST /skills** — Create a skill (turn a website into an API endpoint).
+Body: `{ goal: string, agent_prompt: string, ... }`
+Response: SkillView.
+
+**GET /skills** — List all skills.
+
+**GET /skills/{id}** — Get skill details.
+
+**POST /skills/{id}/execute** — Execute a skill.
+Body: `{ parameters: {} }`
+
+**POST /skills/{id}/refine** — Refine with feedback (free).
+Body: `{ feedback: string }`
+
+**POST /skills/{id}/cancel** — Cancel skill training.
+
+**POST /skills/{id}/rollback** — Rollback to previous version.
+
+**GET /skills/{id}/executions** — List skill executions.
+
+**GET /skills/{id}/executions/{eid}/output** — Get execution output.
+
+---
+
+## Marketplace
+
+**GET /marketplace/skills** — Browse community skills.
+
+**GET /marketplace/skills/{slug}** — Get marketplace skill details.
+
+**POST /marketplace/skills/{id}/clone** — Clone skill to your workspace.
+
+**POST /marketplace/skills/{id}/execute** — Execute a marketplace skill.
+Body: `{ parameters: {} }`
+
+---
+
+## Billing
+
+**GET /billing/account** — Account info and credits.
+Response: `{ name?, monthlyCreditsBalanceUsd, additionalCreditsBalanceUsd, totalCreditsBalanceUsd, rateLimit, planInfo: { planName, subscriptionStatus?, subscriptionId?, subscriptionCurrentPeriodEnd?, subscriptionCanceledAt? }, projectId }`
+
+---
+
+## Pagination
+
+All list endpoints use page-based pagination:
+
+| Param | Type | Description |
+|-------|------|-------------|
+| pageSize | integer | Items per page |
+| pageNumber | integer | Page number (1-based) |
+
+Response includes: `{ items: [...], totalItems, pageNumber, pageSize }`
+
+---
+
+## Enums
+
+| Enum | Values |
+|------|--------|
+| TaskStatus | `started`, `paused`, `finished`, `stopped` |
+| TaskUpdateAction | `stop`, `pause`, `resume`, `stop_task_and_session` |
+| SessionStatus | `active`, `stopped` |
+| BrowserSessionStatus | `active`, `stopped` |
+| ProxyCountryCode | `us`, `uk`, `fr`, `it`, `jp`, `au`, `de`, `fi`, `ca`, `in` (+185 more) |
+| SupportedLLMs | `browser-use-llm`, `gpt-4.1`, `gpt-4.1-mini`, `o4-mini`, `o3`, `gemini-2.5-flash`, `gemini-2.5-pro`, `gemini-flash-latest`, `gemini-flash-lite-latest`, `claude-sonnet-4-20250514`, `gpt-4o`, `gpt-4o-mini`, `llama-4-maverick-17b-128e-instruct`, `claude-3-7-sonnet-20250219` |
+| UploadContentType | `image/jpg`, `image/jpeg`, `image/png`, `image/gif`, `image/webp`, `image/svg+xml`, `application/pdf`, `application/msword`, `application/vnd.openxmlformats-officedocument.wordprocessingml.document`, `application/vnd.ms-excel`, `application/vnd.openxmlformats-officedocument.spreadsheetml.sheet`, `text/plain`, `text/csv`, `text/markdown` |
+
+## Response Schemas
+
+**TaskItemView:** id, sessionId, llm, task, status, startedAt, finishedAt?, metadata?, output?, browserUseVersion?, isSuccess?
+
+**TaskView:** extends TaskItemView + steps: TaskStepView[], outputFiles: FileView[]
+
+**TaskStepView:** number, memory, evaluationPreviousGoal, nextGoal, url, screenshotUrl?, actions: string[]
+
+**FileView:** id, fileName
+
+**SessionItemView:** id, status, liveUrl?, startedAt, finishedAt?
+
+**SessionView:** extends SessionItemView + tasks: TaskItemView[], publicShareUrl?
+
+**BrowserSessionItemView:** id, status, liveUrl?, cdpUrl?, timeoutAt, startedAt, finishedAt?
+
+**ProfileView:** id, name?, lastUsedAt?, createdAt, updatedAt, cookieDomains?: string[]
+
+**ShareView:** shareToken, shareUrl, viewCount, lastViewedAt?
+
+**AccountView:** name?, monthlyCreditsBalanceUsd, additionalCreditsBalanceUsd, totalCreditsBalanceUsd, rateLimit, planInfo, projectId
diff --git a/skills/browser-use-docs/references/cloud/api-v3.md b/skills/browser-use-docs/references/cloud/api-v3.md
new file mode 100644
index 000000000..f1f6ef075
--- /dev/null
+++ b/skills/browser-use-docs/references/cloud/api-v3.md
@@ -0,0 +1,257 @@
+# BU Agent API (v3 — Experimental)
+
+Next-generation agent API. Session-based, token-based billing, workspaces, message history.
+
+## Table of Contents
+- [Authentication](#authentication)
+- [SDK Setup](#sdk-setup)
+- [run() — Execute a Task](#run--execute-a-task)
+- [REST Endpoints](#rest-endpoints)
+- [Sessions](#sessions)
+- [Messages](#messages)
+- [Files](#files)
+- [Workspaces](#workspaces)
+- [Polling & Terminal Statuses](#polling--terminal-statuses)
+- [Error Handling](#error-handling)
+- [Session Statuses & Enums](#session-statuses--enums)
+- [Response Schemas](#response-schemas)
+
+---
+
+## Authentication
+
+- **Header:** `X-Browser-Use-API-Key: <your-key>`
+- **Base URL:** `https://api.browser-use.com/api/v3`
+- **Get key:** https://cloud.browser-use.com/new-api-key
+
+Same package as v2, different import path:
+
+## SDK Setup
+
+```python
+# Python (async — recommended)
+from browser_use_sdk.v3 import AsyncBrowserUse
+client = AsyncBrowserUse() # Uses BROWSER_USE_API_KEY env var
+
+# Python (sync)
+from browser_use_sdk.v3 import BrowserUse
+client = BrowserUse()
+```
+
+```typescript
+// TypeScript
+import { BrowserUse } from "browser-use-sdk/v3";
+const client = new BrowserUse();
+```
+
+Constructor: `api_key`, `base_url`, `timeout` (HTTP request timeout, not polling).
+
+## run() — Execute a Task
+
+```python
+result = await client.run("Find the top HN post")
+print(result.output) # str
+print(result.id) # session UUID
+print(result.status) # e.g. "idle"
+print(result.total_cost_usd) # cost breakdown
+```
+
+### Parameters
+
+| Param | Type | Description |
+|-------|------|-------------|
+| task | string | **Required.** What to do. |
+| model | string | `"bu-mini"` (default, faster/cheaper) or `"bu-max"` (more capable) |
+| output_schema | Pydantic/Zod | Structured output schema |
+| session_id | string | Reuse existing session |
+| keep_alive | boolean | Keep session idle after task (default: false) |
+| max_cost_usd | float | Cost cap in USD; agent stops if exceeded |
+| profile_id | string | Browser profile UUID |
+| proxy_country_code | string | Residential proxy country (195+ countries) |
+| workspace_id | string | Attach workspace for file I/O |
+
+### Structured Output
+
+```python
+from pydantic import BaseModel
+
+class Product(BaseModel):
+ name: str
+ price: float
+
+result = await client.run("Get product info", output_schema=Product)
+print(result.output) # Product instance
+```
+
+### SessionResult Fields
+
+| Field | Type | Description |
+|-------|------|-------------|
+| output | str / BaseModel | Task result (typed if schema provided) |
+| id | uuid | Session ID |
+| status | string | Session status |
+| model | string | bu-mini or bu-max |
+| title | string? | Auto-generated title |
+| live_url | string | Real-time browser monitoring URL |
+| profile_id | string? | Echo of request |
+| proxy_country_code | string? | Echo of request |
+| max_cost_usd | float? | Echo of request |
+| total_input_tokens | int | Input tokens used |
+| total_output_tokens | int | Output tokens used |
+| llm_cost_usd | string | LLM cost |
+| proxy_cost_usd | string | Proxy cost |
+| proxy_used_mb | string | Proxy data used |
+| total_cost_usd | string | Total cost |
+| created_at | datetime | Session creation time |
+| updated_at | datetime | Last update time |
+
+---
+
+## REST Endpoints
+
+All 16 endpoints in the v3 API:
+
+### Sessions
+
+**POST /sessions** — Create session and/or dispatch task.
+Body: `{ task?, model?, session_id?, keep_alive?, max_cost_usd?, profile_id?, proxy_country_code?, output_schema? (JSON Schema dict) }`
+Response: SessionView
+
+**GET /sessions** — List sessions.
+Query: `page?` (int), `page_size?` (int)
+Response: `{ sessions: SessionView[], total, page, page_size }`
+
+**GET /sessions/{id}** — Get session details (includes cost breakdown).
+Response: SessionView
+
+**DELETE /sessions/{id}** — Delete session.
+Response: 204
+
+**POST /sessions/{id}/stop** — Stop session or task.
+Query: `strategy?` — `"session"` (default, destroy sandbox) or `"task"` (stop task only, keep session alive)
+Response: 200
+
+### Messages
+
+**GET /sessions/{id}/messages** — Cursor-paginated message history.
+
+| Param | Type | Description |
+|-------|------|-------------|
+| limit | int | Max messages per page (default 50, max 100) |
+| after | string | Cursor for forward pagination |
+| before | string | Cursor for backward pagination |
+
+Response: `{ messages: [{ id, role: "user"|"assistant", data: string, timestamp }], next_cursor?, has_more: boolean }`
+
+### Files
+
+**GET /sessions/{id}/files** — List files in session workspace.
+
+| Param | Type | Description |
+|-------|------|-------------|
+| include_urls | boolean | Include presigned download URLs (60s expiry) |
+| prefix | string | Filter by path prefix (e.g. `"outputs/"`) |
+| limit | int | Max per page (default 50, max 100) |
+| cursor | string | Pagination cursor |
+
+Response: `{ files: [{ path, size, last_modified, url? }], next_cursor?, has_more }`
+
+**POST /sessions/{id}/files/upload** — Get presigned upload URLs.
+Body: `{ files: [{ name: string, content_type: string }] }`
+Response: `{ files: [{ name, upload_url, path }] }`
+
+Upload via **PUT** to `upload_url` with matching `Content-Type` header. Max **10 files** per batch. Presigned URLs expire in **120 seconds**. Max file size: **10 MB**.
+
+### Workspaces
+
+**POST /workspaces** — Create persistent workspace.
+Body: `{ name?: string, metadata?: object }`
+Response: WorkspaceView
+
+**GET /workspaces** — List workspaces.
+Query: `page?`, `page_size?`
+Response: `{ items: WorkspaceView[], total, page, page_size }`
+
+**GET /workspaces/{id}** — Get workspace details.
+
+**PATCH /workspaces/{id}** — Update workspace.
+Body: `{ name?: string, metadata?: object }`
+
+**DELETE /workspaces/{id}** — Delete workspace and all files (irreversible).
+
+**GET /workspaces/{id}/files** — List workspace files.
+Query: `include_urls?`, `prefix?`, `limit?`, `cursor?`
+Response: same format as session files
+
+**GET /workspaces/{id}/size** — Storage usage.
+Response: `{ size_bytes: int, quota_bytes: int }`
+
+**POST /workspaces/{id}/files/upload** — Upload files to workspace.
+Same format as session file upload.
+
+---
+
+## Polling & Terminal Statuses
+
+`run()` polls automatically:
+- **Interval:** 2 seconds
+- **Timeout:** 300 seconds (5 minutes) — raises `TimeoutError` if exceeded
+- **Terminal statuses:** `idle`, `stopped`, `timed_out`, `error`
+
+### Stop Strategies
+
+| Strategy | Behavior |
+|----------|----------|
+| `"session"` (default) | Destroy sandbox completely |
+| `"task"` | Stop current task, keep session alive for follow-ups |
+
+```python
+await client.sessions.stop(session_id, strategy="task") # keep session
+await client.sessions.stop(session_id, strategy="session") # destroy
+```
+
+---
+
+## Error Handling
+
+```python
+from browser_use_sdk.v3 import AsyncBrowserUse, BrowserUseError
+
+try:
+ result = await client.run("Do something")
+except TimeoutError:
+ print("Polling timed out (5 min default)")
+except BrowserUseError as e:
+ print(f"API error: {e}")
+```
+
+---
+
+## Session Statuses & Enums
+
+| Status | Description |
+|--------|-------------|
+| `created` | Session created, not yet running |
+| `idle` | Task completed, session still alive (keep_alive=True) |
+| `running` | Task in progress |
+| `stopped` | Manually stopped |
+| `timed_out` | Session timed out |
+| `error` | Session errored |
+
+**Models:** `bu-mini` (default, faster/cheaper), `bu-max` (more capable)
+
+## Response Schemas
+
+**SessionView (v3):** id, status, model, title?, live_url, output?, profile_id?, proxy_country_code?, max_cost_usd?, total_input_tokens, total_output_tokens, llm_cost_usd, proxy_cost_usd, proxy_used_mb, total_cost_usd, created_at, updated_at
+
+**MessageView:** id, role ("user"|"assistant"), data (string), timestamp
+
+**FileInfo:** path, size, last_modified, url?
+
+**WorkspaceView:** id, name?, metadata?, created_at, updated_at, size_bytes?
+
+**Key concepts:**
+- **Autonomous execution** — agent decides how many steps (no max_steps param)
+- **Cost control** — `max_cost_usd` caps spending; check `total_cost_usd` on result
+- **Integrations** — agent auto-discovers third-party services (email, Slack, calendars)
+- **File I/O** — upload before task, download from workspace after. Max 10 files per batch, download URLs expire in 60s
diff --git a/skills/browser-use-docs/references/cloud/api.md b/skills/browser-use-docs/references/cloud/api.md
deleted file mode 100644
index a071f1a4d..000000000
--- a/skills/browser-use-docs/references/cloud/api.md
+++ /dev/null
@@ -1,228 +0,0 @@
-# Cloud API Reference (v2 + v3)
-
-## Table of Contents
-- [Authentication](#authentication)
-- [Core Concepts](#core-concepts)
-- [SDK Methods](#sdk-methods)
-- [REST Endpoints (v2)](#rest-endpoints-v2)
-- [V3 API](#v3-api)
-- [Enums](#enums)
-- [Response Schemas](#response-schemas)
-
----
-
-## Authentication
-
-- **Header:** `X-Browser-Use-API-Key: <key>`
-- **Base URL:** `https://api.browser-use.com/api/v2/`
-- **Get key:** https://cloud.browser-use.com/new-api-key
-
-## Core Concepts
-
-- **Session** — Infrastructure container (one Browser, sequential Agents). Max 15 min (free) or 4 hours (paid).
-- **Browser** — Chromium fork, CDP-controllable, stealth-optimized, adblockers built-in.
-- **Agent** — LLM-powered framework for iterative browser steps. Independent judge verifies completion.
-- **Model** — Best: `browser-use-llm` (ChatBrowserUse) — fastest, cheapest, routes to best frontier model.
-- **Browser Profile** — Persistent cookies/localStorage/passwords across sessions. Uploadable from local Chrome.
-- **Task** — Prompt (text + optional files/images) given to Agent.
-- **Workspace** — Persistent file storage across sessions (v3).
-- **Profile Sync** — `export BROWSER_USE_API_KEY=<key> && curl -fsSL https://browser-use.com/profile.sh | sh`
-
-## SDK Methods
-
-### Python
-
-```python
-from browser_use_sdk import BrowserUse
-client = BrowserUse() # BROWSER_USE_API_KEY env var
-
-# Tasks
-result = await client.run("task", llm="browser-use-llm", output_schema=MyModel)
-task = await client.tasks.get(task_id)
-
-# Sessions
-session = await client.sessions.create(profile_id="uuid", proxy_country_code="us")
-session = await client.sessions.get(session_id)
-await client.sessions.stop(session_id)
-share = await client.sessions.create_share(session_id)
-
-# Browsers
-browser = await client.browsers.create(profile_id="uuid", proxy_country_code="us", timeout=60)
-await client.browsers.stop(session_id)
-
-# Profiles
-profiles = await client.profiles.list()
-profile = await client.profiles.create(name="my-profile")
-await client.profiles.update(profile_id, name="new-name")
-await client.profiles.delete(profile_id)
-
-# Files
-url = await client.files.session_url(session_id, file_name="doc.pdf", content_type="application/pdf", size_bytes=1024)
-output = await client.files.task_output(task_id, file_id)
-
-# Billing
-account = await client.billing.account()
-
-# Skills
-skill = await client.skills.create(...)
-result = await client.skills.execute(skill_id, params={})
-await client.skills.refine(skill_id, feedback="...")
-skills = await client.marketplace.list()
-```
-
----
-
-## REST Endpoints (v2)
-
-### Billing
-
-**GET /billing/account** — Account info and credit balances.
-Response: `{ name?, monthlyCreditsBalanceUsd, additionalCreditsBalanceUsd, totalCreditsBalanceUsd, rateLimit, planInfo, projectId }`
-
-### Tasks
-
-**GET /tasks** — Paginated list.
-Params: `pageSize`, `pageNumber`, `sessionId?`, `filterBy?` (TaskStatus), `after?`, `before?`
-
-**POST /tasks** — Create task. Auto-creates session or uses existing.
-
-| Param | Type | Required | Description |
-|-------|------|----------|-------------|
-| task | string | **yes** | Task prompt |
-| llm | SupportedLLMs | no | Model (default: browser-use-llm) |
-| startUrl | string | no | Initial URL |
-| maxSteps | integer | no | Max agent steps |
-| structuredOutput | string | no | JSON schema |
-| sessionId | uuid | no | Existing session |
-| metadata | object | no | Key-value metadata |
-| secrets | object | no | Sensitive key-value data |
-| allowedDomains | string[] | no | Domain restrictions |
-| opVaultId | string | no | 1Password vault ID |
-| highlightElements | boolean | no | Highlight elements |
-| flashMode | boolean | no | Fast mode |
-| thinking | boolean | no | Enable thinking |
-| vision | boolean\|"auto" | no | Vision mode |
-| systemPromptExtension | string | no | Extend system prompt |
-
-Response (202): `{ id, sessionId }`
-Errors: 400 (busy), 404 (not found), 422 (validation), 429 (rate limit)
-
-**GET /tasks/{task_id}** — Detailed info with steps and output files.
-
-**PATCH /tasks/{task_id}** — Control: `{ action: "stop"|"pause"|"resume"|"stop_task_and_session" }`
-
-**GET /tasks/{task_id}/logs** — Download URL: `{ downloadUrl }`
-
-### Sessions
-
-**GET /sessions** — Paginated list. Params: `pageSize`, `pageNumber`, `filterBy?`
-
-**POST /sessions** — Create. Body: `{ profileId?, proxyCountryCode?, startUrl? }`
-Response (201): SessionItemView. Errors: 404, 429.
-
-**GET /sessions/{id}** — Detailed info with tasks.
-
-**PATCH /sessions/{id}** — Stop: `{ action: "stop" }`
-
-**GET /sessions/{id}/public-share** — Share info.
-
-**POST /sessions/{id}/public-share** — Create share (201).
-
-**DELETE /sessions/{id}/public-share** — Remove share (204).
-
-### Browsers
-
-**GET /browsers** — Paginated list.
-
-**POST /browsers** — Create. Body: `{ profileId?, proxyCountryCode?, timeout? }`
-Pricing: $0.05/hr upfront, refund on stop, min 1 min. Free: 15 min max, Paid: 4 hrs.
-Response (201): BrowserSessionItemView (has `cdpUrl`, `liveUrl`). Errors: 403, 404, 429.
-
-**GET /browsers/{id}** — Detailed info.
-
-**PATCH /browsers/{id}** — Stop: `{ action: "stop" }` (unused time refunded).
-
-### Files
-
-**POST /files/sessions/{id}/presigned-url** — Upload URL.
-Body: `{ fileName, contentType, sizeBytes }`. Response: `{ url, method:"POST", fields, fileName, expiresIn }`
-
-**POST /files/browsers/{id}/presigned-url** — Same for browser sessions.
-
-**GET /files/tasks/{task_id}/output-files/{file_id}** — Download URL: `{ id, fileName, downloadUrl }`
-
-### Profiles
-
-**GET /profiles** — Paginated list.
-
-**POST /profiles** — Create: `{ name? }`. Error: 402 (subscription needed).
-
-**GET /profiles/{id}** — Details.
-
-**DELETE /profiles/{id}** — Delete (204).
-
-**PATCH /profiles/{id}** — Update: `{ name? }`
-
----
-
-## V3 API
-
-Experimental next-gen agent. Token-based billing, workspaces, session messages.
-
-```python
-from browser_use_sdk.v3 import AsyncBrowserUse
-
-client = AsyncBrowserUse()
-
-# Run task
-result = await client.run("Find top HN post")
-
-# Sessions with messages
-session = await client.sessions.create(task="...", keep_alive=True)
-messages = await client.sessions.messages(session.id)
-
-# Workspaces (persistent files)
-workspace = await client.workspaces.create(name="my-workspace")
-await client.sessions.upload_files(session.id, workspace_id=workspace.id, files=[...])
-files = await client.sessions.files(session.id)
-
-# Cleanup
-await client.sessions.stop(session.id)
-await client.close()
-```
-
----
-
-## Enums
-
-| Enum | Values |
-|------|--------|
-| TaskStatus | started, paused, finished, stopped |
-| TaskUpdateAction | stop, pause, resume, stop_task_and_session |
-| SessionStatus | active, stopped |
-| BrowserSessionStatus | active, stopped |
-| ProxyCountryCode | us, uk, fr, it, jp, au, de, fi, ca, in (+185 more) |
-| SupportedLLMs | browser-use-llm, gpt-4.1, gpt-4.1-mini, o4-mini, o3, gemini-2.5-flash, gemini-2.5-pro, gemini-flash-latest, gemini-flash-lite-latest, claude-sonnet-4-20250514, gpt-4o, gpt-4o-mini, llama-4-maverick-17b-128e-instruct, claude-3-7-sonnet-20250219 |
-| UploadContentType | image/jpg, jpeg, png, gif, webp, svg+xml, application/pdf, msword, vnd.openxmlformats*.document, vnd.ms-excel, vnd.openxmlformats*.sheet, text/plain, csv, markdown |
-
-## Response Schemas
-
-**TaskItemView:** id, sessionId, llm, task, status, startedAt, finishedAt?, metadata?, output?, browserUseVersion?, isSuccess?
-
-**TaskView:** extends TaskItemView + steps: TaskStepView[], outputFiles: FileView[]
-
-**TaskStepView:** number, memory, evaluationPreviousGoal, nextGoal, url, screenshotUrl?, actions[]
-
-**FileView:** id, fileName
-
-**SessionItemView:** id, status, liveUrl?, startedAt, finishedAt?
-
-**SessionView:** extends SessionItemView + tasks: TaskItemView[], publicShareUrl?
-
-**BrowserSessionItemView:** id, status, liveUrl?, cdpUrl?, timeoutAt, startedAt, finishedAt?
-
-**ProfileView:** id, name?, lastUsedAt?, createdAt, updatedAt, cookieDomains?[]
-
-**ShareView:** shareToken, shareUrl, viewCount, lastViewedAt?
-
-**AccountView:** name?, monthlyCreditsBalanceUsd, additionalCreditsBalanceUsd, totalCreditsBalanceUsd, rateLimit, planInfo, projectId
diff --git a/skills/browser-use-docs/references/cloud/browser-api.md b/skills/browser-use-docs/references/cloud/browser-api.md
index 755539ab1..063aff66d 100644
--- a/skills/browser-use-docs/references/cloud/browser-api.md
+++ b/skills/browser-use-docs/references/cloud/browser-api.md
@@ -13,10 +13,15 @@ Connect directly to Browser Use stealth browsers via Chrome DevTools Protocol.
## WebSocket Connection
-Single URL with all config as query params. Browser auto-stops on disconnect.
+Single URL with all config as query params. Browser **auto-starts on connect** and **auto-stops on disconnect** — no REST calls needed to start or stop.
```
-wss://connect.browser-use.com/?apiKey=YOUR_KEY&proxyCountryCode=us&timeout=30
+wss://connect.browser-use.com?apiKey=YOUR_KEY&proxyCountryCode=us&timeout=30
+```
+
+CDP discovery is also available over HTTPS (for tools that use HTTP auto-discovery):
+```
+https://connect.browser-use.com/json/version?apiKey=YOUR_API_KEY
```
### Query Parameters