harivansh-afk/sandbox-agent
1
0
Fork 0
mirror of https://github.com/harivansh-afk/sandbox-agent.git synced 2026-04-15 14:03:52 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions
sandbox-agent/docs/openapi.json
Nathan Flurry 45cc8a8383 feat: [US-019] - Add TypeScript SDK browser types 
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
2026-03-17 06:15:04 -07:00

8097 lines
216 KiB
JSON
Raw Blame History

{
"openapi": "3.0.3",
"info": {
"title": "sandbox-agent",
"description": "Universal API for automatic coding agents in sandboxes. Supports Claude Code, Codex, OpenCode, and Amp.",
"contact": {
"name": "Rivet Gaming, LLC",
"email": "developer@rivet.gg"
},
"license": {
"name": "Apache-2.0"
},
"version": "0.5.0-rc.1"
},
"servers": [
{
"url": "http://localhost:2468"
}
],
"paths": {
"/v1/acp": {
"get": {
"tags": ["v1"],
"operationId": "get_v1_acp_servers",
"responses": {
"200": {
"description": "Active ACP server instances",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/AcpServerListResponse"
}
}
}
}
}
}
},
"/v1/acp/{server_id}": {
"get": {
"tags": ["v1"],
"operationId": "get_v1_acp",
"parameters": [
{
"name": "server_id",
"in": "path",
"description": "Client-defined ACP server id",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "SSE stream of ACP envelopes"
},
"400": {
"description": "Invalid request",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
}
},
"404": {
"description": "Unknown ACP server",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
}
},
"406": {
"description": "Client does not accept SSE responses",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
}
}
}
},
"post": {
"tags": ["v1"],
"operationId": "post_v1_acp",
"parameters": [
{
"name": "server_id",
"in": "path",
"description": "Client-defined ACP server id",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "agent",
"in": "query",
"description": "Agent id required for first POST",
"required": false,
"schema": {
"type": "string",
"nullable": true
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/AcpEnvelope"
}
}
},
"required": true
},
"responses": {
"200": {
"description": "JSON-RPC response envelope",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/AcpEnvelope"
}
}
}
},
"202": {
"description": "JSON-RPC notification accepted"
},
"400": {
"description": "Invalid ACP envelope",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
}
},
"404": {
"description": "Unknown ACP server",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
}
},
"406": {
"description": "Client does not accept JSON responses",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
}
},
"409": {
"description": "ACP server bound to different agent",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
}
},
"415": {
"description": "Unsupported media type",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
}
},
"504": {
"description": "ACP agent process response timeout",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
}
}
}
},
"delete": {
"tags": ["v1"],
"operationId": "delete_v1_acp",
"parameters": [
{
"name": "server_id",
"in": "path",
"description": "Client-defined ACP server id",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"204": {
"description": "ACP server closed"
}
}
}
},
"/v1/agents": {
"get": {
"tags": ["v1"],
"operationId": "get_v1_agents",
"parameters": [
{
"name": "config",
"in": "query",
"description": "When true, include version/path/configOptions (slower)",
"required": false,
"schema": {
"type": "boolean",
"nullable": true
}
},
{
"name": "no_cache",
"in": "query",
"description": "When true, bypass version cache",
"required": false,
"schema": {
"type": "boolean",
"nullable": true
}
}
],
"responses": {
"200": {
"description": "List of v1 agents",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/AgentListResponse"
}
}
}
},
"401": {
"description": "Authentication required",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
}
}
}
}
},
"/v1/agents/{agent}": {
"get": {
"tags": ["v1"],
"operationId": "get_v1_agent",
"parameters": [
{
"name": "agent",
"in": "path",
"description": "Agent id",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "config",
"in": "query",
"description": "When true, include version/path/configOptions (slower)",
"required": false,
"schema": {
"type": "boolean",
"nullable": true
}
},
{
"name": "no_cache",
"in": "query",
"description": "When true, bypass version cache",
"required": false,
"schema": {
"type": "boolean",
"nullable": true
}
}
],
"responses": {
"200": {
"description": "Agent info",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/AgentInfo"
}
}
}
},
"400": {
"description": "Unknown agent",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
}
},
"401": {
"description": "Authentication required",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
}
}
}
}
},
"/v1/agents/{agent}/install": {
"post": {
"tags": ["v1"],
"operationId": "post_v1_agent_install",
"parameters": [
{
"name": "agent",
"in": "path",
"description": "Agent id",
"required": true,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/AgentInstallRequest"
}
}
},
"required": true
},
"responses": {
"200": {
"description": "Agent install result",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/AgentInstallResponse"
}
}
}
},
"400": {
"description": "Invalid request",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
}
},
"500": {
"description": "Install failed",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
}
}
}
}
},
"/v1/browser/back": {
"post": {
"tags": ["v1"],
"summary": "Navigate the browser back in history.",
"description": "Sends a CDP `Page.navigateToHistoryEntry` command with the previous\nhistory entry and returns the resulting page URL and title.",
"operationId": "post_v1_browser_back",
"responses": {
"200": {
"description": "Page info after navigating back",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/BrowserPageInfo"
}
}
}
},
"409": {
"description": "Browser runtime is not active",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
}
},
"502": {
"description": "CDP command failed",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
}
}
}
}
},
"/v1/browser/cdp": {
"get": {
"tags": ["v1"],
"summary": "Open a CDP WebSocket proxy session.",
"description": "Upgrades the connection to a WebSocket that relays bidirectionally to\nChromium's internal CDP WebSocket endpoint. External tools like Playwright\nor Puppeteer can connect via `ws://sandbox-host:2468/v1/browser/cdp`.",
"operationId": "get_v1_browser_cdp_ws",
"responses": {
"101": {
"description": "WebSocket upgraded"
},
"409": {
"description": "Browser runtime is not active",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
}
},
"502": {
"description": "CDP connection failed",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
}
}
}
}
},
"/v1/browser/click": {
"post": {
"tags": ["v1"],
"summary": "Click an element in the browser page.",
"description": "Finds the element matching `selector`, computes its center point via\n`DOM.getBoxModel`, and dispatches mouse events through `Input.dispatchMouseEvent`.",
"operationId": "post_v1_browser_click",
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/BrowserClickRequest"
}
}
},
"required": true
},
"responses": {
"200": {
"description": "Click performed",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/BrowserActionResponse"
}
}
}
},
"404": {
"description": "Element not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
}
},
"409": {
"description": "Browser runtime is not active",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
}
},
"502": {
"description": "CDP command failed",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
}
}
}
}
},
"/v1/browser/console": {
"get": {
"tags": ["v1"],
"summary": "Get browser console messages.",
"description": "Returns console messages captured from the browser, optionally filtered by\nlevel (log, debug, info, warning, error) and limited in count.",
"operationId": "get_v1_browser_console",
"parameters": [
{
"name": "level",
"in": "query",
"required": false,
"schema": {
"type": "string",
"nullable": true
}
},
{
"name": "limit",
"in": "query",
"required": false,
"schema": {
"type": "integer",
"format": "int32",
"nullable": true,
"minimum": 0
}
}
],
"responses": {
"200": {
"description": "Console messages retrieved",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/BrowserConsoleResponse"
}
}
}
},
"409": {
"description": "Browser not active",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
}
},
"500": {
"description": "Internal error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
}
}
}
}
},
"/v1/browser/content": {
"get": {
"tags": ["v1"],
"summary": "Get the HTML content of the current browser page.",
"description": "Returns the outerHTML of the page or a specific element selected by a CSS\nselector, along with the current URL and title.",
"operationId": "get_v1_browser_content",
"parameters": [
{
"name": "selector",
"in": "query",
"required": false,
"schema": {
"type": "string",
"nullable": true
}
}
],
"responses": {
"200": {
"description": "Page HTML content",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/BrowserContentResponse"
}
}
}
},
"409": {
"description": "Browser runtime is not active",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
}
},
"502": {
"description": "CDP command failed",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
}
}
}
}
},
"/v1/browser/contexts": {
"get": {
"tags": ["v1"],
"summary": "List browser contexts (persistent profiles).",
"description": "Returns all browser context directories with their name, creation date,\nand on-disk size.",
"operationId": "get_v1_browser_contexts",
"responses": {
"200": {
"description": "Browser contexts listed",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/BrowserContextListResponse"
}
}
}
},
"500": {
"description": "Internal error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
}
}
}
},
"post": {
"tags": ["v1"],
"summary": "Create a browser context (persistent profile).",
"description": "Creates a new browser context directory that can be passed as contextId\nto the browser start endpoint for persistent cookies and storage.",
"operationId": "post_v1_browser_contexts",
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/BrowserContextCreateRequest"
}
}
},
"required": true
},
"responses": {
"201": {
"description": "Browser context created",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/BrowserContextInfo"
}
}
}
},
"500": {
"description": "Internal error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
}
}
}
}
},
"/v1/browser/contexts/{context_id}": {
"delete": {
"tags": ["v1"],
"summary": "Delete a browser context (persistent profile).",
"description": "Removes the browser context directory and all stored data (cookies,\nlocal storage, cache, etc.).",
"operationId": "delete_v1_browser_context",
"parameters": [
{
"name": "context_id",
"in": "path",
"description": "Browser context ID",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Browser context deleted",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/BrowserActionResponse"
}
}
}
},
"404": {
"description": "Browser context not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
}
},
"500": {
"description": "Internal error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
}
}
}
}
},
"/v1/browser/cookies": {
"get": {
"tags": ["v1"],
"summary": "Get browser cookies.",
"description": "Returns cookies from the browser, optionally filtered by URL.\nUses CDP Network.getCookies.",
"operationId": "get_v1_browser_cookies",
"parameters": [
{
"name": "url",
"in": "query",
"required": false,
"schema": {
"type": "string",
"nullable": true
}
}
],
"responses": {
"200": {
"description": "Cookies retrieved",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/BrowserCookiesResponse"
}
}
}
},
"409": {
"description": "Browser not active",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
}
},
"502": {
"description": "CDP command failed",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
}
}
}
},
"post": {
"tags": ["v1"],
"summary": "Set browser cookies.",
"description": "Sets one or more cookies in the browser via CDP Network.setCookies.",
"operationId": "post_v1_browser_cookies",
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/BrowserSetCookiesRequest"
}
}
},
"required": true
},
"responses": {
"200": {
"description": "Cookies set",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/BrowserActionResponse"
}
}
}
},
"409": {
"description": "Browser not active",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
}
},
"502": {
"description": "CDP command failed",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
}
}
}
},
"delete": {
"tags": ["v1"],
"summary": "Delete browser cookies.",
"description": "Deletes cookies matching the given name and/or domain. If no filters are\nprovided, clears all browser cookies.",
"operationId": "delete_v1_browser_cookies",
"parameters": [
{
"name": "name",
"in": "query",
"required": false,
"schema": {
"type": "string",
"nullable": true
}
},
{
"name": "domain",
"in": "query",
"required": false,
"schema": {
"type": "string",
"nullable": true
}
}
],
"responses": {
"200": {
"description": "Cookies deleted",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/BrowserActionResponse"
}
}
}
},
"409": {
"description": "Browser not active",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
}
},
"502": {
"description": "CDP command failed",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
}
}
}
}
},
"/v1/browser/crawl": {
"post": {
"tags": ["v1"],
"summary": "Crawl multiple pages starting from a URL.",
"description": "Performs a breadth-first crawl: navigates to each page, extracts content in\nthe requested format, collects links, and follows them within the configured\ndomain and depth limits.",
"operationId": "post_v1_browser_crawl",
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/BrowserCrawlRequest"
}
}
},
"required": true
},
"responses": {
"200": {
"description": "Crawl results",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/BrowserCrawlResponse"
}
}
}
},
"409": {
"description": "Browser runtime is not active",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
}
},
"502": {
"description": "CDP command failed",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
}
}
}
}
},
"/v1/browser/dialog": {
"post": {
"tags": ["v1"],
"summary": "Handle a JavaScript dialog (alert, confirm, prompt) in the browser.",
"description": "Accepts or dismisses the currently open dialog using\n`Page.handleJavaScriptDialog`, optionally providing prompt text.",
"operationId": "post_v1_browser_dialog",
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/BrowserDialogRequest"
}
}
},
"required": true
},
"responses": {
"200": {
"description": "Dialog handled",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/BrowserActionResponse"
}
}
}
},
"409": {
"description": "Browser runtime is not active",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
}
},
"502": {
"description": "CDP command failed",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
}
}
}
}
},
"/v1/browser/execute": {
"post": {
"tags": ["v1"],
"summary": "Execute a JavaScript expression in the browser.",
"description": "Evaluates the given expression via CDP `Runtime.evaluate` and returns the\nresult value and its type. Set `awaitPromise` to resolve async expressions.",
"operationId": "post_v1_browser_execute",
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/BrowserExecuteRequest"
}
}
},
"required": true
},
"responses": {
"200": {
"description": "Execution result",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/BrowserExecuteResponse"
}
}
}
},
"409": {
"description": "Browser runtime is not active",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
}
},
"502": {
"description": "CDP command failed",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
}
}
}
}
},
"/v1/browser/forward": {
"post": {
"tags": ["v1"],
"summary": "Navigate the browser forward in history.",
"description": "Sends a CDP `Page.navigateToHistoryEntry` command with the next\nhistory entry and returns the resulting page URL and title.",
"operationId": "post_v1_browser_forward",
"responses": {
"200": {
"description": "Page info after navigating forward",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/BrowserPageInfo"
}
}
}
},
"409": {
"description": "Browser runtime is not active",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
}
},
"502": {
"description": "CDP command failed",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
}
}
}
}
},
"/v1/browser/hover": {
"post": {
"tags": ["v1"],
"summary": "Hover over an element.",
"description": "Finds the element matching `selector`, computes its center via `DOM.getBoxModel`,\nand dispatches a `mouseMoved` event.",
"operationId": "post_v1_browser_hover",
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/BrowserHoverRequest"
}
}
},
"required": true
},
"responses": {
"200": {
"description": "Hover performed",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/BrowserActionResponse"
}
}
}
},
"404": {
"description": "Element not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
}
},
"409": {
"description": "Browser runtime is not active",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
}
},
"502": {
"description": "CDP command failed",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
}
}
}
}
},
"/v1/browser/links": {
"get": {
"tags": ["v1"],
"summary": "Get all links on the current page.",
"description": "Extracts all anchor elements from the page via CDP and returns their href\nand text content.",
"operationId": "get_v1_browser_links",
"responses": {
"200": {
"description": "Links on the page",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/BrowserLinksResponse"
}
}
}
},
"409": {
"description": "Browser runtime is not active",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
}
},
"502": {
"description": "CDP command failed",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
}
}
}
}
},
"/v1/browser/markdown": {
"get": {
"tags": ["v1"],
"summary": "Get the page content as Markdown.",
"description": "Extracts the DOM HTML via CDP, strips navigation/footer/aside elements, and\nconverts the remaining content to Markdown using html2md.",
"operationId": "get_v1_browser_markdown",
"responses": {
"200": {
"description": "Page content as Markdown",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/BrowserMarkdownResponse"
}
}
}
},
"409": {
"description": "Browser runtime is not active",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
}
},
"502": {
"description": "CDP command failed",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
}
}
}
}
},
"/v1/browser/navigate": {
"post": {
"tags": ["v1"],
"summary": "Navigate the browser to a URL.",
"description": "Sends a CDP `Page.navigate` command and optionally waits for a lifecycle\nevent before returning the resulting page URL, title, and HTTP status.",
"operationId": "post_v1_browser_navigate",
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/BrowserNavigateRequest"
}
}
},
"required": true
},
"responses": {
"200": {
"description": "Navigation result",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/BrowserPageInfo"
}
}
}
},
"409": {
"description": "Browser runtime is not active",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
}
},
"502": {
"description": "CDP command failed",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
}
}
}
}
},
"/v1/browser/network": {
"get": {
"tags": ["v1"],
"summary": "Get browser network requests.",
"description": "Returns network requests captured from the browser, optionally filtered by\nURL pattern and limited in count.",
"operationId": "get_v1_browser_network",
"parameters": [
{
"name": "limit",
"in": "query",
"required": false,
"schema": {
"type": "integer",
"format": "int32",
"nullable": true,
"minimum": 0
}
},
{
"name": "urlPattern",
"in": "query",
"required": false,
"schema": {
"type": "string",
"nullable": true
}
}
],
"responses": {
"200": {
"description": "Network requests retrieved",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/BrowserNetworkResponse"
}
}
}
},
"409": {
"description": "Browser not active",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
}
},
"500": {
"description": "Internal error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
}
}
}
}
},
"/v1/browser/pdf": {
"get": {
"tags": ["v1"],
"summary": "Generate a PDF of the current browser page.",
"description": "Generates a PDF document from the current page via CDP `Page.printToPDF`\nand returns the PDF bytes.",
"operationId": "get_v1_browser_pdf",
"parameters": [
{
"name": "format",
"in": "query",
"required": false,
"schema": {
"allOf": [
{
"$ref": "#/components/schemas/BrowserPdfFormat"
}
],
"nullable": true
}
},
{
"name": "landscape",
"in": "query",
"required": false,
"schema": {
"type": "boolean",
"nullable": true
}
},
{
"name": "printBackground",
"in": "query",
"required": false,
"schema": {
"type": "boolean",
"nullable": true
}
},
{
"name": "scale",
"in": "query",
"required": false,
"schema": {
"type": "number",
"format": "float",
"nullable": true
}
}
],
"responses": {
"200": {
"description": "Browser page as PDF bytes"
},
"409": {
"description": "Browser runtime is not active",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
}
},
"502": {
"description": "CDP command failed",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
}
}
}
}
},
"/v1/browser/reload": {
"post": {
"tags": ["v1"],
"summary": "Reload the current browser page.",
"description": "Sends a CDP `Page.reload` command with an optional cache bypass flag\nand returns the resulting page URL and title.",
"operationId": "post_v1_browser_reload",
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/BrowserReloadRequest"
}
}
},
"required": true
},
"responses": {
"200": {
"description": "Page info after reload",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/BrowserPageInfo"
}
}
}
},
"409": {
"description": "Browser runtime is not active",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
}
},
"502": {
"description": "CDP command failed",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
}
}
}
}
},
"/v1/browser/scrape": {
"post": {
"tags": ["v1"],
"summary": "Scrape structured data from the current page using CSS selectors.",
"description": "For each key in the `selectors` map, runs `querySelectorAll` with the CSS\nselector value and collects `textContent` from every match. If `url` is\nprovided the browser navigates there first.",
"operationId": "post_v1_browser_scrape",
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/BrowserScrapeRequest"
}
}
},
"required": true
},
"responses": {
"200": {
"description": "Scraped data",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/BrowserScrapeResponse"
}
}
}
},
"409": {
"description": "Browser runtime is not active",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
}
},
"502": {
"description": "CDP command failed",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
}
}
}
}
},
"/v1/browser/screenshot": {
"get": {
"tags": ["v1"],
"summary": "Capture a browser page screenshot.",
"description": "Captures a screenshot of the current browser page via CDP\n`Page.captureScreenshot` and returns the image bytes with the appropriate\nContent-Type header.",
"operationId": "get_v1_browser_screenshot",
"parameters": [
{
"name": "format",
"in": "query",
"required": false,
"schema": {
"allOf": [
{
"$ref": "#/components/schemas/BrowserScreenshotFormat"
}
],
"nullable": true
}
},
{
"name": "quality",
"in": "query",
"required": false,
"schema": {
"type": "integer",
"format": "int32",
"nullable": true,
"minimum": 0
}
},
{
"name": "fullPage",
"in": "query",
"required": false,
"schema": {
"type": "boolean",
"nullable": true
}
},
{
"name": "selector",
"in": "query",
"required": false,
"schema": {
"type": "string",
"nullable": true
}
}
],
"responses": {
"200": {
"description": "Browser screenshot as image bytes"
},
"409": {
"description": "Browser runtime is not active",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
}
},
"502": {
"description": "CDP command failed",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
}
}
}
}
},
"/v1/browser/scroll": {
"post": {
"tags": ["v1"],
"summary": "Scroll the page or a specific element.",
"description": "If a `selector` is provided, scrolls that element. Otherwise scrolls the\npage window by the given `x` and `y` pixel offsets.",
"operationId": "post_v1_browser_scroll",
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/BrowserScrollRequest"
}
}
},
"required": true
},
"responses": {
"200": {
"description": "Scroll performed",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/BrowserActionResponse"
}
}
}
},
"404": {
"description": "Element not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
}
},
"409": {
"description": "Browser runtime is not active",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
}
},
"502": {
"description": "CDP command failed",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
}
}
}
}
},
"/v1/browser/select": {
"post": {
"tags": ["v1"],
"summary": "Select an option in a `<select>` element.",
"description": "Finds the element matching `selector` and sets its value via `Runtime.evaluate`,\nthen dispatches a `change` event so listeners fire.",
"operationId": "post_v1_browser_select",
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/BrowserSelectRequest"
}
}
},
"required": true
},
"responses": {
"200": {
"description": "Option selected",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/BrowserActionResponse"
}
}
}
},
"404": {
"description": "Element not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
}
},
"409": {
"description": "Browser runtime is not active",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
}
},
"502": {
"description": "CDP command failed",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
}
}
}
}
},
"/v1/browser/snapshot": {
"get": {
"tags": ["v1"],
"summary": "Get an accessibility tree snapshot of the current page.",
"description": "Returns a text representation of the page accessibility tree via CDP\n`Accessibility.getFullAXTree`.",
"operationId": "get_v1_browser_snapshot",
"responses": {
"200": {
"description": "Accessibility tree snapshot",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/BrowserSnapshotResponse"
}
}
}
},
"409": {
"description": "Browser runtime is not active",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
}
},
"502": {
"description": "CDP command failed",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
}
}
}
}
},
"/v1/browser/start": {
"post": {
"tags": ["v1"],
"summary": "Start the browser runtime.",
"description": "Launches Chromium with remote debugging, optionally starts Xvfb for\nnon-headless mode, and returns the resulting browser status snapshot.",
"operationId": "post_v1_browser_start",
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/BrowserStartRequest"
}
}
},
"required": true
},
"responses": {
"200": {
"description": "Browser runtime status after start",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/BrowserStatusResponse"
}
}
}
},
"400": {
"description": "Invalid browser start request",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
}
},
"409": {
"description": "Browser or desktop runtime conflict",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
}
},
"424": {
"description": "Browser dependencies not installed",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
}
},
"500": {
"description": "Browser runtime could not be started",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
}
}
}
}
},
"/v1/browser/status": {
"get": {
"tags": ["v1"],
"summary": "Get browser runtime status.",
"description": "Returns the current browser state, display information, CDP URL,\nand managed process details.",
"operationId": "get_v1_browser_status",
"responses": {
"200": {
"description": "Browser runtime status",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/BrowserStatusResponse"
}
}
}
},
"401": {
"description": "Authentication required",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
}
}
}
}
},
"/v1/browser/stop": {
"post": {
"tags": ["v1"],
"summary": "Stop the browser runtime.",
"description": "Terminates Chromium, the CDP client, and any associated Xvfb/Neko\nprocesses, then returns the resulting status snapshot.",
"operationId": "post_v1_browser_stop",
"responses": {
"200": {
"description": "Browser runtime status after stop",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/BrowserStatusResponse"
}
}
}
},
"409": {
"description": "Browser runtime is not active",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
}
}
}
}
},
"/v1/browser/tabs": {
"get": {
"tags": ["v1"],
"summary": "List open browser tabs.",
"description": "Returns all open browser tabs (pages) via CDP `Target.getTargets`,\nfiltered to type \"page\".",
"operationId": "get_v1_browser_tabs",
"responses": {
"200": {
"description": "List of open browser tabs",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/BrowserTabListResponse"
}
}
}
},
"409": {
"description": "Browser runtime is not active",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
}
},
"502": {
"description": "CDP command failed",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
}
}
}
},
"post": {
"tags": ["v1"],
"summary": "Create a new browser tab.",
"description": "Opens a new tab via CDP `Target.createTarget` and returns the tab info.",
"operationId": "post_v1_browser_tabs",
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/BrowserCreateTabRequest"
}
}
},
"required": true
},
"responses": {
"201": {
"description": "New tab created",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/BrowserTabInfo"
}
}
}
},
"409": {
"description": "Browser runtime is not active",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
}
},
"502": {
"description": "CDP command failed",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
}
}
}
}
},
"/v1/browser/tabs/{tab_id}": {
"delete": {
"tags": ["v1"],
"summary": "Close a browser tab.",
"description": "Closes the specified tab via CDP `Target.closeTarget`.",
"operationId": "delete_v1_browser_tab",
"parameters": [
{
"name": "tab_id",
"in": "path",
"description": "Target ID of the tab to close",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Tab closed",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/BrowserActionResponse"
}
}
}
},
"404": {
"description": "Tab not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
}
},
"409": {
"description": "Browser runtime is not active",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
}
},
"502": {
"description": "CDP command failed",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
}
}
}
}
},
"/v1/browser/tabs/{tab_id}/activate": {
"post": {
"tags": ["v1"],
"summary": "Activate a browser tab.",
"description": "Brings the specified tab to the foreground via CDP `Target.activateTarget`.",
"operationId": "post_v1_browser_tab_activate",
"parameters": [
{
"name": "tab_id",
"in": "path",
"description": "Target ID of the tab to activate",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Tab activated",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/BrowserTabInfo"
}
}
}
},
"404": {
"description": "Tab not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
}
},
"409": {
"description": "Browser runtime is not active",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
}
},
"502": {
"description": "CDP command failed",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
}
}
}
}
},
"/v1/browser/type": {
"post": {
"tags": ["v1"],
"summary": "Type text into a focused element.",
"description": "Finds the element matching `selector`, focuses it via `DOM.focus`, optionally\nclears existing content, then dispatches key events for each character.",
"operationId": "post_v1_browser_type",
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/BrowserTypeRequest"
}
}
},
"required": true
},
"responses": {
"200": {
"description": "Text typed",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/BrowserActionResponse"
}
}
}
},
"404": {
"description": "Element not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
}
},
"409": {
"description": "Browser runtime is not active",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
}
},
"502": {
"description": "CDP command failed",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
}
}
}
}
},
"/v1/browser/upload": {
"post": {
"tags": ["v1"],
"summary": "Upload a file to a file input element in the browser page.",
"description": "Resolves the file input element matching `selector` and sets the specified\nfile path using `DOM.setFileInputFiles`.",
"operationId": "post_v1_browser_upload",
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/BrowserUploadRequest"
}
}
},
"required": true
},
"responses": {
"200": {
"description": "File uploaded to input",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/BrowserActionResponse"
}
}
}
},
"404": {
"description": "Element not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
}
},
"409": {
"description": "Browser runtime is not active",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
}
},
"502": {
"description": "CDP command failed",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
}
}
}
}
},
"/v1/browser/wait": {
"post": {
"tags": ["v1"],
"summary": "Wait for a selector or condition in the browser.",
"description": "Polls the page DOM using `Runtime.evaluate` with a `querySelector` check\nuntil the element is found or the timeout expires.",
"operationId": "post_v1_browser_wait",
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/BrowserWaitRequest"
}
}
},
"required": true
},
"responses": {
"200": {
"description": "Wait result",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/BrowserWaitResponse"
}
}
}
},
"409": {
"description": "Browser runtime is not active",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
}
},
"502": {
"description": "CDP command failed",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
}
},
"504": {
"description": "Timeout waiting for condition",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
}
}
}
}
},
"/v1/config/mcp": {
"get": {
"tags": ["v1"],
"operationId": "get_v1_config_mcp",
"parameters": [
{
"name": "directory",
"in": "query",
"description": "Target directory",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "mcpName",
"in": "query",
"description": "MCP entry name",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "MCP entry",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/McpServerConfig"
}
}
}
},
"404": {
"description": "Entry not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
}
}
}
},
"put": {
"tags": ["v1"],
"operationId": "put_v1_config_mcp",
"parameters": [
{
"name": "directory",
"in": "query",
"description": "Target directory",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "mcpName",
"in": "query",
"description": "MCP entry name",
"required": true,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/McpServerConfig"
}
}
},
"required": true
},
"responses": {
"204": {
"description": "Stored"
}
}
},
"delete": {
"tags": ["v1"],
"operationId": "delete_v1_config_mcp",
"parameters": [
{
"name": "directory",
"in": "query",
"description": "Target directory",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "mcpName",
"in": "query",
"description": "MCP entry name",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"204": {
"description": "Deleted"
}
}
}
},
"/v1/config/skills": {
"get": {
"tags": ["v1"],
"operationId": "get_v1_config_skills",
"parameters": [
{
"name": "directory",
"in": "query",
"description": "Target directory",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "skillName",
"in": "query",
"description": "Skill entry name",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Skills entry",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SkillsConfig"
}
}
}
},
"404": {
"description": "Entry not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
}
}
}
},
"put": {
"tags": ["v1"],
"operationId": "put_v1_config_skills",
"parameters": [
{
"name": "directory",
"in": "query",
"description": "Target directory",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "skillName",
"in": "query",
"description": "Skill entry name",
"required": true,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SkillsConfig"
}
}
},
"required": true
},
"responses": {
"204": {
"description": "Stored"
}
}
},
"delete": {
"tags": ["v1"],
"operationId": "delete_v1_config_skills",
"parameters": [
{
"name": "directory",
"in": "query",
"description": "Target directory",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "skillName",
"in": "query",
"description": "Skill entry name",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"204": {
"description": "Deleted"
}
}
}
},
"/v1/desktop/clipboard": {
"get": {
"tags": ["v1"],
"summary": "Read the desktop clipboard.",
"description": "Returns the current text content of the X11 clipboard.",
"operationId": "get_v1_desktop_clipboard",
"parameters": [
{
"name": "selection",
"in": "query",
"required": false,
"schema": {
"type": "string",
"nullable": true
}
}
],
"responses": {
"200": {
"description": "Clipboard contents",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/DesktopClipboardResponse"
}
}
}
},
"409": {
"description": "Desktop runtime is not ready",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
}
},
"500": {
"description": "Clipboard read failed",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
}
}
}
},
"post": {
"tags": ["v1"],
"summary": "Write to the desktop clipboard.",
"description": "Sets the text content of the X11 clipboard.",
"operationId": "post_v1_desktop_clipboard",
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/DesktopClipboardWriteRequest"
}
}
},
"required": true
},
"responses": {
"200": {
"description": "Clipboard updated",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/DesktopActionResponse"
}
}
}
},
"409": {
"description": "Desktop runtime is not ready",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
}
},
"500": {
"description": "Clipboard write failed",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
}
}
}
}
},
"/v1/desktop/display/info": {
"get": {
"tags": ["v1"],
"summary": "Get desktop display information.",
"description": "Performs a health-gated display query against the managed desktop and\nreturns the current display identifier and resolution.",
"operationId": "get_v1_desktop_display_info",
"responses": {
"200": {
"description": "Desktop display information",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/DesktopDisplayInfoResponse"
}
}
}
},
"409": {
"description": "Desktop runtime is not ready",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
}
},
"503": {
"description": "Desktop runtime health or display query failed",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
}
}
}
}
},
"/v1/desktop/keyboard/down": {
"post": {
"tags": ["v1"],
"summary": "Press and hold a desktop keyboard key.",
"description": "Performs a health-gated `xdotool keydown` operation against the managed\ndesktop.",
"operationId": "post_v1_desktop_keyboard_down",
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/DesktopKeyboardDownRequest"
}
}
},
"required": true
},
"responses": {
"200": {
"description": "Desktop keyboard action result",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/DesktopActionResponse"
}
}
}
},
"400": {
"description": "Invalid keyboard down request",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
}
},
"409": {
"description": "Desktop runtime is not ready",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
}
},
"502": {
"description": "Desktop runtime health or input failed",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
}
}
}
}
},
"/v1/desktop/keyboard/press": {
"post": {
"tags": ["v1"],
"summary": "Press a desktop keyboard shortcut.",
"description": "Performs a health-gated `xdotool key` operation against the managed\ndesktop.",
"operationId": "post_v1_desktop_keyboard_press",
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/DesktopKeyboardPressRequest"
}
}
},
"required": true
},
"responses": {
"200": {
"description": "Desktop keyboard action result",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/DesktopActionResponse"
}
}
}
},
"400": {
"description": "Invalid keyboard press request",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
}
},
"409": {
"description": "Desktop runtime is not ready",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
}
},
"502": {
"description": "Desktop runtime health or input failed",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
}
}
}
}
},
"/v1/desktop/keyboard/type": {
"post": {
"tags": ["v1"],
"summary": "Type desktop keyboard text.",
"description": "Performs a health-gated `xdotool type` operation against the managed\ndesktop.",
"operationId": "post_v1_desktop_keyboard_type",
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/DesktopKeyboardTypeRequest"
}
}
},
"required": true
},
"responses": {
"200": {
"description": "Desktop keyboard action result",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/DesktopActionResponse"
}
}
}
},
"400": {
"description": "Invalid keyboard type request",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
}
},
"409": {
"description": "Desktop runtime is not ready",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
}
},
"502": {
"description": "Desktop runtime health or input failed",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
}
}
}
}
},
"/v1/desktop/keyboard/up": {
"post": {
"tags": ["v1"],
"summary": "Release a desktop keyboard key.",
"description": "Performs a health-gated `xdotool keyup` operation against the managed\ndesktop.",
"operationId": "post_v1_desktop_keyboard_up",
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/DesktopKeyboardUpRequest"
}
}
},
"required": true
},
"responses": {
"200": {
"description": "Desktop keyboard action result",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/DesktopActionResponse"
}
}
}
},
"400": {
"description": "Invalid keyboard up request",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
}
},
"409": {
"description": "Desktop runtime is not ready",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
}
},
"502": {
"description": "Desktop runtime health or input failed",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
}
}
}
}
},
"/v1/desktop/launch": {
"post": {
"tags": ["v1"],
"summary": "Launch a desktop application.",
"description": "Launches an application by name on the managed desktop, optionally waiting\nfor its window to appear.",
"operationId": "post_v1_desktop_launch",
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/DesktopLaunchRequest"
}
}
},
"required": true
},
"responses": {
"200": {
"description": "Application launched",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/DesktopLaunchResponse"
}
}
}
},
"404": {
"description": "Application not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
}
},
"409": {
"description": "Desktop runtime is not ready",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
}
}
}
}
},
"/v1/desktop/mouse/click": {
"post": {
"tags": ["v1"],
"summary": "Click on the desktop.",
"description": "Performs a health-gated pointer move and click against the managed desktop\nand returns the resulting mouse position.",
"operationId": "post_v1_desktop_mouse_click",
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/DesktopMouseClickRequest"
}
}
},
"required": true
},
"responses": {
"200": {
"description": "Desktop mouse position after click",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/DesktopMousePositionResponse"
}
}
}
},
"400": {
"description": "Invalid mouse click request",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
}
},
"409": {
"description": "Desktop runtime is not ready",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
}
},
"502": {
"description": "Desktop runtime health or input failed",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
}
}
}
}
},
"/v1/desktop/mouse/down": {
"post": {
"tags": ["v1"],
"summary": "Press and hold a desktop mouse button.",
"description": "Performs a health-gated optional pointer move followed by `xdotool mousedown`\nand returns the resulting mouse position.",
"operationId": "post_v1_desktop_mouse_down",
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/DesktopMouseDownRequest"
}
}
},
"required": true
},
"responses": {
"200": {
"description": "Desktop mouse position after button press",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/DesktopMousePositionResponse"
}
}
}
},
"400": {
"description": "Invalid mouse down request",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
}
},
"409": {
"description": "Desktop runtime is not ready",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
}
},
"502": {
"description": "Desktop runtime health or input failed",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
}
}
}
}
},
"/v1/desktop/mouse/drag": {
"post": {
"tags": ["v1"],
"summary": "Drag the desktop mouse.",
"description": "Performs a health-gated drag gesture against the managed desktop and\nreturns the resulting mouse position.",
"operationId": "post_v1_desktop_mouse_drag",
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/DesktopMouseDragRequest"
}
}
},
"required": true
},
"responses": {
"200": {
"description": "Desktop mouse position after drag",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/DesktopMousePositionResponse"
}
}
}
},
"400": {
"description": "Invalid mouse drag request",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
}
},
"409": {
"description": "Desktop runtime is not ready",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
}
},
"502": {
"description": "Desktop runtime health or input failed",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
}
}
}
}
},
"/v1/desktop/mouse/move": {
"post": {
"tags": ["v1"],
"summary": "Move the desktop mouse.",
"description": "Performs a health-gated absolute pointer move on the managed desktop and\nreturns the resulting mouse position.",
"operationId": "post_v1_desktop_mouse_move",
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/DesktopMouseMoveRequest"
}
}
},
"required": true
},
"responses": {
"200": {
"description": "Desktop mouse position after move",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/DesktopMousePositionResponse"
}
}
}
},
"400": {
"description": "Invalid mouse move request",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
}
},
"409": {
"description": "Desktop runtime is not ready",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
}
},
"502": {
"description": "Desktop runtime health or input failed",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
}
}
}
}
},
"/v1/desktop/mouse/position": {
"get": {
"tags": ["v1"],
"summary": "Get the current desktop mouse position.",
"description": "Performs a health-gated mouse position query against the managed desktop.",
"operationId": "get_v1_desktop_mouse_position",
"responses": {
"200": {
"description": "Desktop mouse position",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/DesktopMousePositionResponse"
}
}
}
},
"409": {
"description": "Desktop runtime is not ready",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
}
},
"502": {
"description": "Desktop runtime health or input check failed",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
}
}
}
}
},
"/v1/desktop/mouse/scroll": {
"post": {
"tags": ["v1"],
"summary": "Scroll the desktop mouse wheel.",
"description": "Performs a health-gated scroll gesture at the requested coordinates and\nreturns the resulting mouse position.",
"operationId": "post_v1_desktop_mouse_scroll",
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/DesktopMouseScrollRequest"
}
}
},
"required": true
},
"responses": {
"200": {
"description": "Desktop mouse position after scroll",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/DesktopMousePositionResponse"
}
}
}
},
"400": {
"description": "Invalid mouse scroll request",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
}
},
"409": {
"description": "Desktop runtime is not ready",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
}
},
"502": {
"description": "Desktop runtime health or input failed",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
}
}
}
}
},
"/v1/desktop/mouse/up": {
"post": {
"tags": ["v1"],
"summary": "Release a desktop mouse button.",
"description": "Performs a health-gated optional pointer move followed by `xdotool mouseup`\nand returns the resulting mouse position.",
"operationId": "post_v1_desktop_mouse_up",
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/DesktopMouseUpRequest"
}
}
},
"required": true
},
"responses": {
"200": {
"description": "Desktop mouse position after button release",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/DesktopMousePositionResponse"
}
}
}
},
"400": {
"description": "Invalid mouse up request",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
}
},
"409": {
"description": "Desktop runtime is not ready",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
}
},
"502": {
"description": "Desktop runtime health or input failed",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
}
}
}
}
},
"/v1/desktop/open": {
"post": {
"tags": ["v1"],
"summary": "Open a file or URL with the default handler.",
"description": "Opens a file path or URL using xdg-open on the managed desktop.",
"operationId": "post_v1_desktop_open",
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/DesktopOpenRequest"
}
}
},
"required": true
},
"responses": {
"200": {
"description": "Target opened",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/DesktopOpenResponse"
}
}
}
},
"409": {
"description": "Desktop runtime is not ready",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
}
}
}
}
},
"/v1/desktop/recording/start": {
"post": {
"tags": ["v1"],
"summary": "Start desktop recording.",
"description": "Starts an ffmpeg x11grab recording against the managed desktop and returns\nthe created recording metadata.",
"operationId": "post_v1_desktop_recording_start",
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/DesktopRecordingStartRequest"
}
}
},
"required": true
},
"responses": {
"200": {
"description": "Desktop recording started",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/DesktopRecordingInfo"
}
}
}
},
"409": {
"description": "Desktop runtime is not ready or a recording is already active",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
}
},
"502": {
"description": "Desktop recording failed",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
}
}
}
}
},
"/v1/desktop/recording/stop": {
"post": {
"tags": ["v1"],
"summary": "Stop desktop recording.",
"description": "Stops the active desktop recording and returns the finalized recording\nmetadata.",
"operationId": "post_v1_desktop_recording_stop",
"responses": {
"200": {
"description": "Desktop recording stopped",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/DesktopRecordingInfo"
}
}
}
},
"409": {
"description": "No active desktop recording",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
}
},
"502": {
"description": "Desktop recording stop failed",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
}
}
}
}
},
"/v1/desktop/recordings": {
"get": {
"tags": ["v1"],
"summary": "List desktop recordings.",
"description": "Returns the current desktop recording catalog.",
"operationId": "get_v1_desktop_recordings",
"responses": {
"200": {
"description": "Desktop recordings",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/DesktopRecordingListResponse"
}
}
}
},
"502": {
"description": "Desktop recordings query failed",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
}
}
}
}
},
"/v1/desktop/recordings/{id}": {
"get": {
"tags": ["v1"],
"summary": "Get desktop recording metadata.",
"description": "Returns metadata for a single desktop recording.",
"operationId": "get_v1_desktop_recording",
"parameters": [
{
"name": "id",
"in": "path",
"description": "Desktop recording ID",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Desktop recording metadata",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/DesktopRecordingInfo"
}
}
}
},
"404": {
"description": "Unknown desktop recording",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
}
}
}
},
"delete": {
"tags": ["v1"],
"summary": "Delete a desktop recording.",
"description": "Removes a completed desktop recording and its file from disk.",
"operationId": "delete_v1_desktop_recording",
"parameters": [
{
"name": "id",
"in": "path",
"description": "Desktop recording ID",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"204": {
"description": "Desktop recording deleted"
},
"404": {
"description": "Unknown desktop recording",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
}
},
"409": {
"description": "Desktop recording is still active",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
}
}
}
}
},
"/v1/desktop/recordings/{id}/download": {
"get": {
"tags": ["v1"],
"summary": "Download a desktop recording.",
"description": "Serves the recorded MP4 bytes for a completed desktop recording.",
"operationId": "get_v1_desktop_recording_download",
"parameters": [
{
"name": "id",
"in": "path",
"description": "Desktop recording ID",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Desktop recording as MP4 bytes"
},
"404": {
"description": "Unknown desktop recording",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
}
}
}
}
},
"/v1/desktop/screenshot": {
"get": {
"tags": ["v1"],
"summary": "Capture a full desktop screenshot.",
"description": "Performs a health-gated full-frame screenshot of the managed desktop and\nreturns the requested image bytes.",
"operationId": "get_v1_desktop_screenshot",
"parameters": [
{
"name": "format",
"in": "query",
"required": false,
"schema": {
"allOf": [
{
"$ref": "#/components/schemas/DesktopScreenshotFormat"
}
],
"nullable": true
}
},
{
"name": "quality",
"in": "query",
"required": false,
"schema": {
"type": "integer",
"format": "int32",
"nullable": true,
"minimum": 0
}
},
{
"name": "scale",
"in": "query",
"required": false,
"schema": {
"type": "number",
"format": "float",
"nullable": true
}
},
{
"name": "showCursor",
"in": "query",
"required": false,
"schema": {
"type": "boolean",
"nullable": true
}
}
],
"responses": {
"200": {
"description": "Desktop screenshot as image bytes"
},
"400": {
"description": "Invalid screenshot query",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
}
},
"409": {
"description": "Desktop runtime is not ready",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
}
},
"502": {
"description": "Desktop runtime health or screenshot capture failed",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
}
}
}
}
},
"/v1/desktop/screenshot/region": {
"get": {
"tags": ["v1"],
"summary": "Capture a desktop screenshot region.",
"description": "Performs a health-gated screenshot crop against the managed desktop and\nreturns the requested region image bytes.",
"operationId": "get_v1_desktop_screenshot_region",
"parameters": [
{
"name": "x",
"in": "query",
"required": true,
"schema": {
"type": "integer",
"format": "int32"
}
},
{
"name": "y",
"in": "query",
"required": true,
"schema": {
"type": "integer",
"format": "int32"
}
},
{
"name": "width",
"in": "query",
"required": true,
"schema": {
"type": "integer",
"format": "int32",
"minimum": 0
}
},
{
"name": "height",
"in": "query",
"required": true,
"schema": {
"type": "integer",
"format": "int32",
"minimum": 0
}
},
{
"name": "format",
"in": "query",
"required": false,
"schema": {
"allOf": [
{
"$ref": "#/components/schemas/DesktopScreenshotFormat"
}
],
"nullable": true
}
},
{
"name": "quality",
"in": "query",
"required": false,
"schema": {
"type": "integer",
"format": "int32",
"nullable": true,
"minimum": 0
}
},
{
"name": "scale",
"in": "query",
"required": false,
"schema": {
"type": "number",
"format": "float",
"nullable": true
}
},
{
"name": "showCursor",
"in": "query",
"required": false,
"schema": {
"type": "boolean",
"nullable": true
}
}
],
"responses": {
"200": {
"description": "Desktop screenshot region as image bytes"
},
"400": {
"description": "Invalid screenshot region",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
}
},
"409": {
"description": "Desktop runtime is not ready",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
}
},
"502": {
"description": "Desktop runtime health or screenshot capture failed",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
}
}
}
}
},
"/v1/desktop/start": {
"post": {
"tags": ["v1"],
"summary": "Start the private desktop runtime.",
"description": "Lazily launches the managed Xvfb/openbox stack, validates display health,\nand returns the resulting desktop status snapshot.",
"operationId": "post_v1_desktop_start",
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/DesktopStartRequest"
}
}
},
"required": true
},
"responses": {
"200": {
"description": "Desktop runtime status after start",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/DesktopStatusResponse"
}
}
}
},
"400": {
"description": "Invalid desktop start request",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
}
},
"409": {
"description": "Desktop runtime is already transitioning",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
}
},
"501": {
"description": "Desktop API unsupported on this platform",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
}
},
"503": {
"description": "Desktop runtime could not be started",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
}
}
}
}
},
"/v1/desktop/status": {
"get": {
"tags": ["v1"],
"summary": "Get desktop runtime status.",
"description": "Returns the current desktop runtime state, dependency status, active\ndisplay metadata, and supervised process information.",
"operationId": "get_v1_desktop_status",
"responses": {
"200": {
"description": "Desktop runtime status",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/DesktopStatusResponse"
}
}
}
},
"401": {
"description": "Authentication required",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
}
}
}
}
},
"/v1/desktop/stop": {
"post": {
"tags": ["v1"],
"summary": "Stop the private desktop runtime.",
"description": "Terminates the managed openbox/Xvfb/dbus processes owned by the desktop\nruntime and returns the resulting status snapshot.",
"operationId": "post_v1_desktop_stop",
"responses": {
"200": {
"description": "Desktop runtime status after stop",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/DesktopStatusResponse"
}
}
}
},
"409": {
"description": "Desktop runtime is already transitioning",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
}
}
}
}
},
"/v1/desktop/stream/signaling": {
"get": {
"tags": ["v1"],
"summary": "Open a desktop WebRTC signaling session.",
"description": "Upgrades the connection to a WebSocket used for WebRTC signaling between\nthe browser client and the desktop streaming process. Also accepts mouse\nand keyboard input frames as a fallback transport.",
"operationId": "get_v1_desktop_stream_ws",
"parameters": [
{
"name": "access_token",
"in": "query",
"description": "Bearer token alternative for WS auth",
"required": false,
"schema": {
"type": "string",
"nullable": true
}
}
],
"responses": {
"101": {
"description": "WebSocket upgraded"
},
"409": {
"description": "Desktop runtime or streaming session is not ready",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
}
},
"502": {
"description": "Desktop stream failed",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
}
}
}
}
},
"/v1/desktop/stream/start": {
"post": {
"tags": ["v1"],
"summary": "Start desktop streaming.",
"description": "Enables desktop websocket streaming for the managed desktop.",
"operationId": "post_v1_desktop_stream_start",
"responses": {
"200": {
"description": "Desktop streaming started",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/DesktopStreamStatusResponse"
}
}
}
}
}
}
},
"/v1/desktop/stream/status": {
"get": {
"tags": ["v1"],
"summary": "Get desktop stream status.",
"description": "Returns the current state of the desktop WebRTC streaming session.",
"operationId": "get_v1_desktop_stream_status",
"responses": {
"200": {
"description": "Desktop stream status",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/DesktopStreamStatusResponse"
}
}
}
}
}
}
},
"/v1/desktop/stream/stop": {
"post": {
"tags": ["v1"],
"summary": "Stop desktop streaming.",
"description": "Disables desktop websocket streaming for the managed desktop.",
"operationId": "post_v1_desktop_stream_stop",
"responses": {
"200": {
"description": "Desktop streaming stopped",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/DesktopStreamStatusResponse"
}
}
}
}
}
}
},
"/v1/desktop/windows": {
"get": {
"tags": ["v1"],
"summary": "List visible desktop windows.",
"description": "Performs a health-gated visible-window enumeration against the managed\ndesktop and returns the current window metadata.",
"operationId": "get_v1_desktop_windows",
"responses": {
"200": {
"description": "Visible desktop windows",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/DesktopWindowListResponse"
}
}
}
},
"409": {
"description": "Desktop runtime is not ready",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
}
},
"503": {
"description": "Desktop runtime health or window query failed",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
}
}
}
}
},
"/v1/desktop/windows/focused": {
"get": {
"tags": ["v1"],
"summary": "Get the currently focused desktop window.",
"description": "Returns information about the window that currently has input focus.",
"operationId": "get_v1_desktop_windows_focused",
"responses": {
"200": {
"description": "Focused window info",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/DesktopWindowInfo"
}
}
}
},
"404": {
"description": "No window is focused",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
}
},
"409": {
"description": "Desktop runtime is not ready",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
}
}
}
}
},
"/v1/desktop/windows/{id}/focus": {
"post": {
"tags": ["v1"],
"summary": "Focus a desktop window.",
"description": "Brings the specified window to the foreground and gives it input focus.",
"operationId": "post_v1_desktop_window_focus",
"parameters": [
{
"name": "id",
"in": "path",
"description": "X11 window ID",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Window info after focus",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/DesktopWindowInfo"
}
}
}
},
"404": {
"description": "Window not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
}
},
"409": {
"description": "Desktop runtime is not ready",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
}
}
}
}
},
"/v1/desktop/windows/{id}/move": {
"post": {
"tags": ["v1"],
"summary": "Move a desktop window.",
"description": "Moves the specified window to the given position.",
"operationId": "post_v1_desktop_window_move",
"parameters": [
{
"name": "id",
"in": "path",
"description": "X11 window ID",
"required": true,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/DesktopWindowMoveRequest"
}
}
},
"required": true
},
"responses": {
"200": {
"description": "Window info after move",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/DesktopWindowInfo"
}
}
}
},
"404": {
"description": "Window not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
}
},
"409": {
"description": "Desktop runtime is not ready",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
}
}
}
}
},
"/v1/desktop/windows/{id}/resize": {
"post": {
"tags": ["v1"],
"summary": "Resize a desktop window.",
"description": "Resizes the specified window to the given dimensions.",
"operationId": "post_v1_desktop_window_resize",
"parameters": [
{
"name": "id",
"in": "path",
"description": "X11 window ID",
"required": true,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/DesktopWindowResizeRequest"
}
}
},
"required": true
},
"responses": {
"200": {
"description": "Window info after resize",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/DesktopWindowInfo"
}
}
}
},
"404": {
"description": "Window not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
}
},
"409": {
"description": "Desktop runtime is not ready",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
}
}
}
}
},
"/v1/fs/entries": {
"get": {
"tags": ["v1"],
"operationId": "get_v1_fs_entries",
"parameters": [
{
"name": "path",
"in": "query",
"description": "Directory path",
"required": false,
"schema": {
"type": "string",
"nullable": true
}
}
],
"responses": {
"200": {
"description": "Directory entries",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/FsEntry"
}
}
}
}
}
}
}
},
"/v1/fs/entry": {
"delete": {
"tags": ["v1"],
"operationId": "delete_v1_fs_entry",
"parameters": [
{
"name": "path",
"in": "query",
"description": "File or directory path",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "recursive",
"in": "query",
"description": "Delete directory recursively",
"required": false,
"schema": {
"type": "boolean",
"nullable": true
}
}
],
"responses": {
"200": {
"description": "Delete result",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/FsActionResponse"
}
}
}
}
}
}
},
"/v1/fs/file": {
"get": {
"tags": ["v1"],
"operationId": "get_v1_fs_file",
"parameters": [
{
"name": "path",
"in": "query",
"description": "File path",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "File content"
}
}
},
"put": {
"tags": ["v1"],
"operationId": "put_v1_fs_file",
"parameters": [
{
"name": "path",
"in": "query",
"description": "File path",
"required": true,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"description": "Raw file bytes",
"content": {
"text/plain": {
"schema": {
"type": "string"
}
}
},
"required": true
},
"responses": {
"200": {
"description": "Write result",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/FsWriteResponse"
}
}
}
}
}
}
},
"/v1/fs/mkdir": {
"post": {
"tags": ["v1"],
"operationId": "post_v1_fs_mkdir",
"parameters": [
{
"name": "path",
"in": "query",
"description": "Directory path",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Directory created",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/FsActionResponse"
}
}
}
}
}
}
},
"/v1/fs/move": {
"post": {
"tags": ["v1"],
"operationId": "post_v1_fs_move",
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/FsMoveRequest"
}
}
},
"required": true
},
"responses": {
"200": {
"description": "Move result",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/FsMoveResponse"
}
}
}
}
}
}
},
"/v1/fs/stat": {
"get": {
"tags": ["v1"],
"operationId": "get_v1_fs_stat",
"parameters": [
{
"name": "path",
"in": "query",
"description": "Path to stat",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Path metadata",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/FsStat"
}
}
}
}
}
}
},
"/v1/fs/upload-batch": {
"post": {
"tags": ["v1"],
"operationId": "post_v1_fs_upload_batch",
"parameters": [
{
"name": "path",
"in": "query",
"description": "Destination path",
"required": false,
"schema": {
"type": "string",
"nullable": true
}
}
],
"requestBody": {
"description": "tar archive body",
"content": {
"text/plain": {
"schema": {
"type": "string"
}
}
},
"required": true
},
"responses": {
"200": {
"description": "Upload/extract result",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/FsUploadBatchResponse"
}
}
}
}
}
}
},
"/v1/health": {
"get": {
"tags": ["v1"],
"operationId": "get_v1_health",
"responses": {
"200": {
"description": "Service health response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HealthResponse"
}
}
}
}
}
}
},
"/v1/processes": {
"get": {
"tags": ["v1"],
"summary": "List all managed processes.",
"description": "Returns a list of all processes (running and exited) currently tracked\nby the runtime, sorted by process ID.",
"operationId": "get_v1_processes",
"parameters": [
{
"name": "owner",
"in": "query",
"required": false,
"schema": {
"allOf": [
{
"$ref": "#/components/schemas/ProcessOwner"
}
],
"nullable": true
}
}
],
"responses": {
"200": {
"description": "List processes",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProcessListResponse"
}
}
}
},
"501": {
"description": "Process API unsupported on this platform",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
}
}
}
},
"post": {
"tags": ["v1"],
"summary": "Create a long-lived managed process.",
"description": "Spawns a new process with the given command and arguments. Supports both\npipe-based and PTY (tty) modes. Returns the process descriptor on success.",
"operationId": "post_v1_processes",
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProcessCreateRequest"
}
}
},
"required": true
},
"responses": {
"200": {
"description": "Started process",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProcessInfo"
}
}
}
},
"400": {
"description": "Invalid request",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
}
},
"409": {
"description": "Process limit or state conflict",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
}
},
"501": {
"description": "Process API unsupported on this platform",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
}
}
}
}
},
"/v1/processes/config": {
"get": {
"tags": ["v1"],
"summary": "Get process runtime configuration.",
"description": "Returns the current runtime configuration for the process management API,\nincluding limits for concurrency, timeouts, and buffer sizes.",
"operationId": "get_v1_processes_config",
"responses": {
"200": {
"description": "Current runtime process config",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProcessConfig"
}
}
}
},
"501": {
"description": "Process API unsupported on this platform",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
}
}
}
},
"post": {
"tags": ["v1"],
"summary": "Update process runtime configuration.",
"description": "Replaces the runtime configuration for the process management API.\nValidates that all values are non-zero and clamps default timeout to max.",
"operationId": "post_v1_processes_config",
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProcessConfig"
}
}
},
"required": true
},
"responses": {
"200": {
"description": "Updated runtime process config",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProcessConfig"
}
}
}
},
"400": {
"description": "Invalid config",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
}
},
"501": {
"description": "Process API unsupported on this platform",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
}
}
}
}
},
"/v1/processes/run": {
"post": {
"tags": ["v1"],
"summary": "Run a one-shot command.",
"description": "Executes a command to completion and returns its stdout, stderr, exit code,\nand duration. Supports configurable timeout and output size limits.",
"operationId": "post_v1_processes_run",
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProcessRunRequest"
}
}
},
"required": true
},
"responses": {
"200": {
"description": "One-off command result",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProcessRunResponse"
}
}
}
},
"400": {
"description": "Invalid request",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
}
},
"501": {
"description": "Process API unsupported on this platform",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
}
}
}
}
},
"/v1/processes/{id}": {
"get": {
"tags": ["v1"],
"summary": "Get a single process by ID.",
"description": "Returns the current state of a managed process including its status,\nPID, exit code, and creation/exit timestamps.",
"operationId": "get_v1_process",
"parameters": [
{
"name": "id",
"in": "path",
"description": "Process ID",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Process details",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProcessInfo"
}
}
}
},
"404": {
"description": "Unknown process",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
}
},
"501": {
"description": "Process API unsupported on this platform",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
}
}
}
},
"delete": {
"tags": ["v1"],
"summary": "Delete a process record.",
"description": "Removes a stopped process from the runtime. Returns 409 if the process\nis still running; stop or kill it first.",
"operationId": "delete_v1_process",
"parameters": [
{
"name": "id",
"in": "path",
"description": "Process ID",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"204": {
"description": "Process deleted"
},
"404": {
"description": "Unknown process",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
}
},
"409": {
"description": "Process is still running",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
}
},
"501": {
"description": "Process API unsupported on this platform",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
}
}
}
}
},
"/v1/processes/{id}/input": {
"post": {
"tags": ["v1"],
"summary": "Write input to a process.",
"description": "Sends data to a process's stdin (pipe mode) or PTY writer (tty mode).\nData can be encoded as base64, utf8, or text. Returns 413 if the decoded\npayload exceeds the configured `maxInputBytesPerRequest` limit.",
"operationId": "post_v1_process_input",
"parameters": [
{
"name": "id",
"in": "path",
"description": "Process ID",
"required": true,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProcessInputRequest"
}
}
},
"required": true
},
"responses": {
"200": {
"description": "Input accepted",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProcessInputResponse"
}
}
}
},
"400": {
"description": "Invalid request",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
}
},
"409": {
"description": "Process not writable",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
}
},
"413": {
"description": "Input exceeds configured limit",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
}
},
"501": {
"description": "Process API unsupported on this platform",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
}
}
}
}
},
"/v1/processes/{id}/kill": {
"post": {
"tags": ["v1"],
"summary": "Send SIGKILL to a process.",
"description": "Sends SIGKILL to the process and optionally waits up to `waitMs`\nmilliseconds for the process to exit before returning.",
"operationId": "post_v1_process_kill",
"parameters": [
{
"name": "id",
"in": "path",
"description": "Process ID",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "waitMs",
"in": "query",
"description": "Wait up to N ms for process to exit",
"required": false,
"schema": {
"type": "integer",
"format": "int64",
"nullable": true,
"minimum": 0
}
}
],
"responses": {
"200": {
"description": "Kill signal sent",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProcessInfo"
}
}
}
},
"404": {
"description": "Unknown process",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
}
},
"501": {
"description": "Process API unsupported on this platform",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
}
}
}
}
},
"/v1/processes/{id}/logs": {
"get": {
"tags": ["v1"],
"summary": "Fetch process logs.",
"description": "Returns buffered log entries for a process. Supports filtering by stream\ntype, tail count, and sequence-based resumption. When `follow=true`,\nreturns an SSE stream that replays buffered entries then streams live output.",
"operationId": "get_v1_process_logs",
"parameters": [
{
"name": "id",
"in": "path",
"description": "Process ID",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "stream",
"in": "query",
"description": "stdout|stderr|combined|pty",
"required": false,
"schema": {
"allOf": [
{
"$ref": "#/components/schemas/ProcessLogsStream"
}
],
"nullable": true
}
},
{
"name": "tail",
"in": "query",
"description": "Tail N entries",
"required": false,
"schema": {
"type": "integer",
"nullable": true,
"minimum": 0
}
},
{
"name": "follow",
"in": "query",
"description": "Follow via SSE",
"required": false,
"schema": {
"type": "boolean",
"nullable": true
}
},
{
"name": "since",
"in": "query",
"description": "Only entries with sequence greater than this",
"required": false,
"schema": {
"type": "integer",
"format": "int64",
"nullable": true,
"minimum": 0
}
}
],
"responses": {
"200": {
"description": "Process logs",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProcessLogsResponse"
}
}
}
},
"404": {
"description": "Unknown process",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
}
},
"501": {
"description": "Process API unsupported on this platform",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
}
}
}
}
},
"/v1/processes/{id}/stop": {
"post": {
"tags": ["v1"],
"summary": "Send SIGTERM to a process.",
"description": "Sends SIGTERM to the process and optionally waits up to `waitMs`\nmilliseconds for the process to exit before returning.",
"operationId": "post_v1_process_stop",
"parameters": [
{
"name": "id",
"in": "path",
"description": "Process ID",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "waitMs",
"in": "query",
"description": "Wait up to N ms for process to exit",
"required": false,
"schema": {
"type": "integer",
"format": "int64",
"nullable": true,
"minimum": 0
}
}
],
"responses": {
"200": {
"description": "Stop signal sent",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProcessInfo"
}
}
}
},
"404": {
"description": "Unknown process",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
}
},
"501": {
"description": "Process API unsupported on this platform",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
}
}
}
}
},
"/v1/processes/{id}/terminal/resize": {
"post": {
"tags": ["v1"],
"summary": "Resize a process terminal.",
"description": "Sets the PTY window size (columns and rows) for a tty-mode process and\nsends SIGWINCH so the child process can adapt.",
"operationId": "post_v1_process_terminal_resize",
"parameters": [
{
"name": "id",
"in": "path",
"description": "Process ID",
"required": true,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProcessTerminalResizeRequest"
}
}
},
"required": true
},
"responses": {
"200": {
"description": "Resize accepted",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProcessTerminalResizeResponse"
}
}
}
},
"400": {
"description": "Invalid request",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
}
},
"404": {
"description": "Unknown process",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
}
},
"409": {
"description": "Not a terminal process",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
}
},
"501": {
"description": "Process API unsupported on this platform",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
}
}
}
}
},
"/v1/processes/{id}/terminal/ws": {
"get": {
"tags": ["v1"],
"summary": "Open an interactive WebSocket terminal session.",
"description": "Upgrades the connection to a WebSocket for bidirectional PTY I/O. Accepts\n`access_token` query param for browser-based auth (WebSocket API cannot\nsend custom headers). Streams raw PTY output as binary frames and accepts\nJSON control frames for input, resize, and close.",
"operationId": "get_v1_process_terminal_ws",
"parameters": [
{
"name": "id",
"in": "path",
"description": "Process ID",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "access_token",
"in": "query",
"description": "Bearer token alternative for WS auth",
"required": false,
"schema": {
"type": "string",
"nullable": true
}
}
],
"responses": {
"101": {
"description": "WebSocket upgraded"
},
"400": {
"description": "Invalid websocket frame or upgrade request",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
}
},
"404": {
"description": "Unknown process",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
}
},
"409": {
"description": "Not a terminal process",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
}
},
"501": {
"description": "Process API unsupported on this platform",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
}
}
}
}
}
},
"components": {
"schemas": {
"AcpEnvelope": {
"type": "object",
"required": ["jsonrpc"],
"properties": {
"error": {
"nullable": true
},
"id": {
"nullable": true
},
"jsonrpc": {
"type": "string"
},
"method": {
"type": "string",
"nullable": true
},
"params": {
"nullable": true
},
"result": {
"nullable": true
}
}
},
"AcpPostQuery": {
"type": "object",
"properties": {
"agent": {
"type": "string",
"nullable": true
}
}
},
"AcpServerInfo": {
"type": "object",
"required": ["serverId", "agent", "createdAtMs"],
"properties": {
"agent": {
"type": "string"
},
"createdAtMs": {
"type": "integer",
"format": "int64"
},
"serverId": {
"type": "string"
}
}
},
"AcpServerListResponse": {
"type": "object",
"required": ["servers"],
"properties": {
"servers": {
"type": "array",
"items": {
"$ref": "#/components/schemas/AcpServerInfo"
}
}
}
},
"AgentCapabilities": {
"type": "object",
"required": [
"planMode",
"permissions",
"questions",
"toolCalls",
"toolResults",
"textMessages",
"images",
"fileAttachments",
"sessionLifecycle",
"errorEvents",
"reasoning",
"status",
"commandExecution",
"fileChanges",
"mcpTools",
"streamingDeltas",
"itemStarted",
"sharedProcess"
],
"properties": {
"commandExecution": {
"type": "boolean"
},
"errorEvents": {
"type": "boolean"
},
"fileAttachments": {
"type": "boolean"
},
"fileChanges": {
"type": "boolean"
},
"images": {
"type": "boolean"
},
"itemStarted": {
"type": "boolean"
},
"mcpTools": {
"type": "boolean"
},
"permissions": {
"type": "boolean"
},
"planMode": {
"type": "boolean"
},
"questions": {
"type": "boolean"
},
"reasoning": {
"type": "boolean"
},
"sessionLifecycle": {
"type": "boolean"
},
"sharedProcess": {
"type": "boolean"
},
"status": {
"type": "boolean"
},
"streamingDeltas": {
"type": "boolean"
},
"textMessages": {
"type": "boolean"
},
"toolCalls": {
"type": "boolean"
},
"toolResults": {
"type": "boolean"
}
}
},
"AgentInfo": {
"type": "object",
"required": ["id", "installed", "credentialsAvailable", "capabilities"],
"properties": {
"capabilities": {
"$ref": "#/components/schemas/AgentCapabilities"
},
"configError": {
"type": "string",
"nullable": true
},
"configOptions": {
"type": "array",
"items": {},
"nullable": true
},
"credentialsAvailable": {
"type": "boolean"
},
"id": {
"type": "string"
},
"installed": {
"type": "boolean"
},
"path": {
"type": "string",
"nullable": true
},
"serverStatus": {
"allOf": [
{
"$ref": "#/components/schemas/ServerStatusInfo"
}
],
"nullable": true
},
"version": {
"type": "string",
"nullable": true
}
}
},
"AgentInstallArtifact": {
"type": "object",
"required": ["kind", "path", "source"],
"properties": {
"kind": {
"type": "string"
},
"path": {
"type": "string"
},
"source": {
"type": "string"
},
"version": {
"type": "string",
"nullable": true
}
}
},
"AgentInstallRequest": {
"type": "object",
"properties": {
"agentProcessVersion": {
"type": "string",
"nullable": true
},
"agentVersion": {
"type": "string",
"nullable": true
},
"reinstall": {
"type": "boolean",
"nullable": true
}
}
},
"AgentInstallResponse": {
"type": "object",
"required": ["already_installed", "artifacts"],
"properties": {
"already_installed": {
"type": "boolean"
},
"artifacts": {
"type": "array",
"items": {
"$ref": "#/components/schemas/AgentInstallArtifact"
}
}
}
},
"AgentListResponse": {
"type": "object",
"required": ["agents"],
"properties": {
"agents": {
"type": "array",
"items": {
"$ref": "#/components/schemas/AgentInfo"
}
}
}
},
"BrowserActionResponse": {
"type": "object",
"required": ["ok"],
"properties": {
"ok": {
"type": "boolean"
}
}
},
"BrowserClickRequest": {
"type": "object",
"required": ["selector"],
"properties": {
"button": {
"allOf": [
{
"$ref": "#/components/schemas/BrowserMouseButton"
}
],
"nullable": true
},
"clickCount": {
"type": "integer",
"format": "int32",
"nullable": true,
"minimum": 0
},
"selector": {
"type": "string"
},
"timeout": {
"type": "integer",
"format": "int64",
"nullable": true,
"minimum": 0
}
}
},
"BrowserConsoleMessage": {
"type": "object",
"required": ["level", "text", "timestamp"],
"properties": {
"level": {
"type": "string"
},
"line": {
"type": "integer",
"format": "int32",
"nullable": true,
"minimum": 0
},
"text": {
"type": "string"
},
"timestamp": {
"type": "string"
},
"url": {
"type": "string",
"nullable": true
}
}
},
"BrowserConsoleQuery": {
"type": "object",
"properties": {
"level": {
"type": "string",
"nullable": true
},
"limit": {
"type": "integer",
"format": "int32",
"nullable": true,
"minimum": 0
}
}
},
"BrowserConsoleResponse": {
"type": "object",
"required": ["messages"],
"properties": {
"messages": {
"type": "array",
"items": {
"$ref": "#/components/schemas/BrowserConsoleMessage"
}
}
}
},
"BrowserContentQuery": {
"type": "object",
"properties": {
"selector": {
"type": "string",
"nullable": true
}
}
},
"BrowserContentResponse": {
"type": "object",
"required": ["html", "url", "title"],
"properties": {
"html": {
"type": "string"
},
"title": {
"type": "string"
},
"url": {
"type": "string"
}
}
},
"BrowserContextCreateRequest": {
"type": "object",
"required": ["name"],
"properties": {
"name": {
"type": "string"
}
}
},
"BrowserContextInfo": {
"type": "object",
"required": ["id", "name", "createdAt"],
"properties": {
"createdAt": {
"type": "string"
},
"id": {
"type": "string"
},
"name": {
"type": "string"
},
"sizeBytes": {
"type": "integer",
"format": "int64",
"nullable": true,
"minimum": 0
}
}
},
"BrowserContextListResponse": {
"type": "object",
"required": ["contexts"],
"properties": {
"contexts": {
"type": "array",
"items": {
"$ref": "#/components/schemas/BrowserContextInfo"
}
}
}
},
"BrowserCookie": {
"type": "object",
"required": ["name", "value"],
"properties": {
"domain": {
"type": "string",
"nullable": true
},
"expires": {
"type": "number",
"format": "double",
"nullable": true
},
"httpOnly": {
"type": "boolean",
"nullable": true
},
"name": {
"type": "string"
},
"path": {
"type": "string",
"nullable": true
},
"sameSite": {
"allOf": [
{
"$ref": "#/components/schemas/BrowserCookieSameSite"
}
],
"nullable": true
},
"secure": {
"type": "boolean",
"nullable": true
},
"value": {
"type": "string"
}
}
},
"BrowserCookieSameSite": {
"type": "string",
"enum": ["Strict", "Lax", "None"]
},
"BrowserCookiesQuery": {
"type": "object",
"properties": {
"url": {
"type": "string",
"nullable": true
}
}
},
"BrowserCookiesResponse": {
"type": "object",
"required": ["cookies"],
"properties": {
"cookies": {
"type": "array",
"items": {
"$ref": "#/components/schemas/BrowserCookie"
}
}
}
},
"BrowserCrawlExtract": {
"type": "string",
"enum": ["markdown", "html", "text", "links"]
},
"BrowserCrawlPage": {
"type": "object",
"required": ["url", "title", "content", "depth"],
"properties": {
"content": {
"type": "string"
},
"depth": {
"type": "integer",
"format": "int32",
"minimum": 0
},
"links": {
"type": "array",
"items": {
"type": "string"
}
},
"status": {
"type": "integer",
"format": "int32",
"nullable": true,
"minimum": 0
},
"title": {
"type": "string"
},
"url": {
"type": "string"
}
}
},
"BrowserCrawlRequest": {
"type": "object",
"required": ["url"],
"properties": {
"allowedDomains": {
"type": "array",
"items": {
"type": "string"
},
"nullable": true
},
"extract": {
"allOf": [
{
"$ref": "#/components/schemas/BrowserCrawlExtract"
}
],
"nullable": true
},
"maxDepth": {
"type": "integer",
"format": "int32",
"nullable": true,
"minimum": 0
},
"maxPages": {
"type": "integer",
"format": "int32",
"nullable": true,
"minimum": 0
},
"url": {
"type": "string"
}
}
},
"BrowserCrawlResponse": {
"type": "object",
"required": ["pages", "totalPages", "truncated"],
"properties": {
"pages": {
"type": "array",
"items": {
"$ref": "#/components/schemas/BrowserCrawlPage"
}
},
"totalPages": {
"type": "integer",
"format": "int32",
"minimum": 0
},
"truncated": {
"type": "boolean"
}
}
},
"BrowserCreateTabRequest": {
"type": "object",
"properties": {
"url": {
"type": "string",
"nullable": true
}
}
},
"BrowserDeleteCookiesQuery": {
"type": "object",
"properties": {
"domain": {
"type": "string",
"nullable": true
},
"name": {
"type": "string",
"nullable": true
}
}
},
"BrowserDialogRequest": {
"type": "object",
"required": ["accept"],
"properties": {
"accept": {
"type": "boolean"
},
"text": {
"type": "string",
"nullable": true
}
}
},
"BrowserExecuteRequest": {
"type": "object",
"required": ["expression"],
"properties": {
"awaitPromise": {
"type": "boolean",
"nullable": true
},
"expression": {
"type": "string"
}
}
},
"BrowserExecuteResponse": {
"type": "object",
"required": ["result", "type"],
"properties": {
"result": {},
"type": {
"type": "string"
}
}
},
"BrowserHoverRequest": {
"type": "object",
"required": ["selector"],
"properties": {
"selector": {
"type": "string"
}
}
},
"BrowserLinkInfo": {
"type": "object",
"required": ["href", "text"],
"properties": {
"href": {
"type": "string"
},
"text": {
"type": "string"
}
}
},
"BrowserLinksResponse": {
"type": "object",
"required": ["links", "url"],
"properties": {
"links": {
"type": "array",
"items": {
"$ref": "#/components/schemas/BrowserLinkInfo"
}
},
"url": {
"type": "string"
}
}
},
"BrowserMarkdownResponse": {
"type": "object",
"required": ["markdown", "url", "title"],
"properties": {
"markdown": {
"type": "string"
},
"title": {
"type": "string"
},
"url": {
"type": "string"
}
}
},
"BrowserMouseButton": {
"type": "string",
"enum": ["left", "right", "middle"]
},
"BrowserNavigateRequest": {
"type": "object",
"required": ["url"],
"properties": {
"url": {
"type": "string"
},
"waitUntil": {
"allOf": [
{
"$ref": "#/components/schemas/BrowserNavigateWaitUntil"
}
],
"nullable": true
}
}
},
"BrowserNavigateWaitUntil": {
"type": "string",
"enum": ["load", "domcontentloaded", "networkidle"]
},
"BrowserNetworkQuery": {
"type": "object",
"properties": {
"limit": {
"type": "integer",
"format": "int32",
"nullable": true,
"minimum": 0
},
"urlPattern": {
"type": "string",
"nullable": true
}
}
},
"BrowserNetworkRequest": {
"type": "object",
"required": ["url", "method", "timestamp"],
"properties": {
"duration": {
"type": "integer",
"format": "int64",
"nullable": true,
"minimum": 0
},
"method": {
"type": "string"
},
"mimeType": {
"type": "string",
"nullable": true
},
"responseSize": {
"type": "integer",
"format": "int64",
"nullable": true,
"minimum": 0
},
"status": {
"type": "integer",
"format": "int32",
"nullable": true,
"minimum": 0
},
"timestamp": {
"type": "string"
},
"url": {
"type": "string"
}
}
},
"BrowserNetworkResponse": {
"type": "object",
"required": ["requests"],
"properties": {
"requests": {
"type": "array",
"items": {
"$ref": "#/components/schemas/BrowserNetworkRequest"
}
}
}
},
"BrowserPageInfo": {
"type": "object",
"required": ["url", "title"],
"properties": {
"status": {
"type": "integer",
"format": "int32",
"nullable": true,
"minimum": 0
},
"title": {
"type": "string"
},
"url": {
"type": "string"
}
}
},
"BrowserPdfFormat": {
"type": "string",
"enum": ["a4", "letter", "legal"]
},
"BrowserPdfQuery": {
"type": "object",
"properties": {
"format": {
"allOf": [
{
"$ref": "#/components/schemas/BrowserPdfFormat"
}
],
"nullable": true
},
"landscape": {
"type": "boolean",
"nullable": true
},
"printBackground": {
"type": "boolean",
"nullable": true
},
"scale": {
"type": "number",
"format": "float",
"nullable": true
}
}
},
"BrowserReloadRequest": {
"type": "object",
"properties": {
"ignoreCache": {
"type": "boolean",
"nullable": true
}
}
},
"BrowserScrapeRequest": {
"type": "object",
"required": ["selectors"],
"properties": {
"selectors": {
"type": "object",
"additionalProperties": {
"type": "string"
}
},
"url": {
"type": "string",
"nullable": true
}
}
},
"BrowserScrapeResponse": {
"type": "object",
"required": ["data", "url", "title"],
"properties": {
"data": {
"type": "object",
"additionalProperties": {
"type": "array",
"items": {
"type": "string"
}
}
},
"title": {
"type": "string"
},
"url": {
"type": "string"
}
}
},
"BrowserScreenshotFormat": {
"type": "string",
"enum": ["png", "jpeg", "webp"]
},
"BrowserScreenshotQuery": {
"type": "object",
"properties": {
"format": {
"allOf": [
{
"$ref": "#/components/schemas/BrowserScreenshotFormat"
}
],
"nullable": true
},
"fullPage": {
"type": "boolean",
"nullable": true
},
"quality": {
"type": "integer",
"format": "int32",
"nullable": true,
"minimum": 0
},
"selector": {
"type": "string",
"nullable": true
}
}
},
"BrowserScrollRequest": {
"type": "object",
"properties": {
"selector": {
"type": "string",
"nullable": true
},
"x": {
"type": "integer",
"format": "int32",
"nullable": true
},
"y": {
"type": "integer",
"format": "int32",
"nullable": true
}
}
},
"BrowserSelectRequest": {
"type": "object",
"required": ["selector", "value"],
"properties": {
"selector": {
"type": "string"
},
"value": {
"type": "string"
}
}
},
"BrowserSetCookiesRequest": {
"type": "object",
"required": ["cookies"],
"properties": {
"cookies": {
"type": "array",
"items": {
"$ref": "#/components/schemas/BrowserCookie"
}
}
}
},
"BrowserSnapshotResponse": {
"type": "object",
"required": ["snapshot", "url", "title"],
"properties": {
"snapshot": {
"type": "string"
},
"title": {
"type": "string"
},
"url": {
"type": "string"
}
}
},
"BrowserStartRequest": {
"type": "object",
"properties": {
"contextId": {
"type": "string",
"nullable": true
},
"dpi": {
"type": "integer",
"format": "int32",
"nullable": true,
"minimum": 0
},
"headless": {
"type": "boolean",
"nullable": true
},
"height": {
"type": "integer",
"format": "int32",
"nullable": true,
"minimum": 0
},
"recordingFps": {
"type": "integer",
"format": "int32",
"nullable": true,
"minimum": 0
},
"streamAudioCodec": {
"type": "string",
"nullable": true
},
"streamFrameRate": {
"type": "integer",
"format": "int32",
"nullable": true,
"minimum": 0
},
"streamVideoCodec": {
"type": "string",
"nullable": true
},
"url": {
"type": "string",
"nullable": true
},
"webrtcPortRange": {
"type": "string",
"nullable": true
},
"width": {
"type": "integer",
"format": "int32",
"nullable": true,
"minimum": 0
}
}
},
"BrowserState": {
"type": "string",
"enum": ["inactive", "install_required", "starting", "active", "stopping", "failed"]
},
"BrowserStatusResponse": {
"type": "object",
"required": ["state"],
"properties": {
"cdpUrl": {
"type": "string",
"nullable": true
},
"display": {
"type": "string",
"nullable": true
},
"installCommand": {
"type": "string",
"nullable": true
},
"lastError": {
"allOf": [
{
"$ref": "#/components/schemas/DesktopErrorInfo"
}
],
"nullable": true
},
"missingDependencies": {
"type": "array",
"items": {
"type": "string"
}
},
"processes": {
"type": "array",
"items": {
"$ref": "#/components/schemas/DesktopProcessInfo"
}
},
"resolution": {
"allOf": [
{
"$ref": "#/components/schemas/DesktopResolution"
}
],
"nullable": true
},
"startedAt": {
"type": "string",
"nullable": true
},
"state": {
"$ref": "#/components/schemas/BrowserState"
},
"url": {
"type": "string",
"nullable": true
}
}
},
"BrowserTabInfo": {
"type": "object",
"required": ["id", "url", "title", "active"],
"properties": {
"active": {
"type": "boolean"
},
"id": {
"type": "string"
},
"title": {
"type": "string"
},
"url": {
"type": "string"
}
}
},
"BrowserTabListResponse": {
"type": "object",
"required": ["tabs"],
"properties": {
"tabs": {
"type": "array",
"items": {
"$ref": "#/components/schemas/BrowserTabInfo"
}
}
}
},
"BrowserTypeRequest": {
"type": "object",
"required": ["selector", "text"],
"properties": {
"clear": {
"type": "boolean",
"nullable": true
},
"delay": {
"type": "integer",
"format": "int64",
"nullable": true,
"minimum": 0
},
"selector": {
"type": "string"
},
"text": {
"type": "string"
}
}
},
"BrowserUploadRequest": {
"type": "object",
"required": ["selector", "path"],
"properties": {
"path": {
"type": "string"
},
"selector": {
"type": "string"
}
}
},
"BrowserWaitRequest": {
"type": "object",
"properties": {
"selector": {
"type": "string",
"nullable": true
},
"state": {
"allOf": [
{
"$ref": "#/components/schemas/BrowserWaitState"
}
],
"nullable": true
},
"timeout": {
"type": "integer",
"format": "int64",
"nullable": true,
"minimum": 0
}
}
},
"BrowserWaitResponse": {
"type": "object",
"required": ["found"],
"properties": {
"found": {
"type": "boolean"
}
}
},
"BrowserWaitState": {
"type": "string",
"enum": ["visible", "hidden", "attached"]
},
"DesktopActionResponse": {
"type": "object",
"required": ["ok"],
"properties": {
"ok": {
"type": "boolean"
}
}
},
"DesktopClipboardQuery": {
"type": "object",
"properties": {
"selection": {
"type": "string",
"nullable": true
}
}
},
"DesktopClipboardResponse": {
"type": "object",
"required": ["text", "selection"],
"properties": {
"selection": {
"type": "string"
},
"text": {
"type": "string"
}
}
},
"DesktopClipboardWriteRequest": {
"type": "object",
"required": ["text"],
"properties": {
"selection": {
"type": "string",
"nullable": true
},
"text": {
"type": "string"
}
}
},
"DesktopDisplayInfoResponse": {
"type": "object",
"required": ["display", "resolution"],
"properties": {
"display": {
"type": "string"
},
"resolution": {
"$ref": "#/components/schemas/DesktopResolution"
}
}
},
"DesktopErrorInfo": {
"type": "object",
"required": ["code", "message"],
"properties": {
"code": {
"type": "string"
},
"message": {
"type": "string"
}
}
},
"DesktopKeyModifiers": {
"type": "object",
"properties": {
"alt": {
"type": "boolean",
"nullable": true
},
"cmd": {
"type": "boolean",
"nullable": true
},
"ctrl": {
"type": "boolean",
"nullable": true
},
"shift": {
"type": "boolean",
"nullable": true
}
}
},
"DesktopKeyboardDownRequest": {
"type": "object",
"required": ["key"],
"properties": {
"key": {
"type": "string"
}
}
},
"DesktopKeyboardPressRequest": {
"type": "object",
"required": ["key"],
"properties": {
"key": {
"type": "string"
},
"modifiers": {
"allOf": [
{
"$ref": "#/components/schemas/DesktopKeyModifiers"
}
],
"nullable": true
}
}
},
"DesktopKeyboardTypeRequest": {
"type": "object",
"required": ["text"],
"properties": {
"delayMs": {
"type": "integer",
"format": "int32",
"nullable": true,
"minimum": 0
},
"text": {
"type": "string"
}
}
},
"DesktopKeyboardUpRequest": {
"type": "object",
"required": ["key"],
"properties": {
"key": {
"type": "string"
}
}
},
"DesktopLaunchRequest": {
"type": "object",
"required": ["app"],
"properties": {
"app": {
"type": "string"
},
"args": {
"type": "array",
"items": {
"type": "string"
},
"nullable": true
},
"wait": {
"type": "boolean",
"nullable": true
}
}
},
"DesktopLaunchResponse": {
"type": "object",
"required": ["processId"],
"properties": {
"pid": {
"type": "integer",
"format": "int32",
"nullable": true,
"minimum": 0
},
"processId": {
"type": "string"
},
"windowId": {
"type": "string",
"nullable": true
}
}
},
"DesktopMouseButton": {
"type": "string",
"enum": ["left", "middle", "right"]
},
"DesktopMouseClickRequest": {
"type": "object",
"required": ["x", "y"],
"properties": {
"button": {
"allOf": [
{
"$ref": "#/components/schemas/DesktopMouseButton"
}
],
"nullable": true
},
"clickCount": {
"type": "integer",
"format": "int32",
"nullable": true,
"minimum": 0
},
"x": {
"type": "integer",
"format": "int32"
},
"y": {
"type": "integer",
"format": "int32"
}
}
},
"DesktopMouseDownRequest": {
"type": "object",
"properties": {
"button": {
"allOf": [
{
"$ref": "#/components/schemas/DesktopMouseButton"
}
],
"nullable": true
},
"x": {
"type": "integer",
"format": "int32",
"nullable": true
},
"y": {
"type": "integer",
"format": "int32",
"nullable": true
}
}
},
"DesktopMouseDragRequest": {
"type": "object",
"required": ["startX", "startY", "endX", "endY"],
"properties": {
"button": {
"allOf": [
{
"$ref": "#/components/schemas/DesktopMouseButton"
}
],
"nullable": true
},
"endX": {
"type": "integer",
"format": "int32"
},
"endY": {
"type": "integer",
"format": "int32"
},
"startX": {
"type": "integer",
"format": "int32"
},
"startY": {
"type": "integer",
"format": "int32"
}
}
},
"DesktopMouseMoveRequest": {
"type": "object",
"required": ["x", "y"],
"properties": {
"x": {
"type": "integer",
"format": "int32"
},
"y": {
"type": "integer",
"format": "int32"
}
}
},
"DesktopMousePositionResponse": {
"type": "object",
"required": ["x", "y"],
"properties": {
"screen": {
"type": "integer",
"format": "int32",
"nullable": true
},
"window": {
"type": "string",
"nullable": true
},
"x": {
"type": "integer",
"format": "int32"
},
"y": {
"type": "integer",
"format": "int32"
}
}
},
"DesktopMouseScrollRequest": {
"type": "object",
"required": ["x", "y"],
"properties": {
"deltaX": {
"type": "integer",
"format": "int32",
"nullable": true
},
"deltaY": {
"type": "integer",
"format": "int32",
"nullable": true
},
"x": {
"type": "integer",
"format": "int32"
},
"y": {
"type": "integer",
"format": "int32"
}
}
},
"DesktopMouseUpRequest": {
"type": "object",
"properties": {
"button": {
"allOf": [
{
"$ref": "#/components/schemas/DesktopMouseButton"
}
],
"nullable": true
},
"x": {
"type": "integer",
"format": "int32",
"nullable": true
},
"y": {
"type": "integer",
"format": "int32",
"nullable": true
}
}
},
"DesktopOpenRequest": {
"type": "object",
"required": ["target"],
"properties": {
"target": {
"type": "string"
}
}
},
"DesktopOpenResponse": {
"type": "object",
"required": ["processId"],
"properties": {
"pid": {
"type": "integer",
"format": "int32",
"nullable": true,
"minimum": 0
},
"processId": {
"type": "string"
}
}
},
"DesktopProcessInfo": {
"type": "object",
"required": ["name", "running"],
"properties": {
"logPath": {
"type": "string",
"nullable": true
},
"name": {
"type": "string"
},
"pid": {
"type": "integer",
"format": "int32",
"nullable": true,
"minimum": 0
},
"running": {
"type": "boolean"
}
}
},
"DesktopRecordingInfo": {
"type": "object",
"required": ["id", "status", "fileName", "bytes", "startedAt"],
"properties": {
"bytes": {
"type": "integer",
"format": "int64",
"minimum": 0
},
"endedAt": {
"type": "string",
"nullable": true
},
"fileName": {
"type": "string"
},
"id": {
"type": "string"
},
"processId": {
"type": "string",
"nullable": true
},
"startedAt": {
"type": "string"
},
"status": {
"$ref": "#/components/schemas/DesktopRecordingStatus"
}
}
},
"DesktopRecordingListResponse": {
"type": "object",
"required": ["recordings"],
"properties": {
"recordings": {
"type": "array",
"items": {
"$ref": "#/components/schemas/DesktopRecordingInfo"
}
}
}
},
"DesktopRecordingStartRequest": {
"type": "object",
"properties": {
"fps": {
"type": "integer",
"format": "int32",
"nullable": true,
"minimum": 0
}
}
},
"DesktopRecordingStatus": {
"type": "string",
"enum": ["recording", "completed", "failed"]
},
"DesktopRegionScreenshotQuery": {
"type": "object",
"required": ["x", "y", "width", "height"],
"properties": {
"format": {
"allOf": [
{
"$ref": "#/components/schemas/DesktopScreenshotFormat"
}
],
"nullable": true
},
"height": {
"type": "integer",
"format": "int32",
"minimum": 0
},
"quality": {
"type": "integer",
"format": "int32",
"nullable": true,
"minimum": 0
},
"scale": {
"type": "number",
"format": "float",
"nullable": true
},
"showCursor": {
"type": "boolean",
"nullable": true
},
"width": {
"type": "integer",
"format": "int32",
"minimum": 0
},
"x": {
"type": "integer",
"format": "int32"
},
"y": {
"type": "integer",
"format": "int32"
}
}
},
"DesktopResolution": {
"type": "object",
"required": ["width", "height"],
"properties": {
"dpi": {
"type": "integer",
"format": "int32",
"nullable": true,
"minimum": 0
},
"height": {
"type": "integer",
"format": "int32",
"minimum": 0
},
"width": {
"type": "integer",
"format": "int32",
"minimum": 0
}
}
},
"DesktopScreenshotFormat": {
"type": "string",
"enum": ["png", "jpeg", "webp"]
},
"DesktopScreenshotQuery": {
"type": "object",
"properties": {
"format": {
"allOf": [
{
"$ref": "#/components/schemas/DesktopScreenshotFormat"
}
],
"nullable": true
},
"quality": {
"type": "integer",
"format": "int32",
"nullable": true,
"minimum": 0
},
"scale": {
"type": "number",
"format": "float",
"nullable": true
},
"showCursor": {
"type": "boolean",
"nullable": true
}
}
},
"DesktopStartRequest": {
"type": "object",
"properties": {
"displayNum": {
"type": "integer",
"format": "int32",
"nullable": true
},
"dpi": {
"type": "integer",
"format": "int32",
"nullable": true,
"minimum": 0
},
"height": {
"type": "integer",
"format": "int32",
"nullable": true,
"minimum": 0
},
"recordingFps": {
"type": "integer",
"format": "int32",
"nullable": true,
"minimum": 0
},
"stateDir": {
"type": "string",
"nullable": true
},
"streamAudioCodec": {
"type": "string",
"nullable": true
},
"streamFrameRate": {
"type": "integer",
"format": "int32",
"nullable": true,
"minimum": 0
},
"streamVideoCodec": {
"type": "string",
"nullable": true
},
"webrtcPortRange": {
"type": "string",
"nullable": true
},
"width": {
"type": "integer",
"format": "int32",
"nullable": true,
"minimum": 0
}
}
},
"DesktopState": {
"type": "string",
"enum": ["inactive", "install_required", "starting", "active", "stopping", "failed"]
},
"DesktopStatusResponse": {
"type": "object",
"required": ["state"],
"properties": {
"display": {
"type": "string",
"nullable": true
},
"installCommand": {
"type": "string",
"nullable": true
},
"lastError": {
"allOf": [
{
"$ref": "#/components/schemas/DesktopErrorInfo"
}
],
"nullable": true
},
"missingDependencies": {
"type": "array",
"items": {
"type": "string"
}
},
"processes": {
"type": "array",
"items": {
"$ref": "#/components/schemas/DesktopProcessInfo"
}
},
"resolution": {
"allOf": [
{
"$ref": "#/components/schemas/DesktopResolution"
}
],
"nullable": true
},
"runtimeLogPath": {
"type": "string",
"nullable": true
},
"startedAt": {
"type": "string",
"nullable": true
},
"state": {
"$ref": "#/components/schemas/DesktopState"
},
"windows": {
"type": "array",
"items": {
"$ref": "#/components/schemas/DesktopWindowInfo"
},
"description": "Current visible windows (included when the desktop is active)."
}
}
},
"DesktopStreamStatusResponse": {
"type": "object",
"required": ["active"],
"properties": {
"active": {
"type": "boolean"
},
"processId": {
"type": "string",
"nullable": true
},
"windowId": {
"type": "string",
"nullable": true
}
}
},
"DesktopWindowInfo": {
"type": "object",
"required": ["id", "title", "x", "y", "width", "height", "isActive"],
"properties": {
"height": {
"type": "integer",
"format": "int32",
"minimum": 0
},
"id": {
"type": "string"
},
"isActive": {
"type": "boolean"
},
"title": {
"type": "string"
},
"width": {
"type": "integer",
"format": "int32",
"minimum": 0
},
"x": {
"type": "integer",
"format": "int32"
},
"y": {
"type": "integer",
"format": "int32"
}
}
},
"DesktopWindowListResponse": {
"type": "object",
"required": ["windows"],
"properties": {
"windows": {
"type": "array",
"items": {
"$ref": "#/components/schemas/DesktopWindowInfo"
}
}
}
},
"DesktopWindowMoveRequest": {
"type": "object",
"required": ["x", "y"],
"properties": {
"x": {
"type": "integer",
"format": "int32"
},
"y": {
"type": "integer",
"format": "int32"
}
}
},
"DesktopWindowResizeRequest": {
"type": "object",
"required": ["width", "height"],
"properties": {
"height": {
"type": "integer",
"format": "int32",
"minimum": 0
},
"width": {
"type": "integer",
"format": "int32",
"minimum": 0
}
}
},
"ErrorType": {
"type": "string",
"enum": [
"invalid_request",
"conflict",
"unsupported_agent",
"agent_not_installed",
"install_failed",
"agent_process_exited",
"token_invalid",
"permission_denied",
"not_acceptable",
"unsupported_media_type",
"not_found",
"session_not_found",
"session_already_exists",
"mode_not_supported",
"stream_error",
"timeout"
]
},
"FsActionResponse": {
"type": "object",
"required": ["path"],
"properties": {
"path": {
"type": "string"
}
}
},
"FsDeleteQuery": {
"type": "object",
"required": ["path"],
"properties": {
"path": {
"type": "string"
},
"recursive": {
"type": "boolean",
"nullable": true
}
}
},
"FsEntriesQuery": {
"type": "object",
"properties": {
"path": {
"type": "string",
"nullable": true
}
}
},
"FsEntry": {
"type": "object",
"required": ["name", "path", "entryType", "size"],
"properties": {
"entryType": {
"$ref": "#/components/schemas/FsEntryType"
},
"modified": {
"type": "string",
"nullable": true
},
"name": {
"type": "string"
},
"path": {
"type": "string"
},
"size": {
"type": "integer",
"format": "int64",
"minimum": 0
}
}
},
"FsEntryType": {
"type": "string",
"enum": ["file", "directory"]
},
"FsMoveRequest": {
"type": "object",
"required": ["from", "to"],
"properties": {
"from": {
"type": "string"
},
"overwrite": {
"type": "boolean",
"nullable": true
},
"to": {
"type": "string"
}
}
},
"FsMoveResponse": {
"type": "object",
"required": ["from", "to"],
"properties": {
"from": {
"type": "string"
},
"to": {
"type": "string"
}
}
},
"FsPathQuery": {
"type": "object",
"required": ["path"],
"properties": {
"path": {
"type": "string"
}
}
},
"FsStat": {
"type": "object",
"required": ["path", "entryType", "size"],
"properties": {
"entryType": {
"$ref": "#/components/schemas/FsEntryType"
},
"modified": {
"type": "string",
"nullable": true
},
"path": {
"type": "string"
},
"size": {
"type": "integer",
"format": "int64",
"minimum": 0
}
}
},
"FsUploadBatchQuery": {
"type": "object",
"properties": {
"path": {
"type": "string",
"nullable": true
}
}
},
"FsUploadBatchResponse": {
"type": "object",
"required": ["paths", "truncated"],
"properties": {
"paths": {
"type": "array",
"items": {
"type": "string"
}
},
"truncated": {
"type": "boolean"
}
}
},
"FsWriteResponse": {
"type": "object",
"required": ["path", "bytesWritten"],
"properties": {
"bytesWritten": {
"type": "integer",
"format": "int64",
"minimum": 0
},
"path": {
"type": "string"
}
}
},
"HealthResponse": {
"type": "object",
"required": ["status"],
"properties": {
"status": {
"type": "string"
}
}
},
"McpConfigQuery": {
"type": "object",
"required": ["directory", "mcpName"],
"properties": {
"directory": {
"type": "string"
},
"mcpName": {
"type": "string"
}
}
},
"McpServerConfig": {
"oneOf": [
{
"type": "object",
"required": ["command", "type"],
"properties": {
"args": {
"type": "array",
"items": {
"type": "string"
}
},
"command": {
"$ref": "#/components/schemas/McpCommand"
},
"cwd": {
"type": "string",
"nullable": true
},
"enabled": {
"type": "boolean",
"nullable": true
},
"env": {
"type": "object",
"additionalProperties": {
"type": "string"
},
"nullable": true
},
"timeoutMs": {
"type": "integer",
"format": "int64",
"nullable": true,
"minimum": 0
},
"type": {
"type": "string",
"enum": ["local"]
}
}
},
{
"type": "object",
"required": ["url", "type"],
"properties": {
"bearerTokenEnvVar": {
"type": "string",
"nullable": true
},
"enabled": {
"type": "boolean",
"nullable": true
},
"envHeaders": {
"type": "object",
"additionalProperties": {
"type": "string"
},
"nullable": true
},
"headers": {
"type": "object",
"additionalProperties": {
"type": "string"
},
"nullable": true
},
"oauth": {
"allOf": [
{
"$ref": "#/components/schemas/McpOAuthConfigOrDisabled"
}
],
"nullable": true
},
"timeoutMs": {
"type": "integer",
"format": "int64",
"nullable": true,
"minimum": 0
},
"transport": {
"allOf": [
{
"$ref": "#/components/schemas/McpRemoteTransport"
}
],
"nullable": true
},
"type": {
"type": "string",
"enum": ["remote"]
},
"url": {
"type": "string"
}
}
}
],
"discriminator": {
"propertyName": "type"
}
},
"ProblemDetails": {
"type": "object",
"required": ["type", "title", "status"],
"properties": {
"detail": {
"type": "string",
"nullable": true
},
"instance": {
"type": "string",
"nullable": true
},
"status": {
"type": "integer",
"format": "int32",
"minimum": 0
},
"title": {
"type": "string"
},
"type": {
"type": "string"
}
},
"additionalProperties": {}
},
"ProcessConfig": {
"type": "object",
"required": ["maxConcurrentProcesses", "defaultRunTimeoutMs", "maxRunTimeoutMs", "maxOutputBytes", "maxLogBytesPerProcess", "maxInputBytesPerRequest"],
"properties": {
"defaultRunTimeoutMs": {
"type": "integer",
"format": "int64",
"minimum": 0
},
"maxConcurrentProcesses": {
"type": "integer",
"minimum": 0
},
"maxInputBytesPerRequest": {
"type": "integer",
"minimum": 0
},
"maxLogBytesPerProcess": {
"type": "integer",
"minimum": 0
},
"maxOutputBytes": {
"type": "integer",
"minimum": 0
},
"maxRunTimeoutMs": {
"type": "integer",
"format": "int64",
"minimum": 0
}
}
},
"ProcessCreateRequest": {
"type": "object",
"required": ["command"],
"properties": {
"args": {
"type": "array",
"items": {
"type": "string"
}
},
"command": {
"type": "string"
},
"cwd": {
"type": "string",
"nullable": true
},
"env": {
"type": "object",
"additionalProperties": {
"type": "string"
}
},
"interactive": {
"type": "boolean"
},
"tty": {
"type": "boolean"
}
}
},
"ProcessInfo": {
"type": "object",
"required": ["id", "command", "args", "tty", "interactive", "owner", "status", "createdAtMs"],
"properties": {
"args": {
"type": "array",
"items": {
"type": "string"
}
},
"command": {
"type": "string"
},
"createdAtMs": {
"type": "integer",
"format": "int64"
},
"cwd": {
"type": "string",
"nullable": true
},
"exitCode": {
"type": "integer",
"format": "int32",
"nullable": true
},
"exitedAtMs": {
"type": "integer",
"format": "int64",
"nullable": true
},
"id": {
"type": "string"
},
"interactive": {
"type": "boolean"
},
"owner": {
"$ref": "#/components/schemas/ProcessOwner"
},
"pid": {
"type": "integer",
"format": "int32",
"nullable": true,
"minimum": 0
},
"status": {
"$ref": "#/components/schemas/ProcessState"
},
"tty": {
"type": "boolean"
}
}
},
"ProcessInputRequest": {
"type": "object",
"required": ["data"],
"properties": {
"data": {
"type": "string"
},
"encoding": {
"type": "string",
"nullable": true
}
}
},
"ProcessInputResponse": {
"type": "object",
"required": ["bytesWritten"],
"properties": {
"bytesWritten": {
"type": "integer",
"minimum": 0
}
}
},
"ProcessListQuery": {
"type": "object",
"properties": {
"owner": {
"allOf": [
{
"$ref": "#/components/schemas/ProcessOwner"
}
],
"nullable": true
}
}
},
"ProcessListResponse": {
"type": "object",
"required": ["processes"],
"properties": {
"processes": {
"type": "array",
"items": {
"$ref": "#/components/schemas/ProcessInfo"
}
}
}
},
"ProcessLogEntry": {
"type": "object",
"required": ["sequence", "stream", "timestampMs", "data", "encoding"],
"properties": {
"data": {
"type": "string"
},
"encoding": {
"type": "string"
},
"sequence": {
"type": "integer",
"format": "int64",
"minimum": 0
},
"stream": {
"$ref": "#/components/schemas/ProcessLogsStream"
},
"timestampMs": {
"type": "integer",
"format": "int64"
}
}
},
"ProcessLogsQuery": {
"type": "object",
"properties": {
"follow": {
"type": "boolean",
"nullable": true
},
"since": {
"type": "integer",
"format": "int64",
"nullable": true,
"minimum": 0
},
"stream": {
"allOf": [
{
"$ref": "#/components/schemas/ProcessLogsStream"
}
],
"nullable": true
},
"tail": {
"type": "integer",
"nullable": true,
"minimum": 0
}
}
},
"ProcessLogsResponse": {
"type": "object",
"required": ["processId", "stream", "entries"],
"properties": {
"entries": {
"type": "array",
"items": {
"$ref": "#/components/schemas/ProcessLogEntry"
}
},
"processId": {
"type": "string"
},
"stream": {
"$ref": "#/components/schemas/ProcessLogsStream"
}
}
},
"ProcessLogsStream": {
"type": "string",
"enum": ["stdout", "stderr", "combined", "pty"]
},
"ProcessOwner": {
"type": "string",
"enum": ["user", "desktop", "system"]
},
"ProcessRunRequest": {
"type": "object",
"required": ["command"],
"properties": {
"args": {
"type": "array",
"items": {
"type": "string"
}
},
"command": {
"type": "string"
},
"cwd": {
"type": "string",
"nullable": true
},
"env": {
"type": "object",
"additionalProperties": {
"type": "string"
}
},
"maxOutputBytes": {
"type": "integer",
"nullable": true,
"minimum": 0
},
"timeoutMs": {
"type": "integer",
"format": "int64",
"nullable": true,
"minimum": 0
}
}
},
"ProcessRunResponse": {
"type": "object",
"required": ["timedOut", "stdout", "stderr", "stdoutTruncated", "stderrTruncated", "durationMs"],
"properties": {
"durationMs": {
"type": "integer",
"format": "int64",
"minimum": 0
},
"exitCode": {
"type": "integer",
"format": "int32",
"nullable": true
},
"stderr": {
"type": "string"
},
"stderrTruncated": {
"type": "boolean"
},
"stdout": {
"type": "string"
},
"stdoutTruncated": {
"type": "boolean"
},
"timedOut": {
"type": "boolean"
}
}
},
"ProcessSignalQuery": {
"type": "object",
"properties": {
"waitMs": {
"type": "integer",
"format": "int64",
"nullable": true,
"minimum": 0
}
}
},
"ProcessState": {
"type": "string",
"enum": ["running", "exited"]
},
"ProcessTerminalResizeRequest": {
"type": "object",
"required": ["cols", "rows"],
"properties": {
"cols": {
"type": "integer",
"format": "int32",
"minimum": 0
},
"rows": {
"type": "integer",
"format": "int32",
"minimum": 0
}
}
},
"ProcessTerminalResizeResponse": {
"type": "object",
"required": ["cols", "rows"],
"properties": {
"cols": {
"type": "integer",
"format": "int32",
"minimum": 0
},
"rows": {
"type": "integer",
"format": "int32",
"minimum": 0
}
}
},
"ServerStatus": {
"type": "string",
"enum": ["running", "stopped"]
},
"ServerStatusInfo": {
"type": "object",
"required": ["status"],
"properties": {
"status": {
"$ref": "#/components/schemas/ServerStatus"
},
"uptimeMs": {
"type": "integer",
"format": "int64",
"nullable": true,
"minimum": 0
}
}
},
"SkillSource": {
"type": "object",
"required": ["type", "source"],
"properties": {
"ref": {
"type": "string",
"nullable": true
},
"skills": {
"type": "array",
"items": {
"type": "string"
},
"nullable": true
},
"source": {
"type": "string"
},
"subpath": {
"type": "string",
"nullable": true
},
"type": {
"type": "string"
}
}
},
"SkillsConfig": {
"type": "object",
"required": ["sources"],
"properties": {
"sources": {
"type": "array",
"items": {
"$ref": "#/components/schemas/SkillSource"
}
}
}
},
"SkillsConfigQuery": {
"type": "object",
"required": ["directory", "skillName"],
"properties": {
"directory": {
"type": "string"
},
"skillName": {
"type": "string"
}
}
}
}
},
"tags": [
{
"name": "v1",
"description": "ACP proxy v1 API"
}
]
}
Reference in a new issue View git blame Copy permalink