API Reference

Complete REST API reference for v2 and v3. Endpoints, authentication, SDKs, and request/response examples.

Authentication

All endpoints require an API key via the x-api-key header.

Get your key at cloud.browser-use.com/settings, or set it as BROWSER_USE_API_KEY in your environment.

API Versions

BU Agent API (v3)

Recommended for new projects. Session-based agent API with simplified resource model.

Base URL: https://api.browser-use.com/api/v3

Resources: Sessions, Messages, Files, Workspaces

• Create sessions with optional tasks
• Structured output via JSON Schema
• File upload/download per session
• Persistent workspaces across sessions
• Models: bu-mini (default) and bu-max

Cloud API v2 (Stable)

Full-featured stable API. Task-based with extended resources.

Base URL: https://api.browser-use.com/api/v2

Resources: Tasks, Sessions, Profiles, Browsers, Skills, Marketplace, Billing

• Run tasks with streaming step logs
• Browser profiles for persistent state
• Direct CDP browser access
• Skills: turn websites into API endpoints
• Skill marketplace

SDKs

Both APIs ship in a single package. Install once, import by version.

npm

npm install browser-use-sdk

v3 (TypeScript)

import { BrowserUse } from "browser-use-sdk/v3";

const client = new BrowserUse();
const result = await client.run("Find the top HN post");
console.log(result.output);

Endpoint Overview

BU Agent API (v3)

Method	Path	Description
POST	/sessions	Create a session and/or dispatch a task
GET	/sessions	List sessions
GET	/sessions/{id}	Get session details
DELETE	/sessions/{id}	Delete a session
POST	/sessions/{id}/stop	Stop a session or its running task
GET	/sessions/{id}/messages	Get session message history
GET	/sessions/{id}/files	List files in session workspace
POST	/sessions/{id}/files/upload	Get presigned upload URLs
POST	/workspaces	Create a persistent workspace
GET	/workspaces	List workspaces
GET	/workspaces/{id}	Get workspace details
PATCH	/workspaces/{id}	Update workspace metadata
DELETE	/workspaces/{id}	Delete a workspace
GET	/workspaces/{id}/files	List workspace files
GET	/workspaces/{id}/size	Get workspace storage usage
POST	/workspaces/{id}/files/upload	Upload files to workspace

Cloud API v2 (Stable)

Method	Path	Description
GET	/billing/account	Get account info and credit balance
GET	/tasks	List tasks
POST	/tasks	Create and run a task
GET	/tasks/{id}	Get task details
GET	/tasks/{id}/status	Poll task status
GET	/tasks/{id}/logs	Get task step logs
GET	/sessions	List sessions
POST	/sessions	Create a session
GET	/sessions/{id}	Get session details
POST	/sessions/{id}/purge	Purge session data
GET	/profiles	List browser profiles
POST	/profiles	Create a browser profile
GET	/profiles/{id}	Get profile details
DELETE	/profiles/{id}	Delete a profile
POST	/browsers	Create a CDP browser
GET	/browsers/{id}	Get browser details
POST	/skills	Create a skill
GET	/skills	List skills
GET	/skills/{id}	Get skill details
POST	/skills/{id}/execute	Execute a skill
POST	/skills/{id}/refine	Refine a skill
POST	/skills/{id}/cancel	Cancel skill training
POST	/skills/{id}/rollback	Rollback skill version
GET	/skills/{id}/executions	List skill executions
GET	/skills/{id}/executions/{eid}/output	Get execution output
GET	/marketplace/skills	Browse marketplace skills
GET	/marketplace/skills/{slug}	Get marketplace skill
POST	/marketplace/skills/{id}/clone	Clone a marketplace skill
POST	/marketplace/skills/{id}/execute	Execute a marketplace skill