{
 "openapi": "3.1.0",
 "info": {
  "title": "StateSet Sandbox API",
  "version": "1.0.0",
  "description": "Secure code execution infrastructure for AI agents. Provides isolated Kubernetes pods for running code safely.",
  "contact": {
   "name": "StateSet Engineering",
   "url": "https://stateset.io"
  },
  "license": {
   "name": "MIT",
   "url": "https://opensource.org/licenses/MIT"
  }
 },
 "servers": [
  {
   "url": "https://api.sandbox.stateset.app",
   "description": "Production"
  },
  {
   "url": "http://localhost:8080",
   "description": "Local development"
  }
 ],
 "security": [
  {
   "BearerAuth": []
  },
  {
   "ApiKeyAuth": []
  }
 ],
 "paths": {
  "/api/v1/sandbox/create": {
   "post": {
    "tags": [
     "Sandbox Lifecycle"
    ],
    "summary": "Create a new sandbox",
    "operationId": "createSandbox",
    "requestBody": {
     "required": true,
     "content": {
      "application/json": {
       "schema": {
        "$ref": "#/components/schemas/CreateSandboxRequest"
       }
      }
     }
    },
    "responses": {
     "201": {
      "description": "Sandbox created successfully",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/SandboxResponse"
        }
       }
      }
     },
     "202": {
      "description": "Request queued due to concurrency limits"
     },
     "400": {
      "description": "Invalid request",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorResponse"
        }
       }
      }
     },
     "401": {
      "description": "Authentication required",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorResponse"
        }
       }
      }
     },
     "429": {
      "description": "Concurrent limit exceeded",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorResponse"
        }
       }
      }
     }
    }
   }
  },
  "/api/v1/sandbox/{id}": {
   "get": {
    "tags": [
     "Sandbox Lifecycle"
    ],
    "summary": "Get sandbox details",
    "operationId": "getSandbox",
    "parameters": [
     {
      "name": "id",
      "in": "path",
      "required": true,
      "schema": {
       "type": "string",
       "format": "uuid"
      },
      "description": "Sandbox identifier"
     }
    ],
    "responses": {
     "200": {
      "description": "Sandbox details",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/SandboxResponse"
        }
       }
      }
     },
     "404": {
      "description": "Sandbox not found",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorResponse"
        }
       }
      }
     }
    }
   },
   "delete": {
    "tags": [
     "Sandbox Lifecycle"
    ],
    "summary": "Delete a sandbox (alias for stop)",
    "operationId": "deleteSandbox",
    "parameters": [
     {
      "name": "id",
      "in": "path",
      "required": true,
      "schema": {
       "type": "string",
       "format": "uuid"
      },
      "description": "Sandbox identifier"
     }
    ],
    "responses": {
     "200": {
      "description": "Sandbox deleted"
     },
     "404": {
      "description": "Sandbox not found",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorResponse"
        }
       }
      }
     }
    }
   }
  },
  "/api/v1/sandboxes": {
   "get": {
    "tags": [
     "Sandbox Lifecycle"
    ],
    "summary": "List sandboxes for the authenticated organization",
    "operationId": "listSandboxes",
    "parameters": [
     {
      "name": "limit",
      "in": "query",
      "required": false,
      "schema": {
       "type": "integer"
      },
      "description": "Max results (1-100, default 20)"
     },
     {
      "name": "offset",
      "in": "query",
      "required": false,
      "schema": {
       "type": "integer"
      },
      "description": "Results offset (default 0)"
     },
     {
      "name": "state",
      "in": "query",
      "required": false,
      "schema": {
       "type": "string"
      },
      "description": "Comma-separated state filter (e.g. running,paused)"
     }
    ],
    "responses": {
     "200": {
      "description": "Paginated list of sandboxes"
     }
    }
   }
  },
  "/api/v1/sandbox/{id}/stop": {
   "post": {
    "tags": [
     "Sandbox Lifecycle"
    ],
    "summary": "Stop and delete a sandbox",
    "operationId": "stopSandbox",
    "parameters": [
     {
      "name": "id",
      "in": "path",
      "required": true,
      "schema": {
       "type": "string",
       "format": "uuid"
      },
      "description": "Sandbox identifier"
     }
    ],
    "responses": {
     "200": {
      "description": "Sandbox stopped"
     },
     "404": {
      "description": "Sandbox not found",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorResponse"
        }
       }
      }
     }
    }
   }
  },
  "/api/v1/sandbox/{id}/extend": {
   "post": {
    "tags": [
     "Sandbox Lifecycle"
    ],
    "summary": "Extend sandbox expiration window",
    "operationId": "extendSandbox",
    "parameters": [
     {
      "name": "id",
      "in": "path",
      "required": true,
      "schema": {
       "type": "string",
       "format": "uuid"
      },
      "description": "Sandbox identifier"
     }
    ],
    "requestBody": {
     "required": true,
     "content": {
      "application/json": {
       "schema": {
        "$ref": "#/components/schemas/ExtendSandboxRequest"
       }
      }
     }
    },
    "responses": {
     "200": {
      "description": "Sandbox extended",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/SandboxResponse"
        }
       }
      }
     },
     "404": {
      "description": "Sandbox not found",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorResponse"
        }
       }
      }
     }
    }
   }
  },
  "/api/v1/sandbox/{id}/status": {
   "get": {
    "tags": [
     "Sandbox Lifecycle"
    ],
    "summary": "Get sandbox status (lightweight)",
    "operationId": "getSandboxStatus",
    "parameters": [
     {
      "name": "id",
      "in": "path",
      "required": true,
      "schema": {
       "type": "string",
       "format": "uuid"
      },
      "description": "Sandbox identifier"
     }
    ],
    "responses": {
     "200": {
      "description": "Sandbox status"
     }
    }
   }
  },
  "/api/v1/sandbox/{id}/pause": {
   "post": {
    "tags": [
     "Sandbox Lifecycle"
    ],
    "summary": "Pause a running sandbox",
    "operationId": "pauseSandbox",
    "parameters": [
     {
      "name": "id",
      "in": "path",
      "required": true,
      "schema": {
       "type": "string",
       "format": "uuid"
      },
      "description": "Sandbox identifier"
     }
    ],
    "responses": {
     "200": {
      "description": "Sandbox paused"
     },
     "404": {
      "description": "Sandbox not found",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorResponse"
        }
       }
      }
     },
     "409": {
      "description": "Sandbox not in a pausable state",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorResponse"
        }
       }
      }
     }
    }
   }
  },
  "/api/v1/sandbox/{id}/resume": {
   "post": {
    "tags": [
     "Sandbox Lifecycle"
    ],
    "summary": "Resume a paused sandbox",
    "operationId": "resumeSandbox",
    "parameters": [
     {
      "name": "id",
      "in": "path",
      "required": true,
      "schema": {
       "type": "string",
       "format": "uuid"
      },
      "description": "Sandbox identifier"
     }
    ],
    "responses": {
     "200": {
      "description": "Sandbox resumed"
     },
     "404": {
      "description": "Sandbox not found",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorResponse"
        }
       }
      }
     },
     "409": {
      "description": "Sandbox not paused",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorResponse"
        }
       }
      }
     }
    }
   }
  },
  "/api/v1/sandbox/{id}/execute": {
   "post": {
    "tags": [
     "Execution"
    ],
    "summary": "Execute a command in a sandbox",
    "operationId": "executeCommand",
    "parameters": [
     {
      "name": "id",
      "in": "path",
      "required": true,
      "schema": {
       "type": "string",
       "format": "uuid"
      },
      "description": "Sandbox identifier"
     }
    ],
    "requestBody": {
     "required": true,
     "content": {
      "application/json": {
       "schema": {
        "$ref": "#/components/schemas/ExecuteCommandRequest"
       }
      }
     }
    },
    "responses": {
     "200": {
      "description": "Command result"
     },
     "404": {
      "description": "Sandbox not found",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorResponse"
        }
       }
      }
     }
    }
   }
  },
  "/api/v1/sandbox/{id}/executions": {
   "get": {
    "tags": [
     "Execution"
    ],
    "summary": "List executions for a sandbox",
    "operationId": "listExecutions",
    "parameters": [
     {
      "name": "id",
      "in": "path",
      "required": true,
      "schema": {
       "type": "string",
       "format": "uuid"
      },
      "description": "Sandbox identifier"
     }
    ],
    "responses": {
     "200": {
      "description": "List of executions"
     }
    }
   }
  },
  "/api/v1/sandbox/{id}/executions/{executionId}": {
   "get": {
    "tags": [
     "Execution"
    ],
    "summary": "Get execution details",
    "operationId": "getExecution",
    "parameters": [
     {
      "name": "id",
      "in": "path",
      "required": true,
      "schema": {
       "type": "string",
       "format": "uuid"
      },
      "description": "Sandbox identifier"
     },
     {
      "name": "executionId",
      "in": "path",
      "required": true,
      "schema": {
       "type": "string"
      },
      "description": "Execution identifier"
     }
    ],
    "responses": {
     "200": {
      "description": "Execution details"
     },
     "404": {
      "description": "Execution not found",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorResponse"
        }
       }
      }
     }
    }
   }
  },
  "/api/v1/sandbox/{id}/executions/{executionId}/stream": {
   "get": {
    "tags": [
     "Execution"
    ],
    "summary": "Stream execution output via SSE",
    "operationId": "streamExecution",
    "parameters": [
     {
      "name": "id",
      "in": "path",
      "required": true,
      "schema": {
       "type": "string",
       "format": "uuid"
      },
      "description": "Sandbox identifier"
     },
     {
      "name": "executionId",
      "in": "path",
      "required": true,
      "schema": {
       "type": "string"
      },
      "description": "Execution identifier"
     }
    ],
    "responses": {
     "200": {
      "description": "SSE event stream"
     }
    }
   }
  },
  "/api/v1/sandbox/{id}/files/write": {
   "post": {
    "tags": [
     "Files"
    ],
    "summary": "Write files to a sandbox",
    "operationId": "writeFiles",
    "parameters": [
     {
      "name": "id",
      "in": "path",
      "required": true,
      "schema": {
       "type": "string",
       "format": "uuid"
      },
      "description": "Sandbox identifier"
     }
    ],
    "requestBody": {
     "required": true,
     "content": {
      "application/json": {
       "schema": {
        "$ref": "#/components/schemas/WriteFilesRequest"
       }
      }
     }
    },
    "responses": {
     "200": {
      "description": "Files written"
     },
     "404": {
      "description": "Sandbox not found",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorResponse"
        }
       }
      }
     }
    }
   }
  },
  "/api/v1/sandbox/{id}/files/read": {
   "get": {
    "tags": [
     "Files"
    ],
    "summary": "Read a file from a sandbox",
    "operationId": "readFile",
    "parameters": [
     {
      "name": "id",
      "in": "path",
      "required": true,
      "schema": {
       "type": "string",
       "format": "uuid"
      },
      "description": "Sandbox identifier"
     },
     {
      "name": "path",
      "in": "query",
      "required": true,
      "schema": {
       "type": "string"
      },
      "description": "File path within /workspace"
     }
    ],
    "responses": {
     "200": {
      "description": "File content"
     },
     "404": {
      "description": "Sandbox not found",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorResponse"
        }
       }
      }
     }
    }
   }
  },
  "/api/v1/sandbox/{id}/files": {
   "get": {
    "tags": [
     "Files"
    ],
    "summary": "List files in a sandbox directory",
    "operationId": "listFiles",
    "parameters": [
     {
      "name": "id",
      "in": "path",
      "required": true,
      "schema": {
       "type": "string",
       "format": "uuid"
      },
      "description": "Sandbox identifier"
     },
     {
      "name": "path",
      "in": "query",
      "required": false,
      "schema": {
       "type": "string"
      },
      "description": "Directory path (default /workspace)"
     },
     {
      "name": "recursive",
      "in": "query",
      "required": false,
      "schema": {
       "type": "string"
      },
      "description": "Recurse into subdirectories (true/false)"
     }
    ],
    "responses": {
     "200": {
      "description": "File listing"
     }
    }
   },
   "delete": {
    "tags": [
     "Files"
    ],
    "summary": "Delete a file or directory from the sandbox",
    "operationId": "deleteFile",
    "parameters": [
     {
      "name": "id",
      "in": "path",
      "required": true,
      "schema": {
       "type": "string",
       "format": "uuid"
      },
      "description": "Sandbox identifier"
     }
    ],
    "requestBody": {
     "required": true,
     "content": {
      "application/json": {
       "schema": {
        "$ref": "#/components/schemas/DeleteFileRequest"
       }
      }
     }
    },
    "responses": {
     "200": {
      "description": "File or directory deleted"
     },
     "404": {
      "description": "Sandbox not found",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorResponse"
        }
       }
      }
     }
    }
   }
  },
  "/api/v1/sandbox/{id}/files/glob": {
   "post": {
    "tags": [
     "Files"
    ],
    "summary": "Find files matching a glob pattern",
    "operationId": "globFiles",
    "parameters": [
     {
      "name": "id",
      "in": "path",
      "required": true,
      "schema": {
       "type": "string",
       "format": "uuid"
      },
      "description": "Sandbox identifier"
     }
    ],
    "requestBody": {
     "required": true,
     "content": {
      "application/json": {
       "schema": {
        "$ref": "#/components/schemas/GlobQueryRequest"
       }
      }
     }
    },
    "responses": {
     "200": {
      "description": "Matching files"
     },
     "404": {
      "description": "Sandbox not found",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorResponse"
        }
       }
      }
     }
    }
   }
  },
  "/api/v1/sandbox/{id}/files/mkdir": {
   "post": {
    "tags": [
     "Files"
    ],
    "summary": "Create a directory in the sandbox",
    "operationId": "mkdirFile",
    "parameters": [
     {
      "name": "id",
      "in": "path",
      "required": true,
      "schema": {
       "type": "string",
       "format": "uuid"
      },
      "description": "Sandbox identifier"
     }
    ],
    "requestBody": {
     "required": true,
     "content": {
      "application/json": {
       "schema": {
        "$ref": "#/components/schemas/MkdirRequest"
       }
      }
     }
    },
    "responses": {
     "200": {
      "description": "Directory created"
     },
     "404": {
      "description": "Sandbox not found",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorResponse"
        }
       }
      }
     }
    }
   }
  },
  "/api/v1/sandbox/{id}/files/move": {
   "post": {
    "tags": [
     "Files"
    ],
    "summary": "Move or rename a file",
    "operationId": "moveFile",
    "parameters": [
     {
      "name": "id",
      "in": "path",
      "required": true,
      "schema": {
       "type": "string",
       "format": "uuid"
      },
      "description": "Sandbox identifier"
     }
    ],
    "requestBody": {
     "required": true,
     "content": {
      "application/json": {
       "schema": {
        "$ref": "#/components/schemas/MoveFileRequest"
       }
      }
     }
    },
    "responses": {
     "200": {
      "description": "File moved"
     },
     "404": {
      "description": "Sandbox not found",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorResponse"
        }
       }
      }
     }
    }
   }
  },
  "/api/v1/sandbox/{id}/files/copy": {
   "post": {
    "tags": [
     "Files"
    ],
    "summary": "Copy a file or directory",
    "operationId": "copyFile",
    "parameters": [
     {
      "name": "id",
      "in": "path",
      "required": true,
      "schema": {
       "type": "string",
       "format": "uuid"
      },
      "description": "Sandbox identifier"
     }
    ],
    "requestBody": {
     "required": true,
     "content": {
      "application/json": {
       "schema": {
        "$ref": "#/components/schemas/CopyFileRequest"
       }
      }
     }
    },
    "responses": {
     "200": {
      "description": "File copied"
     },
     "404": {
      "description": "Sandbox not found",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorResponse"
        }
       }
      }
     }
    }
   }
  },
  "/api/v1/sandbox/{id}/files/watch": {
   "get": {
    "tags": [
     "Files"
    ],
    "summary": "Watch for file changes via SSE",
    "operationId": "watchFiles",
    "parameters": [
     {
      "name": "id",
      "in": "path",
      "required": true,
      "schema": {
       "type": "string",
       "format": "uuid"
      },
      "description": "Sandbox identifier"
     },
     {
      "name": "path",
      "in": "query",
      "required": false,
      "schema": {
       "type": "string"
      },
      "description": "Directory to watch (default /workspace)"
     }
    ],
    "responses": {
     "200": {
      "description": "SSE stream of file change events"
     },
     "404": {
      "description": "Sandbox not found",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorResponse"
        }
       }
      }
     }
    }
   }
  },
  "/api/v1/sandbox/{id}/screenshot": {
   "get": {
    "tags": [
     "Computer Use"
    ],
    "summary": "Capture a screenshot of the sandbox desktop",
    "operationId": "getScreenshot",
    "parameters": [
     {
      "name": "id",
      "in": "path",
      "required": true,
      "schema": {
       "type": "string",
       "format": "uuid"
      },
      "description": "Sandbox identifier"
     }
    ],
    "responses": {
     "200": {
      "description": "Screenshot as base64-encoded image"
     },
     "404": {
      "description": "Sandbox not found",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorResponse"
        }
       }
      }
     },
     "500": {
      "description": "Screenshot capture failed",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorResponse"
        }
       }
      }
     }
    }
   },
   "post": {
    "tags": [
     "Computer Use"
    ],
    "summary": "Capture a screenshot with options (format, quality, region)",
    "operationId": "takeScreenshot",
    "parameters": [
     {
      "name": "id",
      "in": "path",
      "required": true,
      "schema": {
       "type": "string",
       "format": "uuid"
      },
      "description": "Sandbox identifier"
     }
    ],
    "requestBody": {
     "required": true,
     "content": {
      "application/json": {
       "schema": {
        "$ref": "#/components/schemas/ScreenshotRequest"
       }
      }
     }
    },
    "responses": {
     "200": {
      "description": "Screenshot as base64-encoded image"
     },
     "400": {
      "description": "Invalid request",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorResponse"
        }
       }
      }
     },
     "404": {
      "description": "Sandbox not found",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorResponse"
        }
       }
      }
     },
     "500": {
      "description": "Screenshot capture failed",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorResponse"
        }
       }
      }
     }
    }
   }
  },
  "/api/v1/sandbox/{id}/mouse": {
   "post": {
    "tags": [
     "Computer Use"
    ],
    "summary": "Perform a mouse action (click, move, drag, double-click)",
    "operationId": "mouseAction",
    "parameters": [
     {
      "name": "id",
      "in": "path",
      "required": true,
      "schema": {
       "type": "string",
       "format": "uuid"
      },
      "description": "Sandbox identifier"
     }
    ],
    "requestBody": {
     "required": true,
     "content": {
      "application/json": {
       "schema": {
        "$ref": "#/components/schemas/MouseActionRequest"
       }
      }
     }
    },
    "responses": {
     "200": {
      "description": "Mouse action executed successfully"
     },
     "400": {
      "description": "Invalid request",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorResponse"
        }
       }
      }
     },
     "404": {
      "description": "Sandbox not found",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorResponse"
        }
       }
      }
     },
     "500": {
      "description": "Mouse action failed",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorResponse"
        }
       }
      }
     }
    }
   }
  },
  "/api/v1/sandbox/{id}/keyboard": {
   "post": {
    "tags": [
     "Computer Use"
    ],
    "summary": "Perform a keyboard action (type, key, hotkey)",
    "operationId": "keyboardAction",
    "parameters": [
     {
      "name": "id",
      "in": "path",
      "required": true,
      "schema": {
       "type": "string",
       "format": "uuid"
      },
      "description": "Sandbox identifier"
     }
    ],
    "requestBody": {
     "required": true,
     "content": {
      "application/json": {
       "schema": {
        "$ref": "#/components/schemas/KeyboardActionRequest"
       }
      }
     }
    },
    "responses": {
     "200": {
      "description": "Keyboard action executed successfully"
     },
     "400": {
      "description": "Invalid request",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorResponse"
        }
       }
      }
     },
     "404": {
      "description": "Sandbox not found",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorResponse"
        }
       }
      }
     },
     "500": {
      "description": "Keyboard action failed",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorResponse"
        }
       }
      }
     }
    }
   }
  },
  "/api/v1/sandbox/{id}/screen": {
   "get": {
    "tags": [
     "Computer Use"
    ],
    "summary": "Get screen dimensions of the sandbox desktop",
    "operationId": "getScreenSize",
    "parameters": [
     {
      "name": "id",
      "in": "path",
      "required": true,
      "schema": {
       "type": "string",
       "format": "uuid"
      },
      "description": "Sandbox identifier"
     }
    ],
    "responses": {
     "200": {
      "description": "Screen dimensions (width, height)"
     },
     "404": {
      "description": "Sandbox not found",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorResponse"
        }
       }
      }
     },
     "500": {
      "description": "Failed to get screen size",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorResponse"
        }
       }
      }
     }
    }
   }
  },
  "/api/status": {
   "get": {
    "tags": [
     "Health"
    ],
    "summary": "Public service status (no auth required)",
    "operationId": "getServiceStatus",
    "responses": {
     "200": {
      "description": "All services operational"
     },
     "503": {
      "description": "Service outage detected"
     }
    }
   }
  },
  "/api/v1/api-keys": {
   "post": {
    "tags": [
     "API Keys"
    ],
    "summary": "Create a new API key",
    "operationId": "createApiKey",
    "requestBody": {
     "required": true,
     "content": {
      "application/json": {
       "schema": {
        "$ref": "#/components/schemas/CreateApiKeyRequest"
       }
      }
     }
    },
    "responses": {
     "201": {
      "description": "API key created"
     },
     "400": {
      "description": "Invalid request",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorResponse"
        }
       }
      }
     }
    }
   },
   "get": {
    "tags": [
     "API Keys"
    ],
    "summary": "List API keys",
    "operationId": "listApiKeys",
    "responses": {
     "200": {
      "description": "List of API keys"
     }
    }
   }
  },
  "/api/v1/api-keys/{id}": {
   "delete": {
    "tags": [
     "API Keys"
    ],
    "summary": "Revoke an API key",
    "operationId": "revokeApiKey",
    "parameters": [
     {
      "name": "id",
      "in": "path",
      "required": true,
      "schema": {
       "type": "string",
       "format": "uuid"
      },
      "description": "API key identifier"
     }
    ],
    "responses": {
     "200": {
      "description": "API key revoked"
     },
     "404": {
      "description": "API key not found",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorResponse"
        }
       }
      }
     }
    }
   }
  },
  "/api/v1/secrets": {
   "post": {
    "tags": [
     "Secrets"
    ],
    "summary": "Create a new secret",
    "operationId": "createSecret",
    "requestBody": {
     "required": true,
     "content": {
      "application/json": {
       "schema": {
        "$ref": "#/components/schemas/CreateSecretRequest"
       }
      }
     }
    },
    "responses": {
     "201": {
      "description": "Secret created"
     },
     "400": {
      "description": "Invalid request",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorResponse"
        }
       }
      }
     }
    }
   },
   "get": {
    "tags": [
     "Secrets"
    ],
    "summary": "List secrets",
    "operationId": "listSecrets",
    "responses": {
     "200": {
      "description": "List of secrets (values redacted)"
     }
    }
   }
  },
  "/api/v1/secrets/{name}": {
   "put": {
    "tags": [
     "Secrets"
    ],
    "summary": "Update a secret",
    "operationId": "updateSecret",
    "parameters": [
     {
      "name": "name",
      "in": "path",
      "required": true,
      "schema": {
       "type": "string"
      },
      "description": "Secret name"
     }
    ],
    "requestBody": {
     "required": true,
     "content": {
      "application/json": {
       "schema": {
        "$ref": "#/components/schemas/UpdateSecretRequest"
       }
      }
     }
    },
    "responses": {
     "200": {
      "description": "Secret updated"
     },
     "404": {
      "description": "Secret not found",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorResponse"
        }
       }
      }
     }
    }
   },
   "delete": {
    "tags": [
     "Secrets"
    ],
    "summary": "Delete a secret",
    "operationId": "deleteSecret",
    "parameters": [
     {
      "name": "name",
      "in": "path",
      "required": true,
      "schema": {
       "type": "string"
      },
      "description": "Secret name"
     }
    ],
    "responses": {
     "200": {
      "description": "Secret deleted"
     },
     "404": {
      "description": "Secret not found",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorResponse"
        }
       }
      }
     }
    }
   }
  },
  "/api/v1/webhooks": {
   "post": {
    "tags": [
     "Webhooks"
    ],
    "summary": "Register a webhook endpoint",
    "operationId": "createWebhook",
    "requestBody": {
     "required": true,
     "content": {
      "application/json": {
       "schema": {
        "$ref": "#/components/schemas/CreateWebhookRequest"
       }
      }
     }
    },
    "responses": {
     "201": {
      "description": "Webhook registered"
     },
     "400": {
      "description": "Invalid request",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorResponse"
        }
       }
      }
     }
    }
   },
   "get": {
    "tags": [
     "Webhooks"
    ],
    "summary": "List registered webhooks",
    "operationId": "listWebhooks",
    "responses": {
     "200": {
      "description": "List of webhooks"
     }
    }
   }
  },
  "/api/v1/register": {
   "post": {
    "tags": [
     "Registration"
    ],
    "summary": "Register a new organization",
    "operationId": "registerOrganization",
    "requestBody": {
     "required": true,
     "content": {
      "application/json": {
       "schema": {
        "$ref": "#/components/schemas/RegisterOrganizationRequest"
       }
      }
     }
    },
    "responses": {
     "201": {
      "description": "Organization registered"
     },
     "400": {
      "description": "Invalid request",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorResponse"
        }
       }
      }
     },
     "409": {
      "description": "Organization already exists",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorResponse"
        }
       }
      }
     }
    }
   }
  },
  "/health": {
   "get": {
    "tags": [
     "Health"
    ],
    "summary": "Health check",
    "operationId": "healthCheck",
    "responses": {
     "200": {
      "description": "Service is healthy"
     }
    }
   }
  },
  "/ready": {
   "get": {
    "tags": [
     "Health"
    ],
    "summary": "Readiness check",
    "operationId": "readinessCheck",
    "responses": {
     "200": {
      "description": "Service is ready"
     },
     "503": {
      "description": "Service is not ready"
     }
    }
   }
  },
  "/api/v1/usage/current": {
   "get": {
    "tags": [
     "Usage"
    ],
    "summary": "Get current billing period usage",
    "operationId": "getCurrentUsage",
    "responses": {
     "200": {
      "description": "Current usage data"
     }
    }
   }
  },
  "/api/v1/usage/history": {
   "get": {
    "tags": [
     "Usage"
    ],
    "summary": "Get usage history",
    "operationId": "getUsageHistory",
    "parameters": [
     {
      "name": "start_date",
      "in": "query",
      "required": false,
      "schema": {
       "type": "string",
       "format": "date"
      },
      "description": "Start date"
     },
     {
      "name": "end_date",
      "in": "query",
      "required": false,
      "schema": {
       "type": "string",
       "format": "date"
      },
      "description": "End date"
     },
     {
      "name": "granularity",
      "in": "query",
      "required": false,
      "schema": {
       "type": "string"
      },
      "description": "hourly, daily, or monthly"
     }
    ],
    "responses": {
     "200": {
      "description": "Usage history data"
     }
    }
   }
  },
  "/api/v1/sandbox/create-from-template": {
   "post": {
    "operationId": "createSandboxFromTemplate",
    "summary": "Create sandbox from a template",
    "description": "Creates a new sandbox pre-configured from a named template\n\nServed by the live controller (answers 401 unauthenticated) but absent from its published `/openapi.json` \u2014 verified 2026-08-31.",
    "tags": [
     "Sandbox Lifecycle"
    ],
    "requestBody": {
     "required": true,
     "content": {
      "application/json": {
       "schema": {
        "$ref": "#/components/schemas/CreateFromTemplateRequest"
       }
      }
     }
    },
    "responses": {
     "200": {
      "description": "Sandbox created from template",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/CreateSandboxResponse"
        }
       }
      }
     },
     "400": {
      "$ref": "#/components/responses/BadRequest"
     },
     "401": {
      "$ref": "#/components/responses/Unauthorized"
     },
     "404": {
      "$ref": "#/components/responses/NotFound"
     },
     "500": {
      "$ref": "#/components/responses/InternalError"
     }
    }
   }
  },
  "/api/v1/sandbox/{id}/tunnels": {
   "post": {
    "operationId": "createTunnel",
    "summary": "Create a tunnel",
    "description": "Creates a public tunnel to a sandbox port\n\nServed by the live controller (answers 401 unauthenticated) but absent from its published `/openapi.json` \u2014 verified 2026-08-31.",
    "tags": [
     "Sandbox Lifecycle"
    ],
    "parameters": [
     {
      "$ref": "#/components/parameters/SandboxId"
     }
    ],
    "requestBody": {
     "required": true,
     "content": {
      "application/json": {
       "schema": {
        "$ref": "#/components/schemas/CreateTunnelRequest"
       }
      }
     }
    },
    "responses": {
     "200": {
      "description": "Tunnel created",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Tunnel"
        }
       }
      }
     },
     "400": {
      "$ref": "#/components/responses/BadRequest"
     },
     "401": {
      "$ref": "#/components/responses/Unauthorized"
     },
     "404": {
      "$ref": "#/components/responses/NotFound"
     }
    }
   },
   "get": {
    "operationId": "listTunnels",
    "summary": "List tunnels",
    "description": "Lists active tunnels for a sandbox\n\nServed by the live controller (answers 401 unauthenticated) but absent from its published `/openapi.json` \u2014 verified 2026-08-31.",
    "tags": [
     "Sandbox Lifecycle"
    ],
    "parameters": [
     {
      "$ref": "#/components/parameters/SandboxId"
     }
    ],
    "responses": {
     "200": {
      "description": "Tunnel list",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/TunnelListResponse"
        }
       }
      }
     },
     "401": {
      "$ref": "#/components/responses/Unauthorized"
     },
     "404": {
      "$ref": "#/components/responses/NotFound"
     }
    }
   }
  },
  "/api/v1/tunnels/{tunnelId}": {
   "delete": {
    "operationId": "deleteTunnel",
    "summary": "Close a tunnel",
    "description": "Closes an active tunnel\n\nServed by the live controller (answers 401 unauthenticated) but absent from its published `/openapi.json` \u2014 verified 2026-08-31.",
    "tags": [
     "Sandbox Lifecycle"
    ],
    "parameters": [
     {
      "$ref": "#/components/parameters/TunnelId"
     }
    ],
    "responses": {
     "200": {
      "description": "Tunnel closed",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/SuccessResponse"
        }
       }
      }
     },
     "401": {
      "$ref": "#/components/responses/Unauthorized"
     },
     "404": {
      "$ref": "#/components/responses/NotFound"
     }
    }
   }
  },
  "/api/v1/sandbox/{id}/files/download": {
   "get": {
    "operationId": "downloadFile",
    "summary": "Download a file from sandbox",
    "description": "Downloads a file as binary content\n\nServed by the live controller (answers 401 unauthenticated) but absent from its published `/openapi.json` \u2014 verified 2026-08-31.",
    "tags": [
     "File Operations"
    ],
    "parameters": [
     {
      "$ref": "#/components/parameters/SandboxId"
     },
     {
      "name": "path",
      "in": "query",
      "required": true,
      "description": "Path to the file in the sandbox",
      "schema": {
       "type": "string"
      }
     }
    ],
    "responses": {
     "200": {
      "description": "File binary content",
      "content": {
       "application/octet-stream": {
        "schema": {
         "type": "string",
         "format": "binary"
        }
       }
      }
     }
    }
   }
  },
  "/api/v1/sandbox/{id}/files/list": {
   "get": {
    "operationId": "listFiles",
    "summary": "List files in a sandbox directory",
    "description": "Returns a listing of files and directories at the specified path within the sandbox\n\nServed by the live controller (answers 401 unauthenticated) but absent from its published `/openapi.json` \u2014 verified 2026-08-31.",
    "tags": [
     "File Operations"
    ],
    "parameters": [
     {
      "$ref": "#/components/parameters/SandboxId"
     },
     {
      "name": "path",
      "in": "query",
      "required": false,
      "description": "Directory path to list (relative to sandbox root)",
      "schema": {
       "type": "string",
       "default": "/workspace"
      }
     },
     {
      "name": "recursive",
      "in": "query",
      "required": false,
      "description": "Whether to list files recursively",
      "schema": {
       "type": "boolean",
       "default": false
      }
     }
    ],
    "responses": {
     "200": {
      "description": "File listing",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/FileListResponse"
        }
       }
      }
     },
     "400": {
      "$ref": "#/components/responses/BadRequest"
     },
     "401": {
      "$ref": "#/components/responses/Unauthorized"
     },
     "404": {
      "$ref": "#/components/responses/NotFound"
     }
    }
   }
  },
  "/api/v1/sandbox/{id}/inference": {
   "post": {
    "operationId": "proxyInference",
    "summary": "Proxy an LLM inference request",
    "description": "Forwards an inference request to a supported LLM provider from within the sandbox context\n\nServed by the live controller (answers 401 unauthenticated) but absent from its published `/openapi.json` \u2014 verified 2026-08-31.",
    "tags": [
     "Inference"
    ],
    "parameters": [
     {
      "$ref": "#/components/parameters/SandboxId"
     }
    ],
    "requestBody": {
     "required": true,
     "content": {
      "application/json": {
       "schema": {
        "$ref": "#/components/schemas/InferenceRequest"
       }
      }
     }
    },
    "responses": {
     "200": {
      "description": "Inference response from provider",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/InferenceResponse"
        }
       }
      }
     },
     "400": {
      "$ref": "#/components/responses/BadRequest"
     },
     "401": {
      "$ref": "#/components/responses/Unauthorized"
     },
     "404": {
      "$ref": "#/components/responses/NotFound"
     },
     "500": {
      "$ref": "#/components/responses/InternalError"
     }
    }
   }
  }
 },
 "components": {
  "schemas": {
   "CreateSandboxRequest": {
    "type": "object",
    "properties": {
     "session_id": {
      "type": "string",
      "format": "uuid",
      "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
     },
     "cpus": {
      "type": "string",
      "pattern": "^(\\d+(\\.\\d+)?|\\d+m)$"
     },
     "memory": {
      "type": "string",
      "pattern": "^\\d+(Mi|Gi|Ki|M|G|K)$"
     },
     "isolation": {
      "type": "string",
      "enum": [
       "container",
       "gvisor",
       "microvm",
       "kata"
      ]
     },
     "timeout_seconds": {
      "type": "integer",
      "minimum": 60,
      "maximum": 86400
     },
     "env": {
      "type": "object",
      "propertyNames": {
       "type": "string",
       "maxLength": 256,
       "pattern": "^[A-Za-z_][A-Za-z0-9_]*$"
      },
      "additionalProperties": {
       "type": "string",
       "maxLength": 10000
      }
     },
     "gpu": {
      "type": "object",
      "properties": {
       "count": {
        "type": "integer",
        "minimum": 1,
        "maximum": 8
       },
       "type": {
        "type": "string",
        "minLength": 1,
        "maxLength": 128
       },
       "memory_gb": {
        "type": "integer",
        "minimum": 1,
        "maximum": 256
       }
      },
      "additionalProperties": false
     },
     "image": {
      "type": "string",
      "minLength": 1,
      "maxLength": 500
     },
     "desktop_os": {
      "default": "linux",
      "type": "string",
      "enum": [
       "linux",
       "windows",
       "macos"
      ]
     }
    },
    "required": [
     "desktop_os"
    ],
    "additionalProperties": false,
    "description": "Request to create a new isolated sandbox for code execution"
   },
   "ExecuteCommandRequest": {
    "type": "object",
    "properties": {
     "command": {
      "anyOf": [
       {
        "type": "string",
        "minLength": 1,
        "maxLength": 100000
       },
       {
        "minItems": 1,
        "maxItems": 1000,
        "type": "array",
        "items": {
         "type": "string",
         "minLength": 1,
         "maxLength": 10000
        }
       },
       {
        "type": "object",
        "properties": {
         "cmd": {
          "type": "string",
          "minLength": 1,
          "maxLength": 10000
         },
         "args": {
          "maxItems": 1000,
          "type": "array",
          "items": {
           "type": "string",
           "minLength": 1,
           "maxLength": 10000
          }
         },
         "shell": {
          "type": "boolean",
          "const": false
         }
        },
        "required": [
         "cmd"
        ],
        "additionalProperties": false
       }
      ]
     },
     "working_dir": {
      "type": "string",
      "minLength": 1,
      "maxLength": 4096
     },
     "env": {
      "type": "object",
      "propertyNames": {
       "type": "string",
       "maxLength": 256,
       "pattern": "^[A-Za-z_][A-Za-z0-9_]*$"
      },
      "additionalProperties": {
       "type": "string",
       "maxLength": 10000
      }
     },
     "stream": {
      "type": "boolean"
     },
     "timeout": {
      "type": "integer",
      "minimum": 1000,
      "maximum": 600000
     },
     "sandbox_epoch": {
      "type": "integer",
      "minimum": 0,
      "maximum": 9007199254740991
     }
    },
    "required": [
     "command"
    ],
    "additionalProperties": false,
    "description": "Request to execute a command in a sandbox"
   },
   "WriteFilesRequest": {
    "type": "object",
    "properties": {
     "files": {
      "minItems": 1,
      "maxItems": 100,
      "type": "array",
      "items": {
       "type": "object",
       "properties": {
        "path": {
         "type": "string",
         "minLength": 1,
         "maxLength": 4096
        },
        "content": {
         "type": "string",
         "maxLength": 10485760
        }
       },
       "required": [
        "path",
        "content"
       ],
       "additionalProperties": false
      }
     }
    },
    "required": [
     "files"
    ],
    "additionalProperties": false,
    "description": "Request to write one or more files into a sandbox"
   },
   "ReadFileQuery": {
    "type": "object",
    "properties": {
     "path": {
      "type": "string",
      "minLength": 1,
      "maxLength": 4096
     }
    },
    "required": [
     "path"
    ],
    "additionalProperties": false,
    "description": "Query parameters for reading a file from a sandbox"
   },
   "ListFilesQuery": {
    "type": "object",
    "properties": {
     "path": {
      "default": "/workspace",
      "type": "string",
      "minLength": 1,
      "maxLength": 4096
     },
     "recursive": {}
    },
    "required": [
     "path",
     "recursive"
    ],
    "additionalProperties": false,
    "description": "Query parameters for listing files in a sandbox"
   },
   "ExtendSandboxRequest": {
    "type": "object",
    "properties": {
     "additional_seconds": {
      "type": "integer",
      "minimum": 60,
      "maximum": 86400
     }
    },
    "required": [
     "additional_seconds"
    ],
    "additionalProperties": false,
    "description": "Request to extend sandbox expiration window"
   },
   "CreateApiKeyRequest": {
    "type": "object",
    "properties": {
     "name": {
      "type": "string",
      "minLength": 1,
      "maxLength": 100
     },
     "scopes": {
      "minItems": 1,
      "type": "array",
      "items": {
       "type": "string",
       "enum": [
        "sandbox:create",
        "sandbox:read",
        "sandbox:write",
        "sandbox:*"
       ]
      }
     },
     "expires_in_days": {
      "type": "integer",
      "minimum": 1,
      "maximum": 365
     }
    },
    "required": [
     "name"
    ],
    "additionalProperties": false,
    "description": "Request to create a new API key"
   },
   "CreateSecretRequest": {
    "type": "object",
    "properties": {
     "name": {
      "type": "string",
      "minLength": 1,
      "maxLength": 256,
      "pattern": "^[A-Z_][A-Z0-9_]*$"
     },
     "value": {
      "type": "string",
      "minLength": 1,
      "maxLength": 65536
     },
     "scope": {
      "default": "sandbox",
      "type": "string",
      "enum": [
       "sandbox",
       "global"
      ]
     },
     "allowed_sandbox_patterns": {
      "type": "array",
      "items": {
       "type": "string",
       "maxLength": 256
      }
     },
     "expires_in_days": {
      "type": "integer",
      "minimum": 1,
      "maximum": 365
     }
    },
    "required": [
     "name",
     "value",
     "scope"
    ],
    "additionalProperties": false,
    "description": "Request to create a new secret"
   },
   "UpdateSecretRequest": {
    "type": "object",
    "properties": {
     "value": {
      "type": "string",
      "minLength": 1,
      "maxLength": 65536
     },
     "scope": {
      "type": "string",
      "enum": [
       "sandbox",
       "global"
      ]
     },
     "allowed_sandbox_patterns": {
      "type": "array",
      "items": {
       "type": "string",
       "maxLength": 256
      }
     },
     "expires_in_days": {
      "type": "integer",
      "minimum": 1,
      "maximum": 365
     }
    },
    "additionalProperties": false,
    "description": "Request to update an existing secret"
   },
   "CreateWebhookRequest": {
    "type": "object",
    "properties": {
     "url": {
      "type": "string",
      "format": "uri"
     },
     "events": {
      "minItems": 1,
      "type": "array",
      "items": {
       "type": "string"
      }
     },
     "secret": {
      "type": "string",
      "minLength": 16,
      "maxLength": 256
     }
    },
    "required": [
     "url",
     "events"
    ],
    "additionalProperties": false,
    "description": "Request to register a webhook endpoint"
   },
   "RegisterOrganizationRequest": {
    "type": "object",
    "properties": {
     "name": {
      "type": "string",
      "minLength": 1,
      "maxLength": 100
     },
     "email": {
      "type": "string",
      "format": "email",
      "pattern": "^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$"
     },
     "plan": {
      "default": "hobby",
      "type": "string",
      "enum": [
       "hobby",
       "pro",
       "team",
       "enterprise"
      ]
     }
    },
    "required": [
     "name",
     "email",
     "plan"
    ],
    "additionalProperties": false,
    "description": "Request to register a new organization"
   },
   "ListSandboxesQuery": {
    "type": "object",
    "properties": {
     "limit": {
      "default": 20,
      "description": "Maximum number of results to return",
      "type": "integer",
      "minimum": 1,
      "maximum": 100
     },
     "offset": {
      "default": 0,
      "description": "Number of results to skip",
      "type": "integer",
      "minimum": 0,
      "maximum": 9007199254740991
     },
     "state": {
      "description": "Comma-separated state filter (e.g. running,paused)"
     }
    },
    "required": [
     "limit",
     "offset"
    ],
    "additionalProperties": false,
    "description": "Query parameters for listing sandboxes with optional state filtering"
   },
   "ScreenshotRequest": {
    "type": "object",
    "properties": {
     "format": {
      "default": "png",
      "type": "string",
      "enum": [
       "png",
       "jpg",
       "jpeg"
      ]
     },
     "quality": {
      "default": 85,
      "type": "integer",
      "minimum": 1,
      "maximum": 100
     },
     "region": {
      "type": "object",
      "properties": {
       "x": {
        "type": "integer",
        "minimum": 0,
        "maximum": 9007199254740991
       },
       "y": {
        "type": "integer",
        "minimum": 0,
        "maximum": 9007199254740991
       },
       "width": {
        "type": "integer",
        "minimum": 1,
        "maximum": 9007199254740991
       },
       "height": {
        "type": "integer",
        "minimum": 1,
        "maximum": 9007199254740991
       }
      },
      "required": [
       "x",
       "y",
       "width",
       "height"
      ],
      "additionalProperties": false
     }
    },
    "required": [
     "format"
    ],
    "additionalProperties": false,
    "description": "Options for capturing a screenshot (format, quality, region)"
   },
   "MouseActionRequest": {
    "type": "object",
    "properties": {
     "action": {
      "type": "string",
      "enum": [
       "click",
       "move",
       "double_click",
       "drag"
      ]
     },
     "x": {
      "type": "integer",
      "minimum": 0,
      "maximum": 9007199254740991
     },
     "y": {
      "type": "integer",
      "minimum": 0,
      "maximum": 9007199254740991
     },
     "button": {
      "anyOf": [
       {
        "type": "integer",
        "minimum": 1,
        "maximum": 3
       },
       {
        "type": "string",
        "enum": [
         "1",
         "2",
         "3",
         "left",
         "middle",
         "right"
        ]
       }
      ]
     },
     "endX": {
      "type": "integer",
      "minimum": 0,
      "maximum": 9007199254740991
     },
     "endY": {
      "type": "integer",
      "minimum": 0,
      "maximum": 9007199254740991
     }
    },
    "required": [
     "action",
     "x",
     "y"
    ],
    "additionalProperties": false,
    "description": "Mouse action to perform on the sandbox desktop"
   },
   "KeyboardActionRequest": {
    "type": "object",
    "properties": {
     "action": {
      "type": "string",
      "enum": [
       "type",
       "key",
       "hotkey",
       "press"
      ]
     },
     "text": {
      "type": "string",
      "maxLength": 10000
     },
     "key": {
      "type": "string",
      "maxLength": 100
     },
     "keys": {
      "maxItems": 10,
      "type": "array",
      "items": {
       "type": "string",
       "maxLength": 50
      }
     },
     "modifiers": {
      "maxItems": 10,
      "type": "array",
      "items": {
       "type": "string",
       "maxLength": 50
      }
     },
     "delayMs": {
      "default": 0,
      "type": "integer",
      "minimum": 0,
      "maximum": 1000
     }
    },
    "required": [
     "action"
    ],
    "additionalProperties": false,
    "description": "Keyboard action to perform on the sandbox desktop"
   },
   "SandboxResponse": {
    "type": "object",
    "properties": {
     "sandbox_id": {
      "type": "string",
      "format": "uuid",
      "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$",
      "description": "Unique sandbox identifier"
     },
     "org_id": {
      "type": "string",
      "description": "Organization that owns this sandbox"
     },
     "session_id": {
      "type": "string",
      "description": "Session identifier"
     },
     "status": {
      "type": "string",
      "enum": [
       "creating",
       "running",
       "paused",
       "terminating",
       "terminated",
       "error"
      ],
      "description": "Current sandbox status"
     },
     "pod_ip": {
      "description": "Internal pod IP address",
      "type": "string"
     },
     "sandbox_epoch": {
      "type": "integer",
      "minimum": -9007199254740991,
      "maximum": 9007199254740991,
      "description": "Sandbox recycle epoch counter"
     },
     "allocated_vcpu": {
      "description": "Allocated vCPU cores",
      "type": "number"
     },
     "allocated_memory_gib": {
      "description": "Allocated memory in GiB",
      "type": "number"
     },
     "created_at": {
      "type": "string",
      "format": "date-time",
      "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$",
      "description": "ISO 8601 creation timestamp"
     },
     "expires_at": {
      "type": "string",
      "format": "date-time",
      "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$",
      "description": "ISO 8601 expiration timestamp"
     },
     "max_expires_at": {
      "type": "string",
      "format": "date-time",
      "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$",
      "description": "Maximum possible expiration"
     },
     "max_lifetime_seconds": {
      "type": "integer",
      "minimum": -9007199254740991,
      "maximum": 9007199254740991,
      "description": "Maximum sandbox lifetime in seconds"
     },
     "remaining_extend_seconds": {
      "type": "integer",
      "minimum": -9007199254740991,
      "maximum": 9007199254740991,
      "description": "Seconds available for extension"
     },
     "lifetime_used_seconds": {
      "type": "integer",
      "minimum": -9007199254740991,
      "maximum": 9007199254740991,
      "description": "Seconds of lifetime consumed"
     },
     "lifetime_used_percent": {
      "type": "number",
      "description": "Percentage of lifetime consumed"
     },
     "startup_metrics": {
      "description": "Startup timing breakdown",
      "type": "object",
      "properties": {
       "total_ms": {
        "type": "number",
        "description": "Total startup time in milliseconds"
       },
       "pod_creation_ms": {
        "type": "number",
        "description": "Pod creation time"
       },
       "pod_ready_ms": {
        "type": "number",
        "description": "Time until pod ready"
       },
       "phases": {
        "type": "array",
        "items": {
         "type": "object",
         "properties": {
          "name": {
           "type": "string"
          },
          "durationMs": {
           "type": "number"
          }
         },
         "required": [
          "name",
          "durationMs"
         ],
         "additionalProperties": false
        }
       }
      },
      "required": [
       "total_ms",
       "pod_creation_ms",
       "pod_ready_ms",
       "phases"
      ],
      "additionalProperties": false
     }
    },
    "required": [
     "sandbox_id",
     "org_id",
     "session_id",
     "status",
     "sandbox_epoch",
     "created_at",
     "expires_at",
     "max_expires_at",
     "max_lifetime_seconds",
     "remaining_extend_seconds",
     "lifetime_used_seconds",
     "lifetime_used_percent"
    ],
    "additionalProperties": false,
    "description": "Sandbox resource representation"
   },
   "ErrorResponse": {
    "type": "object",
    "properties": {
     "error": {
      "type": "object",
      "properties": {
       "code": {
        "type": "string",
        "description": "Machine-readable error code"
       },
       "message": {
        "type": "string",
        "description": "Human-readable error message"
       },
       "details": {
        "description": "Additional error context",
        "type": "object",
        "propertyNames": {
         "type": "string"
        },
        "additionalProperties": {}
       }
      },
      "required": [
       "code",
       "message"
      ],
      "additionalProperties": false
     }
    },
    "required": [
     "error"
    ],
    "additionalProperties": false,
    "description": "Standard error response"
   },
   "CreateTunnelRequest": {
    "type": "object",
    "required": [
     "port"
    ],
    "properties": {
     "port": {
      "type": "integer",
      "description": "Port to expose",
      "minimum": 1,
      "maximum": 65535
     },
     "protocol": {
      "type": "string",
      "description": "Protocol (http or https)",
      "enum": [
       "http",
       "https"
      ]
     },
     "expires_in": {
      "type": "integer",
      "description": "TTL in seconds",
      "minimum": 60,
      "maximum": 86400
     },
     "public": {
      "type": "boolean",
      "description": "When true, no token is required"
     }
    }
   },
   "Tunnel": {
    "type": "object",
    "properties": {
     "tunnel_id": {
      "type": "string"
     },
     "sandbox_id": {
      "type": "string"
     },
     "port": {
      "type": "integer"
     },
     "protocol": {
      "type": "string"
     },
     "url": {
      "type": "string"
     },
     "expires_at": {
      "type": "string",
      "format": "date-time"
     },
     "token": {
      "type": "string"
     }
    }
   },
   "TunnelListResponse": {
    "type": "object",
    "properties": {
     "tunnels": {
      "type": "array",
      "items": {
       "$ref": "#/components/schemas/Tunnel"
      }
     }
    }
   },
   "CreateSandboxResponse": {
    "type": "object",
    "properties": {
     "sandbox_id": {
      "type": "string",
      "format": "uuid"
     },
     "session_id": {
      "type": "string"
     },
     "status": {
      "$ref": "#/components/schemas/SandboxStatusEnum"
     },
     "expires_at": {
      "type": "string",
      "format": "date-time"
     }
    }
   },
   "Sandbox": {
    "type": "object",
    "properties": {
     "sandbox_id": {
      "type": "string",
      "format": "uuid"
     },
     "org_id": {
      "type": "string"
     },
     "session_id": {
      "type": "string"
     },
     "status": {
      "$ref": "#/components/schemas/SandboxStatusEnum"
     },
     "pod_ip": {
      "type": "string"
     },
     "created_at": {
      "type": "string",
      "format": "date-time"
     },
     "expires_at": {
      "type": "string",
      "format": "date-time"
     }
    }
   },
   "SandboxSummary": {
    "type": "object",
    "properties": {
     "sandbox_id": {
      "type": "string",
      "format": "uuid"
     },
     "org_id": {
      "type": "string"
     },
     "session_id": {
      "type": "string"
     },
     "status": {
      "$ref": "#/components/schemas/SandboxStatusEnum"
     },
     "created_at": {
      "type": "string",
      "format": "date-time"
     },
     "expires_at": {
      "type": "string",
      "format": "date-time"
     }
    }
   },
   "SandboxStatus": {
    "type": "object",
    "properties": {
     "sandbox_id": {
      "type": "string",
      "format": "uuid"
     },
     "status": {
      "$ref": "#/components/schemas/SandboxStatusEnum"
     },
     "expires_at": {
      "type": "string",
      "format": "date-time"
     }
    }
   },
   "SandboxStatusEnum": {
    "type": "string",
    "enum": [
     "creating",
     "running",
     "terminating",
     "terminated",
     "error"
    ]
   },
   "FileContent": {
    "type": "object",
    "properties": {
     "path": {
      "type": "string"
     },
     "content": {
      "type": "string",
      "format": "byte",
      "description": "Base64-encoded file content"
     },
     "size": {
      "type": "integer",
      "description": "File size in bytes"
     }
    }
   },
   "ExecuteRequest": {
    "type": "object",
    "required": [
     "command"
    ],
    "properties": {
     "command": {
      "oneOf": [
       {
        "type": "string",
        "description": "Shell command to execute"
       },
       {
        "type": "array",
        "items": {
         "type": "string"
        },
        "description": "Command and arguments array"
       }
      ]
     },
     "working_dir": {
      "type": "string",
      "description": "Working directory",
      "default": "/workspace"
     },
     "env": {
      "type": "object",
      "additionalProperties": {
       "type": "string"
      },
      "description": "Additional environment variables"
     },
     "stream": {
      "type": "boolean",
      "description": "Enable SSE streaming mode",
      "default": false
     }
    }
   },
   "ExecuteResponse": {
    "type": "object",
    "properties": {
     "exit_code": {
      "type": "integer"
     },
     "stdout": {
      "type": "string"
     },
     "stderr": {
      "type": "string"
     }
    }
   },
   "SuccessResponse": {
    "type": "object",
    "properties": {
     "success": {
      "type": "boolean"
     }
    }
   },
   "DeleteSandboxResponse": {
    "type": "object",
    "properties": {
     "success": {
      "type": "boolean"
     },
     "message": {
      "type": "string",
      "description": "Human-readable confirmation message"
     }
    }
   },
   "ExtendSandboxResponse": {
    "type": "object",
    "properties": {
     "sandbox_id": {
      "type": "string",
      "format": "uuid"
     },
     "status": {
      "$ref": "#/components/schemas/SandboxStatusEnum"
     },
     "expires_at": {
      "type": "string",
      "format": "date-time",
      "description": "New expiration time after extension"
     },
     "max_expires_at": {
      "type": "string",
      "format": "date-time",
      "description": "Maximum allowed expiration time"
     },
     "max_lifetime_seconds": {
      "type": "integer",
      "description": "Maximum lifetime in seconds for the sandbox"
     },
     "remaining_extend_seconds": {
      "type": "integer",
      "description": "Seconds still available for future extensions"
     },
     "requested_additional_seconds": {
      "type": "integer",
      "description": "The number of seconds that were requested"
     },
     "applied_additional_seconds": {
      "type": "integer",
      "description": "The number of seconds actually applied (may be capped)"
     }
    }
   },
   "FileListEntry": {
    "type": "object",
    "properties": {
     "name": {
      "type": "string",
      "description": "File or directory name"
     },
     "path": {
      "type": "string",
      "description": "Full path within the sandbox"
     },
     "type": {
      "type": "string",
      "enum": [
       "file",
       "directory"
      ],
      "description": "Whether this entry is a file or directory"
     },
     "size": {
      "type": "integer",
      "description": "File size in bytes (0 for directories)"
     },
     "modified_at": {
      "type": "string",
      "format": "date-time",
      "description": "Last modification timestamp"
     }
    }
   },
   "FileListResponse": {
    "type": "object",
    "properties": {
     "files": {
      "type": "array",
      "items": {
       "$ref": "#/components/schemas/FileListEntry"
      }
     }
    }
   },
   "InferenceRequest": {
    "type": "object",
    "required": [
     "provider",
     "path",
     "body"
    ],
    "properties": {
     "provider": {
      "type": "string",
      "enum": [
       "anthropic",
       "openai",
       "google"
      ],
      "description": "LLM provider to route the request to"
     },
     "path": {
      "type": "string",
      "description": "API path on the provider (e.g., \"/v1/messages\")"
     },
     "body": {
      "type": "object",
      "description": "Request body to forward to the provider"
     },
     "secret_name": {
      "type": "string",
      "description": "Name of the stored secret containing the provider API key"
     },
     "headers": {
      "type": "object",
      "additionalProperties": {
       "type": "string"
      },
      "description": "Additional headers to include in the provider request"
     }
    }
   },
   "InferenceResponse": {
    "type": "object",
    "properties": {
     "status": {
      "type": "integer",
      "description": "HTTP status code from the provider"
     },
     "body": {
      "type": "object",
      "description": "Response body from the provider"
     },
     "headers": {
      "type": "object",
      "additionalProperties": {
       "type": "string"
      },
      "description": "Response headers from the provider"
     }
    }
   },
   "CreateFromTemplateRequest": {
    "type": "object",
    "required": [
     "template_id"
    ],
    "properties": {
     "template_id": {
      "type": "string",
      "description": "Identifier of the template to use"
     },
     "timeout_seconds": {
      "type": "integer",
      "description": "Timeout in seconds (30-3600)",
      "minimum": 30,
      "maximum": 3600
     },
     "env": {
      "type": "object",
      "additionalProperties": {
       "type": "string"
      },
      "description": "Environment variables to inject"
     },
     "override_cpus": {
      "type": "string",
      "description": "Override template CPU limit (e.g., \"2\", \"500m\")"
     },
     "override_memory": {
      "type": "string",
      "description": "Override template memory limit (e.g., \"2Gi\", \"512Mi\")"
     }
    }
   },
   "WarmPoolStatsSimple": {
    "type": "object",
    "properties": {
     "total": {
      "type": "integer"
     },
     "ready": {
      "type": "integer"
     },
     "creating": {
      "type": "integer"
     },
     "claimed": {
      "type": "integer"
     }
    }
   },
   "WarmPoolProfileStats": {
    "type": "object",
    "properties": {
     "cpus": {
      "type": "string"
     },
     "memory": {
      "type": "string"
     },
     "stats": {
      "$ref": "#/components/schemas/WarmPoolStatsSimple"
     }
    }
   },
   "WarmPoolStats": {
    "allOf": [
     {
      "$ref": "#/components/schemas/WarmPoolStatsSimple"
     },
     {
      "type": "object",
      "properties": {
       "pools": {
        "type": "array",
        "items": {
         "$ref": "#/components/schemas/WarmPoolProfileStats"
        }
       }
      }
     }
    ]
   },
   "WarmPoolClaimResponse": {
    "type": "object",
    "properties": {
     "pod_name": {
      "type": "string"
     },
     "pod_ip": {
      "type": "string"
     },
     "pool": {
      "type": "object",
      "properties": {
       "cpus": {
        "type": "string"
       },
       "memory": {
        "type": "string"
       }
      }
     }
    }
   },
   "WarmPoolConfigureRequest": {
    "type": "object",
    "required": [
     "pod_name",
     "sandbox_id",
     "org_id"
    ],
    "properties": {
     "pod_name": {
      "type": "string"
     },
     "sandbox_id": {
      "type": "string"
     },
     "org_id": {
      "type": "string"
     },
     "session_id": {
      "type": "string"
     },
     "timeout_seconds": {
      "type": "integer"
     },
     "env": {
      "type": "object",
      "additionalProperties": {
       "type": "string"
      }
     }
    }
   },
   "WarmPoolReplenishResponse": {
    "type": "object",
    "properties": {
     "message": {
      "type": "string"
     },
     "current_stats": {
      "$ref": "#/components/schemas/WarmPoolStats"
     }
    }
   }
  },
  "securitySchemes": {
   "BearerAuth": {
    "type": "http",
    "scheme": "bearer",
    "bearerFormat": "JWT"
   },
   "ApiKeyAuth": {
    "type": "apiKey",
    "in": "header",
    "name": "X-API-Key"
   }
  },
  "parameters": {
   "SandboxId": {
    "name": "id",
    "in": "path",
    "required": true,
    "description": "Unique sandbox identifier",
    "schema": {
     "type": "string",
     "format": "uuid"
    }
   },
   "TunnelId": {
    "name": "tunnelId",
    "in": "path",
    "required": true,
    "description": "Unique tunnel identifier",
    "schema": {
     "type": "string"
    }
   }
  }
 }
}