{ "openapi": "3.1.0", "info": { "title": "Browser Use Public API v4", "summary": "Browser Use agent runs API (v4)", "version": "4.0.0" }, "servers": [ { "url": "https://api.browser-use.com/api/v4", "description": "Production server" } ], "paths": { "/runs": { "post": { "tags": [ "Runs" ], "summary": "Create Run", "operationId": "create_run_runs_post", "security": [ { "APIKeyHeader": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RunCreateRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RunCreateResponse" } } } }, "402": { "description": "The project has no credits available." }, "403": { "description": "Zero Data Retention is enabled on the project (V4 unsupported)." }, "404": { "description": "Run, session, workspace, or profile not found." }, "409": { "description": "The session already has an active run." }, "400": { "description": "Invalid request (bad session/workspace pairing or file path)." }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "get": { "tags": [ "Runs" ], "summary": "List Runs", "operationId": "list_runs_runs_get", "security": [ { "APIKeyHeader": [] } ], "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "default": 50, "title": "Limit" } }, { "name": "cursor", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Keyset cursor from a prior response.", "title": "Cursor" }, "description": "Keyset cursor from a prior response." }, { "name": "sessionId", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "title": "Sessionid" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RunListResponse" } } } }, "403": { "description": "Zero Data Retention is enabled on the project (V4 unsupported)." }, "400": { "description": "Malformed pagination cursor." }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/runs/{run_id}/attachments": { "get": { "tags": [ "Runs" ], "summary": "List Run Attachments", "description": "The upload files attached to a run, for rendering attachment chips.\nOrdered to match the run's attached_file_ids.", "operationId": "list_run_attachments_runs__run_id__attachments_get", "security": [ { "APIKeyHeader": [] } ], "parameters": [ { "name": "run_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "title": "Run Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RunAttachmentsResponse" } } } }, "403": { "description": "Zero Data Retention is enabled on the project (V4 unsupported)." }, "404": { "description": "Run, session, workspace, or profile not found." }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/runs/{run_id}": { "get": { "tags": [ "Runs" ], "summary": "Get Run", "operationId": "get_run_runs__run_id__get", "security": [ { "APIKeyHeader": [] } ], "parameters": [ { "name": "run_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "title": "Run Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RunSummary" } } } }, "403": { "description": "Zero Data Retention is enabled on the project (V4 unsupported)." }, "404": { "description": "Run, session, workspace, or profile not found." }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/runs/{run_id}/status": { "get": { "tags": [ "Runs" ], "summary": "Get Run Status", "description": "Minimal status poll (see RunStatusResponse). POLL rate bucket: selects\nONLY the status/project columns \u2014 a 2s poll never drags the task/result\ntext (TOAST reads) that GET /runs/{id} pays. Poll until terminal, then\nfetch the full summary once.", "operationId": "get_run_status_runs__run_id__status_get", "security": [ { "APIKeyHeader": [] } ], "parameters": [ { "name": "run_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "title": "Run Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RunStatusResponse" } } } }, "403": { "description": "Zero Data Retention is enabled on the project (V4 unsupported)." }, "404": { "description": "Run, session, workspace, or profile not found." }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/runs/{run_id}/cancel": { "post": { "tags": [ "Runs" ], "summary": "Cancel Run", "description": "Cancel an in-flight run.\n\nIdempotent: a run already in a terminal state (completed / failed /\ncancelled) is returned as-is. Once cancelled, the gateway refuses\nevery subsequent `chat_completions` call from the worker \u2014 so the\nproject cannot be billed further regardless of whether the worker\nsubprocess notices the cancel itself.\n\nThe worker keeps running for at most one more bcode step\n(consuming no LLM tokens because CP 409s them) and then exits when\nbcode realizes the next tool call has no model behind it.", "operationId": "cancel_run_runs__run_id__cancel_post", "security": [ { "APIKeyHeader": [] } ], "parameters": [ { "name": "run_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "title": "Run Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RunSummary" } } } }, "403": { "description": "Zero Data Retention is enabled on the project (V4 unsupported)." }, "404": { "description": "Run, session, workspace, or profile not found." }, "502": { "description": "The request could not be forwarded to the control plane." }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/runs/{run_id}/events": { "get": { "tags": [ "Runs" ], "summary": "Get Run Events", "description": "Paginated event read. `after` is the event id cursor \u2014 clients\ndoing periodic polls pass back the highest id they've seen to get only\nthe delta. Default 0 returns from the start.", "operationId": "get_run_events_runs__run_id__events_get", "security": [ { "APIKeyHeader": [] } ], "parameters": [ { "name": "run_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "title": "Run Id" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "default": 200, "title": "Limit" } }, { "name": "after", "in": "query", "required": false, "schema": { "type": "integer", "default": 0, "title": "After" } }, { "name": "include_output", "in": "query", "required": false, "schema": { "type": "boolean", "default": true, "title": "Include Output" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RunEventsResponse" } } } }, "403": { "description": "Zero Data Retention is enabled on the project (V4 unsupported)." }, "404": { "description": "Run, session, workspace, or profile not found." }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/sessions": { "get": { "tags": [ "Sessions" ], "summary": "List Sessions", "description": "List the project's V4 sessions \u2014 one row per session (its most recent\nrun), most-recent first.\n\nA session is a conversation: follow-up runs reuse the same\npublic_session_id, so GET /api/v4/runs would list one row per RUN. This\ncollapses to one row per SESSION directly in Postgres with DISTINCT ON, so a\nchatty session with 100 runs is still a single row (no scan amplification),\nand selects only the slim columns the session list needs \u2014 never the heavy\nper-run text/token/cost fields.\n\nKeyset-paginated on the latest run's (created_at, id): pass `next_cursor`\nback as `cursor` to page. Offset/COUNT was dropped \u2014 it doesn't scale on\nprojects with many sessions.", "operationId": "list_sessions_sessions_get", "security": [ { "APIKeyHeader": [] } ], "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 100, "minimum": 1, "description": "Max sessions per page (max 100).", "default": 20, "title": "Limit" }, "description": "Max sessions per page (max 100)." }, { "name": "cursor", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Keyset cursor from a prior response.", "title": "Cursor" }, "description": "Keyset cursor from a prior response." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SessionListResponse" } } } }, "403": { "description": "Zero Data Retention is enabled on the project (V4 unsupported)." }, "400": { "description": "Malformed pagination cursor." }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/sessions/{session_id}/purge": { "post": { "tags": [ "Sessions" ], "summary": "Purge Session", "description": "Immediately purge all data for a V4 session (ZDR projects only).\n\nRedacts DB records and deletes S3 objects (bcode state, workspace files,\nrecordings, downloads, staging uploads) for every run in the session. Same\ncleanup the ZDR cron performs, but on-demand and with no grace period. V4\nanalog of the V2 POST /sessions/{id}/purge. Surfaces shared with a still-live\nsibling run are deferred by the same guards the cron uses.", "operationId": "purge_session_sessions__session_id__purge_post", "security": [ { "APIKeyHeader": [] } ], "parameters": [ { "name": "session_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "title": "Session Id" } } ], "responses": { "204": { "description": "Successful Response" }, "403": { "description": "Project is not ZDR-enabled." }, "404": { "description": "Session not found." }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/sessions/{session_id}": { "get": { "tags": [ "Sessions" ], "summary": "Get Session", "description": "Session detail \u2014 the same slim shape as one GET /sessions row (its\nlatest run). Doubles as the busy/idle poll for a conversation (POLL rate\nbucket): slim columns only, indexed public_session_id lookup, never the\nheavy result/token fields.", "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/SessionInfo" } } } }, "403": { "description": "Zero Data Retention is enabled on the project (V4 unsupported)." }, "404": { "description": "Run, session, workspace, or profile not found." }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/sessions/{session_id}/queue": { "post": { "tags": [ "Sessions" ], "summary": "Queue Session Message", "description": "Send a message to a session. If the session is busy it waits on the queue\nand runs as the next turn; if idle it drains immediately.\n\n`interrupt=true` cancels the session's active run so this message takes effect\nnow instead of waiting for the current turn (no-op when the session is idle).", "operationId": "queue_session_message_sessions__session_id__queue_post", "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/QueueMessageRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueuedMessage" } } } }, "403": { "description": "Zero Data Retention is enabled on the project (V4 unsupported)." }, "404": { "description": "Run, session, workspace, or profile not found." }, "429": { "description": "The session message queue is full." }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "get": { "tags": [ "Sessions" ], "summary": "List Session Queue", "description": "List open messages, the latest handoff row, and all steering cutoffs.\n\nIncludes live dispatch claims so clients can restore an accepted steering\nhandoff after a refresh without briefly losing its waiting state. The latest\nconsumed interrupt bridges the primary-write/read-replica gap before its\nreplacement run appears; clients discard it once that run is visible. Compact\nper-source cutoffs preserve every historical interrupted transcript boundary\nwithout returning every historical steering message and its attachments.", "operationId": "list_session_queue_sessions__session_id__queue_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/QueueListResponse" } } } }, "403": { "description": "Zero Data Retention is enabled on the project (V4 unsupported)." }, "404": { "description": "Run, session, workspace, or profile not found." }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/sessions/{session_id}/queue/{message_id}": { "get": { "tags": [ "Sessions" ], "summary": "Get Session Queue Message", "description": "Read one queued message including terminal handoff states.", "operationId": "get_session_queue_message_sessions__session_id__queue__message_id__get", "security": [ { "APIKeyHeader": [] } ], "parameters": [ { "name": "session_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "title": "Session Id" } }, { "name": "message_id", "in": "path", "required": true, "schema": { "type": "integer", "title": "Message Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueuedMessage" } } } }, "403": { "description": "Zero Data Retention is enabled on the project (V4 unsupported)." }, "404": { "description": "Run, session, workspace, or profile not found." }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "delete": { "tags": [ "Sessions" ], "summary": "Cancel Queued Message", "description": "Remove a still-pending queued message; 409 once the drain has claimed it.", "operationId": "cancel_queued_message_sessions__session_id__queue__message_id__delete", "security": [ { "APIKeyHeader": [] } ], "parameters": [ { "name": "session_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "title": "Session Id" } }, { "name": "message_id", "in": "path", "required": true, "schema": { "type": "integer", "title": "Message Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueuedMessage" } } } }, "403": { "description": "Zero Data Retention is enabled on the project (V4 unsupported)." }, "404": { "description": "Run, session, workspace, or profile not found." }, "409": { "description": "The message is no longer pending and cannot be cancelled." }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/workspaces": { "post": { "tags": [ "Workspaces" ], "summary": "Create Workspace", "description": "Mint an empty workspace. Lets callers upload input files BEFORE the\nfirst run exists; pass the id as workspaceId on POST /runs.", "operationId": "create_workspace_workspaces_post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkspaceCreateRequest" } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkspaceInfo" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "APIKeyHeader": [] } ] } }, "/workspaces/{workspace_id}/files/upload": { "post": { "tags": [ "Workspaces" ], "summary": "Upload Workspace Files", "description": "Presigned PUT URLs for input files, placed under ``uploads/`` in the\nworkspace. The agent pulls them in at the start of every run. URLs are\npinned to the declared Content-Type and exact Content-Length.", "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" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkspaceFileUploadRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkspaceFileUploadResponse" } } } }, "403": { "description": "Zero Data Retention is enabled on the project (V4 unsupported)." }, "404": { "description": "Run, session, workspace, or profile not found." }, "400": { "description": "Invalid request (bad session/workspace pairing or file path)." }, "409": { "description": "One or more files would replace existing workspace files." }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/workspaces/{workspace_id}": { "get": { "tags": [ "Workspaces" ], "summary": "Get Workspace", "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/WorkspaceInfo" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "patch": { "tags": [ "Workspaces" ], "summary": "Update Workspace", "description": "Rename a workspace. Explicit null clears the name; omission is a no-op.", "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/WorkspaceInfo" } } } }, "404": { "description": "Run, session, workspace, or profile not found." }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "delete": { "tags": [ "Workspaces" ], "summary": "Delete Workspace", "description": "Archive a workspace. Idempotent for missing, archived, and foreign ids.", "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}/size": { "get": { "tags": [ "Workspaces" ], "summary": "Get Workspace Size", "description": "Return current storage usage and the plan-specific workspace quota.", "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": { "$ref": "#/components/schemas/WorkspaceSizeInfo" } } } }, "404": { "description": "Run, session, workspace, or profile not found." }, "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 the agent has produced for this workspace, paginated.", "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": "contentDisposition", "in": "query", "required": false, "schema": { "anyOf": [ { "const": "attachment", "type": "string" }, { "type": "null" } ], "title": "Contentdisposition" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkspaceFileListResponse" } } } }, "403": { "description": "Zero Data Retention is enabled on the project (V4 unsupported)." }, "404": { "description": "Run, session, workspace, or profile not found." }, "400": { "description": "Malformed pagination cursor." }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "delete": { "tags": [ "Workspaces" ], "summary": "Delete Workspace File", "description": "Delete one exact path from a workspace and remove matching upload metadata.", "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", "minLength": 1, "description": "Relative file path to delete", "title": "Path" }, "description": "Relative file path to delete" } ], "responses": { "204": { "description": "Successful Response" }, "404": { "description": "Run, session, workspace, or profile not found." }, "400": { "description": "Invalid request (bad session/workspace pairing or file path)." }, "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" } } } } } } } }, "components": { "schemas": { "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." }, "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." }, "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" }, "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 }, "metadata": { "anyOf": [ { "additionalProperties": { "type": "string" }, "maxProperties": 10, "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." } }, "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." }, "ExternalBrowserAttach": { "properties": { "cdpUrl": { "type": "string", "maxLength": 2083, "minLength": 1, "format": "uri", "title": "Cdpurl" }, "liveViewUrl": { "anyOf": [ { "type": "string", "maxLength": 2083, "minLength": 1, "format": "uri" }, { "type": "null" } ], "title": "Liveviewurl" } }, "type": "object", "required": [ "cdpUrl" ], "title": "ExternalBrowserAttach", "description": "DEV-ONLY: hand v4 a pre-provisioned browser instead of having CP\ncall UseBrowserService. Gated to env=='development' in the router." }, "HTTPValidationError": { "properties": { "detail": { "items": { "$ref": "#/components/schemas/ValidationError" }, "type": "array", "title": "Detail" } }, "type": "object", "title": "HTTPValidationError" }, "InlineSecretSource": { "properties": { "type": { "type": "string", "const": "inline", "title": "Type" }, "value": { "type": "string", "maxLength": 4096, "minLength": 1, "format": "password", "title": "Value", "description": "The secret itself. Limited to 4096 bytes once encoded for encryption; non-ASCII characters cost more than one byte each.", "writeOnly": true } }, "additionalProperties": false, "type": "object", "required": [ "type", "value" ], "title": "InlineSecretSource", "description": "A value the caller supplies directly with the run." }, "InsufficientCreditsError": { "properties": { "detail": { "type": "string", "title": "Detail", "default": "Insufficient credits" } }, "type": "object", "title": "InsufficientCreditsError", "description": "Error response when there are insufficient credits" }, "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" }, "QueueListResponse": { "properties": { "queue": { "items": { "$ref": "#/components/schemas/QueuedMessage" }, "type": "array", "title": "Queue" }, "steeringCutoffs": { "items": { "$ref": "#/components/schemas/SteeringCutoff" }, "type": "array", "title": "Steeringcutoffs" } }, "type": "object", "required": [ "queue" ], "title": "QueueListResponse" }, "QueueMessageRequest": { "properties": { "text": { "type": "string", "minLength": 1, "title": "Text" }, "interrupt": { "type": "boolean", "title": "Interrupt", "default": false }, "attachedFileIds": { "anyOf": [ { "items": { "type": "string", "format": "uuid" }, "type": "array", "maxItems": 20 }, { "type": "null" } ], "title": "Attachedfileids" } }, "additionalProperties": false, "type": "object", "required": [ "text" ], "title": "QueueMessageRequest", "description": "Send a message to a session. If the session is busy the message waits on\nthe queue and runs as the next turn; if idle it runs immediately.\n\nSet `interrupt` to make it take effect now: the session's active run is\ncancelled and this message drains straight after. Interrupt is a no-op when\nthe session is already idle, and BEST-EFFORT when busy \u2014 if the cancel can't\nbe delivered, the message stays queued and runs after the current turn." }, "QueuedMessage": { "properties": { "id": { "type": "integer", "title": "Id" }, "sessionId": { "type": "string", "format": "uuid", "title": "Sessionid" }, "runId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "title": "Runid" }, "mode": { "type": "string", "enum": [ "queue", "interrupt" ], "title": "Mode" }, "status": { "type": "string", "enum": [ "pending", "dispatching", "consumed", "cancelled", "superseded", "failed" ], "title": "Status" }, "text": { "type": "string", "title": "Text" }, "attachedFileIds": { "anyOf": [ { "items": { "type": "string", "format": "uuid" }, "type": "array" }, { "type": "null" } ], "title": "Attachedfileids" }, "createdAt": { "type": "string", "format": "date-time", "title": "Createdat" } }, "type": "object", "required": [ "id", "sessionId", "runId", "mode", "status", "text", "createdAt" ], "title": "QueuedMessage", "description": "One message on a session's queue (a v4_session_input row)." }, "RunAttachment": { "properties": { "id": { "type": "string", "format": "uuid", "title": "Id" }, "name": { "type": "string", "title": "Name", "description": "Filename shown to the user, e.g. \"data.csv\"." }, "contentType": { "type": "string", "title": "Contenttype" }, "sizeBytes": { "type": "integer", "title": "Sizebytes" }, "status": { "type": "string", "enum": [ "pending", "uploaded" ], "title": "Status", "description": "\"pending\" | \"uploaded\"." } }, "type": "object", "required": [ "id", "name", "contentType", "sizeBytes", "status" ], "title": "RunAttachment" }, "RunAttachmentsResponse": { "properties": { "attachments": { "items": { "$ref": "#/components/schemas/RunAttachment" }, "type": "array", "title": "Attachments" } }, "type": "object", "required": [ "attachments" ], "title": "RunAttachmentsResponse" }, "RunBrowserSettings": { "properties": { "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." }, "proxyCountryCode": { "anyOf": [ { "$ref": "#/components/schemas/ProxyCountryCode" }, { "type": "null" } ], "description": "ISO country code to proxy the browser through. Defaults to US. Pass null to run without a proxy.", "default": "us" }, "customProxy": { "anyOf": [ { "$ref": "#/components/schemas/CustomProxy" }, { "type": "null" } ], "description": "Custom proxy for the browser. Overrides proxyCountryCode. Requires an active subscription. Never stored or inherited by follow-up runs; pass it on each run that should use it." }, "screenWidth": { "anyOf": [ { "type": "integer", "maximum": 6144.0, "minimum": 320.0 }, { "type": "null" } ], "title": "Screenwidth", "description": "Custom screen width in pixels for the browser." }, "screenHeight": { "anyOf": [ { "type": "integer", "maximum": 3456.0, "minimum": 320.0 }, { "type": "null" } ], "title": "Screenheight", "description": "Custom screen height in pixels for the browser." }, "record": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Record", "description": "Record the browser session to an mp4, retrievable via GET /browsers/{id} once the browser stops. API runs default to off; pass true to enable. Like other browser settings, this only applies when a new browser is provisioned: a follow-up that reuses the session's live browser keeps that browser's recording state. Ignored (always off) for Zero Data Retention projects." } }, "additionalProperties": false, "type": "object", "title": "RunBrowserSettings", "description": "Browser config, owned by the browser row (never the run). Follow-ups:\nomitted fields inherit the session's prior browser; explicit values apply\nonly to newly provisioned browsers (a live browser is reused as-is).\nProfile is the exception: a different profile \u2192 400; an explicit value\nmismatching the live browser's profile (incl. null vs a profiled browser)\ndeclines reuse and provisions fresh. A live browser already matching the\nrequested profile is reused." }, "RunCreateRequest": { "properties": { "task": { "type": "string", "minLength": 1, "title": "Task" }, "model": { "type": "string", "enum": [ "glm-5.2", "grok-4.5", "kimi-k3", "minimax-m3", "claude-opus-4.7", "claude-opus-4.8", "claude-opus-5", "claude-fable-5", "claude-sonnet-5", "gpt-5.5", "gpt-5.6", "gpt-5.6-sol", "gpt-5.6-terra", "gpt-5.6-luna", "gemini-3.6-flash", "gemini-3.5-flash", "gemini-3.1-pro", "gemini-3-flash" ], "title": "Model", "default": "gpt-5.6-luna" }, "modelParams": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Modelparams", "description": "Optional provider-native request parameters for the selected model, written with the provider's own field names and values and forwarded unchanged (e.g. {\"reasoning\": {\"effort\": \"high\"}} for OpenAI, {\"thinking\": {\"type\": \"adaptive\"}} for Anthropic, {\"thinkingConfig\": {\"thinkingLevel\": \"high\"}} for Google). Supported paths and values are per-model; an unsupported path, value, or a model that accepts no parameters at all is rejected with 422. Omitting this field applies the model's default parameters (gpt-5.6-luna defaults to {\"reasoning\": {\"effort\": \"xhigh\"}}); passing {} opts out of that default and leaves the provider's own defaults in place." }, "sessionId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "title": "Sessionid" }, "workspaceId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "title": "Workspaceid" }, "browserSettings": { "anyOf": [ { "$ref": "#/components/schemas/RunBrowserSettings" }, { "type": "null" } ] }, "agentmail": { "type": "boolean", "title": "Agentmail", "description": "If true, provisions a persistent temporary email inbox (via AgentMail) for the run workspace. The agent receives the email address in its context and can send, receive, read, and reply to email. Set false to disable AgentMail for this run.", "default": false }, "attachedFileIds": { "anyOf": [ { "items": { "type": "string", "format": "uuid" }, "type": "array", "maxItems": 20 }, { "type": "null" } ], "title": "Attachedfileids" }, "secretBindings": { "anyOf": [ { "items": { "$ref": "#/components/schemas/SecretBinding" }, "type": "array", "maxItems": 10 }, { "type": "null" } ], "title": "Secretbindings", "description": "Credentials this run may use without ever seeing them. The agent can ask the server to type a binding by alias on one of its allowed domains; it cannot read the value. Bindings are not persisted past the run." }, "judge": { "anyOf": [ { "$ref": "#/components/schemas/RunJudgeSettings" }, { "type": "null" } ] }, "maxCostUsd": { "anyOf": [ { "type": "number", "exclusiveMinimum": 0.0 }, { "type": "string", "pattern": "^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$" }, { "type": "null" } ], "title": "Maxcostusd" } }, "additionalProperties": false, "type": "object", "required": [ "task" ], "title": "RunCreateRequest" }, "RunCreateResponse": { "properties": { "id": { "type": "string", "format": "uuid", "title": "Id" }, "status": { "type": "string", "enum": [ "queued", "dispatching", "running", "completed", "failed", "cancelled" ], "title": "Status" }, "model": { "type": "string", "title": "Model" }, "sessionId": { "type": "string", "format": "uuid", "title": "Sessionid" }, "workspaceId": { "type": "string", "format": "uuid", "title": "Workspaceid" }, "eventsUrl": { "type": "string", "title": "Eventsurl" }, "missingFileIds": { "items": { "type": "string", "format": "uuid" }, "type": "array", "title": "Missingfileids" } }, "type": "object", "required": [ "id", "status", "model", "sessionId", "workspaceId", "eventsUrl" ], "title": "RunCreateResponse" }, "RunEvent": { "properties": { "runId": { "type": "string", "format": "uuid", "title": "Runid" }, "id": { "type": "integer", "title": "Id" }, "ts": { "type": "string", "format": "date-time", "title": "Ts" }, "type": { "type": "string", "title": "Type" }, "data": { "additionalProperties": true, "type": "object", "title": "Data" } }, "type": "object", "required": [ "runId", "id", "ts", "type", "data" ], "title": "RunEvent" }, "RunEventsResponse": { "properties": { "events": { "items": { "$ref": "#/components/schemas/RunEvent" }, "type": "array", "title": "Events" }, "nextAfter": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Nextafter" }, "hasMore": { "type": "boolean", "title": "Hasmore", "default": false } }, "type": "object", "required": [ "events" ], "title": "RunEventsResponse" }, "RunJudgeSettings": { "properties": { "context": { "anyOf": [ { "type": "string", "maxLength": 10000 }, { "type": "null" } ], "title": "Context" } }, "additionalProperties": false, "type": "object", "title": "RunJudgeSettings", "description": "Opt-in LLM judgement of the finished run. Presence of this object turns\nthe judge on (send {} for defaults); CP judges the run's trajectory after\nit goes terminal and surfaces the verdict as RunSummary.judgement (null\nuntil it lands). The judge's LLM call is billed to the run." }, "RunListResponse": { "properties": { "runs": { "items": { "$ref": "#/components/schemas/RunSummary" }, "type": "array", "title": "Runs" }, "nextCursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Nextcursor" }, "hasMore": { "type": "boolean", "title": "Hasmore", "default": false } }, "type": "object", "required": [ "runs" ], "title": "RunListResponse" }, "RunStatusResponse": { "properties": { "status": { "type": "string", "enum": [ "queued", "dispatching", "running", "completed", "failed", "cancelled" ], "title": "Status" } }, "type": "object", "required": [ "status" ], "title": "RunStatusResponse", "description": "Minimal poll target: just the run's status. Poll this until terminal\n(cheap indexed lookup, tiny payload \u2014 never the task/result text), then\nfetch the full RunSummary once via GET /runs/{id}. Mirrors v2's\nGET /tasks/{id}/status." }, "RunSummary": { "properties": { "id": { "type": "string", "format": "uuid", "title": "Id" }, "task": { "type": "string", "title": "Task" }, "title": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Title" }, "model": { "type": "string", "title": "Model" }, "contextLimit": { "type": "integer", "title": "Contextlimit" }, "status": { "type": "string", "enum": [ "queued", "dispatching", "running", "completed", "failed", "cancelled" ], "title": "Status" }, "result": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Result" }, "error": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Error" }, "sessionId": { "type": "string", "format": "uuid", "title": "Sessionid" }, "workspaceId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "title": "Workspaceid" }, "attachedFileIds": { "anyOf": [ { "items": { "type": "string", "format": "uuid" }, "type": "array" }, { "type": "null" } ], "title": "Attachedfileids" }, "judgement": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Judgement" }, "totalInputTokens": { "type": "integer", "title": "Totalinputtokens" }, "totalOutputTokens": { "type": "integer", "title": "Totaloutputtokens" }, "totalCostUsd": { "type": "string", "title": "Totalcostusd" }, "createdAt": { "type": "string", "format": "date-time", "title": "Createdat" }, "updatedAt": { "type": "string", "format": "date-time", "title": "Updatedat" } }, "type": "object", "required": [ "id", "task", "title", "model", "contextLimit", "status", "result", "error", "sessionId", "workspaceId", "totalInputTokens", "totalOutputTokens", "totalCostUsd", "createdAt", "updatedAt" ], "title": "RunSummary" }, "SecretBinding": { "properties": { "alias": { "type": "string", "title": "Alias", "description": "Name the agent refers to this secret by, e.g. \"github_password\"." }, "source": { "$ref": "#/components/schemas/InlineSecretSource" }, "allowedDomains": { "items": { "type": "string" }, "type": "array", "maxItems": 10, "minItems": 1, "title": "Alloweddomains", "description": "Hosts the secret may be typed into, e.g. [\"github.com\"]. A host covers its subdomains. Bare hostnames only \u2014 no scheme, port, path, or wildcard." } }, "additionalProperties": false, "type": "object", "required": [ "alias", "source", "allowedDomains" ], "title": "SecretBinding", "description": "One credential this run may have typed into a browser field.\n\nThe value never reaches the agent. It is encrypted at rest, kept out of the\nworker payload, and typed straight into the focused field by the server when\nthe agent asks for the alias by name \u2014 and only while the page it is typing\ninto is on one of `allowedDomains`.\n\nRun-scoped: bindings die with the run, so a follow-up run that needs the same\ncredential must send it again." }, "SessionInfo": { "properties": { "sessionId": { "type": "string", "format": "uuid", "title": "Sessionid" }, "workspaceId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "title": "Workspaceid" }, "latestRunId": { "type": "string", "format": "uuid", "title": "Latestrunid" }, "task": { "type": "string", "title": "Task" }, "title": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Title" }, "status": { "type": "string", "enum": [ "queued", "dispatching", "running", "completed", "failed", "cancelled" ], "title": "Status" }, "createdAt": { "type": "string", "format": "date-time", "title": "Createdat" }, "updatedAt": { "type": "string", "format": "date-time", "title": "Updatedat" } }, "type": "object", "required": [ "sessionId", "workspaceId", "latestRunId", "task", "title", "status", "createdAt", "updatedAt" ], "title": "SessionInfo", "description": "Lightweight metadata for one V4 session (its most recent run).\n\nDeliberately slim \u2014 just what a session list needs (open the conversation,\nshow a label + status + time). The heavy per-run fields (result, error,\ntoken/cost totals) live on RunSummary and aren't repeated here." }, "SessionListResponse": { "properties": { "sessions": { "items": { "$ref": "#/components/schemas/SessionInfo" }, "type": "array", "title": "Sessions" }, "nextCursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Nextcursor" }, "hasMore": { "type": "boolean", "title": "Hasmore", "default": false } }, "type": "object", "required": [ "sessions" ], "title": "SessionListResponse", "description": "One entry per session (the session's most recent run), most-recent first.\n\nA V4 session is a conversation: every follow-up run reuses the same\npublic_session_id. GET /api/v4/runs returns one row per RUN, so callers that\nwant a list of distinct *sessions* (e.g. the recent-sessions panel) should\nuse this instead of de-duplicating runs client-side." }, "SessionNotFoundError": { "properties": { "detail": { "type": "string", "title": "Detail", "default": "Session not found" } }, "type": "object", "title": "SessionNotFoundError", "description": "Error response when a session is not found" }, "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" }, "SteeringCutoff": { "properties": { "sourceRunId": { "type": "string", "format": "uuid", "title": "Sourcerunid" }, "createdAt": { "type": "string", "format": "date-time", "title": "Createdat" } }, "type": "object", "required": [ "sourceRunId", "createdAt" ], "title": "SteeringCutoff", "description": "Earliest accepted steer for one interrupted source run.\n\nThe queue endpoint returns these compact boundaries separately from message\nrows so a remount can keep every interrupted transcript frozen without\nre-sending the full historical steering-message payload." }, "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" } }, "type": "object", "title": "WorkspaceCreateRequest" }, "WorkspaceFileInfo": { "properties": { "path": { "type": "string", "title": "Path", "description": "File path relative to the 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": "WorkspaceFileInfo", "description": "A file the agent has produced for the workspace. Shape mirrors V3\nfiles (FileInfo) so a single UI component can render both." }, "WorkspaceFileListResponse": { "properties": { "files": { "items": { "$ref": "#/components/schemas/WorkspaceFileInfo" }, "type": "array", "title": "Files" }, "nextCursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Nextcursor" }, "hasMore": { "type": "boolean", "title": "Hasmore", "default": false } }, "type": "object", "required": [ "files" ], "title": "WorkspaceFileListResponse" }, "WorkspaceFileUploadItem": { "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": { "type": "integer", "maximum": 52428800.0, "minimum": 1.0, "title": "Size", "description": "Exact file size in bytes; the presigned URL is pinned to it." } }, "type": "object", "required": [ "name", "size" ], "title": "WorkspaceFileUploadItem" }, "WorkspaceFileUploadRequest": { "properties": { "files": { "items": { "$ref": "#/components/schemas/WorkspaceFileUploadItem" }, "type": "array", "maxItems": 10, "minItems": 1, "title": "Files" }, "allowOverrides": { "type": "boolean", "title": "Allowoverrides", "description": "When false, return 409 before reserving storage if any uploaded filename would replace an existing workspace file.", "default": true } }, "type": "object", "required": [ "files" ], "title": "WorkspaceFileUploadRequest" }, "WorkspaceFileUploadResponse": { "properties": { "files": { "items": { "$ref": "#/components/schemas/WorkspaceFileUploadResponseItem" }, "type": "array", "title": "Files" } }, "type": "object", "required": [ "files" ], "title": "WorkspaceFileUploadResponse" }, "WorkspaceFileUploadResponseItem": { "properties": { "id": { "type": "string", "format": "uuid", "title": "Id", "description": "Upload id. Pass THIS in RunCreateRequest.attachedFileIds to attach the file to a run." }, "name": { "type": "string", "title": "Name", "description": "Original filename from the request" }, "storedName": { "type": "string", "title": "Storedname", "description": "Sanitized filename the object is stored under, e.g. \"data.csv\"." }, "path": { "type": "string", "title": "Path", "description": "Path within the workspace, e.g. \"uploads/data.csv\"" }, "willOverride": { "type": "boolean", "title": "Willoverride", "description": "True if a file with this stored_name already exists in the workspace and uploading will replace it. Surface a warning to the user." }, "uploadUrl": { "type": "string", "title": "Uploadurl", "description": "Presigned PUT URL (5 min expiry). PUT the file bytes with the matching Content-Type and Content-Length headers." } }, "type": "object", "required": [ "id", "name", "storedName", "path", "willOverride", "uploadUrl" ], "title": "WorkspaceFileUploadResponseItem" }, "WorkspaceInfo": { "properties": { "id": { "type": "string", "format": "uuid", "title": "Id" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Name" }, "archived": { "type": "boolean", "title": "Archived" }, "createdAt": { "type": "string", "format": "date-time", "title": "Createdat" }, "updatedAt": { "type": "string", "format": "date-time", "title": "Updatedat" } }, "type": "object", "required": [ "id", "archived", "createdAt", "updatedAt" ], "title": "WorkspaceInfo" }, "WorkspaceSizeInfo": { "properties": { "usedBytes": { "type": "integer", "minimum": 0.0, "title": "Usedbytes", "description": "Current workspace storage usage in bytes." }, "maxBytes": { "type": "integer", "exclusiveMinimum": 0.0, "title": "Maxbytes", "description": "Maximum workspace storage allowed in bytes." } }, "type": "object", "required": [ "usedBytes", "maxBytes" ], "title": "WorkspaceSizeInfo" }, "WorkspaceUpdateRequest": { "properties": { "name": { "anyOf": [ { "type": "string", "maxLength": 100 }, { "type": "null" } ], "title": "Name" } }, "type": "object", "title": "WorkspaceUpdateRequest" } }, "securitySchemes": { "APIKeyHeader": { "type": "apiKey", "in": "header", "name": "X-Browser-Use-API-Key" } } } }