harivansh-afk/sandbox-agent
1
0
Fork 0
mirror of https://github.com/harivansh-afk/sandbox-agent.git synced 2026-04-15 08:03:46 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions
sandbox-agent/docs/openapi.json
Nathan Flurry 78e84281e8 chore(release): update version to 0.4.1
2026-03-25 13:20:57 -07:00

5285 lines
139 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.4.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/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"
}
}
}
},
"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