openapi.yml

openapi: 3.0.3
info:
  title: VoidRun API
  description: |
    VoidRun API provides comprehensive management of virtual machines (sandboxes), 
    file system operations, execution environments, and organizational resources.

    All endpoints except `/api/version` require the `X-API-Key` header for authentication.
  version: 1.0.0
  contact:
    name: VoidRun Support
  license:
    name: Proprietary

servers:
  - url: https://platform.void-run.com/api
    description: Production server

tags:
  - name: System
    description: Service metadata endpoints
  - name: Organizations
    description: Organization and API key management
  - name: Users
    description: User profile and management
  - name: Sandboxes
    description: Virtual machine (sandbox) lifecycle management
  - name: Execution
    description: Command execution and PTY session management
  - name: File System
    description: File and directory operations
  - name: Images
    description: Base image management

components:
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key
      description: "API key for authentication (format: vr_...)"

  schemas:
    # Generic API Response for single resource
    ApiResponseSandbox:
      type: object
      properties:
        success:
          type: boolean
          example: true
        message:
          type: string
          nullable: true
          example: Sandbox details fetched successfully
        data:
          $ref: "#/components/schemas/Sandbox"
    # Common Response Types
    SuccessResponse:
      type: object
      properties:
        status:
          type: string
          example: success
        message:
          type: string
          example: Operation completed successfully
        data:
          type: object
          description: Response data (structure varies by endpoint)

    ErrorResponse:
      type: object
      properties:
        error:
          type: string
          example: Invalid request
        details:
          type: string
          example: Additional error details

    # Organization
    Organization:
      type: object
      properties:
        id:
          type: string
          example: 65ae1234567890abcdef1234
        name:
          type: string
          example: My Organization
        ownerId:
          type: string
          example: 65ae1234567890abcdef1234
        members:
          type: array
          items:
            type: string
        plan:
          type: string
          example: free
        usage:
          type: integer
          example: 5
        createdAt:
          type: string
          format: date-time
        createdBy:
          type: string
        updatedAt:
          type: string
          format: date-time

    # API Keys
    GenerateAPIKeyRequest:
      type: object
      required:
        - orgId
        - keyName
      properties:
        orgId:
          type: string
          example: 65ae1234567890abcdef1234
        keyName:
          type: string
          example: CI/CD Key

    GeneratedAPIKeyResponse:
      type: object
      properties:
        plainKey:
          type: string
          description: Only returned once at generation time
          example: hf_1234567890abcdef
        keyId:
          type: string
          example: 65ae1234567890abcdef1234
        keyName:
          type: string
          example: CI/CD Key
        orgId:
          type: string
          example: 65ae1234567890abcdef1234
        createdAt:
          type: string
          format: date-time
        expiresIn:
          type: string
          example: Key expires in 1 year

    APIKeyResponse:
      type: object
      properties:
        id:
          type: string
          example: 65ae1234567890abcdef1234
        orgId:
          type: string
          example: 65ae1234567890abcdef1234
        name:
          type: string
          example: CI/CD Key
        scopes:
          type: array
          items:
            type: string
          example: ["*"]
        createdBy:
          type: string
          example: 65ae1234567890abcdef1234
        createdAt:
          type: string
          format: date-time
        lastUsedAt:
          type: string
          format: date-time
          nullable: true
        isActive:
          type: boolean
          example: true
        updatedAt:
          type: string
          format: date-time

    # Sandbox
    CreateSandboxRequest:
      type: object
      required:
        - name
      properties:
        name:
          type: string
          pattern: '^[a-z0-9]([-a-z0-9]*[a-z0-9])?(\.[a-z0-9]([-a-z0-9]*[a-z0-9])?)*$'
          description: DNS-1123 subdomain format
          example: vm-01
        image:
          type: string
          description: "Image name in `name:ver` or `name` format. If omitted, defaults to the latest active `code` image."
          example: code
        cpu:
          type: integer
          minimum: 1
          maximum: 8
          example: 2
          description: Number of vCPUs
        mem:
          type: integer
          minimum: 1024
          maximum: 16384
          example: 2048
          description: Memory in MiB
        orgId:
          type: string
          description: >-
            Organization that owns the sandbox. When omitted, derived from the
            authenticated API key (the key's org). When provided, must match the
            key's organization or the request is rejected.
          example: 65ae1234567890abcdef1234
        userId:
          type: string
          description: >-
            User attributed as the sandbox creator. When omitted, derived from the
            API key (typically the key creator). When provided, must be an owner or
            member of the resolved org or the request is rejected.
          example: 65ae1234567890abcdef1234
        sync:
          type: boolean
          description: "If true (default), creation blocks until the agent responds (fast readiness check, ~2s timeout)"
          example: true
          default: true
        envVars:
          type: object
          additionalProperties:
            type: string
          description: Environment variables to set on the sandbox
          example:
            DEBUG: "true"
            LOG_LEVEL: "info"
        autoSleep:
          type: boolean
          description: "If true, the sandbox will be auto-paused due to inactivity"
          example: true
        region:
          type: string
          description: "Target region for the sandbox"
          example: eu
        refId:
          type: string
          description: "External reference ID for tracking"
          example: "ftr4dr"

    Sandbox:
      type: object
      properties:
        id:
          type: string
          example: 65ae1234567890abcdef1234
        name:
          type: string
          example: vm-01
        image:
          type: string
          description: "Resolved image in `name:ver` format"
          example: "code:1.0.42"
        cpu:
          type: integer
          description: Number of vCPUs allocated
          example: 2
        mem:
          type: integer
          description: Memory in MiB
          example: 2048
        diskMB:
          type: integer
          description: Disk size in MiB
          example: 5120
        status:
          type: string
          description: >-
            Lifecycle state. Terminal states `killed` and `deleted` may still appear
            in list responses for historical or cleanup rows.
          enum: [running, snapshotted, error, killed, deleted]
          example: running
        createdAt:
          type: string
          format: date-time
        createdBy:
          type: string
          description: User ID who created the sandbox
          example: 65ae1234567890abcdef1234
        orgId:
          type: string
          description: Organization ID the sandbox belongs to
          example: 65ae1234567890abcdef1234
        envVars:
          type: object
          additionalProperties:
            type: string
          description: Environment variables set on the sandbox (optional, only present if configured)
          example:
            DEBUG: "true"
            LOG_LEVEL: "info"
        autoSleep:
          type: boolean
          description: "Indicates if auto-sleep is enabled"
          example: true
        region:
          type: string
          description: "Region where the sandbox is hosted"
          example: us-east-1
        refId:
          type: string
          description: "External reference ID"
          example: "ref-123456"

    # Generic API Response for list with pagination
    ApiResponseSandboxesList:
      type: object
      properties:
        status:
          type: string
          example: success
        message:
          type: string
          example: Sandboxes fetched
        data:
          type: array
          items:
            $ref: "#/components/schemas/Sandbox"
        meta:
          type: object
          properties:
            page:
              type: integer
              example: 1
              description: Current page number
            limit:
              type: integer
              example: 3
              description: Number of items per page (actual page size used)
            total:
              type: integer
              example: 25
              description: Total number of sandboxes
            totalPages:
              type: integer
              example: 9
              description: Total number of pages

    # Execution
    ExecRequest:
      type: object
      required:
        - command
      properties:
        command:
          type: string
          example: ls -la /root
        args:
          type: array
          items:
            type: string
          example: [-la, /root]
        timeout:
          type: integer
          default: 30
          example: 30
          description: Timeout in seconds
        env:
          type: object
          additionalProperties:
            type: string
          example:
            PATH: /usr/bin:/bin
        cwd:
          type: string
          example: /root

    SessionExecRequest:
      type: object
      required:
        - action
      properties:
        action:
          type: string
          enum: [create, exec, input, resize, close]
          example: create
        sessionId:
          type: string
          description: Required for all actions except create
          example: sess-1a2b3c4d5e6f7788
        shell:
          type: string
          example: /bin/bash
        command:
          type: string
          description: Required when action is `exec`
          example: ls -la
        input:
          type: string
          description: Input text when action is `input`
          example: "y\n"
        cols:
          type: integer
          minimum: 1
          maximum: 500
          description: Required when action is `resize`
          example: 120
        rows:
          type: integer
          minimum: 1
          maximum: 200
          description: Required when action is `resize`
          example: 40

    SessionExecResponse:
      type: object
      properties:
        success:
          type: boolean
          example: true
        sessionId:
          type: string
          example: sess-1a2b3c4d5e6f7788
        output:
          type: string
          example: command output
        error:
          type: string
          nullable: true
          example: ""
        exitCode:
          type: integer
          example: 0

    ExecResponse:
      type: object
      properties:
        status:
          type: string
          example: success
        message:
          type: string
          example: ok
        data:
          type: object
          properties:
            stdout:
              type: string
              example: |
                total 16
                drwx------  2 root root 4096 Jan  1 12:00 .
                drwxr-xr-x 18 root root 4096 Jan  1 12:00 ..
            stderr:
              type: string
            exitCode:
              type: integer
              example: 0

    # Background Process Management
    ProcessInfo:
      type: object
      properties:
        pid:
          type: integer
          example: 1234
        command:
          type: string
          example: sleep 3600
        startTime:
          type: string
          format: date-time
        running:
          type: boolean
          description: Whether the process is currently running
          example: true
        exitCode:
          type: integer
          nullable: true
          description: Exit code if process has finished (null if still running)
          example: 0

    CommandRunResponse:
      type: object
      properties:
        success:
          type: boolean
          example: true
        pid:
          type: integer
          example: 1234
        command:
          type: string
          example: sleep 3600

    CommandListResponse:
      type: object
      properties:
        success:
          type: boolean
          example: true
        processes:
          type: array
          items:
            $ref: "#/components/schemas/ProcessInfo"

    CommandKillResponse:
      type: object
      properties:
        success:
          type: boolean
          example: true
        message:
          type: string
          example: Process killed

    CommandWaitResponse:
      type: object
      properties:
        success:
          type: boolean
          example: true
        exitCode:
          type: integer
          example: 0
        error:
          type: string
          nullable: true

    # PTY Sessions
    CreatePTYSessionRequest:
      type: object
      properties:
        cols:
          type: integer
          minimum: 1
          maximum: 500
          default: 80
          example: 80
        rows:
          type: integer
          minimum: 1
          maximum: 200
          default: 24
          example: 24

    PTYSessionInfo:
      type: object
      properties:
        id:
          type: string
          example: session-123456
        createdAt:
          type: string
          format: date-time
        clients:
          type: integer
          example: 1
        alive:
          type: boolean
          example: true

    ExecuteInSessionRequest:
      type: object
      required:
        - command
      properties:
        command:
          type: string
          example: top -b -n 1

    ResizeTerminalRequest:
      type: object
      required:
        - cols
        - rows
      properties:
        cols:
          type: integer
          minimum: 1
          maximum: 500
          example: 100
        rows:
          type: integer
          minimum: 1
          maximum: 200
          example: 40

    # Images
    CreateImageRequest:
      type: object
      required:
        - name
      properties:
        name:
          type: string
          example: custom-image
        version:
          type: string
          example: 1.0
        path:
          type: string
          example: /var/lib/images/custom.img

    Image:
      type: object
      properties:
        id:
          type: string
          example: 65ae1234567890abcdef1234
        name:
          type: string
          example: ubuntu-22.04
        tag:
          type: string
          example: latest
        sizeGB:
          type: integer
          description: Virtual size in GB
          example: 20
        system:
          type: boolean
          example: false
        active:
          type: boolean
          example: true
        orgId:
          type: string
          example: 65ae1234567890abcdef1234
        createdAt:
          type: string
          format: date-time
        createdBy:
          type: string
          example: 65ae1234567890abcdef1234

    # File System
    FileInfo:
      type: object
      properties:
        name:
          type: string
          example: file.txt
        path:
          type: string
          example: /root/file.txt
        size:
          type: integer
          example: 1024
        mode:
          type: string
          example: 0644
        isDir:
          type: boolean
          example: false
        modTime:
          type: string
          format: date-time

    FileStats:
      type: object
      properties:
        name:
          type: string
        path:
          type: string
        size:
          type: integer
        mode:
          type: string
        isDir:
          type: boolean
        modTime:
          type: string
          format: date-time
        uid:
          type: integer
        gid:
          type: integer

    DiskUsage:
      type: object
      properties:
        path:
          type: string
        size:
          type: integer
          description: Size in bytes
        humanReadable:
          type: string
          example: 1.5 GB

    FileEvent:
      type: object
      properties:
        type:
          type: string
          enum: [created, modified, deleted, renamed, chmod]
          example: created
          description: Type of filesystem event
        path:
          type: string
          example: /app/logs/app.log
          description: Absolute path to the file
        oldPath:
          type: string
          example: /app/logs/app.log.old
          description: Previous path for rename events (optional)
        size:
          type: integer
          format: int64
          example: 1024
          description: File size in bytes (optional)
        timestamp:
          type: string
          format: date-time
          example: "2024-01-27T09:12:34Z"
          description: When the event occurred

    CreateFileRequest:
      type: object
      properties:
        content:
          type: string
          example: hello world

    CompressRequest:
      type: object
      required:
        - path
      properties:
        path:
          type: string
          example: /dir/to/compress
        format:
          type: string
          enum: [tar, tar.gz, tar.bz2, zip]
          default: tar.gz
          example: tar.gz

    ExtractRequest:
      type: object
      required:
        - archive
        - dest
      properties:
        archive:
          type: string
          example: /backup.tar.gz
        dest:
          type: string
          example: /restore

paths:
  /version:
    get:
      tags:
        - System
      summary: Get server version
      description: Get server version, commit, and build metadata.
      operationId: getVersion
      security: []
      responses:
        "200":
          description: Version information
          content:
            application/json:
              schema:
                type: object
                properties:
                  version:
                    type: string
                    example: 0.1.0
                  commit:
                    type: string
                    example: a1b2c3d
                  buildTime:
                    type: string
                    example: "2026-02-28T12:00:00Z"

  /orgs/users:
    get:
      tags:
        - Organizations
      summary: List organization users
      description: Get users who are members of the authenticated user's organization. The organization is derived from the API key context.
      operationId: getOrgUsers
      security:
        - ApiKeyAuth: []
      responses:
        "200":
          description: Organization users
          content:
            application/json:
              schema:
                allOf:
                  - $ref: "#/components/schemas/SuccessResponse"
                  - type: object
                    properties:
                      data:
                        type: array
                        items:
                          type: object
                          properties:
                            id:
                              type: string
                              example: 65ae1234567890abcdef1234
                            name:
                              type: string
                              example: Admin User
                            email:
                              type: string
                              example: admin@example.com
                            imageUrl:
                              type: string
                              example: https://example.com/avatar.png
                            createdAt:
                              type: string
                              format: date-time
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "404":
          description: Organization not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"

  /orgs/apikeys:
    get:
      tags:
        - Organizations
      summary: List API keys
      description: Get all API keys for the authenticated user's organization. The organization is derived from the API key context.
      operationId: listAPIKeys
      security:
        - ApiKeyAuth: []
      responses:
        "200":
          description: List of API keys
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/APIKeyResponse"
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"

    post:
      tags:
        - Organizations
      summary: Generate new API key
      description: Create a new API key for the organization. The plain key is only returned once. The organization is derived from the API key context.
      operationId: generateAPIKey
      security:
        - ApiKeyAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - keyName
              properties:
                keyName:
                  type: string
                  example: CI/CD Key
                  description: A descriptive name for the API key
      responses:
        "200":
          description: API key generated
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/GeneratedAPIKeyResponse"
        "400":
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"

  /orgs/apikeys/{keyId}:
    delete:
      tags:
        - Organizations
      summary: Revoke API key
      description: Delete/revoke an API key. The organization is derived from the API key context.
      operationId: revokeAPIKey
      security:
        - ApiKeyAuth: []
      parameters:
        - name: keyId
          in: path
          required: true
          schema:
            type: string
          example: 65ae1234567890abcdef1234
      responses:
        "200":
          description: API key revoked
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SuccessResponse"
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "404":
          description: API key not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"

  /orgs/apikeys/{keyId}/activate:
    post:
      tags:
        - Organizations
      summary: Activate or deactivate API key
      description: Toggle an API key's active status. The organization is derived from the API key context.
      operationId: activateAPIKey
      security:
        - ApiKeyAuth: []
      parameters:
        - name: keyId
          in: path
          required: true
          schema:
            type: string
          example: 65ae1234567890abcdef1234
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                isActive:
                  type: boolean
                  example: true
      responses:
        "200":
          description: API key status updated
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SuccessResponse"
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "404":
          description: API key not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"

  /orgs/apikeys/{keyId}/touch:
    patch:
      tags:
        - Organizations
      summary: Touch API key
      description: Update the API key last-used timestamp. The organization is derived from the API key context.
      operationId: touchAPIKey
      security:
        - ApiKeyAuth: []
      parameters:
        - name: keyId
          in: path
          required: true
          schema:
            type: string
          example: 65ae1234567890abcdef1234
      responses:
        "200":
          description: API key touched
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SuccessResponse"
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "404":
          description: API key not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"

  /users/me:
    get:
      tags:
        - Users
      summary: Get current user
      description: Get the authenticated user's profile information
      operationId: getCurrentUser
      security:
        - ApiKeyAuth: []
      responses:
        "200":
          description: User profile
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                    example: 65ae1234567890abcdef1234
                  name:
                    type: string
                    example: Admin User
                  email:
                    type: string
                    example: admin@example.com
                  imageUrl:
                    type: string
                    example: https://example.com/avatar.png
                  createdAt:
                    type: string
                    format: date-time
                  orgs:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: string
                          example: 65ae1234567890abcdef1234
                        name:
                          type: string
                          example: My Organization
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"

  /sandboxes:
    get:
      tags:
        - Sandboxes
      summary: List sandboxes
      description: Get all sandboxes for the current organization with pagination support
      operationId: listSandboxes
      security:
        - ApiKeyAuth: []
      parameters:
        - name: page
          in: query
          schema:
            type: integer
            default: 1
            minimum: 1
          example: 1
          description: Page number (default 1, must be >= 1)
        - name: limit
          in: query
          schema:
            type: integer
            minimum: 1
            maximum: 100
          example: 50
          description: Number of sandboxes per page (min 1, max 100, default from server config)
      responses:
        "200":
          description: List of sandboxes with pagination metadata
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiResponseSandboxesList"
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
    post:
      tags:
        - Sandboxes
      summary: Create sandbox
      description: Create a new virtual machine sandbox
      operationId: createSandbox
      security:
        - ApiKeyAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CreateSandboxRequest"
      responses:
        "201":
          description: Sandbox created
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    example: success
                  message:
                    type: string
                    example: Sandbox created
                  data:
                    $ref: "#/components/schemas/Sandbox"
        "400":
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "409":
          description: Sandbox already exists
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"

  /sandboxes/{id}:
    get:
      tags:
        - Sandboxes
      summary: Get sandbox details
      description: Get detailed information about a specific sandbox
      operationId: getSandbox
      security:
        - ApiKeyAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
          example: 65ae1234567890abcdef1234
      responses:
        "200":
          description: Sandbox details
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiResponseSandbox"
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "404":
          description: Sandbox not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"

    delete:
      tags:
        - Sandboxes
      summary: Delete sandbox
      description: Delete a sandbox and all its resources
      operationId: deleteSandbox
      security:
        - ApiKeyAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
          example: 65ae1234567890abcdef1234
      responses:
        "200":
          description: Sandbox deleted
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SuccessResponse"
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "404":
          description: Sandbox not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"

  /sandboxes/{id}/sleep:
    post:
      tags:
        - Sandboxes
      summary: Sleep sandbox
      description: Put a running sandbox to sleep (state is persisted, VM process exits).
      operationId: sleepSandbox
      security:
        - ApiKeyAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
          example: 65ae1234567890abcdef1234
      responses:
        "200":
          description: Sandbox snapshotted
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SuccessResponse"
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "404":
          description: Sandbox not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"

  /sandboxes/{id}/wake:
    post:
      tags:
        - Sandboxes
      summary: Wake sandbox
      description: Wake a sleeping sandbox from its persisted state.
      operationId: wakeSandbox
      security:
        - ApiKeyAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
          example: 65ae1234567890abcdef1234
      responses:
        "200":
          description: Sandbox restored
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SuccessResponse"
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "404":
          description: Sandbox not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"

  /sandboxes/{id}/start:
    post:
      tags:
        - Sandboxes
      summary: Start sandbox
      description: |
        Boot a stopped sandbox back into a running state. Accepts sandboxes in
        `snapshotted`, `killed`, or `error` status and restores from the latest
        on-disk snapshot. Returns 500 if no snapshot is available (the sandbox
        must then be deleted and recreated).
      operationId: startSandbox
      security:
        - ApiKeyAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
          example: 65ae1234567890abcdef1234
      responses:
        "200":
          description: Sandbox started
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SuccessResponse"
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "404":
          description: Sandbox not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "500":
          description: Start failed (e.g. no snapshot available, or restore error)
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"

  /sandboxes/{id}/exec:
    post:
      tags:
        - Execution
      summary: Execute command (synchronous)
      description: Execute a command in the sandbox and wait for the result. For a non-blocking start with a PID, use `POST /sandboxes/{id}/commands/run`.
      operationId: execCommand
      security:
        - ApiKeyAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
          example: 65ae1234567890abcdef1234
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ExecRequest"
      responses:
        "200":
          description: Command executed
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ExecResponse"
        "400":
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "404":
          description: Sandbox not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"

  /sandboxes/{id}/exec-stream:
    post:
      tags:
        - Execution
      summary: Execute command (SSE stream)
      description: |
        Execute a command and stream output as Server-Sent Events.
        Events: `stdout`, `stderr`, and final `exit`.
      operationId: execCommandStream
      security:
        - ApiKeyAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
          example: 65ae1234567890abcdef1234
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ExecRequest"
      responses:
        "200":
          description: SSE stream of command output
          content:
            text/event-stream:
              schema:
                type: string
              example: |-
                event: stdout
                data: Hello from exec

                event: stderr
                data: warning: something happened

                event: exit
                data: {"exitCode":0}
        "400":
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "404":
          description: Sandbox not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"

  /sandboxes/{id}/session-exec:
    post:
      tags:
        - Execution
      summary: Execute PTY session action
      description: Send a PTY session action (`create`, `exec`, `input`, `resize`, `close`) to the sandbox agent.
      operationId: sessionExec
      security:
        - ApiKeyAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
          example: 65ae1234567890abcdef1234
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/SessionExecRequest"
      responses:
        "200":
          description: Session action result
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SessionExecResponse"
        "400":
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "404":
          description: Sandbox not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"

  /sandboxes/{id}/session-exec-stream:
    post:
      tags:
        - Execution
      summary: Stream PTY session command output
      description: Execute a command in an existing PTY session and stream NDJSON output chunks.
      operationId: sessionExecStream
      security:
        - ApiKeyAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
          example: 65ae1234567890abcdef1234
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - sessionId
                - command
              properties:
                sessionId:
                  type: string
                  example: sess-1a2b3c4d5e6f7788
                command:
                  type: string
                  example: tail -f /var/log/syslog
      responses:
        "200":
          description: NDJSON stream of command output
          content:
            application/x-ndjson:
              schema:
                type: string
              example: |-
                {"type":"stdout","data":"line 1"}
                {"type":"stdout","data":"line 2"}
                {"type":"exit","exitCode":0}
        "400":
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "404":
          description: Sandbox not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"

  /sandboxes/{id}/commands/run:
    post:
      tags:
        - Execution
      summary: Start background process
      description: Start a command as a background process and return its PID
      operationId: runBackgroundCommand
      security:
        - ApiKeyAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
          example: 65ae1234567890abcdef1234
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - command
              properties:
                command:
                  type: string
                  example: sleep 3600
                env:
                  type: object
                  additionalProperties:
                    type: string
                cwd:
                  type: string
                  example: /root
                timeout:
                  type: integer
                  description: Command timeout in seconds (0 = no timeout, max 900)
                  minimum: 0
                  maximum: 900
                  example: 30
      responses:
        "200":
          description: Process started
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CommandRunResponse"
        "400":
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "404":
          description: Sandbox not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"

  /sandboxes/{id}/commands/list:
    get:
      tags:
        - Execution
      summary: List running processes
      description: Get list of all running background processes in the sandbox
      operationId: listBackgroundProcesses
      security:
        - ApiKeyAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
          example: 65ae1234567890abcdef1234
      responses:
        "200":
          description: Process list
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CommandListResponse"
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "404":
          description: Sandbox not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"

  /sandboxes/{id}/commands/kill:
    post:
      tags:
        - Execution
      summary: Kill background process
      description: Terminate a running background process by PID
      operationId: killBackgroundProcess
      security:
        - ApiKeyAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
          example: 65ae1234567890abcdef1234
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - pid
              properties:
                pid:
                  type: integer
                  example: 1234
      responses:
        "200":
          description: Process killed
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CommandKillResponse"
        "400":
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "404":
          description: Process not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"

  /sandboxes/{id}/commands/attach:
    post:
      tags:
        - Execution
      summary: Attach to process output (SSE stream)
      description: |
        Connect to a background process and stream its output as Server-Sent Events.
        Events: `stdout`, `stderr`, `exit`, `error`.
      operationId: attachToBackgroundProcess
      security:
        - ApiKeyAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
          example: 65ae1234567890abcdef1234
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - pid
              properties:
                pid:
                  type: integer
                  example: 1234
      responses:
        "200":
          description: SSE stream of process output
          content:
            text/event-stream:
              schema:
                type: string
              example: |-
                event: stdout
                data: Process output line 1

                event: stdout
                data: Process output line 2

                event: exit
                data: {"exitCode":0}
        "400":
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "404":
          description: Process not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"

  /sandboxes/{id}/commands/wait:
    post:
      tags:
        - Execution
      summary: Wait for process completion
      description: Block until a background process completes and return its exit code
      operationId: waitForBackgroundProcess
      security:
        - ApiKeyAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
          example: 65ae1234567890abcdef1234
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - pid
              properties:
                pid:
                  type: integer
                  example: 1234
      responses:
        "200":
          description: Process completed
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CommandWaitResponse"
        "400":
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "404":
          description: Process not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"

  /sandboxes/{id}/pty:
    get:
      tags:
        - Execution
      summary: Connect to ephemeral PTY (WebSocket)
      description: |
        Establish a WebSocket connection for temporary terminal access.
        The WebSocket URL format is: `ws://host/api/sandboxes/{id}/pty`
      operationId: connectPTY
      security:
        - ApiKeyAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
          example: 65ae1234567890abcdef1234
      responses:
        "101":
          description: Switching to WebSocket protocol
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "404":
          description: Sandbox not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"

  /sandboxes/{id}/pty/sessions:
    post:
      tags:
        - Execution
      summary: Create PTY session
      description: Create a new PTY (pseudo-terminal) session for interactive commands
      operationId: createPTYSession
      security:
        - ApiKeyAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
          example: 65ae1234567890abcdef1234
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CreatePTYSessionRequest"
      responses:
        "200":
          description: Session created
          content:
            application/json:
              schema:
                allOf:
                  - $ref: "#/components/schemas/SuccessResponse"
                  - type: object
                    properties:
                      data:
                        type: object
                        properties:
                          sessionId:
                            type: string
                            example: session-123456
                          createdAt:
                            type: string
                            format: date-time
                            example: 2024-01-27T10:15:00Z
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "404":
          description: Sandbox not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"

    get:
      tags:
        - Execution
      summary: List PTY sessions
      description: Get all active PTY sessions for a sandbox
      operationId: listPTYSessions
      security:
        - ApiKeyAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
          example: 65ae1234567890abcdef1234
      responses:
        "200":
          description: List of sessions
          content:
            application/json:
              schema:
                allOf:
                  - $ref: "#/components/schemas/SuccessResponse"
                  - type: object
                    properties:
                      data:
                        type: object
                        properties:
                          sessions:
                            type: array
                            items:
                              $ref: "#/components/schemas/PTYSessionInfo"
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "404":
          description: Sandbox not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"

  /sandboxes/{id}/pty/sessions/{sessionId}:
    get:
      tags:
        - Execution
      summary: Connect to PTY session (WebSocket)
      description: |
        Establish a WebSocket connection to a PTY session for interactive terminal access.
        The WebSocket URL format is: `ws://host/api/sandboxes/{id}/pty/sessions/{sessionId}`
      operationId: connectPTYSession
      security:
        - ApiKeyAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
          example: 65ae1234567890abcdef1234
        - name: sessionId
          in: path
          required: true
          schema:
            type: string
          example: session-123456
      responses:
        "101":
          description: Switching to WebSocket protocol
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "404":
          description: Session not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"

    delete:
      tags:
        - Execution
      summary: Delete PTY session
      description: Close and delete a PTY session
      operationId: deletePTYSession
      security:
        - ApiKeyAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
          example: 65ae1234567890abcdef1234
        - name: sessionId
          in: path
          required: true
          schema:
            type: string
          example: session-123456
      responses:
        "200":
          description: Session deleted
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SuccessResponse"
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "404":
          description: Session not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"

  /sandboxes/{id}/pty/sessions/{sessionId}/execute:
    post:
      tags:
        - Execution
      summary: Execute command in PTY session
      description: Execute a command asynchronously in an existing PTY session
      operationId: executeInPTYSession
      security:
        - ApiKeyAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
          example: 65ae1234567890abcdef1234
        - name: sessionId
          in: path
          required: true
          schema:
            type: string
          example: session-123456
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ExecuteInSessionRequest"
      responses:
        "200":
          description: Command executed
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SuccessResponse"
        "400":
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "404":
          description: Session not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"

  /sandboxes/{id}/pty/sessions/{sessionId}/buffer:
    get:
      tags:
        - Execution
      summary: Get output buffer
      description: Get the current output buffer from a PTY session
      operationId: getPTYBuffer
      security:
        - ApiKeyAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
          example: 65ae1234567890abcdef1234
        - name: sessionId
          in: path
          required: true
          schema:
            type: string
          example: session-123456
      responses:
        "200":
          description: Output buffer
          content:
            application/json:
              schema:
                allOf:
                  - $ref: "#/components/schemas/SuccessResponse"
                  - type: object
                    properties:
                      data:
                        type: object
                        properties:
                          output:
                            type: string
                            example: Command output text
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "404":
          description: Session not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"

  /sandboxes/{id}/pty/sessions/{sessionId}/resize:
    post:
      tags:
        - Execution
      summary: Resize terminal
      description: Resize the terminal dimensions for a PTY session
      operationId: resizeTerminal
      security:
        - ApiKeyAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
          example: 65ae1234567890abcdef1234
        - name: sessionId
          in: path
          required: true
          schema:
            type: string
          example: session-123456
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ResizeTerminalRequest"
      responses:
        "200":
          description: Terminal resized
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SuccessResponse"
        "400":
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "404":
          description: Session not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"

  /sandboxes/{id}/files:
    get:
      tags:
        - File System
      summary: List files
      description: List files and directories in a path
      operationId: listFiles
      security:
        - ApiKeyAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
          example: 65ae1234567890abcdef1234
        - name: path
          in: query
          required: true
          schema:
            type: string
          example: /root
      responses:
        "200":
          description: List of files
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    example: success
                  message:
                    type: string
                    example: ok
                  data:
                    type: object
                    properties:
                      success:
                        type: boolean
                        example: true
                      files:
                        type: array
                        items:
                          $ref: "#/components/schemas/FileInfo"
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "404":
          description: Sandbox or path not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"

    delete:
      tags:
        - File System
      summary: Delete file or directory
      description: Delete a file or directory
      operationId: deleteFile
      security:
        - ApiKeyAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
          example: 65ae1234567890abcdef1234
        - name: path
          in: query
          required: true
          schema:
            type: string
          example: /root/file.txt
      responses:
        "200":
          description: File deleted
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ExecResponse"
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "404":
          description: File not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"

  /sandboxes/{id}/files/upload:
    post:
      tags:
        - File System
      summary: Upload file
      description: Upload a file to the sandbox
      operationId: uploadFile
      security:
        - ApiKeyAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
          example: 65ae1234567890abcdef1234
        - name: path
          in: query
          required: true
          schema:
            type: string
          example: /root/script.sh
      requestBody:
        required: true
        content:
          application/octet-stream:
            schema:
              type: string
              format: binary
      responses:
        "200":
          description: File uploaded
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SuccessResponse"
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "404":
          description: Sandbox not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"

  /sandboxes/{id}/files/download:
    get:
      tags:
        - File System
      summary: Download file
      description: Download a file from the sandbox
      operationId: downloadFile
      security:
        - ApiKeyAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
          example: 65ae1234567890abcdef1234
        - name: path
          in: query
          required: true
          schema:
            type: string
          example: /root/output.log
      responses:
        "200":
          description: File content
          content:
            application/octet-stream:
              schema:
                type: string
                format: binary
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "404":
          description: File not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"

  /sandboxes/{id}/files/head-tail:
    get:
      tags:
        - File System
      summary: Read file head or tail
      description: Get the first or last N lines of a file
      operationId: headTail
      security:
        - ApiKeyAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
          example: 65ae1234567890abcdef1234
        - name: path
          in: query
          required: true
          schema:
            type: string
          example: /var/log/syslog
        - name: lines
          in: query
          schema:
            type: integer
            default: 10
            minimum: 1
          example: 50
        - name: head
          in: query
          schema:
            type: boolean
            default: true
          description: If true, return head (first lines), if false, return tail (last lines)
          example: false
      responses:
        "200":
          description: File content (head or tail)
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ExecResponse"
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "404":
          description: File not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"

  /sandboxes/{id}/files/search:
    get:
      tags:
        - File System
      summary: Search files
      description: Search for files matching a pattern
      operationId: searchFiles
      security:
        - ApiKeyAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
          example: 65ae1234567890abcdef1234
        - name: path
          in: query
          required: true
          schema:
            type: string
          example: /var/log
        - name: pattern
          in: query
          required: true
          schema:
            type: string
          example: "*.error"
      responses:
        "200":
          description: Matching files
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ExecResponse"
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "404":
          description: Path not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"

  /sandboxes/{id}/files/mkdir:
    post:
      tags:
        - File System
      summary: Create directory
      description: Create a new directory
      operationId: createDirectory
      security:
        - ApiKeyAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
          example: 65ae1234567890abcdef1234
        - name: path
          in: query
          required: true
          schema:
            type: string
          example: /new/dir
      responses:
        "200":
          description: Directory created
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ExecResponse"
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "400":
          description: Invalid path or already exists
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"

  /sandboxes/{id}/files/create:
    post:
      tags:
        - File System
      summary: Create file
      description: Create a new file with optional content
      operationId: createFile
      security:
        - ApiKeyAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
          example: 65ae1234567890abcdef1234
        - name: path
          in: query
          required: true
          schema:
            type: string
          example: /file.txt
        - name: content
          in: query
          schema:
            type: string
          example: hello
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CreateFileRequest"
      responses:
        "200":
          description: File created
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ExecResponse"
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "400":
          description: Invalid path
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"

  /sandboxes/{id}/files/copy:
    post:
      tags:
        - File System
      summary: Copy file or directory
      description: Copy a file or directory to a new location
      operationId: copyFile
      security:
        - ApiKeyAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
          example: 65ae1234567890abcdef1234
        - name: from
          in: query
          required: true
          schema:
            type: string
          example: /src
        - name: to
          in: query
          required: true
          schema:
            type: string
          example: /dst
      responses:
        "200":
          description: File copied
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ExecResponse"
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "400":
          description: Invalid paths or source not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"

  /sandboxes/{id}/files/move:
    post:
      tags:
        - File System
      summary: Move file or directory
      description: Move or rename a file or directory
      operationId: moveFile
      security:
        - ApiKeyAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
          example: 65ae1234567890abcdef1234
        - name: from
          in: query
          required: true
          schema:
            type: string
          example: /src
        - name: to
          in: query
          required: true
          schema:
            type: string
          example: /dst
      responses:
        "200":
          description: File moved
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ExecResponse"
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "400":
          description: Invalid paths or source not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"

  /sandboxes/{id}/files/chmod:
    post:
      tags:
        - File System
      summary: Change file permissions
      description: Change the permissions (mode) of a file or directory
      operationId: changePermissions
      security:
        - ApiKeyAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
          example: 65ae1234567890abcdef1234
        - name: path
          in: query
          required: true
          schema:
            type: string
          example: /script.sh
        - name: mode
          in: query
          required: true
          schema:
            type: string
            pattern: "^[0-7]{3,4}$"
          example: "755"
          description: Octal file mode (e.g., 755, 0644)
      responses:
        "200":
          description: Permissions changed
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ExecResponse"
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "400":
          description: Invalid mode or path not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"

  /sandboxes/{id}/files/stat:
    get:
      tags:
        - File System
      summary: Get file stats
      description: Get detailed information about a file or directory
      operationId: statFile
      security:
        - ApiKeyAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
          example: 65ae1234567890abcdef1234
        - name: path
          in: query
          required: true
          schema:
            type: string
          example: /file.txt
      responses:
        "200":
          description: File statistics
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ExecResponse"
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "404":
          description: File not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"

  /sandboxes/{id}/files/du:
    get:
      tags:
        - File System
      summary: Disk usage
      description: Get disk usage for a path
      operationId: diskUsage
      security:
        - ApiKeyAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
          example: 65ae1234567890abcdef1234
        - name: path
          in: query
          required: true
          schema:
            type: string
          example: /dir
      responses:
        "200":
          description: Disk usage information
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ExecResponse"
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "404":
          description: Path not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"

  /sandboxes/{id}/files/compress:
    post:
      tags:
        - File System
      summary: Compress file or directory
      description: Create an archive from a file or directory
      operationId: compressFile
      security:
        - ApiKeyAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
          example: 65ae1234567890abcdef1234
        - name: path
          in: query
          required: true
          schema:
            type: string
          example: /dir
        - name: format
          in: query
          schema:
            type: string
            enum: [tar, tar.gz, tar.bz2, zip]
            default: tar.gz
          example: tar.gz
      responses:
        "200":
          description: File compressed
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ExecResponse"
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "400":
          description: Invalid path or format
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"

  /sandboxes/{id}/files/extract:
    post:
      tags:
        - File System
      summary: Extract archive
      description: Extract an archive to a destination directory
      operationId: extractArchive
      security:
        - ApiKeyAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
          example: 65ae1234567890abcdef1234
        - name: archive
          in: query
          required: true
          schema:
            type: string
          example: /backup.tar.gz
        - name: dest
          in: query
          required: true
          schema:
            type: string
          example: /restore
      responses:
        "200":
          description: Archive extracted
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ExecResponse"
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "400":
          description: Invalid archive or destination
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"

  /sandboxes/{id}/files/watch:
    post:
      tags:
        - File System
      summary: Start watching a directory
      description: Start monitoring a directory for file system events (create, modify, delete, rename) with optional recursion and hidden-dir filtering.
      operationId: startWatch
      security:
        - ApiKeyAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
          example: 65ae1234567890abcdef1234
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - path
              properties:
                path:
                  type: string
                  example: /app/logs
                recursive:
                  type: boolean
                  default: false
                ignoreHidden:
                  type: boolean
                  description: Skip directories that start with '.'
                  default: true
      responses:
        "200":
          description: Watch session started successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    example: success
                  message:
                    type: string
                    example: watch started
                  data:
                    type: object
                    properties:
                      sessionId:
                        type: string
                        format: uuid
                        example: "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
        "400":
          description: Invalid path or parameters
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "404":
          description: Sandbox not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"

  /sandboxes/{id}/files/watch/{sessionId}/stream:
    get:
      tags:
        - File System
      summary: Stream file watch events (WebSocket)
      description: |
        **RECOMMENDED:** Real-time WebSocket streaming of file system events.

        Connect via WebSocket to receive events as they occur. This is more efficient than polling
        the `/events` endpoint and provides immediate notification of file system changes.

        **WebSocket Protocol:**
        - Client connects to this endpoint
        - Server upgrades connection to WebSocket
        - Events are pushed to client as JSON objects
        - Connection stays open until client disconnects or session is stopped

        **Event Format:** Each message is a FileEvent object (same as polling endpoint)
      operationId: streamWatchEvents
      security:
        - ApiKeyAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
          example: 65ae1234567890abcdef1234
        - name: sessionId
          in: path
          required: true
          schema:
            type: string
            format: uuid
          example: "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
      responses:
        "101":
          description: Switching Protocols - WebSocket connection established
        "400":
          description: Invalid session ID or upgrade failed
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "404":
          description: Sandbox or session not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"

  /images:
    get:
      tags:
        - Images
      summary: List images
      description: Get active base images visible to the organization (inactive or superseded images are omitted)
      operationId: listImages
      security:
        - ApiKeyAuth: []
      responses:
        "200":
          description: List of images
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/Image"
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"

  /images/{id}:
    get:
      tags:
        - Images
      summary: Get image by ID
      description: Get detailed information about a specific image
      operationId: getImage
      security:
        - ApiKeyAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
          example: 65ae1234567890abcdef1234
      responses:
        "200":
          description: Image details
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Image"
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "404":
          description: Image not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"

  /images/name/{name}:
    get:
      tags:
        - Images
      summary: Get image by name
      description: Get an image by its name
      operationId: getImageByName
      security:
        - ApiKeyAuth: []
      parameters:
        - name: name
          in: path
          required: true
          schema:
            type: string
          example: ubuntu-22.04
      responses:
        "200":
          description: Image details
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Image"
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "404":
          description: Image not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"