{ "openapi": "3.1.0", "info": { "title": "Browser Use Public API v3", "summary": "Browser Use session-based agent API (v3)", "version": "3.0.0" }, "servers": [ { "url": "https://api.browser-use.com/api/v3", "description": "Production server" } ], "paths": { "/sessions": { "post": { "tags": [ "Sessions" ], "summary": "Create Session", "description": "Create a session and/or dispatch a task.\n\n- Without session_id, without task: creates a new idle session (e.g. for file uploads).\n- Without session_id, with task: creates a new session and dispatches the task.\n- With session_id, with task: dispatches the task to an existing idle session.\n- With session_id, without task: 422 \u2014 task is required when targeting an existing session.\n\nIf keep_alive is false (default), the session auto-stops when the task finishes.\nIf keep_alive is true, the session stays idle after the task, ready for follow-ups.", "operationId": "create_session_sessions_post", "security": [ { "APIKeyHeader": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RunTaskRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SessionResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "get": { "tags": [ "Sessions" ], "summary": "List Sessions", "description": "List sessions for the authenticated project.\n\nList responses intentionally omit per-session presigned URLs\n(`screenshot_url`, `recording_urls`). Each presign is a synchronous boto3\nSigV4 signing call that holds the GIL and blocks the event loop. With\npage_size up to 100 this CPU-pegs the worker and starves the DB pool,\ncascading into pool exhaustion across the fleet. Clients should fetch\nthese URLs on demand via `GET /api/v3/sessions/{id}`, which signs exactly\none screenshot URL plus any recording URLs for a single session.", "operationId": "list_sessions_sessions_get", "security": [ { "APIKeyHeader": [] } ], "parameters": [ { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "description": "Page number (1-indexed).", "default": 1, "title": "Page" }, "description": "Page number (1-indexed)." }, { "name": "page_size", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 100, "minimum": 1, "description": "Number of sessions per page (max 100).", "default": 20, "title": "Page Size" }, "description": "Number of sessions per page (max 100)." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SessionListResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/sessions/{session_id}": { "get": { "tags": [ "Sessions" ], "summary": "Get Session", "description": "Get session details. Use this to poll for task completion and output.", "operationId": "get_session_sessions__session_id__get", "security": [ { "APIKeyHeader": [] } ], "parameters": [ { "name": "session_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "title": "Session Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SessionResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "delete": { "tags": [ "Sessions" ], "summary": "Delete Session", "description": "Soft-delete a session. Stops the sandbox first if still running.", "operationId": "delete_session_sessions__session_id__delete", "security": [ { "APIKeyHeader": [] } ], "parameters": [ { "name": "session_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "title": "Session Id" } } ], "responses": { "204": { "description": "Successful Response" }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/sessions/{session_id}/stop": { "post": { "tags": [ "Sessions" ], "summary": "Stop Session", "description": "Stop a session or the running task.\n\n- strategy=session (default): destroy sandbox entirely, session \u2192 stopped.\n- strategy=task: stop the running query, session stays alive (\u2192 idle).", "operationId": "stop_session_sessions__session_id__stop_post", "security": [ { "APIKeyHeader": [] } ], "parameters": [ { "name": "session_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "title": "Session Id" } } ], "requestBody": { "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/StopSessionRequest" }, { "type": "null" } ], "title": "Body" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SessionResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/sessions/{session_id}/messages": { "get": { "tags": [ "Sessions" ], "summary": "List Session Messages", "description": "Return messages for a session with cursor-based pagination (chronological order).", "operationId": "list_session_messages_sessions__session_id__messages_get", "security": [ { "APIKeyHeader": [] } ], "parameters": [ { "name": "session_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "title": "Session Id" } }, { "name": "after", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "description": "Cursor: return messages after this message ID", "title": "After" }, "description": "Cursor: return messages after this message ID" }, { "name": "before", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "description": "Cursor: return messages before this message ID", "title": "Before" }, "description": "Cursor: return messages before this message ID" }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 100, "minimum": 1, "description": "Maximum number of messages to return (max 100).", "default": 10, "title": "Limit" }, "description": "Maximum number of messages to return (max 100)." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessageListResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/browsers": { "get": { "tags": [ "Browsers" ], "summary": "List Browser Sessions", "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", "required": false, "schema": { "type": "integer", "maximum": 100, "minimum": 1, "default": 10, "title": "Pagesize" } }, { "name": "pageNumber", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "default": 1, "title": "Pagenumber" } }, { "name": "filterBy", "in": "query", "required": false, "schema": { "anyOf": [ { "$ref": "#/components/schemas/BrowserSessionStatus" }, { "type": "null" } ], "title": "Filterby" } }, { "name": "agentSessionId", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "title": "Agentsessionid" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BrowserSessionListResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "post": { "tags": [ "Browsers" ], "summary": "Create Browser Session", "description": "Create a new browser session.\n\n**Pricing:** Browser sessions are charged at $0.02/hour for all users.\n\nThe full rate is charged upfront when the session starts.\nWhen you stop the session, any unused time is automatically refunded proportionally.\n\nBilling is rounded up to the minute (minimum 1 minute).\nFor example, if you stop a session after 30 minutes, you'll be refunded half the charged amount.\n\n**Session Limits:**\n- All users: Up to 4 hours per session", "operationId": "create_browser_session_browsers_post", "security": [ { "APIKeyHeader": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateBrowserSessionRequest" } } } }, "responses": { "201": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BrowserSessionItemView" } } } }, "403": { "description": "Session timeout limit exceeded (maximum 4 hours)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SessionTimeoutLimitExceededError" } } } }, "404": { "description": "Profile not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProfileNotFoundError" } } } }, "422": { "description": "Request validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationError" } } } }, "429": { "description": "Too many concurrent active sessions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TooManyConcurrentActiveSessionsError" } } } } } } }, "/browsers/{session_id}": { "get": { "tags": [ "Browsers" ], "summary": "Get Browser Session", "description": "Get detailed browser session information including status and URLs.", "operationId": "get_browser_session_browsers__session_id__get", "security": [ { "APIKeyHeader": [] } ], "parameters": [ { "name": "session_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "title": "Session Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BrowserSessionView" } } } }, "404": { "description": "Session not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SessionNotFoundError" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "patch": { "tags": [ "Browsers" ], "summary": "Update Browser Session", "description": "Stop a browser session.\n\n**Refund:** When you stop a session, unused time is automatically refunded.\nIf the session ran for less than 1 hour, you'll receive a proportional refund.\nBilling is ceil to the nearest minute (minimum 1 minute).", "operationId": "update_browser_session_browsers__session_id__patch", "security": [ { "APIKeyHeader": [] } ], "parameters": [ { "name": "session_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "title": "Session Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateBrowserSessionRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BrowserSessionView" } } } }, "404": { "description": "Session not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SessionNotFoundError" } } } }, "422": { "description": "Request validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationError" } } } } } } }, "/browsers/{session_id}/downloads": { "get": { "tags": [ "Browsers" ], "summary": "List Browser Session Downloads", "description": "List files the browser downloaded to S3 during the session.\n\nPass ``includeUrls=true`` to receive presigned download URLs (15 min expiry) inline.\nFiles are stored at ``downloads/projects/{project_id}/sessions/{session_id}/`` in\nthe private bucket.", "operationId": "list_browser_session_downloads_browsers__session_id__downloads_get", "security": [ { "APIKeyHeader": [] } ], "parameters": [ { "name": "session_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "title": "Session Id" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 100, "minimum": 1, "default": 50, "title": "Limit" } }, { "name": "cursor", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Cursor" } }, { "name": "includeUrls", "in": "query", "required": false, "schema": { "type": "boolean", "default": false, "title": "Includeurls" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BrowserDownloadListResponse" } } } }, "404": { "description": "Session not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SessionNotFoundError" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/profiles": { "get": { "tags": [ "Profiles" ], "summary": "List Profiles", "description": "Get paginated list of profiles.\n\nUse the `query` parameter to search profiles by name or user_id.\nThis is useful when you have many profiles and need to find a specific user.\n\nExample: If you set `user_id` to your internal user identifier when creating profiles,\nyou can later search for that user by passing their identifier as the `query` parameter.", "operationId": "list_profiles_profiles_get", "security": [ { "APIKeyHeader": [] } ], "parameters": [ { "name": "pageSize", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 100, "minimum": 1, "default": 10, "title": "Pagesize" } }, { "name": "pageNumber", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "default": 1, "title": "Pagenumber" } }, { "name": "query", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "maxLength": 200 }, { "type": "null" } ], "title": "Query" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProfileListResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "post": { "tags": [ "Profiles" ], "summary": "Create Profile", "description": "Profiles allow you to preserve the state of the browser between tasks.\n\nThey are most commonly used to allow users to preserve the log-in state in the agent between tasks.\nYou'd normally create one profile per user and then use it for all their tasks.\n\nYou can set a `user_id` when creating a profile to associate it with a user in your system.\nThis allows you to later search for the profile using the GET /profiles endpoint with a query parameter.", "operationId": "create_profile_profiles_post", "security": [ { "APIKeyHeader": [] } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProfileCreateRequest" } } } }, "responses": { "201": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProfileView" } } } }, "402": { "description": "Subscription required for additional profiles", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InsufficientCreditsError" } } } }, "422": { "description": "Request validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationError" } } } } } } }, "/profiles/{profile_id}": { "get": { "tags": [ "Profiles" ], "summary": "Get Profile", "description": "Get profile details.", "operationId": "get_profile_profiles__profile_id__get", "security": [ { "APIKeyHeader": [] } ], "parameters": [ { "name": "profile_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "title": "Profile Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProfileView" } } } }, "404": { "description": "Profile not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProfileNotFoundError" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "patch": { "tags": [ "Profiles" ], "summary": "Update Profile", "description": "Update a browser profile's information.", "operationId": "update_profile_profiles__profile_id__patch", "security": [ { "APIKeyHeader": [] } ], "parameters": [ { "name": "profile_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "title": "Profile Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProfileUpdateRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProfileView" } } } }, "404": { "description": "Profile not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProfileNotFoundError" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "delete": { "tags": [ "Profiles" ], "summary": "Delete Browser Profile", "description": "Permanently delete a browser profile and its configuration.", "operationId": "delete_browser_profile_profiles__profile_id__delete", "security": [ { "APIKeyHeader": [] } ], "parameters": [ { "name": "profile_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "title": "Profile Id" } } ], "responses": { "204": { "description": "Successful Response" }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/workspaces": { "get": { "tags": [ "Workspaces" ], "summary": "List Workspaces", "description": "Get paginated list of workspaces.", "operationId": "list_workspaces_workspaces_get", "security": [ { "APIKeyHeader": [] } ], "parameters": [ { "name": "pageSize", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 100, "minimum": 1, "default": 10, "title": "Pagesize" } }, { "name": "pageNumber", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "default": 1, "title": "Pagenumber" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkspaceListResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "post": { "tags": [ "Workspaces" ], "summary": "Create Workspace", "description": "Create a new workspace for persistent shared file storage across sessions.", "operationId": "create_workspace_workspaces_post", "security": [ { "APIKeyHeader": [] } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkspaceCreateRequest" } } } }, "responses": { "201": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkspaceView" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/workspaces/{workspace_id}": { "get": { "tags": [ "Workspaces" ], "summary": "Get Workspace", "description": "Get workspace details.", "operationId": "get_workspace_workspaces__workspace_id__get", "security": [ { "APIKeyHeader": [] } ], "parameters": [ { "name": "workspace_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "title": "Workspace Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkspaceView" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "patch": { "tags": [ "Workspaces" ], "summary": "Update Workspace", "description": "Update a workspace's name.", "operationId": "update_workspace_workspaces__workspace_id__patch", "security": [ { "APIKeyHeader": [] } ], "parameters": [ { "name": "workspace_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "title": "Workspace Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkspaceUpdateRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkspaceView" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "delete": { "tags": [ "Workspaces" ], "summary": "Delete Workspace", "description": "Delete a workspace and its S3 data.", "operationId": "delete_workspace_workspaces__workspace_id__delete", "security": [ { "APIKeyHeader": [] } ], "parameters": [ { "name": "workspace_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "title": "Workspace Id" } } ], "responses": { "204": { "description": "Successful Response" }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/workspaces/{workspace_id}/files": { "get": { "tags": [ "Workspaces" ], "summary": "List Workspace Files", "description": "List files in a workspace's S3 prefix.", "operationId": "list_workspace_files_workspaces__workspace_id__files_get", "security": [ { "APIKeyHeader": [] } ], "parameters": [ { "name": "workspace_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "title": "Workspace Id" } }, { "name": "prefix", "in": "query", "required": false, "schema": { "type": "string", "default": "", "title": "Prefix" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 100, "minimum": 1, "default": 50, "title": "Limit" } }, { "name": "cursor", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Cursor" } }, { "name": "includeUrls", "in": "query", "required": false, "schema": { "type": "boolean", "default": false, "title": "Includeurls" } }, { "name": "shallow", "in": "query", "required": false, "schema": { "type": "boolean", "default": false, "title": "Shallow" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FileListResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "delete": { "tags": [ "Workspaces" ], "summary": "Delete Workspace File", "description": "Delete a single file from a workspace.", "operationId": "delete_workspace_file_workspaces__workspace_id__files_delete", "security": [ { "APIKeyHeader": [] } ], "parameters": [ { "name": "workspace_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "title": "Workspace Id" } }, { "name": "path", "in": "query", "required": true, "schema": { "type": "string", "description": "Relative file path to delete", "title": "Path" }, "description": "Relative file path to delete" } ], "responses": { "204": { "description": "Successful Response" }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/workspaces/{workspace_id}/size": { "get": { "tags": [ "Workspaces" ], "summary": "Get Workspace Size", "description": "Get current storage usage for a workspace.", "operationId": "get_workspace_size_workspaces__workspace_id__size_get", "security": [ { "APIKeyHeader": [] } ], "parameters": [ { "name": "workspace_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "title": "Workspace Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/workspaces/{workspace_id}/files/upload": { "post": { "tags": [ "Workspaces" ], "summary": "Upload Workspace Files", "description": "Get presigned PUT URLs for uploading files to a workspace.", "operationId": "upload_workspace_files_workspaces__workspace_id__files_upload_post", "security": [ { "APIKeyHeader": [] } ], "parameters": [ { "name": "workspace_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "title": "Workspace Id" } }, { "name": "prefix", "in": "query", "required": false, "schema": { "type": "string", "description": "Directory prefix to upload into (e.g. \"uploads/\")", "default": "", "title": "Prefix" }, "description": "Directory prefix to upload into (e.g. \"uploads/\")" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FileUploadRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FileUploadResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/billing/account": { "get": { "tags": [ "Billing" ], "summary": "Get Account Billing", "description": "Get authenticated account information including credit balance and account details.", "operationId": "get_account_billing_billing_account_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountView" } } } }, "404": { "description": "Project for a given API key not found!", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountNotFoundError" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "APIKeyHeader": [] } ] } }, "/x402/balance": { "post": { "tags": [ "x402" ], "summary": "X402 Balance", "description": "Read a wallet-derived project's credit balance auth by off-chain wallet signature", "operationId": "x402_balance_x402_balance_post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/X402BalanceRequest" } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/X402BalanceResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } } }, "components": { "schemas": { "AccountNotFoundError": { "properties": { "detail": { "type": "string", "title": "Detail", "default": "Account not found" } }, "type": "object", "title": "AccountNotFoundError", "description": "Error response when an account is not found" }, "AccountView": { "properties": { "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Name", "description": "The name of the user" }, "totalCreditsBalanceUsd": { "type": "number", "title": "Credits Balance USD", "description": "The total credits balance in USD" }, "monthlyCreditsBalanceUsd": { "type": "number", "title": "Monthly Credits Balance USD", "description": "Monthly subscription credits balance in USD" }, "additionalCreditsBalanceUsd": { "type": "number", "title": "Additional Credits Balance USD", "description": "Additional top-up credits balance in USD" }, "rateLimit": { "type": "integer", "title": "Rate Limit", "description": "Legacy alias for the concurrent browser session limit" }, "concurrentSessionLimit": { "type": "integer", "title": "Concurrent Session Limit", "description": "The maximum number of concurrent browser sessions for the project" }, "activeSessionCount": { "type": "integer", "title": "Active Session Count", "description": "The number of browser sessions currently active for the project" }, "planInfo": { "$ref": "#/components/schemas/PlanInfo", "title": "Plan Info", "description": "The plan information" }, "isFreeTier": { "type": "boolean", "title": "Is Free Tier", "description": "Whether the account is on the free tier", "default": false }, "projectId": { "type": "string", "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", "required": [ "totalCreditsBalanceUsd", "monthlyCreditsBalanceUsd", "additionalCreditsBalanceUsd", "rateLimit", "concurrentSessionLimit", "activeSessionCount", "planInfo", "projectId" ], "title": "AccountView", "description": "View model for account information." }, "BrowserDownloadFile": { "properties": { "path": { "type": "string", "title": "Path", "description": "File name (basename relative to the session downloads prefix)" }, "size": { "type": "integer", "title": "Size", "description": "File size in bytes" }, "lastModified": { "type": "string", "format": "date-time", "title": "Lastmodified", "description": "When the file was last modified in S3" }, "url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Url", "description": "Presigned download URL (15 min expiry). Only included when `includeUrls=true`." } }, "type": "object", "required": [ "path", "size", "lastModified" ], "title": "BrowserDownloadFile", "description": "A single file the browser downloaded during the session." }, "BrowserDownloadListResponse": { "properties": { "files": { "items": { "$ref": "#/components/schemas/BrowserDownloadFile" }, "type": "array", "title": "Files", "description": "List of files downloaded by the browser" }, "nextCursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Nextcursor", "description": "Cursor for the next page. Pass as the `cursor` query parameter to fetch the next page." }, "hasMore": { "type": "boolean", "title": "Hasmore", "description": "Whether there are more files beyond this page.", "default": false } }, "type": "object", "required": [ "files" ], "title": "BrowserDownloadListResponse", "description": "Paginated list of browser downloads with optional presigned URLs." }, "BrowserSessionItemView": { "properties": { "id": { "type": "string", "format": "uuid", "title": "ID", "description": "Unique identifier for the session" }, "status": { "$ref": "#/components/schemas/BrowserSessionStatus", "title": "Status", "description": "Current status of the session (active/stopped)" }, "liveUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Live URL", "description": "URL where the browser can be viewed live in real-time" }, "cdpUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "CDP URL", "description": "Chrome DevTools Protocol URL for browser automation" }, "timeoutAt": { "type": "string", "format": "date-time", "title": "Timeout At", "description": "Timestamp when the session will timeout" }, "startedAt": { "type": "string", "format": "date-time", "title": "Started At", "description": "Timestamp when the session was created and started" }, "finishedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Finished At", "description": "Timestamp when the session was stopped (None if still active)" }, "proxyUsedMb": { "type": "string", "pattern": "^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$", "title": "Proxy Used MB", "description": "Amount of proxy data used in MB", "default": "0" }, "proxyCost": { "type": "string", "pattern": "^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$", "title": "Proxy Cost", "description": "Cost of proxy usage in USD", "default": "0" }, "browserCost": { "type": "string", "pattern": "^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$", "title": "Browser Cost", "description": "Cost of browser session hosting in USD", "default": "0" }, "agentSessionId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "title": "Agent Session ID", "description": "ID of the agent session that created this browser (None for standalone BaaS sessions)" }, "recordingUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Recording URL", "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", "required": [ "id", "status", "timeoutAt", "startedAt" ], "title": "BrowserSessionItemView", "description": "View model for representing a browser session in list views." }, "BrowserSessionListResponse": { "properties": { "items": { "items": { "$ref": "#/components/schemas/BrowserSessionItemView" }, "type": "array", "title": "Items", "description": "List of browser session views for the current page" }, "totalItems": { "type": "integer", "title": "Total Items", "description": "Total number of items in the list" }, "pageNumber": { "type": "integer", "title": "Page Number", "description": "Page number" }, "pageSize": { "type": "integer", "title": "Page Size", "description": "Number of items per page" } }, "type": "object", "required": [ "items", "totalItems", "pageNumber", "pageSize" ], "title": "BrowserSessionListResponse", "description": "Response model for paginated browser session list requests." }, "BrowserSessionStatus": { "type": "string", "enum": [ "active", "stopped" ], "title": "BrowserSessionStatus", "description": "Enumeration of possible browser session states\n\nAttributes:\n ACTIVE: Session is currently active and running (browser is running)\n STOPPED: Session has been stopped and is no longer active (browser is stopped)" }, "BrowserSessionUpdateAction": { "type": "string", "enum": [ "stop" ], "title": "BrowserSessionUpdateAction", "description": "Available actions that can be performed on a browser session\n\nAttributes:\n STOP: Stop the browser session (cannot be undone)" }, "BrowserSessionView": { "properties": { "id": { "type": "string", "format": "uuid", "title": "ID", "description": "Unique identifier for the session" }, "status": { "$ref": "#/components/schemas/BrowserSessionStatus", "title": "Status", "description": "Current status of the session (active/stopped)" }, "liveUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Live URL", "description": "URL where the browser can be viewed live in real-time" }, "cdpUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "CDP URL", "description": "Chrome DevTools Protocol URL for browser automation" }, "timeoutAt": { "type": "string", "format": "date-time", "title": "Timeout At", "description": "Timestamp when the session will timeout" }, "startedAt": { "type": "string", "format": "date-time", "title": "Started At", "description": "Timestamp when the session was created and started" }, "finishedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Finished At", "description": "Timestamp when the session was stopped (None if still active)" }, "proxyUsedMb": { "type": "string", "pattern": "^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$", "title": "Proxy Used MB", "description": "Amount of proxy data used in MB", "default": "0" }, "proxyCost": { "type": "string", "pattern": "^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$", "title": "Proxy Cost", "description": "Cost of proxy usage in USD", "default": "0" }, "browserCost": { "type": "string", "pattern": "^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$", "title": "Browser Cost", "description": "Cost of browser session hosting in USD", "default": "0" }, "agentSessionId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "title": "Agent Session ID", "description": "ID of the agent session that created this browser (None for standalone BaaS sessions)" }, "recordingUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Recording URL", "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", "required": [ "id", "status", "timeoutAt", "startedAt" ], "title": "BrowserSessionView", "description": "View model for representing a browser session." }, "BuAgentSessionStatus": { "type": "string", "enum": [ "created", "idle", "running", "stopped", "timed_out", "error" ], "title": "BuAgentSessionStatus", "description": "Session lifecycle status. Progresses through: created \u2192 idle \u2192 running \u2192 idle \u2192 ... \u2192 stopped / timed_out / error.\n\n- `created`: Sandbox is starting up. The session is not yet ready to accept tasks.\n- `idle`: Sandbox is healthy and waiting for a task. You can dispatch a task or upload files.\n- `running`: A task is currently being executed by the agent.\n- `stopped`: Session was stopped \u2014 either explicitly via the stop endpoint, or automatically after task completion (when `keepAlive` is false).\n- `timed_out`: Session was cleaned up due to inactivity timeout.\n- `error`: Sandbox failed to start or encountered an unrecoverable error." }, "BuModel": { "type": "string", "enum": [ "bu-mini", "bu-max", "bu-ultra", "gemini-3-flash", "claude-opus-4.6", "claude-opus-4.7", "claude-sonnet-5", "claude-opus-4.8", "gpt-5.4-mini", "glm-5.2", "minimax-m3", "claude-haiku-4.5", "gpt-5.2", "gpt-5-mini", "gpt-5.5", "gpt-5.6-sol", "gpt-5.6-terra", "gpt-5.6-luna", "gemini-3-pro", "gemini-3.1-pro", "gemini-3.5-flash" ], "title": "BuModel", "description": "The model to use for the agent. Each model has different capabilities and pricing.\n\n- `bu-mini` / `gemini-3-flash`: Gemini 3 Flash \u2014 fast and cost-effective. Best for simple, well-defined tasks like form filling or data extraction.\n- `bu-max` / `claude-sonnet-4.6` (legacy aliases) / `claude-sonnet-5`: Claude Sonnet 5 \u2014 balanced performance. Best for multi-step workflows that require reasoning and decision-making.\n- `bu-ultra` / `claude-opus-4.6`: Claude Opus 4.6 \u2014 capable general-purpose Opus tier.\n- `claude-opus-4.7`: Claude Opus 4.7 \u2014 most capable. Best for complex tasks that require advanced reasoning, long-horizon planning, or handling ambiguous instructions.\n- `claude-opus-4.8`: Claude Opus 4.8 \u2014 most capable Opus-tier model, state-of-the-art on long-horizon agentic work.\n- `gpt-5.4-mini`: GPT-5.4 mini \u2014 OpenAI's fast and efficient model. Best for tasks that benefit from OpenAI's capabilities.\n- `glm-5.2`: Z.ai GLM 5.2 \u2014 capable, low-cost open model. Best for cost-sensitive agentic tasks.\n- `minimax-m3`: MiniMax M3 \u2014 fast, very low-cost model. Best for simple, high-volume tasks.\n\nAdditional provider models (e.g. `gemini-3.5-flash`, `gpt-5.2`, and `gpt-5-mini`)\nare selectable only with `use_own_key=true`, where your own provider key serves\nthem. The GPT-5.6 family is native when either Browser Use's direct OpenAI key\nor Amazon Bedrock route is configured. GPT-5.5 becomes native only through the\nBedrock rollout." }, "CreateBrowserSessionRequest": { "properties": { "profileId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "title": "Profile ID", "description": "The ID of the profile to use for the session" }, "proxyCountryCode": { "anyOf": [ { "$ref": "#/components/schemas/ProxyCountryCode" }, { "type": "null" } ], "title": "Proxy Country Code", "description": "Country code for proxy location. Defaults to US. Set to null to disable proxy.", "default": "us" }, "metadata": { "anyOf": [ { "additionalProperties": { "type": "string" }, "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", "description": "The timeout for the session in minutes. All users can use up to 240 minutes (4 hours). Browser sessions are charged $0.02/hour.", "default": 60, "ge": 1, "le": 240 }, "browserScreenWidth": { "anyOf": [ { "type": "integer", "maximum": 6144.0, "minimum": 320.0 }, { "type": "null" } ], "title": "Browser Screen Width", "description": "Custom screen width in pixels for the browser." }, "browserScreenHeight": { "anyOf": [ { "type": "integer", "maximum": 3456.0, "minimum": 320.0 }, { "type": "null" } ], "title": "Browser Screen Height", "description": "Custom screen height in pixels for the browser." }, "allowResizing": { "type": "boolean", "title": "Allow Resizing", "description": "Whether to allow the browser to be resized during the session (not recommended since it reduces stealthiness).", "default": false }, "customProxy": { "anyOf": [ { "$ref": "#/components/schemas/CustomProxy" }, { "type": "null" } ], "title": "Custom Proxy", "description": "Custom proxy settings to use for the session. If not provided, our proxies will be used. Custom proxies are available on any active subscription." }, "enableRecording": { "type": "boolean", "title": "Enable Recording", "description": "If True, enables session recording. Defaults to False.", "default": false } }, "type": "object", "title": "CreateBrowserSessionRequest", "description": "Request model for creating a browser session." }, "CustomProxy": { "properties": { "host": { "type": "string", "maxLength": 255, "minLength": 1, "title": "Host", "description": "Host of the proxy." }, "port": { "type": "integer", "maximum": 65535.0, "minimum": 1.0, "title": "Port", "description": "Port of the proxy." }, "username": { "anyOf": [ { "type": "string", "maxLength": 255, "minLength": 1 }, { "type": "null" } ], "title": "Username", "description": "Username for proxy authentication." }, "password": { "anyOf": [ { "type": "string", "maxLength": 255, "minLength": 1 }, { "type": "null" } ], "title": "Password", "description": "Password for proxy authentication." }, "ignoreCertErrors": { "type": "boolean", "title": "Ignore Certificate Errors", "description": "Ignore TLS certificate errors. Enable this if your proxy uses a self-signed or untrusted certificate (e.g. Burp Suite, corporate proxies).", "default": false } }, "type": "object", "required": [ "host", "port" ], "title": "CustomProxy", "description": "Request model for creating a custom proxy." }, "FileInfo": { "properties": { "path": { "type": "string", "title": "Path", "description": "File path relative to the session workspace root." }, "size": { "type": "integer", "title": "Size", "description": "File size in bytes." }, "lastModified": { "type": "string", "format": "date-time", "title": "Lastmodified", "description": "When the file was last modified." }, "url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Url", "description": "Presigned download URL (60s expiry). Only included when `includeUrls=true`." } }, "type": "object", "required": [ "path", "size", "lastModified" ], "title": "FileInfo", "description": "A file in a session's workspace." }, "FileListResponse": { "properties": { "files": { "items": { "$ref": "#/components/schemas/FileInfo" }, "type": "array", "title": "Files" }, "folders": { "items": { "type": "string" }, "type": "array", "title": "Folders", "description": "Immediate sub-folder names at this prefix level" }, "nextCursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Nextcursor", "description": "Cursor for the next page. Pass as the `cursor` query parameter to fetch the next page." }, "hasMore": { "type": "boolean", "title": "Hasmore", "description": "Whether there are more files beyond this page.", "default": false } }, "type": "object", "required": [ "files" ], "title": "FileListResponse", "description": "Paginated file listing with optional presigned download URLs." }, "FileUploadItem": { "properties": { "name": { "type": "string", "maxLength": 255, "minLength": 1, "title": "Name", "description": "Filename, e.g. \"data.csv\"" }, "contentType": { "type": "string", "maxLength": 255, "title": "Contenttype", "description": "MIME type, e.g. \"text/csv\"", "default": "application/octet-stream" }, "size": { "anyOf": [ { "type": "integer", "minimum": 1.0 }, { "type": "null" } ], "title": "Size", "description": "File size in bytes (required for workspace uploads)" } }, "type": "object", "required": [ "name" ], "title": "FileUploadItem", "description": "A single file to upload." }, "FileUploadRequest": { "properties": { "files": { "items": { "$ref": "#/components/schemas/FileUploadItem" }, "type": "array", "maxItems": 10, "minItems": 1, "title": "Files" } }, "type": "object", "required": [ "files" ], "title": "FileUploadRequest", "description": "Request body for generating presigned upload URLs." }, "FileUploadResponse": { "properties": { "files": { "items": { "$ref": "#/components/schemas/FileUploadResponseItem" }, "type": "array", "title": "Files" } }, "type": "object", "required": [ "files" ], "title": "FileUploadResponse", "description": "Presigned upload URLs for the requested files." }, "FileUploadResponseItem": { "properties": { "name": { "type": "string", "title": "Name", "description": "Original filename as requested." }, "uploadUrl": { "type": "string", "title": "Uploadurl", "description": "Presigned PUT URL. Upload the file by sending a PUT request to this URL with the file content and matching Content-Type header. Expires after 5 minutes." }, "path": { "type": "string", "title": "Path", "description": "Path where the file will be stored in the workspace, e.g. \"uploads/data.csv\"." } }, "type": "object", "required": [ "name", "uploadUrl", "path" ], "title": "FileUploadResponseItem", "description": "Presigned upload URL for a single file." }, "HTTPValidationError": { "properties": { "detail": { "items": { "$ref": "#/components/schemas/ValidationError" }, "type": "array", "title": "Detail" } }, "type": "object", "title": "HTTPValidationError" }, "InsufficientCreditsError": { "properties": { "detail": { "type": "string", "title": "Detail", "default": "Insufficient credits" } }, "type": "object", "title": "InsufficientCreditsError", "description": "Error response when there are insufficient credits" }, "MessageListResponse": { "properties": { "messages": { "items": { "$ref": "#/components/schemas/MessageResponse" }, "type": "array", "title": "Messages", "description": "List of messages in chronological order." }, "hasMore": { "type": "boolean", "title": "Hasmore", "description": "Whether there are more messages available beyond this page. Use cursor-based pagination with the `after` or `before` query parameters to fetch more." } }, "type": "object", "required": [ "messages", "hasMore" ], "title": "MessageListResponse" }, "MessageResponse": { "properties": { "id": { "type": "string", "format": "uuid", "title": "Id", "description": "Unique message identifier." }, "sessionId": { "type": "string", "format": "uuid", "title": "Sessionid", "description": "ID of the session this message belongs to." }, "role": { "type": "string", "title": "Role", "description": "Message role: \"human\" for user-submitted tasks, \"ai\" for agent actions and responses." }, "data": { "type": "string", "title": "Data", "description": "Raw message content. Format depends on the message type \u2014 may be plain text, JSON, or structured action data." }, "type": { "type": "string", "title": "Type", "description": "Message category. Common values: `user_message`, `assistant_message`, `browser_action`, `file_operation`, `code_execution`, `integration`, `planning`, `completion`, `browser_action_result`, `browser_action_error`.", "default": "" }, "summary": { "type": "string", "title": "Summary", "description": "One-liner human-readable description of the message (e.g. \"Navigating to google.com\", \"Clicking element #5\"). Useful for building activity feeds.", "default": "" }, "screenshotUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Screenshoturl", "description": "Browser screenshot captured at the time of this message. Presigned URL, expires after 5 minutes." }, "hidden": { "type": "boolean", "title": "Hidden", "description": "Whether this message should be hidden from the user in a chat UI.", "default": false }, "createdAt": { "type": "string", "format": "date-time", "title": "Createdat", "description": "When this message was created." } }, "type": "object", "required": [ "id", "sessionId", "role", "data", "createdAt" ], "title": "MessageResponse", "description": "A single message from the session's message stream.\n\nMessages represent the agent's actions, observations, and decisions as it executes a task." }, "PlanInfo": { "properties": { "planName": { "type": "string", "title": "Plan Name", "description": "The name of the plan" }, "subscriptionStatus": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Subscription Status", "description": "The status of the subscription" }, "subscriptionId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Subscription ID", "description": "The ID of the subscription" }, "subscriptionCurrentPeriodEnd": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Subscription Current Period End", "description": "The end of the current period" }, "subscriptionCanceledAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Subscription Canceled At", "description": "The date the subscription was canceled" } }, "type": "object", "required": [ "planName", "subscriptionStatus", "subscriptionId", "subscriptionCurrentPeriodEnd", "subscriptionCanceledAt" ], "title": "PlanInfo", "description": "View model for plan information" }, "ProfileCreateRequest": { "properties": { "name": { "anyOf": [ { "type": "string", "maxLength": 100 }, { "type": "null" } ], "title": "Name", "description": "Optional name for the profile" }, "userId": { "anyOf": [ { "type": "string", "maxLength": 255 }, { "type": "null" } ], "title": "User ID", "description": "Your internal user identifier for this profile. Use this to associate a profile with a user in your system." } }, "type": "object", "title": "ProfileCreateRequest", "description": "Request model for creating a new profile." }, "ProfileListResponse": { "properties": { "items": { "items": { "$ref": "#/components/schemas/ProfileView" }, "type": "array", "title": "Items", "description": "List of profile views for the current page" }, "totalItems": { "type": "integer", "title": "Total Items", "description": "Total number of items in the list" }, "pageNumber": { "type": "integer", "title": "Page Number", "description": "Page number" }, "pageSize": { "type": "integer", "title": "Page Size", "description": "Number of items per page" } }, "type": "object", "required": [ "items", "totalItems", "pageNumber", "pageSize" ], "title": "ProfileListResponse", "description": "Response model for paginated profile list requests." }, "ProfileNotFoundError": { "properties": { "detail": { "type": "string", "title": "Detail", "default": "Profile not found" } }, "type": "object", "title": "ProfileNotFoundError", "description": "Error response when a profile is not found" }, "ProfileUpdateRequest": { "properties": { "name": { "anyOf": [ { "type": "string", "maxLength": 100 }, { "type": "null" } ], "title": "Name", "description": "Optional name for the profile" }, "userId": { "anyOf": [ { "type": "string", "maxLength": 255 }, { "type": "null" } ], "title": "User ID", "description": "Your internal user identifier for this profile. Use this to associate a profile with a user in your system." } }, "type": "object", "title": "ProfileUpdateRequest", "description": "Request model for updating a profile." }, "ProfileView": { "properties": { "id": { "type": "string", "format": "uuid", "title": "ID", "description": "Unique identifier for the profile" }, "userId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "User ID", "description": "Your internal user identifier for this profile. Use this to associate a profile with a user in your system." }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Name", "description": "Optional name for the profile" }, "lastUsedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Last Used At", "description": "Timestamp when the profile was last used" }, "createdAt": { "type": "string", "format": "date-time", "title": "Created At", "description": "Timestamp when the profile was created" }, "updatedAt": { "type": "string", "format": "date-time", "title": "Updated At", "description": "Timestamp when the profile was last updated" }, "cookieDomains": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Cookie Domains", "description": "List of domain URLs that have cookies stored for this profile" } }, "type": "object", "required": [ "id", "createdAt", "updatedAt" ], "title": "ProfileView", "description": "View model for representing a profile. A profile lets you preserve the login state between sessions.\n\nWe recommend that you create a separate profile for each user of your app.\nYou can assign a user_id to each profile to easily identify which user the profile belongs to." }, "ProxyCountryCode": { "type": "string", "enum": [ "ad", "ae", "af", "ag", "ai", "al", "am", "an", "ao", "aq", "ar", "as", "at", "au", "aw", "az", "ba", "bb", "bd", "be", "bf", "bg", "bh", "bi", "bj", "bl", "bm", "bn", "bo", "bq", "br", "bs", "bt", "bv", "bw", "by", "bz", "ca", "cc", "cd", "cf", "cg", "ch", "ci", "ck", "cl", "cm", "co", "cr", "cs", "cu", "cv", "cw", "cx", "cy", "cz", "de", "dj", "dk", "dm", "do", "dz", "ec", "ee", "eg", "eh", "er", "es", "et", "fi", "fj", "fk", "fm", "fo", "fr", "ga", "gd", "ge", "gf", "gg", "gh", "gi", "gl", "gm", "gn", "gp", "gq", "gr", "gs", "gt", "gu", "gw", "gy", "hk", "hm", "hn", "hr", "ht", "hu", "id", "ie", "il", "im", "in", "iq", "ir", "is", "it", "je", "jm", "jo", "jp", "ke", "kg", "kh", "ki", "km", "kn", "kp", "kr", "kw", "ky", "kz", "la", "lb", "lc", "li", "lk", "lr", "ls", "lt", "lu", "lv", "ly", "ma", "mc", "md", "me", "mf", "mg", "mh", "mk", "ml", "mm", "mn", "mo", "mp", "mq", "mr", "ms", "mt", "mu", "mv", "mw", "mx", "my", "mz", "na", "nc", "ne", "nf", "ng", "ni", "nl", "no", "np", "nr", "nu", "nz", "om", "pa", "pe", "pf", "pg", "ph", "pk", "pl", "pm", "pn", "pr", "ps", "pt", "pw", "py", "qa", "re", "ro", "rs", "ru", "rw", "sa", "sb", "sc", "sd", "se", "sg", "sh", "si", "sj", "sk", "sl", "sm", "sn", "so", "sr", "ss", "st", "sv", "sx", "sy", "sz", "tc", "td", "tf", "tg", "th", "tj", "tk", "tl", "tm", "tn", "to", "tr", "tt", "tv", "tw", "tz", "ua", "ug", "uk", "us", "uy", "uz", "va", "vc", "ve", "vg", "vi", "vn", "vu", "wf", "ws", "xk", "ye", "yt", "za", "zm", "zw" ], "title": "ProxyCountryCode" }, "RunTaskRequest": { "properties": { "task": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Task", "description": "The natural-language instruction for the agent to execute (e.g. \"Go to amazon.com and find the best-rated wireless mouse under $50\"). Required when dispatching to an existing session." }, "model": { "$ref": "#/components/schemas/BuModel", "description": "The model to use. \"gemini-3-flash\" is fast and cheap, \"claude-sonnet-5\" is balanced, \"claude-opus-4.7\" is most capable (default), and \"claude-opus-4.8\" is the newest Opus-tier model. GPT-5.6 models are Browser Use native models when either direct OpenAI or Amazon Bedrock routing is configured; otherwise they require use_own_key=true. GPT-5.5 becomes native when Bedrock routing is enabled; otherwise it requires use_own_key=true. Other additional provider models (e.g. \"gemini-3.5-flash\" and \"gpt-5.2\") require use_own_key=true. See BuModel for details.", "default": "claude-opus-4.7" }, "thinkingLevel": { "anyOf": [ { "$ref": "#/components/schemas/ThinkingLevel" }, { "type": "null" } ], "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." }, "sessionId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "title": "Sessionid", "description": "ID of an existing idle session to dispatch the task to. If omitted, a new session is created." }, "keepAlive": { "type": "boolean", "title": "Keepalive", "description": "If true, the session stays alive in idle state after the task completes instead of automatically stopping. This lets you dispatch follow-up tasks to the same session, preserving browser state and files.", "default": false }, "maxCostUsd": { "anyOf": [ { "type": "number" }, { "type": "string", "pattern": "^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$" }, { "type": "null" } ], "title": "Maxcostusd", "description": "Maximum total cost in USD allowed for this session. The task will be stopped if this limit is reached. If omitted, a default limit applies (capped by your available balance). When dispatching a follow-up task to an existing session (`sessionId` is set), supplying this value overrides the session's budget for the upcoming dispatch; otherwise the budget is automatically refreshed to current spend + default." }, "profileId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "title": "Profileid", "description": "ID of a browser profile to load into the session. Profiles persist cookies, local storage, and other browser state across sessions. Create profiles via the Profiles API." }, "workspaceId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "title": "Workspaceid", "description": "ID of a workspace to attach to the session. Workspaces provide persistent file storage that carries across sessions. Create workspaces via the Workspaces API." }, "proxyCountryCode": { "anyOf": [ { "$ref": "#/components/schemas/ProxyCountryCode" }, { "type": "null" } ], "description": "Country code for the browser proxy (e.g. \"US\", \"DE\", \"JP\"). Set to null to disable the proxy. The proxy routes browser traffic through the specified country, useful for accessing geo-restricted content.", "default": "us" }, "browserScreenWidth": { "anyOf": [ { "type": "integer", "maximum": 6144.0, "minimum": 320.0 }, { "type": "null" } ], "title": "Browserscreenwidth", "description": "Custom browser screen width in pixels. Must be set together with browserScreenHeight. When omitted, the browser keeps its own default resolution." }, "browserScreenHeight": { "anyOf": [ { "type": "integer", "maximum": 3456.0, "minimum": 320.0 }, { "type": "null" } ], "title": "Browserscreenheight", "description": "Custom browser screen height in pixels. Must be set together with browserScreenWidth. When omitted, the browser keeps its own default resolution." }, "outputSchema": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Outputschema", "description": "A JSON Schema that the agent's final output must conform to. When set, the agent will return structured data matching this schema in the `output` field of the response. Example: {\"type\": \"object\", \"properties\": {\"price\": {\"type\": \"number\"}, \"title\": {\"type\": \"string\"}}}." }, "enableScheduledTasks": { "type": "boolean", "title": "Enablescheduledtasks", "description": "If true, the agent can create scheduled tasks that run on a recurring basis (e.g. \"every Monday morning, check my inbox and summarize new emails\"). Scheduled tasks are tied to your project and persist beyond the session. Note: all scheduled tasks are visible project-wide, so avoid enabling this in multi-user setups where task isolation is needed.", "default": false }, "sensitiveData": { "anyOf": [ { "additionalProperties": { "type": "string" }, "type": "object" }, { "type": "null" } ], "title": "Sensitivedata", "description": "Key-value pairs of sensitive data (e.g. passwords, API keys) that the agent can use via secure placeholders. Keys are exposed to the LLM; values are never shown. The agent uses `key` placeholders in browser_type_text to securely enter values." }, "enableRecording": { "type": "boolean", "title": "Enablerecording", "description": "If true, records a video of the browser session. The recording URLs will be available in the `recordingUrls` field of the session response after the task completes.", "default": false }, "skills": { "type": "boolean", "title": "Skills", "description": "If true, the agent generates and persists reusable skills from completed tasks (saved per-domain in the DB and auto-injected into future runs). Set to false to skip skill generation \u2014 useful for privacy-sensitive tasks or to avoid the extra LLM cost.", "default": true }, "agentmail": { "type": "boolean", "title": "Agentmail", "description": "If true, provisions a temporary email inbox (via AgentMail) for the session. The email address is available in the `agentmailEmail` field of the session response. Useful for tasks that require email verification or sign-ups.", "default": true }, "codeMode": { "type": "boolean", "title": "Codemode", "description": "When true, the agent returns structured output with `text` (summary) and `code` (validated Python source) fields instead of free-form text.", "default": false }, "cacheScript": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Cachescript", "description": "Controls deterministic script caching. `null` (default): auto-detected \u2014 enabled when the task contains `@{{value}}` brackets and a workspace is attached. `true`: force-enable script caching even without brackets (caches the exact task). `false`: force-disable, even if brackets are present. When active, the first call runs the full agent and saves a reusable script. Subsequent calls with the same task template execute the cached script with $0 LLM cost. Requires workspace_id when enabled. Example: \"Get prices from @{{https://example.com}} for @{{electronics}}\"." }, "useOwnKey": { "type": "boolean", "title": "Useownkey", "description": "If true, uses your own LLM API key (configured in project settings) instead of Browser Use managed keys. You pay your provider directly for inference; Browser Use charges a reduced orchestration fee (0.2\u00d7 of provider list prices). If no key is configured for the model's provider, the request is rejected.", "default": false }, "autoHeal": { "type": "boolean", "title": "Autoheal", "description": "When cache_script is active, controls whether a lightweight LLM validates the cached script output. If the output looks incorrect (empty, error, wrong structure), the system automatically re-triggers the full agent to generate a new version of the script. Set to false to disable validation and always return the raw script output.", "default": true } }, "type": "object", "title": "RunTaskRequest", "description": "Create a new session, dispatch a task, or both.\n\n- **No `sessionId` + no `task`**: creates an idle session (useful for uploading files before running a task).\n- **No `sessionId` + `task`**: creates a new session and immediately runs the task.\n- **`sessionId` + `task`**: dispatches the task to an existing idle session.\n- **`sessionId` + no `task`**: returns 422 \u2014 a task is required when targeting an existing session." }, "SessionListResponse": { "properties": { "sessions": { "items": { "$ref": "#/components/schemas/SessionResponse" }, "type": "array", "title": "Sessions", "description": "List of sessions." }, "total": { "type": "integer", "title": "Total", "description": "Total number of sessions matching the query." }, "page": { "type": "integer", "title": "Page", "description": "Current page number (1-indexed)." }, "pageSize": { "type": "integer", "title": "Pagesize", "description": "Number of sessions per page." } }, "type": "object", "required": [ "sessions", "total", "page", "pageSize" ], "title": "SessionListResponse" }, "SessionNotFoundError": { "properties": { "detail": { "type": "string", "title": "Detail", "default": "Session not found" } }, "type": "object", "title": "SessionNotFoundError", "description": "Error response when a session is not found" }, "SessionResponse": { "properties": { "id": { "type": "string", "format": "uuid", "title": "Id", "description": "Unique session identifier." }, "status": { "$ref": "#/components/schemas/BuAgentSessionStatus", "description": "Current session lifecycle status. Progresses through: `created` (sandbox starting) \u2192 `idle` (ready, waiting for task) \u2192 `running` (task executing) \u2192 `stopped` / `timed_out` / `error`. Poll this field to track progress." }, "model": { "$ref": "#/components/schemas/BuModel", "description": "The model tier used for this session." }, "thinkingLevel": { "anyOf": [ { "$ref": "#/components/schemas/ThinkingLevel" }, { "type": "null" } ], "description": "Configured model reasoning depth for this session, or null when provider defaults are used." }, "title": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Title", "description": "Auto-generated short title summarizing the task. Available after the task starts running." }, "output": { "anyOf": [ {}, { "type": "null" } ], "title": "Output", "description": "The agent's final output. If `codeMode` was true, this will be an object with `text` (summary), `code` (Python source), and optionally `output` (execution result). If `outputSchema` was provided, this will be structured data conforming to that schema. Otherwise it may be a free-form string or null." }, "outputSchema": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Outputschema", "description": "The JSON Schema that was requested for structured output, if any." }, "stepCount": { "type": "integer", "title": "Stepcount", "description": "Number of steps the agent has executed so far.", "default": 0 }, "lastStepSummary": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Laststepsummary", "description": "Human-readable summary of the most recent agent step (e.g. \"Clicking the Submit button\"). Useful for showing real-time progress." }, "isTaskSuccessful": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Istasksuccessful", "description": "Whether the task completed successfully. `true` if the agent achieved the goal, `false` if it failed or gave up, `null` if the task is still running or no task was dispatched." }, "liveUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Liveurl", "description": "URL to view the live browser session. Available immediately on session creation \u2014 can be embedded in an iframe to show the browser in real time." }, "recordingUrls": { "items": { "type": "string" }, "type": "array", "title": "Recordingurls", "description": "URLs to download session recordings. Only populated on `GET /api/v3/sessions/{id}`; always `[]` in list responses.", "default": [] }, "profileId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "title": "Profileid", "description": "ID of the browser profile loaded in this session, if any." }, "workspaceId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "title": "Workspaceid", "description": "ID of the workspace attached to this session, if any." }, "proxyCountryCode": { "anyOf": [ { "$ref": "#/components/schemas/ProxyCountryCode" }, { "type": "null" } ], "description": "Country code of the proxy used for this session, or null if no proxy." }, "browserScreenWidth": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Browserscreenwidth", "description": "Custom browser screen width set for this session, or null for the default." }, "browserScreenHeight": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Browserscreenheight", "description": "Custom browser screen height set for this session, or null for the default." }, "maxCostUsd": { "anyOf": [ { "type": "string", "pattern": "^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$" }, { "type": "null" } ], "title": "Maxcostusd", "description": "Maximum cost limit in USD set for this session." }, "totalInputTokens": { "type": "integer", "title": "Totalinputtokens", "description": "Total LLM input tokens consumed by this session.", "default": 0 }, "totalOutputTokens": { "type": "integer", "title": "Totaloutputtokens", "description": "Total LLM output tokens consumed by this session.", "default": 0 }, "proxyUsedMb": { "type": "string", "pattern": "^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$", "title": "Proxyusedmb", "description": "Proxy bandwidth used in megabytes.", "default": "0" }, "llmCostUsd": { "type": "string", "pattern": "^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$", "title": "Llmcostusd", "description": "Cost of LLM usage in USD.", "default": "0" }, "proxyCostUsd": { "type": "string", "pattern": "^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$", "title": "Proxycostusd", "description": "Cost of proxy bandwidth in USD.", "default": "0" }, "browserCostUsd": { "type": "string", "pattern": "^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$", "title": "Browsercostusd", "description": "Cost of browser compute time in USD.", "default": "0" }, "totalCostUsd": { "type": "string", "pattern": "^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$", "title": "Totalcostusd", "description": "Total session cost in USD (LLM + proxy + browser).", "default": "0" }, "screenshotUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Screenshoturl", "description": "Presigned URL of the latest screenshot (expires after 5 minutes). Only populated on `GET /api/v3/sessions/{id}`; always `null` in list responses." }, "agentmailEmail": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Agentmailemail", "description": "Temporary email address provisioned for this session (via AgentMail). Only present if `agentmail` was enabled." }, "integrationsUsed": { "items": { "type": "string" }, "type": "array", "title": "Integrationsused", "description": "List of integration providers used during this session (e.g. [\"gmail\", \"slack\", \"agentmail\"])." }, "createdAt": { "type": "string", "format": "date-time", "title": "Createdat", "description": "When the session was created." }, "updatedAt": { "type": "string", "format": "date-time", "title": "Updatedat", "description": "When the session was last updated." } }, "type": "object", "required": [ "id", "status", "model", "createdAt", "updatedAt" ], "title": "SessionResponse", "description": "Represents a session and its current state.\n\nPoll this endpoint to track task progress. The `status` field indicates the session lifecycle stage,\nand `output` contains the agent's structured result once the task completes." }, "SessionTimeoutLimitExceededError": { "properties": { "detail": { "type": "string", "title": "Detail", "default": "Maximum session timeout is 4 hours (240 minutes)." } }, "type": "object", "title": "SessionTimeoutLimitExceededError", "description": "Error response when session timeout exceeds the maximum allowed limit" }, "StopSessionRequest": { "properties": { "strategy": { "$ref": "#/components/schemas/StopStrategy", "description": "How to stop the session. Use \"task\" to stop only the current task and keep the session alive, or \"session\" to destroy the sandbox entirely.", "default": "session" } }, "type": "object", "title": "StopSessionRequest" }, "StopStrategy": { "type": "string", "enum": [ "task", "session" ], "title": "StopStrategy", "description": "Strategy for stopping a session.\n\n- `task`: Stop the currently running task but keep the session alive in idle state. You can dispatch another task to the same session afterwards.\n- `session`: Stop the session entirely and destroy the sandbox. The session cannot be reused after this." }, "ThinkingLevel": { "type": "string", "enum": [ "disabled", "low", "medium", "high" ], "title": "ThinkingLevel", "description": "Provider-neutral model reasoning depth." }, "TooManyConcurrentActiveSessionsError": { "properties": { "detail": { "type": "string", "title": "Detail", "default": "Too many concurrent active sessions. Please wait for one to finish, kill one, or upgrade your plan." } }, "type": "object", "title": "TooManyConcurrentActiveSessionsError", "description": "Error response when user has too many concurrent active sessions" }, "UpdateBrowserSessionRequest": { "properties": { "action": { "$ref": "#/components/schemas/BrowserSessionUpdateAction", "title": "Action", "description": "The action to perform on the session" } }, "type": "object", "required": [ "action" ], "title": "UpdateBrowserSessionRequest", "description": "Request model for updating browser session state." }, "ValidationError": { "properties": { "loc": { "items": { "anyOf": [ { "type": "string" }, { "type": "integer" } ] }, "type": "array", "title": "Location" }, "msg": { "type": "string", "title": "Message" }, "type": { "type": "string", "title": "Error Type" } }, "type": "object", "required": [ "loc", "msg", "type" ], "title": "ValidationError" }, "WorkspaceCreateRequest": { "properties": { "name": { "anyOf": [ { "type": "string", "maxLength": 100 }, { "type": "null" } ], "title": "Name", "description": "Optional name for the workspace" } }, "type": "object", "title": "WorkspaceCreateRequest", "description": "Request model for creating a new workspace." }, "WorkspaceListResponse": { "properties": { "items": { "items": { "$ref": "#/components/schemas/WorkspaceView" }, "type": "array", "title": "Items", "description": "List of workspace views for the current page" }, "totalItems": { "type": "integer", "title": "Total Items", "description": "Total number of items in the list" }, "pageNumber": { "type": "integer", "title": "Page Number", "description": "Page number" }, "pageSize": { "type": "integer", "title": "Page Size", "description": "Number of items per page" } }, "type": "object", "required": [ "items", "totalItems", "pageNumber", "pageSize" ], "title": "WorkspaceListResponse", "description": "Response model for paginated workspace list requests." }, "WorkspaceUpdateRequest": { "properties": { "name": { "anyOf": [ { "type": "string", "maxLength": 100 }, { "type": "null" } ], "title": "Name", "description": "Optional name for the workspace" } }, "type": "object", "title": "WorkspaceUpdateRequest", "description": "Request model for updating a workspace." }, "WorkspaceView": { "properties": { "id": { "type": "string", "format": "uuid", "title": "ID", "description": "Unique identifier for the workspace" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Name", "description": "Optional name for the workspace" }, "createdAt": { "type": "string", "format": "date-time", "title": "Created At", "description": "Timestamp when the workspace was created" }, "updatedAt": { "type": "string", "format": "date-time", "title": "Updated At", "description": "Timestamp when the workspace was last updated" } }, "type": "object", "required": [ "id", "createdAt", "updatedAt" ], "title": "WorkspaceView", "description": "View model for a workspace \u2014 persistent shared storage across sessions." }, "X402BalanceRequest": { "properties": { "address": { "type": "string", "title": "Address", "description": "EVM wallet address that signed the message (0x...)." }, "issued_at": { "type": "string", "title": "Issued At", "description": "ISO-8601 UTC timestamp included in the signed message." }, "nonce": { "type": "string", "title": "Nonce", "description": "Random single-use nonce included in the signed message." }, "signature": { "type": "string", "title": "Signature", "description": "EIP-191 personal_sign signature of the canonical message." } }, "type": "object", "required": [ "address", "issued_at", "nonce", "signature" ], "title": "X402BalanceRequest", "description": "Wallet-signature auth payload for a free, read-only balance check" }, "X402BalanceResponse": { "properties": { "wallet": { "type": "string", "title": "Wallet", "description": "Lowercased wallet address (verified from the signature)." }, "project_id": { "type": "string", "format": "uuid", "title": "Project Id", "description": "Wallet-derived project the balance belongs to." }, "total_credits_usd": { "type": "number", "title": "Total Credits Usd", "description": "Total spendable credit balance in USD." }, "additional_credits_usd": { "type": "number", "title": "Additional Credits Usd", "description": "Standalone (x402 top-up / one_off) credit balance in USD." } }, "type": "object", "required": [ "wallet", "project_id", "total_credits_usd", "additional_credits_usd" ], "title": "X402BalanceResponse" } }, "securitySchemes": { "APIKeyHeader": { "type": "apiKey", "in": "header", "name": "X-Browser-Use-API-Key" } } } }