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
          example: 65ae1234567890abcdef1234
        userId:
          type: string
          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, stopped, paused, 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}/start:
    post:
      tags:
        - Sandboxes
      summary: Start sandbox
      description: Start a stopped sandbox
      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"
        "400":
          description: Invalid request (sandbox not stopped)
          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}/stop:
    post:
      tags:
        - Sandboxes
      summary: Stop sandbox
      description: Stop a running sandbox
      operationId: stopSandbox
      security:
        - ApiKeyAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
          example: 65ae1234567890abcdef1234
      responses:
        "200":
          description: Sandbox stopped
          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}/pause:
    post:
      tags:
        - Sandboxes
      summary: Pause sandbox
      description: Pause a running sandbox
      operationId: pauseSandbox
      security:
        - ApiKeyAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
          example: 65ae1234567890abcdef1234
      responses:
        "200":
          description: Sandbox paused
          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}/resume:
    post:
      tags:
        - Sandboxes
      summary: Resume sandbox
      description: Resume a paused sandbox
      operationId: resumeSandbox
      security:
        - ApiKeyAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
          example: 65ae1234567890abcdef1234
      responses:
        "200":
          description: Sandbox resumed
          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}/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"