components:
  parameters:
    ComputerId:
      description: Computer UUID
      in: path
      name: id
      required: true
      schema:
        example: 3fa85f64-5717-4562-b3fc-2c963f66afa6
        format: uuid
        type: string
    CursorParam:
      description: Opaque pagination cursor from a previous response
      in: query
      name: cursor
      schema:
        type: string
    DeploymentId:
      description: Deployment UUID
      in: path
      name: id
      required: true
      schema:
        example: 3fa85f64-5717-4562-b3fc-2c963f66afa6
        format: uuid
        type: string
    DomainId:
      description: Custom domain record UUID
      in: path
      name: domain_id
      required: true
      schema:
        example: 3d4e5f6a-7b8c-9012-cdef-123456789012
        format: uuid
        type: string
    ExternalProjectId:
      description: "Customer-supplied project/application identifier for white-label attribution. Used for grouping and chargeback only.\n"
      in: query
      name: external_project_id
      required: false
      schema:
        example: landing-page-789
        maxLength: 255
        type: string
    ExternalUserId:
      description: "Customer-supplied end-user identifier for white-label attribution. Never grants MIOSA authorization by itself.\n"
      in: query
      name: external_user_id
      required: false
      schema:
        example: dr-smith-456
        maxLength: 255
        type: string
    ExternalWorkspaceId:
      description: "Customer-supplied workspace/team/account identifier for white-label attribution. Always scoped under the authenticated MIOSA tenant.\n"
      in: query
      name: external_workspace_id
      required: false
      schema:
        example: dental-office-123
        maxLength: 255
        type: string
    LimitParam:
      in: query
      name: limit
      schema:
        default: 20
        maximum: 100
        minimum: 1
        type: integer
    PtySessionId:
      description: PTY session identifier returned by `POST /computers/{id}/terminal`
      in: path
      name: session_id
      required: true
      schema:
        example: pty_7a9c2e4f
        type: string
    SandboxId:
      description: Sandbox UUID
      in: path
      name: id
      required: true
      schema:
        example: 3fa85f64-5717-4562-b3fc-2c963f66afa6
        format: uuid
        type: string
    ServiceName:
      description: Service name (e.g. `nginx`, `redis`, `my-worker`)
      in: path
      name: name
      required: true
      schema:
        example: nginx
        type: string
    SessionId:
      description: CUA session UUID
      in: path
      name: session_id
      required: true
      schema:
        example: a1b2c3d4-e5f6-7890-abcd-ef1234567890
        format: uuid
        type: string
    SnapshotId:
      description: Snapshot UUID
      in: path
      name: snap_id
      required: true
      schema:
        example: 2c3d4e5f-6a7b-8901-bcde-f12345678901
        format: uuid
        type: string
    WorkspaceId:
      description: Workspace UUID
      in: path
      name: id
      required: true
      schema:
        example: 1b2c3d4e-5f6a-7890-abcd-ef1234567890
        format: uuid
        type: string
  responses:
    AgentUnavailable:
      content:
        application/json:
          example:
            error:
              code: AGENT_UNAVAILABLE
              message: In-VM agent is not reachable. The computer may be starting up.
              type: https://docs.miosa.ai/errors/agent-unavailable
          schema:
            $ref: "#/components/schemas/ErrorResponse"
      description: The in-VM agent (envd/OSA) is unreachable
    BadRequest:
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorResponse"
      description: The request contains an invalid identifier or parameter.
    ComputerNotRunning:
      content:
        application/json:
          example:
            error:
              code: COMPUTER_NOT_RUNNING
              message: "Computer is not running (current status: stopped)"
              type: https://docs.miosa.ai/errors/computer-not-running
          schema:
            $ref: "#/components/schemas/ErrorResponse"
      description: The operation requires the computer to be in `running` status
    FileTooLarge:
      content:
        application/json:
          example:
            error:
              code: FILE_TOO_LARGE
              message: File exceeds the 10 MB upload limit
              type: https://docs.miosa.ai/errors/file-too-large
          schema:
            $ref: "#/components/schemas/ErrorResponse"
      description: Upload exceeds the 10 MB size limit
    Forbidden:
      content:
        application/json:
          example:
            error:
              code: FORBIDDEN
              message: You do not have access to this computer
              type: https://docs.miosa.ai/errors/forbidden
          schema:
            $ref: "#/components/schemas/ErrorResponse"
      description: Authenticated but not authorized to access this resource
    NotFound:
      content:
        application/json:
          example:
            error:
              code: NOT_FOUND
              message: Computer not found
              type: https://docs.miosa.ai/errors/not-found
          schema:
            $ref: "#/components/schemas/ErrorResponse"
      description: Resource not found
    RateLimited:
      content:
        application/json:
          example:
            error:
              code: RATE_LIMITED
              message: Too many requests. Retry after 30 seconds.
              type: https://docs.miosa.ai/errors/rate-limited
          schema:
            $ref: "#/components/schemas/ErrorResponse"
      description: Too many requests
      headers:
        Retry-After:
          description: Seconds to wait before retrying
          schema:
            type: integer
        X-RateLimit-Limit:
          schema:
            type: integer
        X-RateLimit-Remaining:
          schema:
            type: integer
        X-RateLimit-Reset:
          description: Unix timestamp when the window resets
          schema:
            type: integer
    Unauthorized:
      content:
        application/json:
          example:
            error:
              code: UNAUTHORIZED
              message: Bearer token is missing or invalid
              type: https://docs.miosa.ai/errors/unauthorized
          schema:
            $ref: "#/components/schemas/ErrorResponse"
      description: Missing or invalid authentication credentials
    UnprocessableEntity:
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorResponse"
      description: The request is syntactically valid but violates the resource contract.
    ValidationError:
      content:
        application/json:
          example:
            error:
              code: VALIDATION_ERROR
              details:
                - field: name
                  reason: must be between 1 and 100 characters
              message: Request body failed validation
              type: https://docs.miosa.ai/errors/validation
          schema:
            $ref: "#/components/schemas/ValidationErrorResponse"
      description: Request body failed validation
  schemas:
    AdminUserWorkspaceRow:
      description: One workspace membership entry in the admin user-workspaces response.
      properties:
        joined_at:
          format: date-time
          nullable: true
          type: string
        role:
          enum:
            - owner
            - admin
            - member
            - viewer
          type: string
        tenant_id:
          format: uuid
          type: string
        tenant_name:
          type: string
        workspace_id:
          format: uuid
          type: string
        workspace_name:
          type: string
        workspace_slug:
          type: string
      required:
        - workspace_id
        - workspace_name
        - workspace_slug
        - tenant_id
        - tenant_name
        - role
      type: object
    AgentSession:
      description: A CUA (Computer Use Agent) session
      properties:
        completed_at:
          example: 2026-04-11T14:35:12Z
          format: date-time
          type:
            - string
            - "null"
        computer_id:
          description: Computer this session is running on
          format: uuid
          type: string
        created_at:
          description: ISO 8601 timestamp when the session was created
          example: 2026-04-11T14:30:00Z
          format: date-time
          type: string
        current_turn:
          description: Current action turn number
          example: 3
          type: integer
        error:
          description: Error message if the session failed
          type:
            - string
            - "null"
        goal:
          description: The natural-language goal given to the agent
          example: Open a terminal and create a new Python virtual environment
          type: string
        id:
          description: Session identifier
          example: a1b2c3d4-e5f6-7890-abcd-ef1234567890
          format: uuid
          type: string
        last_reasoning:
          description: The agent's most recent reasoning text
          type:
            - string
            - "null"
        max_turns:
          default: 25
          description: Maximum turns before the session is auto-cancelled
          example: 25
          type: integer
        model_id:
          description: AI model used for this session (defaults to tenant default)
          example: nemotron-3-super
          type:
            - string
            - "null"
        pending_approval:
          description: "Present when `status` is `awaiting_approval`. Describes the action the agent wants to take and is waiting for human approval.\n"
          properties:
            action_type:
              example: click
              type: string
            description:
              example: Click the "Delete All" button
              type: string
          type:
            - object
            - "null"
        result:
          description: Summary of what the agent accomplished (on completion)
          type:
            - string
            - "null"
        started_at:
          example: 2026-04-11T14:30:00Z
          format: date-time
          type:
            - string
            - "null"
        status:
          description: Current session state
          enum:
            - pending
            - running
            - awaiting_approval
            - completed
            - failed
            - cancelled
            - timed_out
          example: running
          type: string
        tenant_id:
          description: Owning tenant
          format: uuid
          type: string
      required:
        - id
        - computer_id
        - goal
        - status
        - created_at
      type: object
    ApiKey:
      description: "A developer API key. The raw key value is only present in the creation response and is never returned again.\n"
      properties:
        created_at:
          example: 2026-04-01T10:00:00Z
          format: date-time
          type: string
        id:
          description: Key record identifier
          example: b2c3d4e5-f6a7-8901-bcde-f12345678901
          format: uuid
          type: string
        key:
          description: "Raw API key value — **returned only at creation**. Store it securely; it cannot be retrieved again.\n"
          example: msk_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6
          type: string
        key_prefix:
          description: Non-secret prefix for identifying the key in logs
          example: msk_a1b2c3
          type: string
        key_purpose:
          description: "`api` keys authenticate against compute endpoints. `optimal` keys authenticate against the AI/LLM proxy.\n"
          enum:
            - api
            - optimal
          example: api
          type: string
        key_type:
          description: Role encoded by the key
          enum:
            - user
            - admin
            - platform
          example: user
          type: string
        last_used_at:
          description: When this key was last used to make a request
          example: 2026-04-11T13:00:00Z
          format: date-time
          type:
            - string
            - "null"
        name:
          description: Human-readable label
          example: Production SDK Key
          type: string
        rate_limit_rpm:
          description: Requests per minute allowed for this key
          example: 60
          type: integer
        replaced_by_key_id:
          description: Replacement key created by an atomic rotation
          format: uuid
          type:
            - string
            - "null"
        replaces_key_id:
          description: Key replaced atomically by this key
          format: uuid
          type:
            - string
            - "null"
        revoked_at:
          format: date-time
          type:
            - string
            - "null"
        rotated_at:
          format: date-time
          type:
            - string
            - "null"
        status:
          enum:
            - active
            - revoked
          example: active
          type: string
      required:
        - id
        - key_prefix
        - name
        - key_type
        - status
        - created_at
      type: object
    App:
      additionalProperties: true
      properties:
        icon_url:
          description: Optional icon URL
          example: https://cdn.miosa.ai/icons/vscode.png
          format: uri
          type:
            - string
            - "null"
        id:
          description: Launch identifier — pass as `app` to `POST /computers/{id}/desktop/launch`
          example: code
          type: string
        name:
          description: Human-readable app name
          example: Visual Studio Code
          type: string
      required:
        - id
        - name
      type: object
    AppsList:
      additionalProperties: true
      properties:
        apps:
          items:
            $ref: "#/components/schemas/App"
          type: array
      required:
        - apps
      type: object
    AutoStopConfig:
      properties:
        auto_stop_seconds:
          description: Timeout in seconds. `null` or `0` means disabled.
          example: 3600
          type:
            - integer
            - "null"
        enabled:
          description: Whether auto-stop is active for this computer
          example: true
          type: boolean
      required:
        - auto_stop_seconds
        - enabled
      type: object
    CatalogResourceContract:
      additionalProperties: false
      properties:
        contract_id:
          type: string
        contract_version:
          const: v1
          type: string
        disk_size_mb:
          type: integer
        memory_mb:
          type: integer
        product:
          type: string
        size:
          type: string
        vcpus:
          type: integer
      required:
        - contract_id
        - contract_version
        - product
        - size
        - vcpus
        - memory_mb
        - disk_size_mb
      type: object
    CloneRequest:
      description: Request body for cloning a computer
      properties:
        name:
          description: Name for the cloned computer
          example: My Dev Computer (clone)
          maxLength: 100
          minLength: 1
          type: string
        size:
          description: "Resource tier for the clone. Defaults to the source computer's size.\n"
          enum:
            - small
            - medium
            - large
            - xlarge
          type: string
        workspace_id:
          description: "Workspace to place the clone in. Defaults to the source computer's workspace.\n"
          format: uuid
          type:
            - string
            - "null"
      required:
        - name
      type: object
    Computer:
      description: A MIOSA cloud computer — a Firecracker microVM with a Linux desktop
      properties:
        agent_session_id:
          description: Currently active OSA agent session identifier
          type:
            - string
            - "null"
        agent_status:
          description: Current OSA agent status
          enum:
            - idle
            - running
            - error
            - null
          type:
            - string
            - "null"
        ai_config:
          additionalProperties: true
          description: AI/agent configuration overrides
          type:
            - object
            - "null"
        auto_stop:
          description: Auto-stop timeout in seconds. `null` or `0` disables auto-stop.
          example: 3600
          type:
            - integer
            - "null"
        created_at:
          description: ISO 8601 creation timestamp
          example: 2026-04-11T14:30:00Z
          format: date-time
          type: string
        desktop_url:
          description: URL to the KasmVNC web desktop client
          example: https://my-dev-computer.miosa.ai/desktop/index.html
          format: uri
          type: string
        id:
          description: Unique computer identifier
          example: 3fa85f64-5717-4562-b3fc-2c963f66afa6
          format: uuid
          type: string
        ip_address:
          description: Private IP address of the computer
          example: 10.0.1.42
          type:
            - string
            - "null"
        memory_mb:
          description: RAM in megabytes
          example: 2048
          type: integer
        name:
          description: Human-readable display name
          example: My Dev Computer
          type: string
        owner_user_id:
          description: User who created this computer
          format: uuid
          type: string
        resolution:
          description: Desktop resolution (e.g. `1920x1080`)
          example: 1920x1080
          type:
            - string
            - "null"
        sandbox_url:
          description: Base sandbox URL for this computer
          example: https://my-dev-computer.miosa.ai
          format: uri
          type: string
        selected_apps:
          description: Apps installed or pre-selected for this computer
          example:
            - vscode
            - firefox
          items:
            type: string
          type: array
        settings:
          additionalProperties: true
          description: Arbitrary key-value settings attached to the computer
          type:
            - object
            - "null"
        size:
          description: Resource tier
          enum:
            - small
            - medium
            - large
            - xlarge
          example: small
          type: string
        slug:
          description: "URL-safe slug used in the computer's subdomain (e.g. `my-dev-computer.miosa.ai`)\n"
          example: my-dev-computer
          type: string
        status:
          description: Current lifecycle state
          enum:
            - creating
            - provisioning
            - running
            - active
            - stopped
            - paused
            - error
            - deleted
          example: running
          type: string
        template_type:
          description: Base image template
          enum:
            - miosa-desktop
            - ubuntu-22
            - ubuntu-24
          example: miosa-desktop
          type: string
        tenant_id:
          description: Tenant (organisation) that owns this computer
          format: uuid
          type: string
        updated_at:
          description: ISO 8601 last-update timestamp
          example: 2026-04-11T15:00:00Z
          format: date-time
          type: string
        vcpus:
          description: Number of virtual CPUs
          example: 1
          type: integer
        visibility:
          description: "Access control mode. `public` — anyone with the URL; `tenant` — tenant members only; `key` — API key required.\n"
          enum:
            - public
            - tenant
            - key
          example: tenant
          type: string
        vm_id:
          description: Internal Firecracker VM identifier
          type:
            - string
            - "null"
        workspace_id:
          description: Workspace this computer belongs to
          example: 1b2c3d4e-5f6a-7890-abcd-ef1234567890
          format: uuid
          type:
            - string
            - "null"
      required:
        - id
        - name
        - slug
        - template_type
        - size
        - status
        - created_at
      type: object
    ComputerCreate:
      description: Request body for creating a new computer
      properties:
        name:
          description: Human-readable display name
          example: My Dev Computer
          maxLength: 100
          minLength: 1
          type: string
        selected_apps:
          description: Apps to install during provisioning
          example:
            - vscode
            - firefox
          items:
            type: string
          type: array
        settings:
          additionalProperties: true
          description: Arbitrary key-value settings
          type: object
        size:
          default: small
          description: Resource tier (defaults to `small`)
          enum:
            - small
            - medium
            - large
            - xlarge
          example: small
          type: string
        template_type:
          default: miosa-desktop
          description: Base image template (defaults to `miosa-desktop`)
          enum:
            - miosa-desktop
            - ubuntu-22
            - ubuntu-24
          example: miosa-desktop
          type: string
        visibility:
          default: tenant
          description: "Controls who can access this computer. `public` — anyone with the URL; `tenant` — members of your tenant only; `key` — requires a valid API key on every request.\n"
          enum:
            - public
            - tenant
            - key
          example: tenant
          type: string
      required:
        - name
      type: object
    ComputerUpdate:
      description: Request body for updating a computer (all fields optional)
      properties:
        ai_config:
          additionalProperties: true
          type: object
        name:
          example: Renamed Computer
          maxLength: 100
          minLength: 1
          type: string
        settings:
          additionalProperties: true
          type: object
        visibility:
          description: "Controls who can access this computer. `public` — anyone with the URL; `tenant` — members of your tenant only; `key` — requires a valid API key on every request.\n"
          enum:
            - public
            - tenant
            - key
          example: key
          type: string
      type: object
    ComputerUrls:
      properties:
        computer_id:
          format: uuid
          type: string
        desktop_url:
          description: URL to the KasmVNC web desktop client (requires a stream token)
          example: https://my-computer.miosa.ai/desktop/index.html
          format: uri
          type: string
        terminal_url:
          description: Base WebSocket URL for interactive terminal sessions. Append `/{session_id}?auth=<stream_token>` to connect.
          example: wss://my-computer.miosa.ai/ws/terminal/3fa85f64-5717-4562-b3fc-2c963f66afa6
          type: string
        vnc_url:
          description: Alias of `desktop_url` — kept for compatibility with older clients
          example: https://my-computer.miosa.ai/desktop/index.html
          format: uri
          type: string
      required:
        - computer_id
        - desktop_url
        - vnc_url
        - terminal_url
      type: object
    CopyRequest:
      description: Request body for copying a file or directory
      properties:
        destination:
          description: Absolute destination path inside the computer
          example: /home/user/copy.py
          type: string
        overwrite:
          default: false
          description: Overwrite the destination if it already exists
          type: boolean
        recursive:
          default: false
          description: Copy directories recursively
          type: boolean
        source:
          description: Absolute source path inside the computer
          example: /home/user/original.py
          type: string
      required:
        - source
        - destination
      type: object
    CreateDatabaseRequest:
      properties:
        cpu_count:
          default: 1
          maximum: 16
          minimum: 1
          type: integer
        engine:
          default: postgresql
          enum:
            - postgresql
            - mysql
            - redis
          type: string
        engine_version:
          example: "16"
          type: string
        external_project_id:
          type: string
        external_user_id:
          type: string
        external_workspace_id:
          type: string
        memory_mb:
          default: 2048
          maximum: 65536
          minimum: 512
          type: integer
        metadata:
          additionalProperties: true
          type: object
        name:
          example: app-postgres
          type: string
        region:
          default: us-mia
          type: string
        storage_mb:
          default: 10240
          maximum: 1048576
          minimum: 1024
          type: integer
      required:
        - name
      type: object
    CreateDeploymentRequest:
      properties:
        auto_deploy:
          default: true
          description: Rebuild on every push to `branch`.
          type: boolean
        branch:
          default: main
          description: Branch to watch for auto-deploys.
          example: main
          type: string
        build_command:
          description: "Override the build command. If omitted, the platform will attempt framework detection (Optimal sprint) to determine the correct command.\n"
          example: npm run build
          type: string
        database:
          description: "Request a MIOSA-managed database for the deployment. `true` provisions the default PostgreSQL instance; an object can choose engine, size, storage, and region.\n"
          oneOf:
            - type: boolean
            - properties:
                engine:
                  default: postgresql
                  enum:
                    - postgresql
                    - mysql
                    - redis
                  type: string
                region:
                  default: us-mia
                  type: string
                size:
                  default: xs
                  enum:
                    - xs
                    - small
                    - medium
                    - large
                  type: string
                storage_mb:
                  default: 10240
                  minimum: 1024
                  type: integer
              type: object
        env:
          additionalProperties:
            type: string
          description: Initial env vars — encrypted at rest immediately.
          example:
            NODE_ENV: production
          type: object
        external_project_id:
          description: Customer-supplied project/application identifier for attribution only.
          example: landing-page-789
          maxLength: 255
          nullable: true
          type: string
        external_user_id:
          description: Customer-supplied end-user identifier for attribution only.
          example: dr-smith-456
          maxLength: 255
          nullable: true
          type: string
        external_workspace_id:
          description: Customer-supplied workspace/team/account identifier for attribution only.
          example: dental-office-123
          maxLength: 255
          nullable: true
          type: string
        metadata:
          additionalProperties: true
          description: Arbitrary caller metadata.
          type: object
        name:
          description: Human-readable deployment name.
          example: my-app
          maxLength: 100
          minLength: 1
          type: string
        repo_url:
          description: "HTTPS GitHub URL. `.git` suffix is stripped automatically.\n"
          example: https://github.com/acme/my-app
          format: uri
          type: string
        run_command:
          description: Override the run command.
          example: npm start
          type: string
      required:
        - name
        - repo_url
      type: object
    CreateRunRequest:
      properties:
        command:
          description: Explicit command for command/custom runners.
          nullable: true
          type: string
        connectors:
          description: Connector intents such as `refero/design-research`.
          items:
            type: string
          type: array
        cwd:
          nullable: true
          type: string
        env:
          additionalProperties:
            type: string
          description: Structured environment variables. Do not put secrets in command text.
          type: object
        execution_packet:
          additionalProperties: true
          description: Runtime bundle used by white-label products and agent runners.
          type: object
        expected_outputs:
          $ref: "#/components/schemas/RunExpectedOutputs"
        instruction:
          description: User-facing task for the runner.
          type: string
        metadata:
          additionalProperties: true
          type: object
        runner:
          enum:
            - claude-code
            - codex
            - command
            - custom
          type: string
        target_id:
          type: string
        target_kind:
          enum:
            - sandbox
            - computer
          type: string
        timeout_sec:
          minimum: 1
          nullable: true
          type: integer
        workspace_id:
          format: uuid
          nullable: true
          type: string
      required:
        - target_kind
        - target_id
        - runner
        - instruction
      type: object
    CreateSandboxRequest:
      properties:
        always_on:
          default: false
          description: Keep the sandbox running until an explicit lifecycle action.
          type: boolean
        auto_start:
          default: false
          description: "If true, MIOSA waits for the sandbox to enter `running` state and then runs the selected template lifecycle in the background. Most generated-app platforms should keep this false, write files first, then call `/sandboxes/{id}/template/start`.\n"
          type: boolean
        cpu_count:
          description: "Explicit vCPU parameter. When any explicit resource parameter is supplied, the complete set must identify a published size contract.\n"
          maximum: 16
          minimum: 1
          type: integer
        disk_mb:
          deprecated: true
          description: Deprecated alias for `disk_size_mb`.
          maximum: 81920
          minimum: 10240
          type: integer
        disk_size_mb:
          description: "Explicit root disk parameter in MiB. It must match the same published contract as `cpu_count` and `memory_mb`.\n"
          maximum: 81920
          minimum: 10240
          type: integer
        env:
          additionalProperties:
            type: string
          description: Environment variables injected into the VM at boot.
          example:
            API_KEY: sk-abc123
            DEBUG: "true"
          type: object
        external_project_id:
          description: Customer-supplied project/application identifier for attribution only.
          example: landing-page-789
          maxLength: 255
          nullable: true
          type: string
        external_user_id:
          description: Customer-supplied end-user identifier for attribution only.
          example: dr-smith-456
          maxLength: 255
          nullable: true
          type: string
        external_workspace_id:
          description: Customer-supplied workspace/team/account identifier for attribution only.
          example: dental-office-123
          maxLength: 255
          nullable: true
          type: string
        idle_timeout_sec:
          default: 0
          description: Seconds without activity before auto-stop. Zero disables idle timeout.
          minimum: 0
          type: integer
        memory_mb:
          description: "Explicit RAM parameter in MiB. It must match the same published contract as `cpu_count` and `disk_size_mb`.\n"
          maximum: 32768
          minimum: 2048
          type: integer
        metadata:
          additionalProperties: true
          description: "Arbitrary metadata stored on the sandbox record. Useful for tagging with agent run IDs, task names, or other caller context.\n"
          type: object
        persistent:
          default: true
          description: Preserve filesystem state across stop and timeout so the sandbox can resume.
          type: boolean
        size:
          default: small
          description: "Preferred resource selector. The default `small` contract is 2 vCPU, 4096 MiB RAM, and 10240 MiB disk.\n"
          enum:
            - xs
            - small
            - medium
            - large
            - xl
          type: string
        template_id:
          description: "Boot template alias or image ID. Defaults to `miosa-sandbox`.\n"
          example: miosa-sandbox
          type: string
        timeout_sec:
          default: 3600
          description: "Sandbox timeout policy in seconds. Defaults to 3600 seconds and accepts up to 86400 seconds. Persistence and idle-pause behavior are configured independently.\n"
          maximum: 86400
          minimum: 1
          type: integer
      type: object
    CreateStorageBucketRequest:
      properties:
        metadata:
          additionalProperties: true
          type: object
        name:
          type: string
        quota_bytes:
          format: int64
          type: integer
        region:
          default: us-mia
          type: string
        visibility:
          default: private
          enum:
            - private
            - public
          type: string
      required:
        - name
      type: object
    CreditBalance:
      properties:
        balance:
          description: Current credit balance
          example: 2450
          type: integer
        tenant_id:
          description: Owning tenant
          example: 3fa85f64-5717-4562-b3fc-2c963f66afa6
          format: uuid
          type: string
      required:
        - balance
        - tenant_id
      type: object
    CreditTransaction:
      properties:
        amount:
          description: Credit amount (positive = credit, negative = debit)
          example: -10
          type: integer
        balance_after:
          description: Balance immediately after this transaction
          example: 2440
          type: integer
        created_at:
          example: 2026-04-11T14:30:00Z
          format: date-time
          type: string
        description:
          example: "Compute: small VM, 1h"
          type:
            - string
            - "null"
        id:
          format: uuid
          type: string
        reference_id:
          description: Related resource ID (computer ID, session ID, etc.)
          type:
            - string
            - "null"
        type:
          description: Transaction category
          enum:
            - grant
            - purchase
            - compute_usage
            - ai_usage
            - refund
            - expiry
          example: compute_usage
          type: string
      required:
        - id
        - amount
        - type
        - created_at
      type: object
    CuaEvent:
      description: "A Server-Sent Event emitted on the CUA session event stream. The `event:` field in the SSE envelope indicates the event type; `data:` is always a JSON-encoded object.\n"
      properties:
        action_type:
          description: Type of action being taken (click, type, key, etc.)
          type:
            - string
            - "null"
        error:
          description: Error description on failure events
          type:
            - string
            - "null"
        reasoning:
          description: Agent's reasoning for this step
          type:
            - string
            - "null"
        result:
          description: Outcome summary on completion events
          type:
            - string
            - "null"
        session_id:
          format: uuid
          type: string
        turn:
          type:
            - integer
            - "null"
      type: object
    CustomDomain:
      description: A custom hostname attached to a computer or deployment.
      properties:
        computer_id:
          description: Computer this domain routes to, when this is a computer domain.
          format: uuid
          nullable: true
          type: string
        created_at:
          example: 2026-04-11T14:30:00Z
          format: date-time
          type: string
        deployment_id:
          description: Deployment this domain routes to, when this is a deployment domain.
          format: uuid
          nullable: true
          type: string
        error_message:
          description: Error detail when status is `error`
          type:
            - string
            - "null"
        external_project_id:
          description: Customer-supplied project/application identifier for attribution only.
          example: landing-page-789
          nullable: true
          type: string
        external_user_id:
          description: Customer-supplied end-user identifier for attribution only.
          example: dr-smith-456
          nullable: true
          type: string
        external_workspace_id:
          description: Customer-supplied workspace/team/account identifier for attribution only.
          example: dental-office-123
          nullable: true
          type: string
        fqdn:
          description: Fully-qualified domain name. Newer APIs return `fqdn`.
          example: app.example.com
          type: string
        hostname:
          description: The custom hostname (e.g. `app.example.com`)
          example: app.example.com
          type: string
        id:
          description: Domain record identifier
          example: 3d4e5f6a-7b8c-9012-cdef-123456789012
          format: uuid
          type: string
        status:
          description: Verification and activation state
          enum:
            - pending_verification
            - verified
            - active
            - error
          example: pending_verification
          type: string
        target_port:
          description: Port inside the computer to proxy traffic to (defaults to 80)
          example: 3000
          type:
            - integer
            - "null"
        tenant_id:
          description: Owning MIOSA tenant.
          format: uuid
          nullable: true
          type: string
        verification_method:
          description: Challenge type used to verify domain ownership
          enum:
            - dns_txt
            - http_file
          example: dns_txt
          type: string
        verification_token:
          description: Token to place in the DNS TXT record or HTTP challenge file
          example: miosa-verify=abc123def456
          type: string
        verified_at:
          description: When the domain was successfully verified
          format: date-time
          type:
            - string
            - "null"
      required:
        - id
        - fqdn
        - status
        - created_at
      type: object
    CustomDomainCreateRequest:
      description: Request body for attaching a custom domain
      properties:
        external_project_id:
          description: Customer-supplied project/application identifier for attribution only.
          maxLength: 255
          nullable: true
          type: string
        external_user_id:
          description: Customer-supplied end-user identifier for attribution only.
          maxLength: 255
          nullable: true
          type: string
        external_workspace_id:
          description: Customer-supplied workspace/team/account identifier for attribution only.
          maxLength: 255
          nullable: true
          type: string
        hostname:
          description: Fully-qualified domain name to attach
          example: app.example.com
          type: string
        target_port:
          default: 80
          description: Port inside the computer to proxy traffic to
          example: 3000
          maximum: 65535
          minimum: 1
          type: integer
        verification_method:
          default: dns_txt
          description: Challenge method to verify domain ownership
          enum:
            - dns_txt
            - http_file
          type: string
      required:
        - hostname
      type: object
    CustomDomainListResponse:
      properties:
        domains:
          items:
            $ref: "#/components/schemas/CustomDomain"
          type: array
      required:
        - domains
      type: object
    Database:
      description: "MIOSA-managed database service. The database survives sandbox/runtime shutdown; credentials are encrypted at rest and only returned from the credentials endpoint.\n"
      properties:
        cpu_count:
          example: 1
          type: integer
        created_at:
          format: date-time
          type: string
        engine:
          enum:
            - postgresql
            - mysql
            - redis
          example: postgresql
          type: string
        engine_version:
          example: "16"
          type: string
        external_project_id:
          nullable: true
          type: string
        external_user_id:
          nullable: true
          type: string
        external_workspace_id:
          nullable: true
          type: string
        host:
          description: Private database address when running.
          nullable: true
          type: string
        id:
          format: uuid
          type: string
        memory_mb:
          example: 2048
          type: integer
        metadata:
          additionalProperties: true
          type: object
        name:
          example: app-postgres
          type: string
        node_id:
          nullable: true
          type: string
        owner_id:
          format: uuid
          type: string
        port:
          nullable: true
          type: integer
        region:
          example: us-mia
          type: string
        started_at:
          format: date-time
          nullable: true
          type: string
        state:
          enum:
            - provisioning
            - running
            - stopped
            - stopping
            - restarting
            - destroying
            - destroyed
            - error
          example: running
          type: string
        stopped_at:
          format: date-time
          nullable: true
          type: string
        storage_mb:
          example: 10240
          type: integer
        tenant_id:
          format: uuid
          type: string
      required:
        - id
        - tenant_id
        - owner_id
        - name
        - engine
        - engine_version
        - state
        - region
        - cpu_count
        - memory_mb
        - storage_mb
        - created_at
      type: object
    DatabaseCredentials:
      additionalProperties: true
      description: Decrypted database credentials. Returned only by `/databases/{id}/credentials`.
      properties:
        database:
          type: string
        host:
          type: string
        password:
          type: string
        port:
          type: integer
        user:
          type: string
        username:
          type: string
      type: object
    Deployment:
      description: "A MIOSA deployment record. Today it supports static deployment versions, sandbox-backed compatibility publishing, and repo-connected build metadata. The production target model is release/runtime-instance based, not an editable sandbox.\n"
      properties:
        auto_deploy:
          default: true
          description: Automatically rebuild on push to `branch`.
          type: boolean
        branch:
          default: main
          example: main
          type: string
        build_command:
          description: "Override the auto-detected build command. If null, the platform uses framework detection (Optimal sprint) to determine the command.\n"
          example: npm run build
          nullable: true
          type: string
        created_at:
          format: date-time
          type: string
        current_build_id:
          description: ID of the most recently triggered build.
          format: uuid
          nullable: true
          type: string
        custom_domain_id:
          format: uuid
          nullable: true
          type: string
        external_project_id:
          description: Customer-supplied project/application identifier for attribution only.
          example: landing-page-789
          nullable: true
          type: string
        external_user_id:
          description: Customer-supplied end-user identifier for attribution only.
          example: dr-smith-456
          nullable: true
          type: string
        external_workspace_id:
          description: Customer-supplied workspace/team/account identifier for attribution only.
          example: dental-office-123
          nullable: true
          type: string
        id:
          format: uuid
          type: string
        linked_database_id:
          description: "Auto-provisioned managed database linked to this deployment, when `database` was requested at creation.\n"
          format: uuid
          nullable: true
          type: string
        metadata:
          additionalProperties: true
          default: {}
          type: object
        name:
          example: my-app
          maxLength: 100
          type: string
        owner_id:
          format: uuid
          type: string
        repo_provider:
          enum:
            - github
          example: github
          type: string
        repo_url:
          example: https://github.com/acme/my-app
          format: uri
          type: string
        run_command:
          description: Override the auto-detected run command.
          example: npm start
          nullable: true
          type: string
        runtime_image:
          description: OCI image digest of the most recently built image.
          nullable: true
          type: string
        slug:
          description: "Auto-generated URL-safe slug. Determines the subdomain: `<slug>.<tenant-slug>.miosa.app`\n"
          example: my-app-a3f8b2
          maxLength: 63
          type: string
        state:
          enum:
            - pending
            - building
            - running
            - stopped
            - failed
          example: running
          type: string
        tenant_id:
          format: uuid
          type: string
        updated_at:
          format: date-time
          type: string
      required:
        - id
        - tenant_id
        - owner_id
        - name
        - slug
        - repo_url
        - repo_provider
        - branch
        - state
        - auto_deploy
        - created_at
        - updated_at
      type: object
    DeploymentBuild:
      description: A single build run for a deployment.
      properties:
        commit_message:
          example: "feat: add dark mode"
          nullable: true
          type: string
        commit_sha:
          example: a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0
          nullable: true
          type: string
        created_at:
          format: date-time
          type: string
        deployment_id:
          format: uuid
          type: string
        duration_ms:
          description: Build duration in milliseconds.
          example: 45321
          nullable: true
          type: integer
        error_message:
          description: Human-readable failure reason (set on `failed` state).
          nullable: true
          type: string
        finished_at:
          format: date-time
          nullable: true
          type: string
        id:
          format: uuid
          type: string
        image_digest:
          description: OCI image digest produced by a successful build.
          example: sha256:abc123...
          nullable: true
          type: string
        log_url:
          description: Signed object-storage URL for the build log file.
          format: uri
          nullable: true
          type: string
        started_at:
          format: date-time
          nullable: true
          type: string
        state:
          enum:
            - queued
            - building
            - succeeded
            - failed
            - cancelled
          example: queued
          type: string
        triggered_by:
          enum:
            - webhook
            - manual
            - scheduled
          example: webhook
          type: string
      required:
        - id
        - deployment_id
        - triggered_by
        - state
        - created_at
      type: object
    DeploymentRelease:
      description: Immutable release artifact attached to a deployment service.
      properties:
        artifact_sha256:
          nullable: true
          type: string
        artifact_uri:
          nullable: true
          type: string
        created_at:
          format: date-time
          type: string
        deployment_id:
          format: uuid
          type: string
        deployment_version_id:
          format: uuid
          type: string
        health_check_path:
          nullable: true
          type: string
        id:
          format: uuid
          type: string
        kind:
          enum:
            - static
            - slug
            - rootfs
            - oci_image
            - function_bundle
          example: static
          type: string
        metadata:
          additionalProperties: true
          type: object
        port:
          nullable: true
          type: integer
        ready_at:
          format: date-time
          nullable: true
          type: string
        start_command:
          nullable: true
          type: string
        state:
          enum:
            - building
            - ready
            - failed
            - archived
          example: ready
          type: string
        storage_backend:
          example: s3
          nullable: true
          type: string
        tenant_id:
          format: uuid
          type: string
        updated_at:
          format: date-time
          type: string
      type: object
    DeploymentVersion:
      description: Immutable version produced by one publish/build.
      properties:
        archived_at:
          format: date-time
          nullable: true
          type: string
        artifact_manifest:
          additionalProperties: true
          type: object
        artifact_sha256:
          nullable: true
          type: string
        artifact_uri:
          nullable: true
          type: string
        build_id:
          format: uuid
          nullable: true
          type: string
        created_at:
          format: date-time
          type: string
        created_by:
          format: uuid
          nullable: true
          type: string
        deployment_id:
          format: uuid
          type: string
        external_project_id:
          nullable: true
          type: string
        external_user_id:
          nullable: true
          type: string
        external_workspace_id:
          nullable: true
          type: string
        health_check_path:
          nullable: true
          type: string
        id:
          format: uuid
          type: string
        kind:
          enum:
            - static
            - dynamic
          example: static
          type: string
        metadata:
          additionalProperties: true
          type: object
        promoted_at:
          format: date-time
          nullable: true
          type: string
        runtime_command:
          nullable: true
          type: string
        runtime_image:
          nullable: true
          type: string
        runtime_port:
          nullable: true
          type: integer
        source_sandbox_id:
          format: uuid
          nullable: true
          type: string
        state:
          enum:
            - building
            - ready
            - failed
            - archived
          example: ready
          type: string
        tenant_id:
          format: uuid
          type: string
        updated_at:
          format: date-time
          type: string
        version_number:
          example: 3
          type: integer
      type: object
    DirEntry:
      description: A single entry returned by a directory listing
      properties:
        modified_at:
          example: 2026-04-11T12:00:00Z
          format: date-time
          type: string
        name:
          description: Entry name (filename, not full path)
          example: server.py
          type: string
        path:
          description: Absolute path inside the computer
          example: /home/user/app/server.py
          type: string
        size_bytes:
          description: File size in bytes (0 for directories)
          example: 1024
          type: integer
        type:
          enum:
            - file
            - directory
            - symlink
            - unknown
          example: file
          type: string
      required:
        - name
        - path
        - type
      type: object
    EnvVarPreview:
      description: "Public representation of an env var. Plaintext value is never returned.\n"
      properties:
        created_at:
          format: date-time
          type: string
        name:
          description: Variable name (UPPER_SNAKE_CASE)
          example: DATABASE_URL
          type: string
        preview:
          description: "Masked value: first 3 + \"...\" + last 3 chars, or all asterisks if the value is 6 chars or shorter.\n"
          example: pos...url
          type: string
        updated_at:
          format: date-time
          type: string
      required:
        - name
        - preview
      type: object
    ErrorResponse:
      properties:
        error:
          additionalProperties: true
          properties:
            code:
              description: Machine-readable error code (SCREAMING_SNAKE_CASE)
              example: NOT_FOUND
              type: string
            message:
              description: Human-readable description
              example: Computer not found
              type: string
            type:
              description: Link to error documentation
              example: https://docs.miosa.ai/errors/not-found
              format: uri
              type: string
          required:
            - code
          type: object
      required:
        - error
      type: object
    ExecResult:
      description: Result of a shell command or Python execution
      properties:
        error:
          description: Error message if the exec call itself failed
          example: null
          type:
            - string
            - "null"
        exit_code:
          description: Process exit code
          example: 0
          type:
            - integer
            - "null"
        output:
          description: Combined stdout and stderr
          example: "hello world\n"
          type: string
        success:
          description: Whether the command exited with code 0
          example: true
          type: boolean
      required:
        - output
        - success
      type: object
    ExtendSandboxRequest:
      additionalProperties: false
      properties:
        timeout:
          deprecated: true
          description: Compatibility alias for `timeout_sec`.
          maximum: 86400
          minimum: 1
          type: integer
        timeout_sec:
          maximum: 86400
          minimum: 1
          type: integer
      type: object
    FileInfo:
      description: Metadata for a file or directory inside the computer
      properties:
        modified_at:
          description: Last modification time in ISO 8601
          example: 2026-04-10T09:00:00Z
          format: date-time
          type: string
        name:
          description: Filename (not the full path)
          example: script.py
          type: string
        size_bytes:
          description: File size in bytes (0 for directories)
          example: 4096
          type: integer
        type:
          description: Entry type
          enum:
            - file
            - directory
            - unknown
          example: file
          type: string
      required:
        - name
        - type
        - size_bytes
      type: object
    FileStat:
      description: Detailed stat information for a single filesystem entry
      properties:
        created_at:
          description: Creation time (not available on all filesystems)
          example: 2026-04-10T09:00:00Z
          format: date-time
          type:
            - string
            - "null"
        group:
          description: Owning group name
          example: user
          type:
            - string
            - "null"
        mode:
          description: Unix file mode in octal string notation
          example: "0644"
          type: string
        modified_at:
          description: Last modification time
          example: 2026-04-11T12:00:00Z
          format: date-time
          type: string
        owner:
          description: Owning username
          example: user
          type:
            - string
            - "null"
        path:
          description: Absolute path inside the computer
          example: /home/user/app/server.py
          type: string
        size_bytes:
          description: File size in bytes (0 for directories)
          example: 4096
          type: integer
        symlink_target:
          description: Resolved target path when type is `symlink`
          example: /usr/local/bin/python
          type:
            - string
            - "null"
        type:
          description: Entry type
          enum:
            - file
            - directory
            - symlink
            - unknown
          example: file
          type: string
      required:
        - path
        - type
        - size_bytes
        - mode
        - modified_at
      type: object
    ForkSandboxRequest:
      additionalProperties: false
      properties:
        template_id:
          type: string
        timeout_sec:
          maximum: 86400
          minimum: 1
          type: integer
      type: object
    IntelligenceAgentModelAssignment:
      properties:
        agent_id:
          maxLength: 255
          minLength: 1
          type: string
        created_at:
          format: date-time
          type: string
        enabled:
          type: boolean
        fallback_models:
          items:
            type: string
          type: array
        id:
          format: uuid
          type: string
        model:
          type: string
        parameters:
          additionalProperties: true
          type: object
        updated_at:
          format: date-time
          type: string
      required:
        - id
        - agent_id
        - model
        - fallback_models
        - parameters
        - enabled
      type: object
    IntelligenceEvaluationPolicy:
      properties:
        created_at:
          format: date-time
          type: string
        dataset:
          items:
            additionalProperties: true
            type: object
          maxItems: 500
          type: array
        description:
          type:
            - string
            - "null"
        enabled:
          type: boolean
        id:
          format: uuid
          type: string
        metrics:
          items:
            enum:
              - exact_match
              - contains
              - json_valid
              - latency_ms
            type: string
          type: array
        model:
          type: string
        name:
          maxLength: 120
          minLength: 1
          type: string
        thresholds:
          additionalProperties: true
          type: object
        updated_at:
          format: date-time
          type: string
      required:
        - id
        - name
        - model
        - dataset
        - metrics
        - thresholds
        - enabled
      type: object
    IntelligenceEvaluationRun:
      properties:
        completed_at:
          format: date-time
          type:
            - string
            - "null"
        created_at:
          format: date-time
          type: string
        error:
          additionalProperties: true
          type:
            - object
            - "null"
        id:
          format: uuid
          type: string
        idempotency_key:
          type: string
        input_count:
          minimum: 0
          type: integer
        model:
          type: string
        policy_id:
          format: uuid
          type: string
        results:
          items:
            additionalProperties: true
            type: object
          type: array
        started_at:
          format: date-time
          type:
            - string
            - "null"
        status:
          enum:
            - queued
            - running
            - completed
            - failed
            - cancelled
          type: string
        summary:
          additionalProperties: true
          type: object
        updated_at:
          format: date-time
          type: string
      required:
        - id
        - policy_id
        - status
        - model
        - idempotency_key
        - input_count
      type: object
    IntelligenceGatewayBudget:
      properties:
        consumed_credits:
          minimum: 0
          type: integer
        hard_limit:
          type: boolean
        id:
          format: uuid
          type: string
        monthly_credit_limit:
          minimum: 1
          type:
            - integer
            - "null"
        per_request_credit_limit:
          minimum: 1
          type:
            - integer
            - "null"
        period_end:
          format: date-time
          type: string
        period_start:
          format: date-time
          type: string
        requests_per_minute:
          minimum: 1
          type:
            - integer
            - "null"
        updated_at:
          format: date-time
          type: string
      type: object
    IntelligenceGatewayHealth:
      properties:
        budget:
          additionalProperties: true
          type: object
        configured_policies:
          minimum: 0
          type: integer
        enabled_policies:
          minimum: 0
          type: integer
        execution_readiness:
          description: Provider execution readiness is not inferred from policy configuration
          enum:
            - not_observed
          type: string
        providers:
          items:
            type: string
          type: array
        status:
          enum:
            - configured
            - unconfigured
          type: string
      required:
        - status
        - execution_readiness
        - configured_policies
        - enabled_policies
        - budget
        - providers
      type: object
    IntelligenceGatewayPolicy:
      properties:
        created_at:
          format: date-time
          type: string
        enabled:
          type: boolean
        fallback_models:
          items:
            type: string
          type: array
        id:
          format: uuid
          type: string
        name:
          maxLength: 120
          minLength: 1
          type: string
        primary_model:
          type: string
        priority:
          minimum: 0
          type: integer
        selector:
          additionalProperties: true
          type: object
        updated_at:
          format: date-time
          type: string
      required:
        - id
        - name
        - selector
        - primary_model
        - fallback_models
        - priority
        - enabled
      type: object
    IntelligenceProviderCredential:
      description: Safe provider credential metadata. Encrypted and raw credential values are never returned.
      properties:
        inserted_at:
          format: date-time
          type: string
        last_validated_at:
          format: date-time
          type:
            - string
            - "null"
        metadata:
          additionalProperties: true
          type: object
        name:
          type:
            - string
            - "null"
        provider:
          enum:
            - anthropic
            - openai
            - groq
            - together
            - openrouter
            - google
            - mistral
          type: string
        updated_at:
          format: date-time
          type: string
        validation_status:
          enum:
            - unverified
            - storage_valid
            - invalid
          type: string
      required:
        - provider
        - validation_status
      type: object
    MkdirRequest:
      description: Request body for creating a directory
      properties:
        exist_ok:
          default: false
          description: Do not error if the directory already exists
          type: boolean
        parents:
          default: false
          description: "Create parent directories as needed (equivalent to `mkdir -p`). Ignored if the directory already exists when `exist_ok` is true.\n"
          type: boolean
        path:
          description: Absolute path of the directory to create
          example: /home/user/projects/new-dir
          type: string
      required:
        - path
      type: object
    MoveRequest:
      description: Request body for moving a computer to a different workspace
      properties:
        workspace_id:
          description: Destination workspace UUID
          example: 1b2c3d4e-5f6a-7890-abcd-ef1234567890
          format: uuid
          type: string
      required:
        - workspace_id
      type: object
    NetworkPolicy:
      description: Firewall rules for a computer
      properties:
        computer_id:
          description: Computer this policy applies to
          format: uuid
          type: string
        default_inbound:
          description: "Action taken on inbound traffic that does not match any rule. Defaults to `deny`.\n"
          enum:
            - allow
            - deny
          example: deny
          type: string
        default_outbound:
          description: "Action taken on outbound traffic that does not match any rule. Defaults to `allow`.\n"
          enum:
            - allow
            - deny
          example: allow
          type: string
        rules:
          description: Ordered list of rules; evaluated top-to-bottom
          items:
            $ref: "#/components/schemas/NetworkPolicyRule"
          type: array
        updated_at:
          example: 2026-04-11T14:30:00Z
          format: date-time
          type: string
      required:
        - computer_id
        - rules
        - default_inbound
        - default_outbound
        - updated_at
      type: object
    NetworkPolicyRule:
      description: A single firewall rule in a network policy
      properties:
        action:
          description: Whether matching traffic is allowed or blocked
          enum:
            - allow
            - deny
          example: allow
          type: string
        cidr:
          description: "Source (inbound) or destination (outbound) CIDR. Defaults to `0.0.0.0/0` (all).\n"
          example: 10.0.0.0/8
          type:
            - string
            - "null"
        description:
          description: Human-readable note about this rule
          example: Allow HTTPS from anywhere
          type:
            - string
            - "null"
        direction:
          description: Traffic direction this rule applies to
          enum:
            - inbound
            - outbound
          example: inbound
          type: string
        port:
          description: "Specific port to match. Omit or set `null` to match all ports for the given protocol.\n"
          example: 443
          maximum: 65535
          minimum: 1
          type:
            - integer
            - "null"
        port_range:
          description: "Port range in `start-end` notation (e.g. `8000-8080`). Mutually exclusive with `port`.\n"
          example: 8000-8080
          type:
            - string
            - "null"
        protocol:
          description: IP protocol to match
          enum:
            - tcp
            - udp
            - icmp
            - any
          example: tcp
          type: string
      required:
        - direction
        - action
        - protocol
      type: object
    NetworkPolicyUpdateRequest:
      description: "Full replacement of a computer's network policy. Omitted optional fields revert to their defaults.\n"
      properties:
        default_inbound:
          default: deny
          description: Default action for unmatched inbound traffic
          enum:
            - allow
            - deny
          type: string
        default_outbound:
          default: allow
          description: Default action for unmatched outbound traffic
          enum:
            - allow
            - deny
          type: string
        rules:
          description: Complete ordered rule list (replaces existing rules)
          items:
            $ref: "#/components/schemas/NetworkPolicyRule"
          type: array
      required:
        - rules
      type: object
    OrgInvite:
      description: A pending org (tenant) invite row.
      properties:
        accepted_at:
          format: date-time
          nullable: true
          type: string
        created_at:
          format: date-time
          type: string
        email:
          format: email
          type: string
        expires_at:
          format: date-time
          type: string
        id:
          format: uuid
          type: string
        invited_by:
          format: uuid
          nullable: true
          type: string
        role:
          enum:
            - owner
            - admin
            - member
          type: string
        tenant_id:
          format: uuid
          type: string
      required:
        - id
        - tenant_id
        - email
        - role
        - expires_at
      type: object
    OrgInviteCreated:
      description: Response from creating an org invite.
      properties:
        email:
          format: email
          type: string
        expires_at:
          format: date-time
          type: string
        invite_id:
          format: uuid
          type: string
        invite_url:
          description: "Full URL for the invite landing page. On white-label tenants this uses the tenant's custom domain.\n"
          format: uri
          type: string
        role:
          enum:
            - owner
            - admin
            - member
          type: string
      required:
        - invite_id
        - email
        - role
        - expires_at
        - invite_url
      type: object
    OrgInvitePreview:
      description: Public preview of an org invite (no auth required).
      properties:
        accepted:
          type: boolean
        email:
          format: email
          type: string
        expired:
          type: boolean
        expires_at:
          format: date-time
          type: string
        role:
          enum:
            - owner
            - admin
            - member
          type: string
        tenant_name:
          type: string
      required:
        - email
        - tenant_name
        - role
        - expires_at
        - expired
        - accepted
      type: object
    ProjectAuthMutationRequest:
      properties:
        config:
          properties:
            email_confirm_required:
              type: boolean
            signup_enabled:
              type: boolean
            token_expiry_sec:
              type: integer
          type: object
        resource_id:
          format: uuid
          type: string
        resource_type:
          enum:
            - sandbox
            - deployment
          type: string
      required:
        - resource_type
        - resource_id
      type: object
    ProjectAuthStatus:
      properties:
        config:
          additionalProperties: true
          type: object
        created_at:
          format: date-time
          type: string
        database_id:
          format: uuid
          nullable: true
          type: string
        enabled:
          type: boolean
        state:
          enum:
            - active
            - disabled
          type: string
        updated_at:
          format: date-time
          type: string
      type: object
    PublicTemplate:
      properties:
        aliases:
          items:
            type: string
          type: array
        benchmark_lane:
          additionalProperties: true
          type: object
        cli_name:
          type: string
        default_size:
          type: string
        description:
          type:
            - string
            - "null"
        id:
          type: string
        image_id:
          description: Public image identifier accepted by compatibility clients.
          type:
            - string
            - "null"
        install_command:
          type:
            - string
            - "null"
        installed_tools:
          items:
            type: string
          type: array
        name:
          type: string
        primitive:
          type: string
        product:
          type: string
        readiness:
          enum:
            - fast_ready
            - cold_boot_only
            - missing
          type: string
        readiness_contract:
          additionalProperties: true
          type: object
        readiness_probe:
          additionalProperties: true
          type:
            - object
            - "null"
        sdk_name:
          type: string
        sizes:
          items:
            additionalProperties: true
            properties:
              resource_contract:
                $ref: "#/components/schemas/CatalogResourceContract"
              size:
                type: string
              state:
                enum:
                  - fast_ready
                  - cold_boot_only
                  - missing
                type: string
            required:
              - size
              - state
            type: object
          type: array
        start_command:
          type:
            - string
            - "null"
      required:
        - id
        - name
        - product
        - default_size
        - primitive
        - sdk_name
        - cli_name
        - sizes
        - readiness
      type: object
    PublishDeploymentRequest:
      properties:
        entrypoint:
          nullable: true
          type: string
        output_path:
          default: /workspace
          type: string
        promote:
          default: false
          type: boolean
        source_sandbox_id:
          format: uuid
          type: string
        source_snapshot_path:
          default: /workspace
          type: string
      required:
        - source_sandbox_id
      type: object
    PublishDeploymentResponse:
      properties:
        data:
          properties:
            deployment:
              $ref: "#/components/schemas/Deployment"
            promoted:
              type: boolean
            release:
              $ref: "#/components/schemas/DeploymentRelease"
            version:
              $ref: "#/components/schemas/DeploymentVersion"
          type: object
      type: object
    RenameRequest:
      description: Request body for renaming or moving a file or directory
      properties:
        destination:
          description: Absolute destination path inside the computer
          example: /home/user/new-name.py
          type: string
        overwrite:
          default: false
          description: Overwrite the destination if it already exists
          type: boolean
        source:
          description: Absolute source path inside the computer
          example: /home/user/old-name.py
          type: string
      required:
        - source
        - destination
      type: object
    ResizeRequest:
      description: Request body for resizing a computer's resource tier
      properties:
        size:
          description: Target resource tier
          enum:
            - small
            - medium
            - large
            - xlarge
          example: medium
          type: string
      required:
        - size
      type: object
    Run:
      description: Canonical MIOSA run record.
      properties:
        command:
          nullable: true
          type: string
        exit_code:
          nullable: true
          type: integer
        finished_at:
          format: date-time
          nullable: true
          type: string
        id:
          format: uuid
          type: string
        inserted_at:
          format: date-time
          nullable: true
          type: string
        instruction:
          type: string
        metadata:
          additionalProperties: true
          type: object
        runner:
          enum:
            - claude-code
            - codex
            - command
            - custom
          type: string
        started_at:
          format: date-time
          nullable: true
          type: string
        status:
          enum:
            - queued
            - running
            - succeeded
            - failed
            - canceled
          type: string
        stderr:
          nullable: true
          type: string
        stdout:
          nullable: true
          type: string
        target_id:
          type: string
        target_kind:
          enum:
            - sandbox
            - computer
          type: string
        updated_at:
          format: date-time
          nullable: true
          type: string
        workspace_id:
          format: uuid
          nullable: true
          type: string
      required:
        - id
        - target_kind
        - target_id
        - runner
        - instruction
        - status
      type: object
    RunActivity:
      properties:
        message:
          type: string
        metadata:
          additionalProperties: true
          type: object
        timestamp:
          format: date-time
          nullable: true
          type: string
        type:
          type: string
      type: object
    RunCommandOutput:
      properties:
        exit_code:
          nullable: true
          type: integer
        stderr:
          nullable: true
          type: string
        stdout:
          nullable: true
          type: string
      type: object
    RunDiagnostic:
      properties:
        code:
          type: string
        message:
          type: string
        metadata:
          additionalProperties: true
          type: object
        severity:
          enum:
            - info
            - warning
            - error
          type: string
        stderr:
          nullable: true
          type: string
        stdout:
          nullable: true
          type: string
      type: object
    RunEvent:
      properties:
        created_at:
          format: date-time
          nullable: true
          type: string
        id:
          format: uuid
          type: string
        message:
          nullable: true
          type: string
        metadata:
          additionalProperties: true
          type: object
        run_id:
          format: uuid
          type: string
        status:
          nullable: true
          type: string
        type:
          type: string
      type: object
    RunEventsResponse:
      properties:
        data:
          items:
            $ref: "#/components/schemas/RunEvent"
          type: array
      type: object
    RunExpectedOutputs:
      properties:
        artifact_root:
          description: Compatibility alias for `output_root`.
          nullable: true
          type: string
        files:
          description: Required output files. Absolute paths are read as-is. Relative paths are resolved under `output_root`.
          items:
            oneOf:
              - type: string
              - properties:
                  downloadable:
                    default: true
                    type: boolean
                  kind:
                    nullable: true
                    type: string
                  mime_type:
                    nullable: true
                    type: string
                  name:
                    nullable: true
                    type: string
                  path:
                    type: string
                  required:
                    default: true
                    type: boolean
                required:
                  - path
                type: object
          type: array
        output_root:
          description: Absolute runtime directory used as the base for relative file paths. Defaults to `/workspace/output`.
          nullable: true
          type: string
        root:
          description: Compatibility alias for `output_root`.
          nullable: true
          type: string
      type: object
    RunFile:
      properties:
        download_url:
          description: Authenticated MIOSA API download path.
          nullable: true
          type: string
        id:
          format: uuid
          type: string
        kind:
          nullable: true
          type: string
        mime_type:
          nullable: true
          type: string
        name:
          nullable: true
          type: string
        path:
          type: string
        run_id:
          format: uuid
          type: string
        size_bytes:
          nullable: true
          type: integer
        status:
          type: string
      required:
        - id
        - run_id
        - path
        - status
      type: object
    RunFilesResponse:
      properties:
        data:
          items:
            $ref: "#/components/schemas/RunFile"
          type: array
      type: object
    RunListResponse:
      properties:
        data:
          items:
            $ref: "#/components/schemas/Run"
          type: array
      type: object
    RunMessage:
      properties:
        content:
          type: string
        created_at:
          format: date-time
          nullable: true
          type: string
        role:
          type: string
      required:
        - role
        - content
      type: object
    RunOutputs:
      properties:
        activity:
          items:
            $ref: "#/components/schemas/RunActivity"
          type: array
        command_output:
          $ref: "#/components/schemas/RunCommandOutput"
        diagnostics:
          items:
            $ref: "#/components/schemas/RunDiagnostic"
          type: array
        downloads:
          items:
            additionalProperties: true
            type: object
          type: array
        events:
          items:
            $ref: "#/components/schemas/RunEvent"
          type: array
        files:
          items:
            $ref: "#/components/schemas/RunFile"
          type: array
        messages:
          items:
            $ref: "#/components/schemas/RunMessage"
          type: array
        previews:
          items:
            $ref: "#/components/schemas/RunPreview"
          type: array
        result:
          additionalProperties: true
          type: object
      type: object
    RunPreview:
      properties:
        file_id:
          nullable: true
          type: string
        id:
          type: string
        path:
          nullable: true
          type: string
        type:
          type: string
        url:
          nullable: true
          type: string
      type: object
    RunResponse:
      properties:
        data:
          $ref: "#/components/schemas/Run"
      type: object
    RuntimeInstance:
      description: "Production runtime VM status for dynamic releases. Static deployments usually have no runtime instances because the edge serves their files directly from release storage.\n"
      properties:
        cpu_limit_millicores:
          nullable: true
          type: integer
        created_at:
          format: date-time
          type: string
        deployment_id:
          format: uuid
          type: string
        desired_state:
          enum:
            - running
            - stopped
          type: string
        error_message:
          nullable: true
          type: string
        external_project_id:
          nullable: true
          type: string
        external_user_id:
          nullable: true
          type: string
        external_workspace_id:
          nullable: true
          type: string
        health_check_path:
          nullable: true
          type: string
        host_id:
          description: Internal host identifier; may be omitted from future public SDKs.
          nullable: true
          type: string
        id:
          format: uuid
          type: string
        ip_address:
          nullable: true
          type: string
        last_health_check_at:
          format: date-time
          nullable: true
          type: string
        last_heartbeat_at:
          format: date-time
          nullable: true
          type: string
        memory_limit_mb:
          nullable: true
          type: integer
        metadata:
          additionalProperties: true
          description: Public runtime metadata. OSA tokens are never returned.
          type: object
        node_id:
          nullable: true
          type: string
        port:
          nullable: true
          type: integer
        release_id:
          format: uuid
          type: string
        restart_count:
          type: integer
        runtime_log_path:
          nullable: true
          type: string
        started_at:
          format: date-time
          nullable: true
          type: string
        state:
          enum:
            - provisioning
            - starting
            - healthy
            - unhealthy
            - error
            - stopped
            - destroyed
          type: string
        tenant_id:
          format: uuid
          type: string
        updated_at:
          format: date-time
          type: string
        vm_id:
          nullable: true
          type: string
      type: object
    RuntimeLogsResponse:
      properties:
        data:
          properties:
            deployment_id:
              format: uuid
              type: string
            log_path:
              type: string
            logs:
              type: string
            runtime_instance_id:
              format: uuid
              type: string
          type: object
        logs:
          type: string
      type: object
    Sandbox:
      description: "A persistent-by-default Firecracker microVM for AI-agent tool execution. Pause preserves the workspace for a later session. Destroy permanently releases the workspace.\n"
      properties:
        always_on:
          default: false
          description: Disable timeout and idle timeout enforcement until an explicit lifecycle action.
          type: boolean
        boot_ms:
          description: Runtime boot time in milliseconds
          example: 32
          nullable: true
          type: integer
        boot_path:
          description: Boot mechanism used by the runtime
          example: snapshot
          nullable: true
          type: string
        cpu_count:
          default: 2
          description: Number of vCPUs allocated. The default small contract uses 2.
          maximum: 16
          minimum: 1
          type: integer
        created_at:
          example: 2026-04-25T10:00:00.000000Z
          format: date-time
          type: string
        destroyed_at:
          description: When the VM was destroyed
          format: date-time
          nullable: true
          type: string
        disk_size_mb:
          description: Root disk size in megabytes
          example: 10240
          maximum: 81920
          minimum: 10240
          type: integer
        envd_ready_ms:
          description: Time to envd readiness in milliseconds when measured
          nullable: true
          type: integer
        external_project_id:
          description: Customer-supplied project/application identifier for attribution only.
          example: landing-page-789
          nullable: true
          type: string
        external_user_id:
          description: Customer-supplied end-user identifier for attribution only.
          example: dr-smith-456
          nullable: true
          type: string
        external_workspace_id:
          description: Customer-supplied workspace/team/account identifier for attribution only.
          example: dental-office-123
          nullable: true
          type: string
        id:
          description: Unique sandbox ID
          example: 3fa85f64-5717-4562-b3fc-2c963f66afa6
          format: uuid
          type: string
        idle_timeout_sec:
          default: 0
          description: Seconds without activity before auto-stop. Zero disables idle timeout.
          minimum: 0
          type: integer
        image_id:
          description: Resolved rootfs image ID
          example: debian-12-sandbox-v8
          nullable: true
          type: string
        memory_mb:
          default: 4096
          description: RAM in megabytes. The default small contract uses 4096.
          maximum: 32768
          minimum: 256
          type: integer
        metadata:
          additionalProperties: true
          description: Arbitrary caller metadata stored as JSON
          example:
            agent_run_id: run_01HX2K3M
            idempotency_key: 01HX2K3M4N5P6Q7R8S9T0UVWXY
          type: object
        name:
          description: Optional tenant-scoped sandbox name.
          type:
            - string
            - "null"
        owner_id:
          description: Creating user ID
          format: uuid
          type: string
        persistent:
          default: true
          description: Whether stop and timeout preserve filesystem state for resume.
          type: boolean
        preview_url:
          description: Tenant-aware base preview URL. Use `/sandboxes/{id}/expose` for a specific port.
          example: https://3fa85f64.sandbox.miosa.app
          nullable: true
          type: string
        ready:
          description: Whether the sandbox is ready for exec/file/terminal operations
          example: true
          type: boolean
        ready_at:
          description: When readiness was reached
          format: date-time
          nullable: true
          type: string
        resource_contract:
          $ref: "#/components/schemas/SandboxResourceContract"
        size:
          description: Canonical named size resolved before admission.
          enum:
            - xs
            - small
            - medium
            - large
            - xl
          example: small
          type: string
        slug:
          description: Tenant-scoped preview slug.
          type: string
        started_at:
          description: When the VM entered `running` state
          format: date-time
          nullable: true
          type: string
        state:
          description: Current lifecycle state
          enum:
            - provisioning
            - running
            - paused
            - destroyed
            - error
          example: running
          type: string
        template_id:
          description: Boot template alias or image ID (for example `miosa-sandbox` or `debian-12-sandbox-v8`)
          example: miosa-sandbox
          type: string
        tenant_id:
          description: Owning tenant ID
          format: uuid
          type: string
        timeout_remaining_ms:
          description: Remaining active-session time. Null before start or when always-on.
          minimum: 0
          type:
            - integer
            - "null"
        timeout_sec:
          default: 3600
          description: Maximum active session duration before lifecycle policy stops or destroys the sandbox.
          maximum: 86400
          minimum: 1
          type: integer
        total_runtime_sec:
          description: "Total seconds the sandbox was in `running` state. Written on destroy. Null until the sandbox is destroyed.\n"
          example: 47
          nullable: true
          type: integer
      required:
        - id
        - tenant_id
        - owner_id
        - template_id
        - state
        - size
        - resource_contract
        - cpu_count
        - memory_mb
        - disk_size_mb
        - persistent
        - timeout_sec
        - idle_timeout_sec
        - created_at
      type: object
    SandboxDeployRequest:
      properties:
        deployment_id:
          description: Existing deployment to publish a new version to.
          format: uuid
          type: string
        domain:
          description: Optional custom FQDN to attach after publish.
          nullable: true
          type: string
        entrypoint:
          example: index.html
          nullable: true
          type: string
        name:
          description: Required when publishing to a new deployment.
          example: clinic-landing-page
          type: string
        output_path:
          default: /workspace
          description: Directory inside the sandbox to publish as the static artifact.
          type: string
      type: object
    SandboxDeployResponse:
      properties:
        data:
          properties:
            custom_domain:
              $ref: "#/components/schemas/CustomDomain"
            deployment:
              $ref: "#/components/schemas/Deployment"
            promoted:
              type: boolean
            release:
              $ref: "#/components/schemas/DeploymentRelease"
            url:
              format: uri
              type: string
            version:
              $ref: "#/components/schemas/DeploymentVersion"
          type: object
        deployment_id:
          format: uuid
          type: string
        release_id:
          format: uuid
          type: string
        state:
          type: string
        url:
          format: uri
          type: string
        version_id:
          format: uuid
          type: string
      type: object
    SandboxExecRequest:
      properties:
        command:
          description: Shell command to run inside the VM
          example: python3 -c "print(1+1)"
          type: string
        timeout:
          default: 30
          description: Max seconds to wait for the command to complete.
          maximum: 300
          minimum: 1
          type: integer
      required:
        - command
      type: object
    SandboxExecResult:
      properties:
        exit_code:
          description: Process exit code (0 = success)
          type: integer
        sandbox_id:
          format: uuid
          type: string
        stderr:
          description: Standard error from the command
          type: string
        stdout:
          description: Standard output from the command
          type: string
      type: object
    SandboxLifecycleState:
      additionalProperties: false
      properties:
        id:
          format: uuid
          type: string
        state:
          enum:
            - paused
            - running
          type: string
      required:
        - id
        - state
      type: object
    SandboxPreview:
      description: Public URL that proxies a sandbox port for live preview.
      properties:
        created_at:
          format: date-time
          type: string
        expires_at:
          format: date-time
          nullable: true
          type: string
        id:
          format: uuid
          type: string
        metadata:
          additionalProperties: true
          type: object
        name:
          nullable: true
          type: string
        port:
          example: 5173
          type: integer
        sandbox_id:
          format: uuid
          type: string
        tenant_id:
          format: uuid
          type: string
        updated_at:
          format: date-time
          type: string
        url:
          example: https://5173-3fa85f64.sandbox.miosa.app
          format: uri
          type: string
        visibility:
          enum:
            - private
            - public
          example: private
          type: string
      type: object
    SandboxResourceContract:
      additionalProperties: false
      properties:
        disk_size_mb:
          maximum: 81920
          minimum: 10240
          type: integer
        id:
          example: sandbox/small@v1
          pattern: ^sandbox/(xs|small|medium|large|xl)@v1$
          type: string
        memory_mb:
          maximum: 32768
          minimum: 2048
          type: integer
        product:
          const: sandbox
          type: string
        size:
          enum:
            - xs
            - small
            - medium
            - large
            - xl
          type: string
        vcpus:
          maximum: 16
          minimum: 1
          type: integer
        version:
          const: v1
          type: string
      required:
        - id
        - product
        - size
        - version
        - vcpus
        - memory_mb
        - disk_size_mb
      type: object
    SandboxSpendSummary:
      additionalProperties: false
      properties:
        accounted_cents:
          description: Sum of settled spend and active durable reservations.
          minimum: 0
          type: integer
        alert_thresholds:
          items:
            maximum: 100
            minimum: 1
            type: integer
          maxItems: 10
          minItems: 1
          type: array
          uniqueItems: true
        cap_cents:
          minimum: 1
          type:
            - integer
            - "null"
        mode:
          enum:
            - limited
            - unlimited
          type: string
        period_end:
          format: date-time
          type: string
        period_start:
          format: date-time
          type: string
        remaining_cents:
          minimum: 0
          type:
            - integer
            - "null"
        reserved_cents:
          description: Durable admission holds not yet converted into settled runtime spend.
          minimum: 0
          type: integer
        spent_cents:
          minimum: 0
          type: integer
        status:
          enum:
            - unlimited
            - ok
            - warning
            - exhausted
          type: string
        tenant_id:
          format: uuid
          type: string
      required:
        - tenant_id
        - period_start
        - period_end
        - cap_cents
        - mode
        - spent_cents
        - reserved_cents
        - accounted_cents
        - remaining_cents
        - status
        - alert_thresholds
      type: object
    SandboxUploadRequest:
      properties:
        content:
          description: "Base64-encoded file content. Alternatively, POST `multipart/form-data` with a `file` field.\n"
          example: cHJpbnQoImhlbGxvIik=
          format: byte
          type: string
        path:
          description: Absolute destination path inside the VM
          example: /workspace/hello.py
          type: string
      required:
        - path
      type: object
    SandboxUsage:
      additionalProperties: false
      properties:
        active_cpu_ms:
          minimum: 0
          type:
            - integer
            - "null"
        creation_count:
          description: Canonical creation count derived from the linked durable sandbox admission.
          minimum: 0
          type: integer
        estimated_cost_cents:
          minimum: 0
          type: integer
        measurement_status:
          properties:
            active_cpu:
              type: string
            network:
              type: string
            provisioned_resources:
              const: measured
              type: string
          required:
            - active_cpu
            - network
            - provisioned_resources
          type: object
        network_egress_bytes:
          minimum: 0
          type:
            - integer
            - "null"
        network_ingress_bytes:
          minimum: 0
          type:
            - integer
            - "null"
        provisioned_memory_mb_ms:
          description: Contract-provisioned memory multiplied by canonical lifecycle milliseconds.
          minimum: 0
          type:
            - integer
            - "null"
        provisioned_vcpu_ms:
          minimum: 0
          type: integer
        runtime_sec:
          minimum: 0
          type: integer
        sandbox_id:
          format: uuid
          type: string
        state:
          type: string
        timeout_remaining_ms:
          minimum: 0
          type:
            - integer
            - "null"
        timeout_sec:
          maximum: 86400
          minimum: 1
          type: integer
      required:
        - sandbox_id
        - state
        - runtime_sec
        - provisioned_vcpu_ms
        - provisioned_memory_mb_ms
        - creation_count
        - active_cpu_ms
        - network_ingress_bytes
        - network_egress_bytes
        - measurement_status
        - estimated_cost_cents
        - timeout_sec
        - timeout_remaining_ms
      type: object
    Service:
      description: A long-running managed process inside a computer
      properties:
        command:
          description: Shell command used to start the service
          example: nginx -g "daemon off;"
          type: string
        created_at:
          example: 2026-04-11T14:30:00Z
          format: date-time
          type: string
        display_name:
          description: Human-readable label
          example: Nginx Web Server
          type:
            - string
            - "null"
        env:
          additionalProperties:
            type: string
          description: Environment variables injected into the process
          type: object
        error_message:
          description: Last error message when status is `error`
          type:
            - string
            - "null"
        name:
          description: Service identifier (unique per computer)
          example: nginx
          type: string
        pid:
          description: OS process ID when running
          example: 1234
          type:
            - integer
            - "null"
        port:
          description: Primary TCP port the service listens on (informational)
          example: 8080
          type:
            - integer
            - "null"
        restart_policy:
          default: on-failure
          description: What to do when the process exits unexpectedly
          enum:
            - never
            - on-failure
            - always
          example: on-failure
          type: string
        status:
          description: Current process state
          enum:
            - starting
            - running
            - stopped
            - error
            - restarting
          example: running
          type: string
        updated_at:
          example: 2026-04-11T15:00:00Z
          format: date-time
          type: string
        working_dir:
          description: Working directory for the process
          example: /home/user/app
          type:
            - string
            - "null"
      required:
        - name
        - status
        - created_at
      type: object
    ServiceCreateRequest:
      description: Request body for registering a new managed service
      properties:
        command:
          description: Shell command to start the service
          example: python worker.py --concurrency 4
          type: string
        display_name:
          description: Human-readable label
          example: Background Worker
          maxLength: 100
          type: string
        env:
          additionalProperties:
            type: string
          description: Environment variables injected into the service process
          type: object
        name:
          description: "Service identifier — lowercase alphanumeric and hyphens only. Must be unique within the computer.\n"
          example: my-worker
          maxLength: 64
          minLength: 1
          pattern: ^[a-z0-9]([a-z0-9\-]*[a-z0-9])?$
          type: string
        port:
          description: Primary TCP port the service listens on (informational only)
          example: 8080
          maximum: 65535
          minimum: 1
          type: integer
        restart_policy:
          default: on-failure
          description: Restart behaviour when the process exits unexpectedly
          enum:
            - never
            - on-failure
            - always
          type: string
        working_dir:
          description: Absolute path to use as the working directory
          example: /home/user/app
          type: string
      required:
        - name
        - command
      type: object
    ServiceListResponse:
      properties:
        services:
          items:
            $ref: "#/components/schemas/Service"
          type: array
      required:
        - services
      type: object
    ServiceLogEvent:
      description: "A single log line emitted on the service log SSE stream. The `event:` field is always `log`. The stream closes with a final `event: done` when the service stops (if `follow` is false or the service exits).\n"
      properties:
        line:
          description: Raw log line text (newline stripped)
          example: Server started on :8080
          type: string
        stream:
          description: Which output stream this line came from
          enum:
            - stdout
            - stderr
          example: stdout
          type: string
        timestamp:
          description: When this log line was produced
          example: 2026-04-11T14:30:00Z
          format: date-time
          type: string
      type: object
    Snapshot:
      description: A point-in-time disk snapshot of a computer
      properties:
        completed_at:
          description: When snapshot creation finished
          example: 2026-04-11T14:32:10Z
          format: date-time
          type:
            - string
            - "null"
        computer_id:
          description: Computer this snapshot was taken from
          example: 3fa85f64-5717-4562-b3fc-2c963f66afa6
          format: uuid
          type: string
        created_at:
          example: 2026-04-11T14:30:00Z
          format: date-time
          type: string
        description:
          description: Optional notes about this snapshot
          type:
            - string
            - "null"
        error_message:
          description: Error detail when status is `error`
          type:
            - string
            - "null"
        id:
          description: Unique snapshot identifier
          example: 2c3d4e5f-6a7b-8901-bcde-f12345678901
          format: uuid
          type: string
        metadata:
          additionalProperties: true
          type: object
        name:
          description: Human-readable snapshot name
          example: Before dependency upgrade
          type: string
        size_bytes:
          description: Compressed snapshot size on disk
          example: 2147483648
          type:
            - integer
            - "null"
        status:
          description: Snapshot lifecycle state
          enum:
            - pending
            - creating
            - available
            - restoring
            - error
            - deleted
          example: available
          type: string
      required:
        - id
        - computer_id
        - name
        - status
        - created_at
      type: object
    SnapshotCreateRequest:
      description: Request body for creating a snapshot
      properties:
        description:
          description: Optional notes about this snapshot
          maxLength: 500
          type: string
        name:
          description: Human-readable snapshot name
          example: Before dependency upgrade
          maxLength: 100
          minLength: 1
          type: string
      required:
        - name
      type: object
    SnapshotListResponse:
      properties:
        cursor:
          type:
            - string
            - "null"
        snapshots:
          items:
            $ref: "#/components/schemas/Snapshot"
          type: array
        total:
          example: 4
          type: integer
      required:
        - snapshots
        - total
      type: object
    StorageBucket:
      properties:
        created_at:
          format: date-time
          type: string
        id:
          format: uuid
          type: string
        metadata:
          additionalProperties: true
          type: object
        name:
          type: string
        object_count:
          format: int64
          type: integer
        quota_bytes:
          format: int64
          type: integer
        region:
          type: string
        tenant_id:
          format: uuid
          type: string
        updated_at:
          format: date-time
          type: string
        used_bytes:
          format: int64
          type: integer
        visibility:
          enum:
            - private
            - public
          type: string
      required:
        - id
        - tenant_id
        - name
        - region
        - visibility
        - quota_bytes
        - used_bytes
        - object_count
      type: object
    StorageObjectList:
      properties:
        keys:
          items:
            type: string
          type: array
        next_marker:
          nullable: true
          type: string
        truncated:
          type: boolean
      type: object
    StreamToken:
      properties:
        expires_at:
          description: Unix timestamp when the token expires (1 hour from issuance)
          example: 1712703600
          type: integer
        token:
          description: Short-lived auth token for the desktop stream WebSocket
          example: tok_aBcDeFgHiJkLmNoPqRsT
          type: string
      required:
        - token
        - expires_at
      type: object
    Tenant:
      description: Org (tenant) summary object.
      properties:
        id:
          format: uuid
          type: string
        inserted_at:
          format: date-time
          type: string
        name:
          type: string
        owner_user_id:
          format: uuid
          nullable: true
          type: string
        plan_id:
          nullable: true
          type: string
        plan_name:
          nullable: true
          type: string
        settings:
          additionalProperties: true
          type: object
        slug:
          type: string
        updated_at:
          format: date-time
          type: string
      required:
        - id
        - name
        - slug
      type: object
    TerminalSession:
      additionalProperties: true
      properties:
        computer_id:
          format: uuid
          type: string
        expires_at:
          description: Unix timestamp when `stream_auth` expires (1 hour from issuance)
          example: 1712703600
          type: integer
        session_id:
          description: PTY session identifier; pass to `POST /computers/{id}/pty/{session_id}/resize`
          example: pty_7a9c2e4f
          type: string
        stream_auth:
          description: Short-lived auth token embedded in `ws_url`; also returned separately so clients can re-sign custom URLs
          example: tok_aBcDeFgHiJkLmNoPqRsT
          type: string
        ws_url:
          description: Authenticated WebSocket URL for bidirectional PTY streaming
          example: wss://my-computer.miosa.ai/ws/terminal/3fa85f64-.../pty_7a9c2e4f?auth=tok_...
          type: string
      required:
        - session_id
        - computer_id
        - ws_url
        - stream_auth
        - expires_at
      type: object
    UpdateSandboxSpendSettingsRequest:
      additionalProperties: false
      minProperties: 1
      properties:
        alert_thresholds:
          items:
            maximum: 100
            minimum: 1
            type: integer
          maxItems: 10
          minItems: 1
          type: array
          uniqueItems: true
        cap_cents:
          description: Required for limited mode and forbidden for unlimited mode.
          minimum: 1
          type: integer
        mode:
          enum:
            - limited
            - unlimited
          type: string
      type: object
    ValidationErrorResponse:
      properties:
        error:
          properties:
            code:
              example: VALIDATION_ERROR
              type: string
            details:
              items:
                properties:
                  field:
                    example: name
                    type: string
                  reason:
                    example: must be between 1 and 100 characters
                    type: string
                required:
                  - field
                  - reason
                type: object
              type: array
            message:
              example: Request body failed validation
              type: string
            type:
              example: https://docs.miosa.ai/errors/validation
              format: uri
              type: string
          required:
            - code
            - message
          type: object
      required:
        - error
      type: object
    VncCredentials:
      properties:
        computer_id:
          format: uuid
          type: string
        expires_at:
          description: Unix timestamp when the token expires (1 hour from issuance)
          example: 1712703600
          type: integer
        slug:
          example: my-computer
          type: string
        token:
          description: Short-lived auth token for the VNC WebSocket
          example: tok_aBcDeFgHiJkLmNoPqRsT
          type: string
        vnc_url:
          description: URL to the KasmVNC web desktop client
          example: https://my-computer.miosa.ai/desktop/index.html
          format: uri
          type: string
        ws_url:
          description: Authenticated WebSocket URL for direct VNC connection
          example: wss://my-computer.miosa.ai/ws/vnc/3fa85f64-...
          type: string
      required:
        - vnc_url
        - ws_url
        - token
        - expires_at
        - computer_id
      type: object
    Volume:
      properties:
        backend:
          description: Storage backend
          enum:
            - s3
            - local
          type: string
        config:
          additionalProperties: true
          description: "Backend-specific connection info. For `s3` contains `bucket`, `prefix`, `region` (credentials redacted on read). For `local` contains `host_path`.\n"
          type: object
        created_at:
          format: date-time
          type: string
        id:
          format: uuid
          type: string
        metadata:
          additionalProperties: true
          type: object
        name:
          type: string
        size_bytes:
          type: integer
        status:
          enum:
            - available
            - in_use
            - error
            - deleting
          type: string
        updated_at:
          format: date-time
          type: string
      required:
        - id
        - name
        - size_bytes
        - backend
        - status
        - created_at
      type: object
    VolumeAttachment:
      properties:
        computer_id:
          format: uuid
          type: string
        created_at:
          format: date-time
          type: string
        id:
          format: uuid
          type: string
        mount_path:
          description: Absolute POSIX path inside the VM
          example: /mnt/shared
          type: string
        read_only:
          default: false
          type: boolean
        status:
          enum:
            - attaching
            - attached
            - detaching
            - detached
            - error
          type: string
        updated_at:
          format: date-time
          type: string
        volume_id:
          format: uuid
          type: string
      required:
        - id
        - volume_id
        - computer_id
        - mount_path
        - status
      type: object
    WindowInfo:
      description: A desktop window
      properties:
        app:
          description: Application name
          example: code
          type:
            - string
            - "null"
        height:
          type:
            - integer
            - "null"
        id:
          description: Window ID (platform-specific)
          example: 65011716
          type: string
        is_active:
          description: Whether this is the currently focused window
          example: true
          type: boolean
        title:
          description: Window title bar text
          example: Visual Studio Code
          type: string
        width:
          type:
            - integer
            - "null"
        x:
          description: Window X position in pixels
          type:
            - integer
            - "null"
        y:
          description: Window Y position in pixels
          type:
            - integer
            - "null"
      required:
        - id
        - title
      type: object
    Workspace:
      description: A logical namespace that groups computers and shared resources
      properties:
        computer_count:
          description: Number of computers in this workspace
          example: 3
          type: integer
        created_at:
          example: 2026-04-11T14:30:00Z
          format: date-time
          type: string
        description:
          description: Optional description of the workspace's purpose
          example: Production workloads for the billing service
          type:
            - string
            - "null"
        id:
          description: Unique workspace identifier
          example: 1b2c3d4e-5f6a-7890-abcd-ef1234567890
          format: uuid
          type: string
        metadata:
          additionalProperties: true
          description: Arbitrary key-value metadata
          type: object
        name:
          description: Human-readable display name
          example: Production Environment
          type: string
        slug:
          description: URL-safe identifier
          example: production-environment
          type: string
        tenant_id:
          description: Tenant that owns this workspace
          format: uuid
          type: string
        updated_at:
          example: 2026-04-11T15:00:00Z
          format: date-time
          type: string
      required:
        - id
        - name
        - slug
        - created_at
      type: object
    WorkspaceCreateRequest:
      description: Request body for creating a workspace
      properties:
        description:
          description: Optional description
          example: Hosts all production compute
          maxLength: 500
          type: string
        metadata:
          additionalProperties: true
          description: Arbitrary key-value metadata
          type: object
        name:
          description: Human-readable display name
          example: Production Environment
          maxLength: 100
          minLength: 1
          type: string
      required:
        - name
      type: object
    WorkspaceInvite:
      description: A pending workspace invite row.
      properties:
        accepted_at:
          format: date-time
          nullable: true
          type: string
        email:
          format: email
          type: string
        expires_at:
          format: date-time
          type: string
        id:
          format: uuid
          type: string
        inserted_at:
          format: date-time
          type: string
        invited_by:
          format: uuid
          nullable: true
          type: string
        role:
          enum:
            - owner
            - admin
            - member
            - viewer
          type: string
        tenant_id:
          format: uuid
          type: string
        workspace_id:
          format: uuid
          type: string
      required:
        - id
        - workspace_id
        - tenant_id
        - email
        - role
        - expires_at
      type: object
    WorkspaceInvitePreview:
      description: Public preview of a workspace invite (no auth required).
      properties:
        accepted:
          type: boolean
        email:
          format: email
          type: string
        expired:
          type: boolean
        expires_at:
          format: date-time
          type: string
        revoked:
          type: boolean
        role:
          enum:
            - owner
            - admin
            - member
            - viewer
          type: string
        tenant_name:
          type: string
        workspace_name:
          type: string
      required:
        - workspace_name
        - tenant_name
        - role
        - email
        - expires_at
        - expired
        - revoked
        - accepted
      type: object
    WorkspaceListResponse:
      properties:
        cursor:
          description: Cursor for the next page; absent when there are no more results
          type:
            - string
            - "null"
        total:
          description: Total number of workspaces for this tenant
          example: 2
          type: integer
        workspaces:
          items:
            $ref: "#/components/schemas/Workspace"
          type: array
      required:
        - workspaces
        - total
      type: object
    WorkspaceMember:
      description: "A workspace member row returned by the list endpoint. Includes denormalised user fields for display.\n"
      properties:
        added_by:
          format: uuid
          nullable: true
          type: string
        avatar_url:
          nullable: true
          type: string
        email:
          format: email
          nullable: true
          type: string
        joined_at:
          format: date-time
          nullable: true
          type: string
        name:
          nullable: true
          type: string
        role:
          enum:
            - owner
            - admin
            - member
            - viewer
          type: string
        user_id:
          format: uuid
          type: string
      required:
        - user_id
        - role
      type: object
    WorkspaceMemberRecord:
      description: "The raw workspace_members schema row returned after add/update operations.\n"
      properties:
        added_by:
          format: uuid
          nullable: true
          type: string
        joined_at:
          format: date-time
          nullable: true
          type: string
        role:
          enum:
            - owner
            - admin
            - member
            - viewer
          type: string
        user_id:
          format: uuid
          type: string
        workspace_id:
          format: uuid
          type: string
      required:
        - user_id
        - workspace_id
        - role
      type: object
    WorkspaceUpdateRequest:
      description: Request body for updating a workspace (all fields optional)
      properties:
        description:
          maxLength: 500
          type:
            - string
            - "null"
        metadata:
          additionalProperties: true
          type: object
        name:
          example: Renamed Workspace
          maxLength: 100
          minLength: 1
          type: string
      type: object
  securitySchemes:
    BearerAuth:
      bearerFormat: JWT or msk_* API key
      description: "Use `Bearer <token>` where token is either a JWT (from `/auth/login`) or a MIOSA API key with the `msk_` prefix. The key's role is encoded in the second segment: `msk_u_*` (user), `msk_a_*` (admin), `msk_p_*` (platform). Admin and platform keys also grant access to the `/api/v1/admin/*` endpoints.\n"
      scheme: bearer
      type: http
info:
  contact:
    email: api@miosa.ai
    name: MIOSA Developer Support
    url: https://docs.miosa.ai
  description: "The MIOSA Developer API gives you programmatic control over cloud computers —\ncreate, start, stop, and interact with desktop environments, execute code,\nmanage files, and run AI computer-use agents.\n\n**Base URL:** `https://api.miosa.ai/api/v1`\n\n## Authentication\n\nEvery endpoint accepts a single `Authorization: Bearer <token>` header. The\ntoken is either a MIOSA API key or a standard JWT from `POST /auth/login`.\n\nMIOSA API keys all use the `msk_` prefix. The second segment encodes the\nkey's role, and the `purpose` field (set at creation) selects which\nbackend the key can call:\n\n| Prefix       | Role     | Capabilities                                          |\n|--------------|----------|-------------------------------------------------------|\n| `msk_u_...`  | user     | Compute, desktop, files, CUA, OSA, credits            |\n| `msk_a_...`  | admin    | Everything user-keys can do **+** `/api/v1/admin/*`   |\n| `msk_p_...`  | platform | Tenant-wide automation issued by the MIOSA platform   |\n\nPurpose is orthogonal to role:\n\n- `purpose: api` — authenticate against the compute/desktop/files API\n- `purpose: optimal` — authenticate against the AI/LLM proxy\n\nUse one key for both purposes by creating two keys — they share the same\n`msk_` family so SDKs do not need separate configuration.\n\nAPI keys are created via `POST /api-keys` or the dashboard. The raw key\nis returned **only at creation** and cannot be retrieved again.\n\n## Rate Limits\n\nThe default rate limit is **300 requests per minute** per API key. Auth\nendpoints are limited to 20 req/min. Rate limit status is returned in every\nresponse via standard headers:\n\n```\nX-RateLimit-Limit: 300\nX-RateLimit-Remaining: 291\nX-RateLimit-Reset: 1712700060\n```\n\nWhen the limit is exceeded the API returns `429 Too Many Requests` with a\n`Retry-After` header.\n\n## Errors\n\nAll errors use a consistent envelope:\n\n```json\n{\n  \"error\": {\n    \"code\": \"NOT_FOUND\",\n    \"message\": \"Computer with id abc-123 not found\",\n    \"type\": \"https://docs.miosa.ai/errors/not-found\"\n  }\n}\n```\n\nValidation errors include a `details` array:\n\n```json\n{\n  \"error\": {\n    \"code\": \"VALIDATION_ERROR\",\n    \"message\": \"Request body failed validation\",\n    \"type\": \"https://docs.miosa.ai/errors/validation\",\n    \"details\": [\n      { \"field\": \"name\", \"reason\": \"must be between 1 and 100 characters\" }\n    ]\n  }\n}\n```\n\n## Computer Sizes\n\n| Size | vCPUs | RAM | Disk |\n|------|-------|-----|------|\n| `small` | 1 | 2 GB | 10 GB |\n| `medium` | 2 | 4 GB | 20 GB |\n| `large` | 4 | 8 GB | 40 GB |\n| `xlarge` | 8 | 16 GB | 80 GB |\n\n## Computer Status\n\nComputers move through the following states:\n\n`creating` → `provisioning` → `running` → `stopped` | `paused` | `error`\n\nDesktop actions, exec, and file operations require the computer to be in\n`running` status.\n"
  license:
    name: Proprietary
    url: https://miosa.ai/terms
  title: MIOSA Developer API
  version: 1.0.0
openapi: 3.1.0
paths:
  /account/billing/invoices:
    get:
      operationId: getAccountBillingInvoices
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: AccountBilling — Invoices
      tags:
        - AccountBilling
  /account/billing/overview:
    get:
      operationId: getAccountBillingOverview
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: AccountBilling — Overview
      tags:
        - AccountBilling
  /account/billing/portal-session:
    post:
      operationId: postAccountBillingPortalSession
      responses:
        "200":
          description: Success
        "201":
          description: Created
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: AccountBilling — Portal Session
      tags:
        - AccountBilling
  /account/billing/timeseries:
    get:
      operationId: getAccountBillingTimeseries
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: AccountBilling — Timeseries
      tags:
        - AccountBilling
  /account/billing/top-consumers:
    get:
      operationId: getAccountBillingTopConsumers
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: AccountBilling — Top Consumers
      tags:
        - AccountBilling
  /account/billing/transactions:
    get:
      operationId: getAccountBillingTransactions
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: AccountBilling — Transactions
      tags:
        - AccountBilling
  /account/billing/upgrade:
    post:
      operationId: postAccountBillingUpgrade
      responses:
        "200":
          description: Success
        "201":
          description: Created
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: AccountBilling — Upgrade
      tags:
        - AccountBilling
  /account/impersonation:
    get:
      operationId: getAccountImpersonation
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: AccountImpersonation — Show
      tags:
        - AccountImpersonation
  /account/impersonation/end:
    post:
      operationId: postAccountImpersonationEnd
      responses:
        "200":
          description: Success
        "201":
          description: Created
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: AccountImpersonation — End All
      tags:
        - AccountImpersonation
  /account/onboarding:
    get:
      operationId: getAccountOnboarding
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: AccountOnboarding — Show
      tags:
        - AccountOnboarding
  /account/onboarding/events:
    post:
      operationId: postAccountOnboardingEvents
      responses:
        "200":
          description: Success
        "201":
          description: Created
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: AccountOnboarding — Track
      tags:
        - AccountOnboarding
  /account/onboarding/funnel:
    get:
      operationId: getAccountOnboardingFunnel
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: OnboardingProgress — Funnel
      tags:
        - OnboardingProgress
  /account/onboarding/progress:
    get:
      operationId: getAccountOnboardingProgress
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: OnboardingProgress — Show
      tags:
        - OnboardingProgress
    patch:
      operationId: patchAccountOnboardingProgress
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: OnboardingProgress — Update
      tags:
        - OnboardingProgress
  /account/onboarding/reset:
    post:
      operationId: postAccountOnboardingReset
      responses:
        "200":
          description: Success
        "201":
          description: Created
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: AccountOnboarding — Reset
      tags:
        - AccountOnboarding
  /account/onboarding/skip:
    post:
      operationId: postAccountOnboardingSkip
      responses:
        "200":
          description: Success
        "201":
          description: Created
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: AccountOnboarding — Skip
      tags:
        - AccountOnboarding
  /account/onboarding/start:
    post:
      operationId: postAccountOnboardingStart
      responses:
        "200":
          description: Success
        "201":
          description: Created
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: AccountOnboarding — Start
      tags:
        - AccountOnboarding
  /account/onboarding/step/{id}/complete:
    post:
      operationId: postAccountOnboardingStepIdComplete
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "201":
          description: Created
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: AccountOnboarding — Complete Step
      tags:
        - AccountOnboarding
  /account/onboarding/tour/complete:
    post:
      operationId: postAccountOnboardingTourComplete
      responses:
        "200":
          description: Success
        "201":
          description: Created
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: OnboardingProgress — Complete Tour
      tags:
        - OnboardingProgress
  /account/shared-with-me:
    get:
      operationId: getAccountSharedWithMe
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: HostShares — Shared With Me
      tags:
        - HostShares
  /account/shared-with-me/{share_id}/accept:
    post:
      operationId: postAccountSharedWithMeShareIdAccept
      parameters:
        - in: path
          name: share_id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "201":
          description: Created
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: HostShares — Accept
      tags:
        - HostShares
  /account/shared-with-me/{share_id}/decline:
    post:
      operationId: postAccountSharedWithMeShareIdDecline
      parameters:
        - in: path
          name: share_id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "201":
          description: Created
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: HostShares — Decline
      tags:
        - HostShares
  /actions/approvals:
    get:
      operationId: getActionsApprovals
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: ActionAuthority — Approvals
      tags:
        - ActionAuthority
  /actions/approvals/{id}/approve:
    post:
      operationId: postActionsApprovalsIdApprove
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "201":
          description: Created
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: ActionAuthority — Approve
      tags:
        - ActionAuthority
  /actions/approvals/{id}/deny:
    post:
      operationId: postActionsApprovalsIdDeny
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "201":
          description: Created
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: ActionAuthority — Deny
      tags:
        - ActionAuthority
  /actions/apps/{id}/authorize:
    post:
      operationId: postActionsAppsIdAuthorize
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "201":
          description: Created
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: ActionAuthority — Authorize App
      tags:
        - ActionAuthority
  /actions/authorize:
    post:
      operationId: postActionsAuthorize
      responses:
        "200":
          description: Success
        "201":
          description: Created
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: ActionAuthority — Authorize
      tags:
        - ActionAuthority
  /actions/catalog:
    get:
      operationId: getActionsCatalog
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: ActionAuthority — Catalog
      tags:
        - ActionAuthority
  /actions/grants:
    get:
      operationId: getActionsGrants
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: ActionAuthority — Grants
      tags:
        - ActionAuthority
    post:
      operationId: postActionsGrants
      responses:
        "200":
          description: Success
        "201":
          description: Created
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: ActionAuthority — Create Grant
      tags:
        - ActionAuthority
  /actions/grants/{id}:
    delete:
      operationId: deleteActionsGrantsId
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        "204":
          description: Deleted
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: ActionAuthority — Revoke Grant
      tags:
        - ActionAuthority
  /actions/receipts:
    get:
      operationId: getActionsReceipts
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: ActionAuthority — Receipts
      tags:
        - ActionAuthority
  /admin/analytics/overview:
    get:
      operationId: adminAnalyticsOverview
      responses:
        "200":
          content:
            application/json:
              schema:
                additionalProperties: true
                type: object
          description: Overview
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
      summary: Analytics overview
      tags:
        - Admin
  /admin/analytics/timeseries:
    get:
      operationId: adminAnalyticsTimeseries
      parameters:
        - in: query
          name: metric
          required: true
          schema:
            enum:
              - signups
              - active_users
              - compute_minutes
              - ai_tokens
              - revenue
            type: string
        - in: query
          name: from
          schema:
            format: date-time
            type: string
        - in: query
          name: to
          schema:
            format: date-time
            type: string
        - in: query
          name: bucket
          schema:
            default: day
            enum:
              - hour
              - day
              - week
              - month
            type: string
      responses:
        "200":
          content:
            application/json:
              schema:
                additionalProperties: true
                type: object
          description: Timeseries data
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
      summary: Analytics timeseries
      tags:
        - Admin
  /admin/api-keys:
    get:
      operationId: adminListApiKeys
      parameters:
        - $ref: "#/components/parameters/LimitParam"
        - $ref: "#/components/parameters/CursorParam"
        - in: query
          name: tenant_id
          schema:
            format: uuid
            type: string
        - in: query
          name: status
          schema:
            enum:
              - active
              - revoked
              - expired
            type: string
      responses:
        "200":
          content:
            application/json:
              schema:
                additionalProperties: true
                type: object
          description: Keys page
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
      summary: List API keys across tenants
      tags:
        - Admin / API Keys
    post:
      description: Admin variant of `POST /api-keys`. Can mint any `key_type` including `admin` and `platform`.
      operationId: adminCreateApiKey
      requestBody:
        content:
          application/json:
            schema:
              properties:
                allowed_ips:
                  items:
                    type: string
                  type: array
                expires_at:
                  format: date-time
                  type:
                    - string
                    - "null"
                key_type:
                  enum:
                    - user
                    - admin
                    - platform
                  type: string
                name:
                  type: string
                purpose:
                  default: api
                  enum:
                    - api
                    - optimal
                  type: string
                rate_limit_rpm:
                  minimum: 1
                  type: integer
                tenant_id:
                  format: uuid
                  type: string
                user_id:
                  format: uuid
                  type: string
              required:
                - name
                - tenant_id
                - user_id
                - key_type
              type: object
        required: true
      responses:
        "201":
          content:
            application/json:
              schema:
                additionalProperties: true
                type: object
          description: Key created — raw key returned once
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "422":
          $ref: "#/components/responses/ValidationError"
      summary: Create an API key on behalf of a tenant/user
      tags:
        - Admin / API Keys
  /admin/api-keys/bulk-revoke:
    post:
      operationId: adminBulkRevokeApiKeys
      requestBody:
        content:
          application/json:
            schema:
              properties:
                key_ids:
                  items:
                    format: uuid
                    type: string
                  maxItems: 500
                  minItems: 1
                  type: array
              required:
                - key_ids
              type: object
        required: true
      responses:
        "200":
          content:
            application/json:
              schema:
                additionalProperties: true
                type: object
          description: Bulk revocation result
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
      summary: Revoke many API keys at once
      tags:
        - Admin / API Keys
  /admin/api-keys/stats:
    get:
      operationId: adminApiKeyStats
      responses:
        "200":
          content:
            application/json:
              schema:
                additionalProperties: true
                type: object
          description: Stats
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
      summary: API key usage stats
      tags:
        - Admin / API Keys
  /admin/api-keys/{id}:
    delete:
      operationId: adminDeleteApiKey
      responses:
        "200":
          content:
            application/json:
              schema:
                additionalProperties: true
                type: object
          description: Key revoked
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
      summary: Revoke an API key
      tags:
        - Admin / API Keys
    get:
      operationId: adminGetApiKey
      responses:
        "200":
          content:
            application/json:
              schema:
                additionalProperties: true
                type: object
          description: Key record
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
      summary: Get an API key record
      tags:
        - Admin / API Keys
    parameters:
      - in: path
        name: id
        required: true
        schema:
          format: uuid
          type: string
    patch:
      description: Rotate rate limits, update allowed IPs, change expiry.
      operationId: adminUpdateApiKey
      requestBody:
        content:
          application/json:
            schema:
              properties:
                allowed_ips:
                  items:
                    type: string
                  type: array
                expires_at:
                  format: date-time
                  type:
                    - string
                    - "null"
                name:
                  type: string
                rate_limit_rpm:
                  minimum: 1
                  type: integer
                status:
                  enum:
                    - active
                    - revoked
                    - expired
                  type: string
              type: object
        required: true
      responses:
        "200":
          content:
            application/json:
              schema:
                additionalProperties: true
                type: object
          description: Key updated
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
      summary: Update an API key record
      tags:
        - Admin / API Keys
  /admin/api-keys/{id}/audit:
    get:
      operationId: adminApiKeyAudit
      responses:
        "200":
          content:
            application/json:
              schema:
                additionalProperties: true
                type: object
          description: Audit entries
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
      summary: Audit log for an API key
      tags:
        - Admin / API Keys
    parameters:
      - in: path
        name: id
        required: true
        schema:
          format: uuid
          type: string
  /admin/api-keys/{id}/usage:
    get:
      operationId: adminApiKeyUsage
      responses:
        "200":
          content:
            application/json:
              schema:
                additionalProperties: true
                type: object
          description: Usage data
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
      summary: Usage series for an API key
      tags:
        - Admin / API Keys
    parameters:
      - in: path
        name: id
        required: true
        schema:
          format: uuid
          type: string
  /admin/audit-log:
    get:
      description: Paginated audit trail of administrative actions across the platform.
      operationId: getAdminAuditLog
      parameters:
        - $ref: "#/components/parameters/LimitParam"
        - $ref: "#/components/parameters/CursorParam"
      responses:
        "200":
          content:
            application/json:
              schema:
                additionalProperties: true
                type: object
          description: Audit log page
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
      summary: Read the audit log
      tags:
        - Admin
  /admin/benchmarks:
    get:
      operationId: getAdminBenchmarks
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Benchmarks — Index
      tags:
        - Benchmarks
    post:
      operationId: postAdminBenchmarks
      responses:
        "200":
          description: Success
        "201":
          description: Created
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Benchmarks — Create
      tags:
        - Benchmarks
  /admin/benchmarks/compare:
    post:
      operationId: postAdminBenchmarksCompare
      responses:
        "200":
          description: Success
        "201":
          description: Created
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Benchmarks — Compare
      tags:
        - Benchmarks
  /admin/benchmarks/{id}:
    get:
      operationId: getAdminBenchmarksId
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Benchmarks — Show
      tags:
        - Benchmarks
  /admin/benchmarks/{id}/cancel:
    post:
      operationId: postAdminBenchmarksIdCancel
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "201":
          description: Created
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Benchmarks — Cancel
      tags:
        - Benchmarks
  /admin/benchmarks/{id}/samples:
    get:
      operationId: getAdminBenchmarksIdSamples
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Benchmarks — Samples
      tags:
        - Benchmarks
  /admin/billing:
    get:
      description: Aggregated revenue, outstanding balances, and subscription counts.
      operationId: getAdminBillingSummary
      responses:
        "200":
          content:
            application/json:
              schema:
                additionalProperties: true
                type: object
          description: Billing summary
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
      summary: Platform billing summary
      tags:
        - Admin
  /admin/billing/events:
    get:
      operationId: getAdminBillingEvents
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Billing — List Events
      tags:
        - Billing
  /admin/billing/health:
    get:
      operationId: getAdminBillingHealth
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Billing — Health
      tags:
        - Billing
  /admin/billing/providers:
    get:
      operationId: getAdminBillingProviders
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Billing — List Providers
      tags:
        - Billing
  /admin/billing/providers/active:
    put:
      operationId: putAdminBillingProvidersActive
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Billing — Set Active Provider
      tags:
        - Billing
  /admin/billing/tenants/{tenant_id}:
    get:
      operationId: getAdminBillingTenantsTenantId
      parameters:
        - in: path
          name: tenant_id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Billing — Tenant Detail
      tags:
        - Billing
  /admin/billing/tenants/{tenant_id}/plan:
    put:
      operationId: putAdminBillingTenantsTenantIdPlan
      parameters:
        - in: path
          name: tenant_id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Billing — Set Plan
      tags:
        - Billing
  /admin/billing/tenants/{tenant_id}/refund:
    post:
      operationId: postAdminBillingTenantsTenantIdRefund
      parameters:
        - in: path
          name: tenant_id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "201":
          description: Created
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Billing — Refund
      tags:
        - Billing
  /admin/billing/tenants/{tenant_id}/remove:
    post:
      operationId: postAdminBillingTenantsTenantIdRemove
      parameters:
        - in: path
          name: tenant_id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "201":
          description: Created
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Billing — Remove
      tags:
        - Billing
  /admin/billing/tenants/{tenant_id}/reset-period:
    post:
      operationId: postAdminBillingTenantsTenantIdResetPeriod
      parameters:
        - in: path
          name: tenant_id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "201":
          description: Created
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Billing — Reset Period
      tags:
        - Billing
  /admin/billing/tenants/{tenant_id}/target-balance:
    put:
      operationId: putAdminBillingTenantsTenantIdTargetBalance
      parameters:
        - in: path
          name: tenant_id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Billing — Set Target Balance
      tags:
        - Billing
  /admin/billing/tenants/{tenant_id}/topup:
    post:
      operationId: postAdminBillingTenantsTenantIdTopup
      parameters:
        - in: path
          name: tenant_id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "201":
          description: Created
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Billing — Topup
      tags:
        - Billing
  /admin/billing/tenants/{tenant_id}/usage-budget:
    put:
      operationId: putAdminBillingTenantsTenantIdUsageBudget
      parameters:
        - in: path
          name: tenant_id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Billing — Set Usage Budget
      tags:
        - Billing
  /admin/computers:
    get:
      operationId: adminListComputers
      parameters:
        - $ref: "#/components/parameters/LimitParam"
        - $ref: "#/components/parameters/CursorParam"
        - in: query
          name: status
          schema:
            enum:
              - creating
              - provisioning
              - running
              - stopped
              - paused
              - error
            type: string
        - in: query
          name: tenant_id
          schema:
            format: uuid
            type: string
      responses:
        "200":
          content:
            application/json:
              schema:
                additionalProperties: true
                type: object
          description: Computer page
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
      summary: List all computers across tenants
      tags:
        - Admin / Computers
    post:
      operationId: postAdminComputers
      responses:
        "200":
          description: Success
        "201":
          description: Created
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Computers — Create Computer
      tags:
        - Computers
  /admin/computers/purge-stale:
    post:
      description: Destroys VMs that have been idle past the platform purge threshold and removes orphaned records.
      operationId: adminPurgeStaleComputers
      responses:
        "200":
          content:
            application/json:
              schema:
                additionalProperties: true
                type: object
          description: Purge report
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
      summary: Sweep stale computer records
      tags:
        - Admin / Computers
  /admin/computers/{id}:
    delete:
      description: Destroys the VM and tombstones the record, bypassing tenant-level guards.
      operationId: adminDeleteComputer
      responses:
        "200":
          content:
            application/json:
              schema:
                additionalProperties: true
                type: object
          description: Computer deleted
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
      summary: Force-delete a computer
      tags:
        - Admin / Computers
    parameters:
      - in: path
        name: id
        required: true
        schema:
          format: uuid
          type: string
  /admin/computers/{id}/restart:
    parameters:
      - in: path
        name: id
        required: true
        schema:
          format: uuid
          type: string
    post:
      operationId: adminRestartComputer
      responses:
        "200":
          content:
            application/json:
              schema:
                additionalProperties: true
                type: object
          description: Computer restarted
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
      summary: Restart a computer
      tags:
        - Admin / Computers
  /admin/computers/{id}/resume:
    parameters:
      - in: path
        name: id
        required: true
        schema:
          format: uuid
          type: string
    post:
      operationId: adminResumeComputer
      responses:
        "200":
          content:
            application/json:
              schema:
                additionalProperties: true
                type: object
          description: Computer resumed
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
      summary: Resume a suspended computer
      tags:
        - Admin / Computers
  /admin/computers/{id}/suspend:
    parameters:
      - in: path
        name: id
        required: true
        schema:
          format: uuid
          type: string
    post:
      operationId: adminSuspendComputer
      responses:
        "200":
          content:
            application/json:
              schema:
                additionalProperties: true
                type: object
          description: Computer suspended
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
      summary: Force-pause a computer
      tags:
        - Admin / Computers
  /admin/credits/deduct:
    post:
      description: Manually deducts credits from a tenant's balance (chargeback, correction, etc.).
      operationId: adminDeductCredits
      requestBody:
        content:
          application/json:
            schema:
              properties:
                amount:
                  minimum: 1
                  type: integer
                description:
                  type: string
                tenant_id:
                  format: uuid
                  type: string
              required:
                - tenant_id
                - amount
                - description
              type: object
        required: true
      responses:
        "200":
          content:
            application/json:
              schema:
                additionalProperties: true
                type: object
          description: Deduction recorded
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "422":
          $ref: "#/components/responses/ValidationError"
      summary: Deduct credits from a tenant
      tags:
        - Admin / Credits
  /admin/credits/grant:
    post:
      description: Adds credits to a tenant's balance. Recorded as a `grant` transaction in the credit ledger.
      operationId: adminGrantCredits
      requestBody:
        content:
          application/json:
            schema:
              properties:
                amount:
                  description: Whole credits to grant
                  example: 1000
                  minimum: 1
                  type: integer
                description:
                  description: Human-readable reason (written to the ledger)
                  example: Q2 goodwill credit
                  type: string
                expires_at:
                  format: date-time
                  type:
                    - string
                    - "null"
                tenant_id:
                  format: uuid
                  type: string
              required:
                - tenant_id
                - amount
                - description
              type: object
        required: true
      responses:
        "200":
          content:
            application/json:
              schema:
                additionalProperties: true
                type: object
          description: Grant recorded
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
        "422":
          $ref: "#/components/responses/ValidationError"
      summary: Grant credits to a tenant
      tags:
        - Admin / Credits
  /admin/credits/refund:
    post:
      description: Reverses a previously-charged amount, recorded as a `refund` transaction.
      operationId: adminRefundCredits
      requestBody:
        content:
          application/json:
            schema:
              properties:
                amount:
                  minimum: 1
                  type: integer
                description:
                  type: string
                tenant_id:
                  format: uuid
                  type: string
                transaction_id:
                  format: uuid
                  type:
                    - string
                    - "null"
              required:
                - tenant_id
                - amount
                - description
              type: object
        required: true
      responses:
        "200":
          content:
            application/json:
              schema:
                additionalProperties: true
                type: object
          description: Refund recorded
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
      summary: Refund credits to a tenant
      tags:
        - Admin / Credits
  /admin/credits/{tenant_id}/balance:
    get:
      operationId: adminGetTenantBalance
      responses:
        "200":
          content:
            application/json:
              schema:
                additionalProperties: true
                type: object
          description: Tenant balance
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
      summary: Read a tenant's credit balance
      tags:
        - Admin / Credits
    parameters:
      - in: path
        name: tenant_id
        required: true
        schema:
          format: uuid
          type: string
  /admin/credits/{tenant_id}/history:
    get:
      operationId: adminGetCreditHistory
      parameters:
        - $ref: "#/components/parameters/LimitParam"
        - $ref: "#/components/parameters/CursorParam"
      responses:
        "200":
          content:
            application/json:
              schema:
                additionalProperties: true
                type: object
          description: Credit history
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
      summary: Read a tenant's credit transaction history
      tags:
        - Admin / Credits
    parameters:
      - in: path
        name: tenant_id
        required: true
        schema:
          format: uuid
          type: string
  /admin/custom-domains:
    get:
      operationId: getAdminCustomDomains
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: CustomDomains — Index
      tags:
        - CustomDomains
  /admin/custom-domains/{id}:
    get:
      operationId: getAdminCustomDomainsId
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: CustomDomains — Show
      tags:
        - CustomDomains
  /admin/dashboard:
    get:
      description: Aggregated counters for the admin landing view (users, tenants, computers, credits, recent activity).
      operationId: getAdminDashboard
      responses:
        "200":
          content:
            application/json:
              schema:
                additionalProperties: true
                type: object
          description: Dashboard snapshot
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
      summary: Get the admin dashboard snapshot
      tags:
        - Admin
  /admin/docker-deploy-hosts:
    get:
      operationId: getAdminDockerDeployHosts
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: DockerDeployHosts — Index
      tags:
        - DockerDeployHosts
  /admin/docker-deploy-hosts/{id}:
    get:
      operationId: getAdminDockerDeployHostsId
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: DockerDeployHosts — Show
      tags:
        - DockerDeployHosts
    patch:
      operationId: patchAdminDockerDeployHostsId
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: DockerDeployHosts — Update
      tags:
        - DockerDeployHosts
  /admin/docker-deploy-hosts/{id}/provision:
    post:
      operationId: postAdminDockerDeployHostsIdProvision
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "201":
          description: Created
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: DockerDeployHosts — Provision
      tags:
        - DockerDeployHosts
  /admin/docker-deploy-hosts/{id}/restart:
    post:
      operationId: postAdminDockerDeployHostsIdRestart
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "201":
          description: Created
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: DockerDeployHosts — Restart
      tags:
        - DockerDeployHosts
  /admin/docker-deploy-hosts/{id}/resume:
    post:
      operationId: postAdminDockerDeployHostsIdResume
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "201":
          description: Created
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: DockerDeployHosts — Resume
      tags:
        - DockerDeployHosts
  /admin/docker-deploy-hosts/{id}/retire:
    post:
      operationId: postAdminDockerDeployHostsIdRetire
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "201":
          description: Created
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: DockerDeployHosts — Retire
      tags:
        - DockerDeployHosts
  /admin/docker-deploy-hosts/{id}/suspend:
    post:
      operationId: postAdminDockerDeployHostsIdSuspend
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "201":
          description: Created
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: DockerDeployHosts — Suspend
      tags:
        - DockerDeployHosts
  /admin/email-campaigns:
    get:
      operationId: getAdminEmailCampaigns
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: EmailCampaigns — Index
      tags:
        - EmailCampaigns
    post:
      operationId: postAdminEmailCampaigns
      responses:
        "200":
          description: Success
        "201":
          description: Created
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: EmailCampaigns — Create
      tags:
        - EmailCampaigns
  /admin/email-campaigns/recipient-count:
    get:
      operationId: getAdminEmailCampaignsRecipientCount
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: EmailCampaigns — Recipient Count
      tags:
        - EmailCampaigns
  /admin/email-campaigns/{id}/cancel:
    post:
      operationId: postAdminEmailCampaignsIdCancel
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "201":
          description: Created
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: EmailCampaigns — Cancel
      tags:
        - EmailCampaigns
  /admin/email-campaigns/{id}/deliveries:
    get:
      operationId: getAdminEmailCampaignsIdDeliveries
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: EmailCampaigns — Deliveries
      tags:
        - EmailCampaigns
  /admin/email-campaigns/{id}/send:
    post:
      operationId: postAdminEmailCampaignsIdSend
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "201":
          description: Created
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: EmailCampaigns — Send Campaign
      tags:
        - EmailCampaigns
  /admin/email-inbox:
    get:
      operationId: getAdminEmailInbox
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: EmailInbox — Index
      tags:
        - EmailInbox
  /admin/email-inbox/send:
    post:
      operationId: postAdminEmailInboxSend
      responses:
        "200":
          description: Success
        "201":
          description: Created
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: EmailInbox — Send Direct
      tags:
        - EmailInbox
  /admin/email-inbox/{id}/archive:
    post:
      operationId: postAdminEmailInboxIdArchive
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "201":
          description: Created
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: EmailInbox — Archive
      tags:
        - EmailInbox
  /admin/email-inbox/{id}/read:
    post:
      operationId: postAdminEmailInboxIdRead
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "201":
          description: Created
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: EmailInbox — Mark Read
      tags:
        - EmailInbox
  /admin/email-templates:
    get:
      operationId: getAdminEmailTemplates
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: EmailTemplates — Index
      tags:
        - EmailTemplates
    post:
      operationId: postAdminEmailTemplates
      responses:
        "200":
          description: Success
        "201":
          description: Created
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: EmailTemplates — Create
      tags:
        - EmailTemplates
  /admin/email-templates/{key}:
    put:
      operationId: putAdminEmailTemplatesKey
      parameters:
        - in: path
          name: key
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: EmailTemplates — Update
      tags:
        - EmailTemplates
  /admin/email-templates/{key}/reset:
    post:
      operationId: postAdminEmailTemplatesKeyReset
      parameters:
        - in: path
          name: key
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "201":
          description: Created
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: EmailTemplates — Reset
      tags:
        - EmailTemplates
  /admin/feedback:
    get:
      operationId: adminListFeedback
      parameters:
        - $ref: "#/components/parameters/LimitParam"
        - $ref: "#/components/parameters/CursorParam"
        - in: query
          name: status
          schema:
            enum:
              - open
              - triaged
              - resolved
              - spam
            type: string
      responses:
        "200":
          content:
            application/json:
              schema:
                additionalProperties: true
                type: object
          description: Feedback page
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
      summary: List user feedback
      tags:
        - Admin
  /admin/feedback/{id}:
    delete:
      operationId: adminDeleteFeedback
      responses:
        "200":
          content:
            application/json:
              schema:
                additionalProperties: true
                type: object
          description: Feedback deleted
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
      summary: Delete a feedback entry
      tags:
        - Admin
    get:
      operationId: adminGetFeedback
      responses:
        "200":
          content:
            application/json:
              schema:
                additionalProperties: true
                type: object
          description: Feedback entry
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
      summary: Get a feedback entry
      tags:
        - Admin
    parameters:
      - in: path
        name: id
        required: true
        schema:
          format: uuid
          type: string
    put:
      operationId: adminUpdateFeedback
      requestBody:
        content:
          application/json:
            schema:
              additionalProperties: true
              type: object
        required: true
      responses:
        "200":
          content:
            application/json:
              schema:
                additionalProperties: true
                type: object
          description: Feedback updated
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
      summary: Update a feedback entry (triage)
      tags:
        - Admin
  /admin/fleet-nodes/{node_id}/pool:
    put:
      operationId: putAdminFleetNodesNodeIdPool
      parameters:
        - in: path
          name: node_id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Pools — Assign Node
      tags:
        - Pools
  /admin/fleet/census:
    get:
      operationId: getAdminFleetCensus
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Fleet — Census
      tags:
        - Fleet
  /admin/fleet/health:
    get:
      operationId: getAdminFleetHealth
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: FleetHealth — Health
      tags:
        - FleetHealth
  /admin/fleet/metrics/history:
    get:
      operationId: getAdminFleetMetricsHistory
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: FleetMetrics — History
      tags:
        - FleetMetrics
  /admin/fleet/nodes:
    get:
      operationId: getAdminFleetNodes
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Fleet — Index
      tags:
        - Fleet
  /admin/fleet/nodes/{hostname}/metrics:
    get:
      operationId: getAdminFleetNodesHostnameMetrics
      parameters:
        - in: path
          name: hostname
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Fleet — Node Metrics
      tags:
        - Fleet
  /admin/fleet/nodes/{id}:
    get:
      operationId: getAdminFleetNodesId
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Fleet — Show
      tags:
        - Fleet
  /admin/fleet/nodes/{id}/logs:
    get:
      operationId: getAdminFleetNodesIdLogs
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Fleet — Stream Node Logs
      tags:
        - Fleet
  /admin/fleet/nodes/{id}/processes/kill:
    post:
      operationId: postAdminFleetNodesIdProcessesKill
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "201":
          description: Created
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Fleet — Kill Process
      tags:
        - Fleet
  /admin/fleet/nodes/{id}/restart-service:
    post:
      operationId: postAdminFleetNodesIdRestartService
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "201":
          description: Created
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Fleet — Restart Node Service
      tags:
        - Fleet
  /admin/fleet/reconcile:
    post:
      operationId: postAdminFleetReconcile
      responses:
        "200":
          description: Success
        "201":
          description: Created
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Fleet — Reconcile
      tags:
        - Fleet
  /admin/fleet/rollup:
    get:
      operationId: getAdminFleetRollup
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: FleetRollup — Rollup
      tags:
        - FleetRollup
  /admin/fleet/stream:
    get:
      operationId: getAdminFleetStream
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Fleet — Stream
      tags:
        - Fleet
  /admin/fleet/summary:
    get:
      operationId: getAdminFleetSummary
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Fleet — Summary
      tags:
        - Fleet
  /admin/fleet/vms:
    post:
      operationId: postAdminFleetVms
      responses:
        "200":
          description: Success
        "201":
          description: Created
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Fleet — Create Vm
      tags:
        - Fleet
  /admin/fleet/vms/bulk:
    post:
      operationId: postAdminFleetVmsBulk
      responses:
        "200":
          description: Success
        "201":
          description: Created
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Fleet — Bulk Vm Action
      tags:
        - Fleet
  /admin/fleet/vms/{type}/{id}/logs:
    get:
      operationId: getAdminFleetVmsTypeIdLogs
      parameters:
        - in: path
          name: type
          required: true
          schema:
            type: string
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Fleet — Stream Vm Logs
      tags:
        - Fleet
  /admin/fleet/vms/{type}/{id}/{action}:
    post:
      operationId: postAdminFleetVmsTypeIdAction
      parameters:
        - in: path
          name: type
          required: true
          schema:
            type: string
        - in: path
          name: id
          required: true
          schema:
            type: string
        - in: path
          name: action
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "201":
          description: Created
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Fleet — Vm Action
      tags:
        - Fleet
  /admin/fleet/warm-pool:
    get:
      operationId: getAdminFleetWarmPool
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Fleet — Warm Pool
      tags:
        - Fleet
  /admin/health/detailed:
    get:
      description: Extended health probe covering DB, Redis, Optimal, Firecracker, and VM pool utilisation.
      operationId: getAdminDetailedHealth
      responses:
        "200":
          content:
            application/json:
              schema:
                additionalProperties: true
                type: object
          description: Detailed health
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
      summary: Detailed subsystem health
      tags:
        - Admin
  /admin/impersonate:
    post:
      operationId: postAdminImpersonate
      responses:
        "200":
          description: Success
        "201":
          description: Created
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Impersonation — Create
      tags:
        - Impersonation
  /admin/impersonations:
    get:
      operationId: getAdminImpersonations
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Impersonation — Index
      tags:
        - Impersonation
    post:
      operationId: postAdminImpersonations
      responses:
        "200":
          description: Success
        "201":
          description: Created
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Impersonation — Create
      tags:
        - Impersonation
  /admin/impersonations/{id}:
    delete:
      operationId: deleteAdminImpersonationsId
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        "204":
          description: Deleted
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Impersonation — Delete
      tags:
        - Impersonation
  /admin/impersonations/{id}/elevate:
    post:
      operationId: postAdminImpersonationsIdElevate
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "201":
          description: Created
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Impersonation — Elevate
      tags:
        - Impersonation
  /admin/ip-bans:
    get:
      operationId: adminListIpBans
      parameters:
        - $ref: "#/components/parameters/LimitParam"
        - $ref: "#/components/parameters/CursorParam"
      responses:
        "200":
          content:
            application/json:
              schema:
                additionalProperties: true
                type: object
          description: IP ban list
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
      summary: List IP bans
      tags:
        - Admin
    post:
      operationId: adminCreateIpBan
      requestBody:
        content:
          application/json:
            schema:
              properties:
                expires_at:
                  format: date-time
                  type:
                    - string
                    - "null"
                ip:
                  description: IPv4, IPv6, or CIDR range
                  example: 203.0.113.0/24
                  type: string
                reason:
                  type: string
              required:
                - ip
                - reason
              type: object
        required: true
      responses:
        "201":
          content:
            application/json:
              schema:
                additionalProperties: true
                type: object
          description: IP ban created
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "422":
          $ref: "#/components/responses/ValidationError"
      summary: Ban an IP (or CIDR range)
      tags:
        - Admin
  /admin/ip-bans/{id}:
    delete:
      operationId: adminDeleteIpBan
      responses:
        "200":
          content:
            application/json:
              schema:
                additionalProperties: true
                type: object
          description: Ban lifted
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
      summary: Lift an IP ban
      tags:
        - Admin
    parameters:
      - in: path
        name: id
        required: true
        schema:
          format: uuid
          type: string
  /admin/login-attempts:
    get:
      operationId: adminListLoginAttempts
      parameters:
        - $ref: "#/components/parameters/LimitParam"
        - $ref: "#/components/parameters/CursorParam"
      responses:
        "200":
          content:
            application/json:
              schema:
                additionalProperties: true
                type: object
          description: Attempts
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
      summary: Platform-wide login attempt log
      tags:
        - Admin / Users
  /admin/observability/events:
    get:
      operationId: getAdminObservabilityEvents
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Observability — Events
      tags:
        - Observability
  /admin/observability/events/stream:
    get:
      operationId: getAdminObservabilityEventsStream
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Observability — Events Stream
      tags:
        - Observability
  /admin/observability/overview:
    get:
      operationId: getAdminObservabilityOverview
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Observability — Overview
      tags:
        - Observability
  /admin/observability/timeseries:
    get:
      operationId: getAdminObservabilityTimeseries
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Observability — Timeseries
      tags:
        - Observability
  /admin/opencomputers/audit:
    get:
      operationId: getAdminOpencomputersAudit
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Audit — Index
      tags:
        - Audit
  /admin/opencomputers/audit/verify:
    post:
      operationId: postAdminOpencomputersAuditVerify
      responses:
        "200":
          description: Success
        "201":
          description: Created
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Audit — Verify
      tags:
        - Audit
  /admin/opencomputers/hosts:
    get:
      operationId: getAdminOpencomputersHosts
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: OpenComputers — Index
      tags:
        - OpenComputers
    post:
      operationId: postAdminOpencomputersHosts
      responses:
        "200":
          description: Success
        "201":
          description: Created
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: OpenComputers — Create
      tags:
        - OpenComputers
  /admin/opencomputers/hosts/{id}:
    delete:
      operationId: deleteAdminOpencomputersHostsId
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        "204":
          description: Deleted
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: OpenComputers — Delete
      tags:
        - OpenComputers
    get:
      operationId: getAdminOpencomputersHostsId
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: OpenComputers — Show
      tags:
        - OpenComputers
    patch:
      operationId: patchAdminOpencomputersHostsId
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: OpenComputers — Update
      tags:
        - OpenComputers
  /admin/opencomputers/stats:
    get:
      operationId: getAdminOpencomputersStats
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: OpenComputersStats — Index
      tags:
        - OpenComputersStats
  /admin/optimal/models:
    get:
      operationId: adminOptimalListModels
      responses:
        "200":
          content:
            application/json:
              schema:
                additionalProperties: true
                type: object
          description: Model list
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
      summary: List available AI models
      tags:
        - Admin / Optimal
  /admin/optimal/models/switch:
    post:
      description: Changes the default model served by Optimal. Per-tenant overrides are preserved.
      operationId: adminOptimalSwitchModel
      requestBody:
        content:
          application/json:
            schema:
              properties:
                model_id:
                  example: nemotron-3-super
                  type: string
              required:
                - model_id
              type: object
        required: true
      responses:
        "200":
          content:
            application/json:
              schema:
                additionalProperties: true
                type: object
          description: Model switched
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "422":
          $ref: "#/components/responses/ValidationError"
      summary: Switch the default AI model
      tags:
        - Admin / Optimal
  /admin/optimal/models/{model_id}/stats:
    get:
      operationId: getAdminOptimalModelsModelIdStats
      parameters:
        - in: path
          name: model_id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Optimal — Model Stats
      tags:
        - Optimal
  /admin/optimal/overview:
    get:
      operationId: getAdminOptimalOverview
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Optimal — Overview
      tags:
        - Optimal
  /admin/optimal/providers:
    get:
      operationId: getAdminOptimalProviders
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Optimal — Providers
      tags:
        - Optimal
  /admin/optimal/status:
    get:
      operationId: adminOptimalStatus
      responses:
        "200":
          content:
            application/json:
              schema:
                additionalProperties: true
                type: object
          description: Status
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
      summary: Optimal (AI proxy) status
      tags:
        - Admin / Optimal
  /admin/optimal/tenants:
    get:
      operationId: getAdminOptimalTenants
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Optimal — Tenants
      tags:
        - Optimal
  /admin/optimal/usage:
    get:
      operationId: getAdminOptimalUsage
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Optimal — Usage
      tags:
        - Optimal
  /admin/pools:
    get:
      operationId: getAdminPools
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Pools — Index
      tags:
        - Pools
    post:
      operationId: postAdminPools
      responses:
        "200":
          description: Success
        "201":
          description: Created
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Pools — Create
      tags:
        - Pools
  /admin/pools/{id}:
    get:
      operationId: getAdminPoolsId
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Pools — Show
      tags:
        - Pools
  /admin/pools/{id}/nodes:
    get:
      operationId: getAdminPoolsIdNodes
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Pools — List Nodes
      tags:
        - Pools
  /admin/provider-defaults:
    get:
      operationId: adminGetProviderDefaults
      responses:
        "200":
          content:
            application/json:
              schema:
                additionalProperties: true
                type: object
          description: Defaults
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
      summary: Read the platform-wide Optimal provider defaults
      tags:
        - Admin / Optimal
    put:
      operationId: adminSetProviderDefaults
      requestBody:
        content:
          application/json:
            schema:
              additionalProperties: true
              type: object
        required: true
      responses:
        "200":
          content:
            application/json:
              schema:
                additionalProperties: true
                type: object
          description: Defaults updated
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
      summary: Update the platform-wide Optimal provider defaults
      tags:
        - Admin / Optimal
  /admin/sandbox-artifact-generations:
    get:
      operationId: getAdminSandboxArtifactGenerations
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: SandboxArtifactGenerations — Index
      tags:
        - SandboxArtifactGenerations
  /admin/sandbox-artifact-generations/{id}:
    get:
      operationId: getAdminSandboxArtifactGenerationsId
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: SandboxArtifactGenerations — Show
      tags:
        - SandboxArtifactGenerations
  /admin/sandbox-artifact-generations/{id}/promote:
    post:
      operationId: postAdminSandboxArtifactGenerationsIdPromote
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "201":
          description: Created
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: SandboxArtifactGenerations — Promote
      tags:
        - SandboxArtifactGenerations
  /admin/sandbox-artifact-generations/{id}/retire:
    post:
      operationId: postAdminSandboxArtifactGenerationsIdRetire
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "201":
          description: Created
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: SandboxArtifactGenerations — Retire
      tags:
        - SandboxArtifactGenerations
  /admin/sandboxes/list:
    get:
      operationId: getAdminSandboxesList
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Sandbox — List
      tags:
        - Sandbox
  /admin/sandboxes/stats:
    get:
      operationId: getAdminSandboxesStats
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Sandbox — Stats
      tags:
        - Sandbox
  /admin/sandboxes/tenants:
    get:
      operationId: getAdminSandboxesTenants
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Sandbox — Tenants
      tags:
        - Sandbox
  /admin/services:
    get:
      operationId: getAdminServices
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Services — Index
      tags:
        - Services
  /admin/snapshots:
    get:
      operationId: getAdminSnapshots
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Snapshots — Index
      tags:
        - Snapshots
  /admin/snapshots/{id}:
    get:
      operationId: getAdminSnapshotsId
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Snapshots — Show
      tags:
        - Snapshots
  /admin/sse-ticket:
    post:
      operationId: postAdminSseTicket
      responses:
        "200":
          description: Success
        "201":
          description: Created
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: SSE — Issue Admin Ticket
      tags:
        - SSE
  /admin/stats:
    get:
      description: Current counts + rolling window metrics across tenants, users, computers, and credits.
      operationId: getAdminStats
      responses:
        "200":
          content:
            application/json:
              schema:
                additionalProperties: true
                type: object
          description: Stats payload
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
      summary: Platform-wide statistics
      tags:
        - Admin
  /admin/status/incidents:
    get:
      operationId: getAdminStatusIncidents
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: StatusIncidents — Index
      tags:
        - StatusIncidents
    post:
      operationId: postAdminStatusIncidents
      responses:
        "200":
          description: Success
        "201":
          description: Created
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: StatusIncidents — Create
      tags:
        - StatusIncidents
  /admin/status/incidents/{id}:
    get:
      operationId: getAdminStatusIncidentsId
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: StatusIncidents — Show
      tags:
        - StatusIncidents
    patch:
      operationId: patchAdminStatusIncidentsId
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: StatusIncidents — Update
      tags:
        - StatusIncidents
  /admin/status/incidents/{id}/updates:
    post:
      operationId: postAdminStatusIncidentsIdUpdates
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "201":
          description: Created
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: StatusIncidents — Add Update
      tags:
        - StatusIncidents
  /admin/tags:
    get:
      operationId: adminListAllTags
      responses:
        "200":
          content:
            application/json:
              schema:
                additionalProperties: true
                type: object
          description: Tag catalogue
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
      summary: List every tag in use
      tags:
        - Admin / Users
  /admin/tags/{tag}/users:
    get:
      operationId: adminUsersByTag
      parameters:
        - $ref: "#/components/parameters/LimitParam"
        - $ref: "#/components/parameters/CursorParam"
      responses:
        "200":
          content:
            application/json:
              schema:
                additionalProperties: true
                type: object
          description: Tagged users
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
      summary: List users carrying a tag
      tags:
        - Admin / Users
    parameters:
      - in: path
        name: tag
        required: true
        schema:
          type: string
  /admin/team:
    get:
      description: Super-admin only — returns the people with platform-level access.
      operationId: adminListTeam
      responses:
        "200":
          content:
            application/json:
              schema:
                additionalProperties: true
                type: object
          description: Team list
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
      summary: List the MIOSA platform team
      tags:
        - Admin / Team
    post:
      operationId: adminAddTeamMember
      requestBody:
        content:
          application/json:
            schema:
              properties:
                role:
                  enum:
                    - admin
                    - super_admin
                  type: string
                user_id:
                  format: uuid
                  type: string
              required:
                - user_id
                - role
              type: object
        required: true
      responses:
        "201":
          content:
            application/json:
              schema:
                additionalProperties: true
                type: object
          description: Member added
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
      summary: Add a team member
      tags:
        - Admin / Team
  /admin/team/{id}:
    delete:
      operationId: adminRemoveTeamMember
      responses:
        "200":
          content:
            application/json:
              schema:
                additionalProperties: true
                type: object
          description: Member removed
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
      summary: Remove a team member
      tags:
        - Admin / Team
    parameters:
      - in: path
        name: id
        required: true
        schema:
          format: uuid
          type: string
    patch:
      operationId: adminPatchTeamMember
      requestBody:
        content:
          application/json:
            schema:
              additionalProperties: true
              type: object
        required: true
      responses:
        "200":
          content:
            application/json:
              schema:
                additionalProperties: true
                type: object
          description: Member updated
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
      summary: Update a team member (partial)
      tags:
        - Admin / Team
    put:
      operationId: adminUpdateTeamMember
      requestBody:
        content:
          application/json:
            schema:
              additionalProperties: true
              type: object
        required: true
      responses:
        "200":
          content:
            application/json:
              schema:
                additionalProperties: true
                type: object
          description: Member updated
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
      summary: Update a team member (full)
      tags:
        - Admin / Team
  /admin/templates:
    get:
      description: Enumerate every `.ext4` rootfs currently installed under `/srv/miosa/templates/` with file size and last-modified time.
      operationId: adminListTemplates
      responses:
        "200":
          content:
            application/json:
              schema:
                properties:
                  templates:
                    items:
                      properties:
                        mtime:
                          format: date-time
                          type: string
                        name:
                          type: string
                        path:
                          type: string
                        size_bytes:
                          type: integer
                      type: object
                    type: array
                type: object
          description: Installed templates
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
      summary: List installed rootfs templates
      tags:
        - Admin / Templates
  /admin/templates/{name}/pull:
    parameters:
      - description: Template slug (`miosa-desktop`, `miosa-sandbox`, ...)
        in: path
        name: name
        required: true
        schema:
          type: string
    post:
      description: "Triggers `deploy/oci-pull-image.sh` on the host to fetch the given OCI image, unpack its layered filesystem, inject the host-managed envd binary, and install the result as `/srv/miosa/templates/<name>.ext4`.\nLong-running — typically 30-90 s depending on network + image size. Synchronous for now; wraps in an Oban job in a later iteration.\n"
      operationId: adminPullTemplate
      requestBody:
        content:
          application/json:
            schema:
              properties:
                cosign_pubkey:
                  description: Optional path to a cosign public key for signature verification
                  type: string
                oci_image:
                  description: Fully-qualified OCI image reference
                  example: ghcr.io/miosa-ai/templates/miosa-sandbox:0.2.0
                  type: string
              required:
                - oci_image
              type: object
        required: true
      responses:
        "200":
          content:
            application/json:
              schema:
                properties:
                  duration_ms:
                    type: integer
                  image:
                    type: string
                  log_tail:
                    type: string
                  rootfs_path:
                    type: string
                  size_bytes:
                    type: integer
                  template:
                    type: string
                type: object
          description: Template installed
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "422":
          $ref: "#/components/responses/ValidationError"
        "500":
          content:
            application/json:
              schema:
                additionalProperties: true
                type: object
          description: Puller failed — stderr tail in `log_tail`
      summary: Pull a template from an OCI registry
      tags:
        - Admin / Templates
  /admin/tenants:
    get:
      operationId: adminListTenants
      parameters:
        - $ref: "#/components/parameters/LimitParam"
        - $ref: "#/components/parameters/CursorParam"
        - in: query
          name: q
          schema:
            type: string
      responses:
        "200":
          content:
            application/json:
              schema:
                additionalProperties: true
                type: object
          description: Tenant page
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
      summary: List tenants
      tags:
        - Admin / Tenants
  /admin/tenants/{id}:
    delete:
      description: Permanently deletes a tenant and all associated data. Irreversible.
      operationId: adminDeleteTenant
      responses:
        "200":
          content:
            application/json:
              schema:
                additionalProperties: true
                type: object
          description: Tenant deleted
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
      summary: Delete a tenant
      tags:
        - Admin / Tenants
    parameters:
      - in: path
        name: id
        required: true
        schema:
          format: uuid
          type: string
  /admin/tenants/{id}/detail:
    get:
      operationId: adminTenantDetail
      responses:
        "200":
          content:
            application/json:
              schema:
                additionalProperties: true
                type: object
          description: Tenant detail
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
      summary: Tenant detail snapshot
      tags:
        - Admin / Tenants
    parameters:
      - in: path
        name: id
        required: true
        schema:
          format: uuid
          type: string
  /admin/tenants/{id}/plan:
    parameters:
      - in: path
        name: id
        required: true
        schema:
          format: uuid
          type: string
    post:
      description: "Moves the tenant onto a new plan. Current plan slugs: `free`, `starter`, `pro`, `scale`."
      operationId: adminChangeTenantPlan
      requestBody:
        content:
          application/json:
            schema:
              properties:
                plan:
                  enum:
                    - free
                    - starter
                    - pro
                    - scale
                  type: string
                prorate:
                  default: true
                  type: boolean
              required:
                - plan
              type: object
        required: true
      responses:
        "200":
          content:
            application/json:
              schema:
                additionalProperties: true
                type: object
          description: Plan changed
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
        "422":
          $ref: "#/components/responses/ValidationError"
      summary: Change a tenant's plan
      tags:
        - Admin / Tenants
  /admin/tenants/{id}/provider-config:
    delete:
      operationId: adminResetTenantProviderConfig
      responses:
        "200":
          content:
            application/json:
              schema:
                additionalProperties: true
                type: object
          description: Provider config reset
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
      summary: Reset a tenant's Optimal provider config to defaults
      tags:
        - Admin / Tenants
    get:
      operationId: adminGetTenantProviderConfig
      responses:
        "200":
          content:
            application/json:
              schema:
                additionalProperties: true
                type: object
          description: Provider config
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
      summary: Read a tenant's Optimal provider config
      tags:
        - Admin / Tenants
    parameters:
      - in: path
        name: id
        required: true
        schema:
          format: uuid
          type: string
    put:
      operationId: adminSetTenantProviderConfig
      requestBody:
        content:
          application/json:
            schema:
              additionalProperties: true
              type: object
        required: true
      responses:
        "200":
          content:
            application/json:
              schema:
                additionalProperties: true
                type: object
          description: Provider config updated
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
      summary: Override a tenant's Optimal provider config
      tags:
        - Admin / Tenants
  /admin/tenants/{id}/suspend:
    parameters:
      - in: path
        name: id
        required: true
        schema:
          format: uuid
          type: string
    post:
      operationId: adminSuspendTenant
      requestBody:
        content:
          application/json:
            schema:
              properties:
                reason:
                  type: string
              type: object
        required: false
      responses:
        "200":
          content:
            application/json:
              schema:
                additionalProperties: true
                type: object
          description: Tenant suspended
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
      summary: Suspend a tenant
      tags:
        - Admin / Tenants
  /admin/tenants/{id}/unsuspend:
    parameters:
      - in: path
        name: id
        required: true
        schema:
          format: uuid
          type: string
    post:
      operationId: adminUnsuspendTenant
      responses:
        "200":
          content:
            application/json:
              schema:
                additionalProperties: true
                type: object
          description: Tenant unsuspended
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
      summary: Unsuspend a tenant
      tags:
        - Admin / Tenants
  /admin/tenants/{tenant_id}/pool:
    get:
      operationId: getAdminTenantsTenantIdPool
      parameters:
        - in: path
          name: tenant_id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Pools — Tenant Pool
      tags:
        - Pools
    put:
      operationId: putAdminTenantsTenantIdPool
      parameters:
        - in: path
          name: tenant_id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Pools — Set Tenant Pool
      tags:
        - Pools
  /admin/tenants/{tenant_id}/rate-limits:
    get:
      operationId: getAdminTenantsTenantIdRateLimits
      parameters:
        - in: path
          name: tenant_id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: RateLimits — List
      tags:
        - RateLimits
  /admin/tenants/{tenant_id}/rate-limits/usage:
    get:
      operationId: getAdminTenantsTenantIdRateLimitsUsage
      parameters:
        - in: path
          name: tenant_id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: RateLimits — Usage
      tags:
        - RateLimits
  /admin/tenants/{tenant_id}/rate-limits/{bucket}:
    delete:
      operationId: deleteAdminTenantsTenantIdRateLimitsBucket
      parameters:
        - in: path
          name: tenant_id
          required: true
          schema:
            type: string
        - in: path
          name: bucket
          required: true
          schema:
            type: string
      responses:
        "204":
          description: Deleted
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: RateLimits — Delete
      tags:
        - RateLimits
    put:
      operationId: putAdminTenantsTenantIdRateLimitsBucket
      parameters:
        - in: path
          name: tenant_id
          required: true
          schema:
            type: string
        - in: path
          name: bucket
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: RateLimits — Upsert
      tags:
        - RateLimits
  /admin/users:
    get:
      operationId: adminListUsers
      parameters:
        - $ref: "#/components/parameters/LimitParam"
        - $ref: "#/components/parameters/CursorParam"
        - description: Search string matched against email + name
          in: query
          name: q
          schema:
            type: string
        - in: query
          name: status
          schema:
            enum:
              - active
              - suspended
              - deleted
            type: string
      responses:
        "200":
          content:
            application/json:
              schema:
                additionalProperties: true
                type: object
          description: User page
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
      summary: List users
      tags:
        - Admin / Users
  /admin/users/bulk:
    post:
      description: "Supported actions: `suspend`, `unsuspend`, `delete`, `tag`, `notify`."
      operationId: adminBulkUserAction
      requestBody:
        content:
          application/json:
            schema:
              properties:
                action:
                  enum:
                    - suspend
                    - unsuspend
                    - delete
                    - tag
                    - notify
                  type: string
                params:
                  additionalProperties: true
                  description: "Action-specific parameters (e.g. `{ reason: \"...\", tag: \"beta\" }`)"
                  type: object
                user_ids:
                  items:
                    format: uuid
                    type: string
                  maxItems: 500
                  minItems: 1
                  type: array
              required:
                - user_ids
                - action
              type: object
        required: true
      responses:
        "200":
          content:
            application/json:
              schema:
                additionalProperties: true
                type: object
          description: Bulk action accepted
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "422":
          $ref: "#/components/responses/ValidationError"
      summary: Apply a bulk action across many users
      tags:
        - Admin / Users
  /admin/users/{id}:
    delete:
      description: Permanently deletes the user and their tenant-scoped data. Not reversible.
      operationId: adminDeleteUser
      responses:
        "200":
          content:
            application/json:
              schema:
                additionalProperties: true
                type: object
          description: User deleted
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
      summary: Delete a user
      tags:
        - Admin / Users
    get:
      operationId: adminGetUser
      responses:
        "200":
          content:
            application/json:
              schema:
                additionalProperties: true
                type: object
          description: User record
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
      summary: Get a user
      tags:
        - Admin / Users
    parameters:
      - in: path
        name: id
        required: true
        schema:
          format: uuid
          type: string
    put:
      operationId: adminUpdateUser
      requestBody:
        content:
          application/json:
            schema:
              additionalProperties: true
              type: object
        required: true
      responses:
        "200":
          content:
            application/json:
              schema:
                additionalProperties: true
                type: object
          description: Updated user
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
        "422":
          $ref: "#/components/responses/ValidationError"
      summary: Update a user
      tags:
        - Admin / Users
  /admin/users/{id}/ban:
    parameters:
      - in: path
        name: id
        required: true
        schema:
          format: uuid
          type: string
    post:
      description: Blocks the user permanently. Ban reason is logged and surfaced in the audit trail.
      operationId: adminBanUser
      requestBody:
        content:
          application/json:
            schema:
              properties:
                expires_at:
                  format: date-time
                  type:
                    - string
                    - "null"
                reason:
                  type: string
              required:
                - reason
              type: object
        required: true
      responses:
        "200":
          content:
            application/json:
              schema:
                additionalProperties: true
                type: object
          description: User banned
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
      summary: Ban a user
      tags:
        - Admin / Users
  /admin/users/{id}/detail:
    get:
      operationId: adminUserDetail
      responses:
        "200":
          content:
            application/json:
              schema:
                additionalProperties: true
                type: object
          description: Detail payload
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
      summary: Full user detail (with recent activity)
      tags:
        - Admin / Users
    parameters:
      - in: path
        name: id
        required: true
        schema:
          format: uuid
          type: string
  /admin/users/{id}/force-logout:
    parameters:
      - in: path
        name: id
        required: true
        schema:
          format: uuid
          type: string
    post:
      operationId: adminForceLogout
      responses:
        "200":
          content:
            application/json:
              schema:
                additionalProperties: true
                type: object
          description: Sessions invalidated
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
      summary: Invalidate all sessions for a user
      tags:
        - Admin / Users
  /admin/users/{id}/login-attempts:
    get:
      operationId: adminUserLoginAttempts
      responses:
        "200":
          content:
            application/json:
              schema:
                additionalProperties: true
                type: object
          description: Login attempts
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
      summary: Recent login attempts for a user
      tags:
        - Admin / Users
    parameters:
      - in: path
        name: id
        required: true
        schema:
          format: uuid
          type: string
  /admin/users/{id}/notifications:
    get:
      operationId: adminListUserNotifications
      parameters:
        - $ref: "#/components/parameters/LimitParam"
        - $ref: "#/components/parameters/CursorParam"
      responses:
        "200":
          content:
            application/json:
              schema:
                additionalProperties: true
                type: object
          description: Notifications
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
      summary: List a user's notifications
      tags:
        - Admin / Users
    parameters:
      - in: path
        name: id
        required: true
        schema:
          format: uuid
          type: string
  /admin/users/{id}/notify:
    parameters:
      - in: path
        name: id
        required: true
        schema:
          format: uuid
          type: string
    post:
      operationId: adminNotifyUser
      requestBody:
        content:
          application/json:
            schema:
              properties:
                body:
                  type: string
                severity:
                  default: info
                  enum:
                    - info
                    - warning
                    - critical
                  type: string
                title:
                  type: string
              required:
                - title
                - body
              type: object
        required: true
      responses:
        "200":
          content:
            application/json:
              schema:
                additionalProperties: true
                type: object
          description: Notification queued
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
      summary: Send a notification to a user
      tags:
        - Admin / Users
  /admin/users/{id}/password-reset:
    post:
      operationId: postAdminUsersIdPasswordReset
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "201":
          description: Created
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Users — Send Password Reset
      tags:
        - Users
  /admin/users/{id}/role:
    parameters:
      - in: path
        name: id
        required: true
        schema:
          format: uuid
          type: string
    post:
      description: Roles are `user`, `admin`, `owner`, `super_admin`. Super-admin elevation is restricted to the platform team.
      operationId: adminChangeUserRole
      requestBody:
        content:
          application/json:
            schema:
              properties:
                role:
                  enum:
                    - user
                    - admin
                    - owner
                    - super_admin
                  type: string
              required:
                - role
              type: object
        required: true
      responses:
        "200":
          content:
            application/json:
              schema:
                additionalProperties: true
                type: object
          description: Role updated
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
      summary: Change a user's role
      tags:
        - Admin / Users
  /admin/users/{id}/suspend:
    parameters:
      - in: path
        name: id
        required: true
        schema:
          format: uuid
          type: string
    post:
      operationId: adminSuspendUser
      requestBody:
        content:
          application/json:
            schema:
              properties:
                reason:
                  type: string
              type: object
        required: false
      responses:
        "200":
          content:
            application/json:
              schema:
                additionalProperties: true
                type: object
          description: User suspended
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
      summary: Suspend a user
      tags:
        - Admin / Users
  /admin/users/{id}/tags:
    get:
      operationId: adminListUserTags
      responses:
        "200":
          content:
            application/json:
              schema:
                additionalProperties: true
                type: object
          description: Tag list
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
      summary: List a user's tags
      tags:
        - Admin / Users
    parameters:
      - in: path
        name: id
        required: true
        schema:
          format: uuid
          type: string
    post:
      operationId: adminAddUserTag
      requestBody:
        content:
          application/json:
            schema:
              properties:
                tag:
                  maxLength: 64
                  minLength: 1
                  type: string
              required:
                - tag
              type: object
        required: true
      responses:
        "200":
          content:
            application/json:
              schema:
                additionalProperties: true
                type: object
          description: Tag added
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
      summary: Tag a user
      tags:
        - Admin / Users
  /admin/users/{id}/tags/{tag}:
    delete:
      operationId: adminRemoveUserTag
      responses:
        "200":
          content:
            application/json:
              schema:
                additionalProperties: true
                type: object
          description: Tag removed
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
      summary: Remove a tag from a user
      tags:
        - Admin / Users
    parameters:
      - in: path
        name: id
        required: true
        schema:
          format: uuid
          type: string
      - in: path
        name: tag
        required: true
        schema:
          type: string
  /admin/users/{id}/unban:
    parameters:
      - in: path
        name: id
        required: true
        schema:
          format: uuid
          type: string
    post:
      operationId: adminUnbanUser
      responses:
        "200":
          content:
            application/json:
              schema:
                additionalProperties: true
                type: object
          description: User unbanned
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
      summary: Unban a user
      tags:
        - Admin / Users
  /admin/users/{id}/unsuspend:
    parameters:
      - in: path
        name: id
        required: true
        schema:
          format: uuid
          type: string
    post:
      operationId: adminUnsuspendUser
      responses:
        "200":
          content:
            application/json:
              schema:
                additionalProperties: true
                type: object
          description: User unsuspended
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
      summary: Unsuspend a user
      tags:
        - Admin / Users
  /admin/users/{id}/workspaces:
    get:
      description: "Returns every workspace-membership row for the given user, grouped across all tenants. Each row includes workspace name/slug, tenant name, role, and join date. Requires admin credential.\n"
      operationId: adminListUserWorkspaces
      responses:
        "200":
          content:
            application/json:
              schema:
                properties:
                  data:
                    items:
                      $ref: "#/components/schemas/AdminUserWorkspaceRow"
                    type: array
                required:
                  - data
                type: object
          description: Workspace membership list.
        "400":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
          description: Invalid user UUID.
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
      security:
        - BearerAuth: []
      summary: (Admin) List workspaces a user belongs to
      tags:
        - Admin / Users
    parameters:
      - description: User UUID.
        in: path
        name: id
        required: true
        schema:
          format: uuid
          type: string
  /admin/webhook-deliveries:
    get:
      operationId: getAdminWebhookDeliveries
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: WebhookDeliveries — Index
      tags:
        - WebhookDeliveries
  /admin/webhook-deliveries/dead-letter:
    get:
      operationId: getAdminWebhookDeliveriesDeadLetter
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: WebhookDeliveries — Dead Letter
      tags:
        - WebhookDeliveries
  /admin/workspaces:
    get:
      operationId: getAdminWorkspaces
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Workspaces — Index
      tags:
        - Workspaces
  /admin/workspaces/{id}:
    get:
      operationId: getAdminWorkspacesId
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Workspaces — Show
      tags:
        - Workspaces
  /agent-runtime-profiles:
    get:
      operationId: getAgentRuntimeProfiles
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: AgentRuntimeProfiles — Index
      tags:
        - AgentRuntimeProfiles
    post:
      operationId: postAgentRuntimeProfiles
      responses:
        "200":
          description: Success
        "201":
          description: Created
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: AgentRuntimeProfiles — Create
      tags:
        - AgentRuntimeProfiles
  /agent-runtime-profiles/{id}:
    delete:
      operationId: deleteAgentRuntimeProfilesId
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        "204":
          description: Deleted
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: AgentRuntimeProfiles — Delete
      tags:
        - AgentRuntimeProfiles
    get:
      operationId: getAgentRuntimeProfilesId
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: AgentRuntimeProfiles — Show
      tags:
        - AgentRuntimeProfiles
    put:
      operationId: putAgentRuntimeProfilesId
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: AgentRuntimeProfiles — Update
      tags:
        - AgentRuntimeProfiles
  /api-keys:
    get:
      description: "Returns all API keys belonging to the authenticated user. Includes revoked keys. The raw key value is never returned here — only the prefix.\n"
      operationId: listApiKeys
      responses:
        "200":
          content:
            application/json:
              schema:
                properties:
                  data:
                    items:
                      $ref: "#/components/schemas/ApiKey"
                    type: array
                required:
                  - data
                type: object
          description: List of API keys
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: List API keys
      tags:
        - API Keys
    post:
      description: "Creates a new API key. The raw key is returned **only in this response** and cannot be retrieved again. Store it securely immediately.\nAll keys use the `msk_` prefix. `purpose` controls which backend the key can authenticate against:\n- `api` — compute, desktop, files, CUA, OSA, credits - `optimal` — AI/LLM proxy (`/v1/chat/completions`, `/v1/responses`)\nThe caller's role determines which `key_type` values they may mint: user-role callers can only create `user` keys; admin/platform callers can mint any type.\n"
      operationId: createApiKey
      requestBody:
        content:
          application/json:
            schema:
              properties:
                key_type:
                  default: user
                  description: "Role the key inherits. Only admin/platform callers may mint `admin` or `platform` keys; user-role callers are restricted to `user`.\n"
                  enum:
                    - user
                    - admin
                    - platform
                  example: user
                  type: string
                name:
                  description: Human-readable label for this key
                  example: Production SDK Key
                  maxLength: 100
                  minLength: 1
                  type: string
                purpose:
                  default: api
                  description: "Backend the key authenticates against. `api` covers the compute / desktop / files / CUA / OSA / credits surface. `optimal` authenticates against the AI/LLM proxy.\n"
                  enum:
                    - api
                    - optimal
                  example: api
                  type: string
              required:
                - name
              type: object
        required: true
      responses:
        "201":
          content:
            application/json:
              example:
                data:
                  created_at: 2026-04-11T14:30:00Z
                  id: b2c3d4e5-f6a7-8901-bcde-f12345678901
                  key: msk_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6
                  key_prefix: msk_a1b2c3
                  key_purpose: api
                  key_type: user
                  name: Production SDK Key
                  rate_limit_rpm: 60
                  status: active
              schema:
                properties:
                  data:
                    allOf:
                      - $ref: "#/components/schemas/ApiKey"
                      - properties:
                          key:
                            description: Raw API key — store this value now
                            example: msk_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6
                            type: string
                        required:
                          - key
                        type: object
                required:
                  - data
                type: object
          description: API key created — raw key returned once only
        "401":
          $ref: "#/components/responses/Unauthorized"
        "422":
          $ref: "#/components/responses/ValidationError"
      summary: Create an API key
      tags:
        - API Keys
  /api-keys/scoped:
    post:
      operationId: postApiKeysScoped
      responses:
        "200":
          description: Success
        "201":
          description: Created
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: ScopedApiKeys — Create
      tags:
        - ScopedApiKeys
  /api-keys/{id}:
    delete:
      description: "Permanently revokes the API key. Any requests using this key will receive `401 Unauthorized` immediately. Revocation is irreversible; create a new key if needed.\n"
      operationId: deleteApiKey
      responses:
        "200":
          content:
            application/json:
              schema:
                properties:
                  data:
                    properties:
                      id:
                        format: uuid
                        type: string
                      status:
                        enum:
                          - revoked
                        example: revoked
                        type: string
                    required:
                      - id
                      - status
                    type: object
                required:
                  - data
                type: object
          description: API key revoked
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"
      summary: Revoke an API key
      tags:
        - API Keys
    parameters:
      - description: API key record UUID
        in: path
        name: id
        required: true
        schema:
          format: uuid
          type: string
  /api-keys/{id}/rotate:
    post:
      description: "Creates one replacement key with inherited purpose, type, and scopes, revokes the original in the same transaction, and returns the new raw key once. Repeating rotation of the original returns `409`.\n"
      operationId: rotateApiKey
      parameters:
        - in: path
          name: id
          required: true
          schema:
            format: uuid
            type: string
      requestBody:
        content:
          application/json:
            schema:
              properties:
                name:
                  maxLength: 100
                  minLength: 1
                  type: string
              type: object
        required: false
      responses:
        "201":
          content:
            application/json:
              schema:
                properties:
                  data:
                    allOf:
                      - $ref: "#/components/schemas/ApiKey"
                      - properties:
                          key:
                            type: string
                        required:
                          - key
                        type: object
                required:
                  - data
                type: object
          description: Replacement key created and original key revoked
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"
        "409":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
          description: Key is revoked or already has a replacement
        "422":
          $ref: "#/components/responses/ValidationError"
      summary: Atomically rotate an API key
      tags:
        - API Keys
  /app-auth/{resource_type}/{resource_id}/email/confirm:
    post:
      operationId: postAppAuthResourceTypeResourceIdEmailConfirm
      parameters:
        - in: path
          name: resource_type
          required: true
          schema:
            type: string
        - in: path
          name: resource_id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "201":
          description: Created
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: AppAuth — Email Confirm
      tags:
        - AppAuth
  /app-auth/{resource_type}/{resource_id}/login:
    post:
      operationId: postAppAuthResourceTypeResourceIdLogin
      parameters:
        - in: path
          name: resource_type
          required: true
          schema:
            type: string
        - in: path
          name: resource_id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "201":
          description: Created
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: AppAuth — Login
      tags:
        - AppAuth
  /app-auth/{resource_type}/{resource_id}/password-reset:
    post:
      operationId: postAppAuthResourceTypeResourceIdPasswordReset
      parameters:
        - in: path
          name: resource_type
          required: true
          schema:
            type: string
        - in: path
          name: resource_id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "201":
          description: Created
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: AppAuth — Password Reset
      tags:
        - AppAuth
  /app-auth/{resource_type}/{resource_id}/password-reset/confirm:
    post:
      operationId: postAppAuthResourceTypeResourceIdPasswordResetConfirm
      parameters:
        - in: path
          name: resource_type
          required: true
          schema:
            type: string
        - in: path
          name: resource_id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "201":
          description: Created
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: AppAuth — Password Reset Confirm
      tags:
        - AppAuth
  /app-auth/{resource_type}/{resource_id}/signup:
    post:
      operationId: postAppAuthResourceTypeResourceIdSignup
      parameters:
        - in: path
          name: resource_type
          required: true
          schema:
            type: string
        - in: path
          name: resource_id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "201":
          description: Created
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: AppAuth — Signup
      tags:
        - AppAuth
  /app-auth/{resource_type}/{resource_id}/verify:
    post:
      operationId: postAppAuthResourceTypeResourceIdVerify
      parameters:
        - in: path
          name: resource_type
          required: true
          schema:
            type: string
        - in: path
          name: resource_id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "201":
          description: Created
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: AppAuth — Verify
      tags:
        - AppAuth
  /application-plans/{id}:
    get:
      operationId: getApplicationPlansId
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: ApplicationPlans — Show
      tags:
        - ApplicationPlans
  /application-plans/{id}/apply:
    post:
      operationId: postApplicationPlansIdApply
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "201":
          description: Created
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: ApplicationPlans — Begin Apply
      tags:
        - ApplicationPlans
  /application-plans/{id}/approve:
    post:
      operationId: postApplicationPlansIdApprove
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "201":
          description: Created
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: ApplicationPlans — Approve
      tags:
        - ApplicationPlans
  /application-plans/{id}/complete:
    post:
      operationId: postApplicationPlansIdComplete
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "201":
          description: Created
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: ApplicationPlans — Complete
      tags:
        - ApplicationPlans
  /audit-log:
    get:
      operationId: getAuditLog
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: AuditLog — Index
      tags:
        - AuditLog
  /auth/avatar:
    delete:
      operationId: deleteAuthAvatar
      responses:
        "204":
          description: Deleted
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Auth — Delete Avatar
      tags:
        - Auth
    post:
      operationId: postAuthAvatar
      responses:
        "200":
          description: Success
        "201":
          description: Created
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Auth — Upload Avatar
      tags:
        - Auth
  /auth/avatar/{user_id}:
    get:
      operationId: getAuthAvatarUserId
      parameters:
        - in: path
          name: user_id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Auth — Avatar
      tags:
        - Auth
  /auth/cli/approve:
    post:
      operationId: postAuthCliApprove
      responses:
        "200":
          description: Success
        "201":
          description: Created
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: CliAuth — Approve
      tags:
        - CliAuth
  /auth/cli/deny:
    post:
      operationId: postAuthCliDeny
      responses:
        "200":
          description: Success
        "201":
          description: Created
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: CliAuth — Deny
      tags:
        - CliAuth
  /auth/cli/start:
    post:
      operationId: postAuthCliStart
      responses:
        "200":
          description: Success
        "201":
          description: Created
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: CliAuth — Start
      tags:
        - CliAuth
  /auth/cli/status:
    get:
      operationId: getAuthCliStatus
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: CliAuth — Status
      tags:
        - CliAuth
  /auth/cli/token:
    post:
      operationId: postAuthCliToken
      responses:
        "200":
          description: Success
        "201":
          description: Created
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: CliAuth — Token
      tags:
        - CliAuth
  /auth/connections:
    get:
      operationId: getAuthConnections
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: OAuth — Connections
      tags:
        - OAuth
  /auth/connections/{provider}:
    delete:
      operationId: deleteAuthConnectionsProvider
      parameters:
        - in: path
          name: provider
          required: true
          schema:
            type: string
      responses:
        "204":
          description: Deleted
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: OAuth — Disconnect
      tags:
        - OAuth
    post:
      operationId: postAuthConnectionsProvider
      parameters:
        - in: path
          name: provider
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "201":
          description: Created
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: OAuth — Connect
      tags:
        - OAuth
  /auth/data/export:
    post:
      operationId: postAuthDataExport
      responses:
        "200":
          description: Success
        "201":
          description: Created
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Auth — Create Account Export
      tags:
        - Auth
  /auth/data/export/{id}:
    get:
      operationId: getAuthDataExportId
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Auth — Download Account Export
      tags:
        - Auth
  /auth/deletion:
    delete:
      operationId: deleteAuthDeletion
      responses:
        "204":
          description: Deleted
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Auth — Cancel Account Deletion
      tags:
        - Auth
    get:
      operationId: getAuthDeletion
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Auth — Deletion Status
      tags:
        - Auth
    post:
      operationId: postAuthDeletion
      responses:
        "200":
          description: Success
        "201":
          description: Created
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Auth — Schedule Account Deletion
      tags:
        - Auth
  /auth/email/change:
    post:
      operationId: postAuthEmailChange
      responses:
        "200":
          description: Success
        "201":
          description: Created
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Auth — Request Email Change
      tags:
        - Auth
  /auth/email/change/confirm:
    post:
      operationId: postAuthEmailChangeConfirm
      responses:
        "200":
          description: Success
        "201":
          description: Created
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Auth — Confirm Email Change
      tags:
        - Auth
  /auth/email/verification:
    post:
      operationId: postAuthEmailVerification
      responses:
        "200":
          description: Success
        "201":
          description: Created
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Auth — Request Email Verification
      tags:
        - Auth
  /auth/email/verify:
    post:
      operationId: postAuthEmailVerify
      responses:
        "200":
          description: Success
        "201":
          description: Created
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Auth — Verify Email
      tags:
        - Auth
  /auth/login:
    post:
      operationId: postAuthLogin
      responses:
        "200":
          description: Success
        "201":
          description: Created
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Auth — Login
      tags:
        - Auth
  /auth/logout:
    post:
      operationId: postAuthLogout
      responses:
        "200":
          description: Success
        "201":
          description: Created
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Auth — Logout
      tags:
        - Auth
  /auth/logout/all:
    post:
      operationId: postAuthLogoutAll
      responses:
        "200":
          description: Success
        "201":
          description: Created
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Auth — Logout All
      tags:
        - Auth
  /auth/me:
    get:
      operationId: getAuthMe
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Auth — Me
      tags:
        - Auth
    patch:
      operationId: patchAuthMe
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Auth — Update Me
      tags:
        - Auth
  /auth/mfa/email:
    get:
      operationId: getAuthMfaEmail
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Auth — Email Mfa Status
      tags:
        - Auth
  /auth/mfa/email/disable:
    post:
      operationId: postAuthMfaEmailDisable
      responses:
        "200":
          description: Success
        "201":
          description: Created
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Auth — Request Email Mfa Disable
      tags:
        - Auth
  /auth/mfa/email/disable/confirm:
    post:
      operationId: postAuthMfaEmailDisableConfirm
      responses:
        "200":
          description: Success
        "201":
          description: Created
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Auth — Confirm Email Mfa Disable
      tags:
        - Auth
  /auth/mfa/email/enable:
    post:
      operationId: postAuthMfaEmailEnable
      responses:
        "200":
          description: Success
        "201":
          description: Created
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Auth — Request Email Mfa Enable
      tags:
        - Auth
  /auth/mfa/email/enable/confirm:
    post:
      operationId: postAuthMfaEmailEnableConfirm
      responses:
        "200":
          description: Success
        "201":
          description: Created
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Auth — Confirm Email Mfa Enable
      tags:
        - Auth
  /auth/mfa/email/verify:
    post:
      operationId: postAuthMfaEmailVerify
      responses:
        "200":
          description: Success
        "201":
          description: Created
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Auth — Verify Email Mfa
      tags:
        - Auth
  /auth/mfa/recovery/regenerate:
    post:
      operationId: postAuthMfaRecoveryRegenerate
      responses:
        "200":
          description: Success
        "201":
          description: Created
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Auth — Regenerate Recovery Codes
      tags:
        - Auth
  /auth/mfa/totp:
    delete:
      operationId: deleteAuthMfaTotp
      responses:
        "204":
          description: Deleted
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Auth — Disable Totp
      tags:
        - Auth
    get:
      operationId: getAuthMfaTotp
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Auth — Totp Status
      tags:
        - Auth
  /auth/mfa/totp/confirm:
    post:
      operationId: postAuthMfaTotpConfirm
      responses:
        "200":
          description: Success
        "201":
          description: Created
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Auth — Confirm Totp
      tags:
        - Auth
  /auth/mfa/totp/setup:
    post:
      operationId: postAuthMfaTotpSetup
      responses:
        "200":
          description: Success
        "201":
          description: Created
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Auth — Setup Totp
      tags:
        - Auth
  /auth/mfa/totp/verify:
    post:
      operationId: postAuthMfaTotpVerify
      responses:
        "200":
          description: Success
        "201":
          description: Created
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Auth — Verify Totp Mfa
      tags:
        - Auth
  /auth/oauth/github:
    get:
      operationId: getAuthOauthGithub
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: OAuth — Github Redirect
      tags:
        - OAuth
  /auth/oauth/github/callback:
    get:
      operationId: getAuthOauthGithubCallback
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: OAuth — Github Callback
      tags:
        - OAuth
  /auth/oauth/google:
    get:
      operationId: getAuthOauthGoogle
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: OAuth — Google Redirect
      tags:
        - OAuth
  /auth/oauth/google/callback:
    get:
      operationId: getAuthOauthGoogleCallback
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: OAuth — Google Callback
      tags:
        - OAuth
  /auth/password/change:
    post:
      operationId: postAuthPasswordChange
      responses:
        "200":
          description: Success
        "201":
          description: Created
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Auth — Change Password
      tags:
        - Auth
  /auth/password/reset:
    post:
      operationId: postAuthPasswordReset
      responses:
        "200":
          description: Success
        "201":
          description: Created
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Auth — Request Password Reset
      tags:
        - Auth
  /auth/password/reset/confirm:
    post:
      operationId: postAuthPasswordResetConfirm
      responses:
        "200":
          description: Success
        "201":
          description: Created
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Auth — Confirm Password Reset
      tags:
        - Auth
  /auth/refresh:
    post:
      operationId: postAuthRefresh
      responses:
        "200":
          description: Success
        "201":
          description: Created
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Auth — Refresh
      tags:
        - Auth
  /auth/register:
    post:
      operationId: postAuthRegister
      responses:
        "200":
          description: Success
        "201":
          description: Created
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Auth — Register
      tags:
        - Auth
  /auth/security/activity:
    get:
      operationId: getAuthSecurityActivity
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Auth — Security Activity
      tags:
        - Auth
  /auth/sessions:
    get:
      operationId: getAuthSessions
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Auth — Sessions
      tags:
        - Auth
  /auth/sessions/{id}:
    delete:
      operationId: deleteAuthSessionsId
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        "204":
          description: Deleted
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Auth — Revoke Session
      tags:
        - Auth
  /auth/sse-ticket:
    post:
      operationId: postAuthSseTicket
      responses:
        "200":
          description: Success
        "201":
          description: Created
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: SSE — Issue Ticket
      tags:
        - SSE
  /auth/token/revoke:
    post:
      operationId: postAuthTokenRevoke
      responses:
        "200":
          description: Success
        "201":
          description: Created
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Auth — Revoke Current Token
      tags:
        - Auth
  /auth/verify:
    post:
      operationId: postAuthVerify
      responses:
        "200":
          description: Success
        "201":
          description: Created
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Auth — Verify
      tags:
        - Auth
  /billing/balance:
    get:
      operationId: getBillingBalance
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Billing — Balance
      tags:
        - Billing
  /billing/cancel:
    post:
      operationId: postBillingCancel
      responses:
        "200":
          description: Success
        "201":
          description: Created
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Billing — Cancel
      tags:
        - Billing
  /billing/checkout:
    post:
      operationId: postBillingCheckout
      responses:
        "200":
          description: Success
        "201":
          description: Created
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Billing — Create Checkout
      tags:
        - Billing
  /billing/estimate:
    get:
      operationId: getBillingEstimate
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Billing — Estimate
      tags:
        - Billing
  /billing/invoices:
    get:
      operationId: getBillingInvoices
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Billing — Invoices
      tags:
        - Billing
  /billing/invoices/{id}:
    get:
      operationId: getBillingInvoicesId
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Billing — Show Invoice
      tags:
        - Billing
  /billing/overview:
    get:
      operationId: getBillingOverview
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Billing — Overview
      tags:
        - Billing
  /billing/payment-methods:
    get:
      operationId: getBillingPaymentMethods
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Billing — Payment Methods
      tags:
        - Billing
  /billing/plans:
    get:
      operationId: getBillingPlans
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Billing — Plans
      tags:
        - Billing
  /billing/settings:
    get:
      operationId: getBillingSettings
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Billing — Get Settings
      tags:
        - Billing
    put:
      operationId: putBillingSettings
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Billing — Update Settings
      tags:
        - Billing
  /billing/subscribe:
    post:
      operationId: postBillingSubscribe
      responses:
        "200":
          description: Success
        "201":
          description: Created
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Billing — Subscribe
      tags:
        - Billing
  /billing/subscription:
    delete:
      operationId: deleteBillingSubscription
      responses:
        "204":
          description: Deleted
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Compat — Cancel Subscription
      tags:
        - Compat
    get:
      operationId: getBillingSubscription
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Compat — Get Subscription
      tags:
        - Compat
    post:
      operationId: postBillingSubscription
      responses:
        "200":
          description: Success
        "201":
          description: Created
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Compat — Create Subscription
      tags:
        - Compat
  /billing/transactions:
    get:
      operationId: getBillingTransactions
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Billing — Transactions
      tags:
        - Billing
  /billing/upcoming:
    get:
      operationId: getBillingUpcoming
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Billing — Upcoming
      tags:
        - Billing
  /builder/apps:
    get:
      operationId: getBuilderApps
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: AppDocuments — Index
      tags:
        - AppDocuments
    post:
      operationId: postBuilderApps
      responses:
        "200":
          description: Success
        "201":
          description: Created
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: AppDocuments — Create
      tags:
        - AppDocuments
  /builder/apps/{id}:
    delete:
      operationId: deleteBuilderAppsId
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        "204":
          description: Deleted
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: AppDocuments — Delete
      tags:
        - AppDocuments
    get:
      operationId: getBuilderAppsId
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: AppDocuments — Show
      tags:
        - AppDocuments
    patch:
      operationId: patchBuilderAppsId
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: AppDocuments — Update
      tags:
        - AppDocuments
  /builder/apps/{id}/approvals:
    post:
      operationId: postBuilderAppsIdApprovals
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "201":
          description: Created
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: AppDocuments — Approve
      tags:
        - AppDocuments
  /builder/apps/{id}/approvals/{approval_id}/revoke:
    post:
      operationId: postBuilderAppsIdApprovalsApprovalIdRevoke
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
        - in: path
          name: approval_id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "201":
          description: Created
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: AppDocuments — Revoke Approval
      tags:
        - AppDocuments
  /builder/apps/{id}/automation-runs:
    get:
      operationId: getBuilderAppsIdAutomationRuns
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: AppDocuments — List Automation Runs
      tags:
        - AppDocuments
  /builder/apps/{id}/automation-runs/{run_id}/claim:
    post:
      operationId: postBuilderAppsIdAutomationRunsRunIdClaim
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
        - in: path
          name: run_id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "201":
          description: Created
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: AppDocuments — Claim Automation Step
      tags:
        - AppDocuments
  /builder/apps/{id}/automation-runs/{run_id}/complete:
    post:
      operationId: postBuilderAppsIdAutomationRunsRunIdComplete
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
        - in: path
          name: run_id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "201":
          description: Created
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: AppDocuments — Complete Automation Step
      tags:
        - AppDocuments
  /builder/apps/{id}/automation-runs/{run_id}/fail:
    post:
      operationId: postBuilderAppsIdAutomationRunsRunIdFail
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
        - in: path
          name: run_id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "201":
          description: Created
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: AppDocuments — Fail Automation Step
      tags:
        - AppDocuments
  /builder/apps/{id}/automations/{automation_id}/runs:
    post:
      operationId: postBuilderAppsIdAutomationsAutomationIdRuns
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
        - in: path
          name: automation_id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "201":
          description: Created
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: AppDocuments — Start Automation Run
      tags:
        - AppDocuments
  /builder/apps/{id}/candidates:
    post:
      operationId: postBuilderAppsIdCandidates
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "201":
          description: Created
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: AppDocuments — Stage Candidate
      tags:
        - AppDocuments
  /builder/apps/{id}/components/{name}:
    get:
      operationId: getBuilderAppsIdComponentsName
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
        - in: path
          name: name
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: AppDocuments — Component
      tags:
        - AppDocuments
  /builder/apps/{id}/data/{collection}:
    get:
      operationId: getBuilderAppsIdDataCollection
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
        - in: path
          name: collection
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: AppDocuments — List Data
      tags:
        - AppDocuments
  /builder/apps/{id}/data/{collection}/{key}:
    delete:
      operationId: deleteBuilderAppsIdDataCollectionKey
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
        - in: path
          name: collection
          required: true
          schema:
            type: string
        - in: path
          name: key
          required: true
          schema:
            type: string
      responses:
        "204":
          description: Deleted
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: AppDocuments — Delete Data
      tags:
        - AppDocuments
    get:
      operationId: getBuilderAppsIdDataCollectionKey
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
        - in: path
          name: collection
          required: true
          schema:
            type: string
        - in: path
          name: key
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: AppDocuments — Get Data
      tags:
        - AppDocuments
    put:
      operationId: putBuilderAppsIdDataCollectionKey
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
        - in: path
          name: collection
          required: true
          schema:
            type: string
        - in: path
          name: key
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: AppDocuments — Put Data
      tags:
        - AppDocuments
  /builder/apps/{id}/diagnostics:
    get:
      operationId: getBuilderAppsIdDiagnostics
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: AppDocuments — Diagnostics
      tags:
        - AppDocuments
  /builder/apps/{id}/publish:
    post:
      operationId: postBuilderAppsIdPublish
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "201":
          description: Created
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: AppDocuments — Publish
      tags:
        - AppDocuments
  /builder/apps/{id}/runtime-token:
    post:
      operationId: postBuilderAppsIdRuntimeToken
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "201":
          description: Created
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: AppDocuments — Runtime Token
      tags:
        - AppDocuments
  /builder/apps/{id}/runtime/bindings/{binding_id}:
    get:
      operationId: getBuilderAppsIdRuntimeBindingsBindingId
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
        - in: path
          name: binding_id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: AppRuntime — Resolve Binding
      tags:
        - AppRuntime
  /builder/apps/{id}/runtime/data/{collection}:
    get:
      operationId: getBuilderAppsIdRuntimeDataCollection
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
        - in: path
          name: collection
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: AppRuntime — List Data
      tags:
        - AppRuntime
  /builder/apps/{id}/runtime/data/{collection}/{key}:
    delete:
      operationId: deleteBuilderAppsIdRuntimeDataCollectionKey
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
        - in: path
          name: collection
          required: true
          schema:
            type: string
        - in: path
          name: key
          required: true
          schema:
            type: string
      responses:
        "204":
          description: Deleted
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: AppRuntime — Delete Data
      tags:
        - AppRuntime
    get:
      operationId: getBuilderAppsIdRuntimeDataCollectionKey
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
        - in: path
          name: collection
          required: true
          schema:
            type: string
        - in: path
          name: key
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: AppRuntime — Get Data
      tags:
        - AppRuntime
    put:
      operationId: putBuilderAppsIdRuntimeDataCollectionKey
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
        - in: path
          name: collection
          required: true
          schema:
            type: string
        - in: path
          name: key
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: AppRuntime — Put Data
      tags:
        - AppRuntime
  /builder/sessions:
    get:
      operationId: getBuilderSessions
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: BuilderSession — Index
      tags:
        - BuilderSession
  /builder/sessions/{id}:
    delete:
      operationId: deleteBuilderSessionsId
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        "204":
          description: Deleted
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: BuilderSession — Delete
      tags:
        - BuilderSession
  /builder/sessions/{id}/title:
    patch:
      operationId: patchBuilderSessionsIdTitle
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: BuilderSession — Update Title
      tags:
        - BuilderSession
  /bulk/jobs/{job_id}:
    get:
      operationId: getBulkJobsJobId
      parameters:
        - in: path
          name: job_id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Bulk — Show Job
      tags:
        - Bulk
  /bulk/policy/apply:
    post:
      operationId: postBulkPolicyApply
      responses:
        "200":
          description: Success
        "201":
          description: Created
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Bulk — Apply Policy
      tags:
        - Bulk
  /bulk/sandboxes/{action}:
    post:
      operationId: postBulkSandboxesAction
      parameters:
        - in: path
          name: action
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "201":
          description: Created
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Bulk — Sandbox Action
      tags:
        - Bulk
  /channels:
    get:
      operationId: getChannels
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Channel — Index
      tags:
        - Channel
    post:
      operationId: postChannels
      responses:
        "200":
          description: Success
        "201":
          description: Created
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Channel — Create
      tags:
        - Channel
  /channels/notifications:
    get:
      operationId: getChannelsNotifications
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Channel — Notification Preferences
      tags:
        - Channel
    put:
      operationId: putChannelsNotifications
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Channel — Update Notification Preferences
      tags:
        - Channel
  /channels/{id}:
    delete:
      operationId: deleteChannelsId
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        "204":
          description: Deleted
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Channel — Delete
      tags:
        - Channel
    get:
      operationId: getChannelsId
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Channel — Show
      tags:
        - Channel
    patch:
      operationId: patchChannelsId
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Channel — Update
      tags:
        - Channel
    put:
      operationId: putChannelsId
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Channel — Update
      tags:
        - Channel
  /channels/{id}/disable:
    post:
      operationId: postChannelsIdDisable
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "201":
          description: Created
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Channel — Disable
      tags:
        - Channel
  /channels/{id}/enable:
    post:
      operationId: postChannelsIdEnable
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "201":
          description: Created
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Channel — Enable
      tags:
        - Channel
  /cloud/accounts:
    get:
      operationId: getCloudAccounts
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Cloud — Accounts
      tags:
        - Cloud
    post:
      operationId: postCloudAccounts
      responses:
        "200":
          description: Success
        "201":
          description: Created
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Cloud — Create Account
      tags:
        - Cloud
  /cloud/accounts/{id}/aws-role:
    post:
      operationId: postCloudAccountsIdAwsRole
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "201":
          description: Created
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Cloud — Attach Aws Role
      tags:
        - Cloud
  /cloud/accounts/{id}/gcp-workload-identity:
    post:
      operationId: postCloudAccountsIdGcpWorkloadIdentity
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "201":
          description: Created
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Cloud — Attach Gcp Workload Identity
      tags:
        - Cloud
  /cloud/capabilities:
    get:
      operationId: getCloudCapabilities
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Cloud — Capabilities
      tags:
        - Cloud
  /cloud/nodes:
    get:
      operationId: getCloudNodes
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Cloud — Nodes
      tags:
        - Cloud
  /cloud/pools:
    get:
      operationId: getCloudPools
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Cloud — Pools
      tags:
        - Cloud
    post:
      operationId: postCloudPools
      responses:
        "200":
          description: Success
        "201":
          description: Created
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Cloud — Create Pool
      tags:
        - Cloud
  /cloud/pools/{id}:
    patch:
      operationId: patchCloudPoolsId
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Cloud — Update Pool
      tags:
        - Cloud
  /cloud/pools/{pool_id}/provision:
    post:
      operationId: postCloudPoolsPoolIdProvision
      parameters:
        - in: path
          name: pool_id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "201":
          description: Created
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Cloud — Provision
      tags:
        - Cloud
  /cloud/preflights:
    get:
      operationId: getCloudPreflights
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Cloud — Preflights
      tags:
        - Cloud
    post:
      operationId: postCloudPreflights
      responses:
        "200":
          description: Success
        "201":
          description: Created
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Cloud — Record Preflight
      tags:
        - Cloud
  /cloud/regions:
    get:
      operationId: getCloudRegions
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Cloud — Regions
      tags:
        - Cloud
    post:
      operationId: postCloudRegions
      responses:
        "200":
          description: Success
        "201":
          description: Created
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Cloud — Create Region
      tags:
        - Cloud
  /cloud/regions/{id}:
    patch:
      operationId: patchCloudRegionsId
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Cloud — Update Region
      tags:
        - Cloud
  /command-center:
    get:
      operationId: getCommandCenter
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: CommandCenter — Show
      tags:
        - CommandCenter
  /command-center/agents:
    get:
      operationId: getCommandCenterAgents
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: CommandCenter — List Agents
      tags:
        - CommandCenter
  /command-center/agents/running:
    get:
      operationId: getCommandCenterAgentsRunning
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: CommandCenter — List Running Agents
      tags:
        - CommandCenter
  /command-center/events:
    get:
      operationId: getCommandCenterEvents
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: CommandCenter — Stream Events
      tags:
        - CommandCenter
  /command-center/metrics:
    get:
      operationId: getCommandCenterMetrics
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: CommandCenter — Metrics
      tags:
        - CommandCenter
  /command-center/presets:
    get:
      operationId: getCommandCenterPresets
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: CommandCenter — List Presets
      tags:
        - CommandCenter
  /command-center/tiers:
    get:
      operationId: getCommandCenterTiers
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: CommandCenter — Tiers Config
      tags:
        - CommandCenter
  /community/agents:
    get:
      operationId: getCommunityAgents
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Community — List Agents
      tags:
        - Community
  /community/agents/{id}:
    get:
      operationId: getCommunityAgentsId
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Community — Get Agent
      tags:
        - Community
  /community/templates:
    get:
      operationId: getCommunityTemplates
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Community — List Templates
      tags:
        - Community
  /community/templates/{id}:
    get:
      operationId: getCommunityTemplatesId
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Community — Get Template
      tags:
        - Community
  /community/templates/{id}/install:
    post:
      operationId: postCommunityTemplatesIdInstall
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "201":
          description: Created
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Community — Install Template
      tags:
        - Community
  /community/templates/{id}/rate:
    post:
      operationId: postCommunityTemplatesIdRate
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "201":
          description: Created
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Community — Rate Template
      tags:
        - Community
  /compute/catalog:
    get:
      operationId: getComputeCatalog
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: ComputePricing — Catalog
      tags:
        - ComputePricing
  /compute/config:
    get:
      operationId: getComputeConfig
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Compat — Get Compute Config
      tags:
        - Compat
    put:
      operationId: putComputeConfig
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Compat — Update Compute Config
      tags:
        - Compat
  /compute/estimate:
    post:
      operationId: postComputeEstimate
      responses:
        "200":
          description: Success
        "201":
          description: Created
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: ComputePricing — Estimate
      tags:
        - ComputePricing
  /compute/llm/{provider}/test:
    post:
      operationId: postComputeLlmProviderTest
      parameters:
        - in: path
          name: provider
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "201":
          description: Created
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Compat — Test Llm Key
      tags:
        - Compat
  /compute/pricing:
    get:
      operationId: getComputePricing
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: ComputePricing — List Pricing
      tags:
        - ComputePricing
  /compute/regions:
    get:
      operationId: getComputeRegions
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: ComputePricing — List Regions
      tags:
        - ComputePricing
  /compute/sizes:
    get:
      operationId: getComputeSizes
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: ComputePricing — List Sizes
      tags:
        - ComputePricing
  /compute/templates:
    get:
      operationId: getComputeTemplates
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Community — List Templates
      tags:
        - Community
  /compute/templates/{id}:
    get:
      operationId: getComputeTemplatesId
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Community — Get Template
      tags:
        - Community
  /computers:
    get:
      description: "Returns all computers belonging to the authenticated tenant. Optionally filter by `tenant_id` (admin use — requires admin JWT).\n"
      operationId: listComputers
      parameters:
        - description: Filter by tenant (admin only)
          in: query
          name: tenant_id
          required: false
          schema:
            format: uuid
            type: string
        - $ref: "#/components/parameters/LimitParam"
        - $ref: "#/components/parameters/CursorParam"
      responses:
        "200":
          content:
            application/json:
              example:
                computers:
                  - created_at: 2026-04-11T14:30:00Z
                    desktop_url: https://my-dev-computer.miosa.ai/desktop/index.html
                    id: 3fa85f64-5717-4562-b3fc-2c963f66afa6
                    name: My Dev Computer
                    size: small
                    slug: my-dev-computer
                    status: running
                    template_type: miosa-desktop
                    updated_at: 2026-04-11T15:00:00Z
                total: 1
              schema:
                properties:
                  computers:
                    items:
                      $ref: "#/components/schemas/Computer"
                    type: array
                  total:
                    description: Total number of computers in this result set
                    example: 3
                    type: integer
                required:
                  - computers
                  - total
                type: object
          description: Paginated list of computers
        "401":
          $ref: "#/components/responses/Unauthorized"
        "429":
          $ref: "#/components/responses/RateLimited"
      summary: List computers
      tags:
        - Computers
    post:
      description: "Provisions a new cloud computer. Returns `201` immediately with `status: creating`. Monitor the computer's `status` field — it transitions to `running` within 30–90 seconds.\nCredit check: creating a computer deducts credits based on the selected size. Returns `402 Payment Required` if the balance is insufficient.\n"
      operationId: createComputer
      requestBody:
        content:
          application/json:
            example:
              name: My Dev Computer
              selected_apps:
                - vscode
                - firefox
              size: small
              template_type: miosa-desktop
            schema:
              $ref: "#/components/schemas/ComputerCreate"
        required: true
      responses:
        "201":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Computer"
          description: Computer created and provisioning started
        "401":
          $ref: "#/components/responses/Unauthorized"
        "402":
          content:
            application/json:
              example:
                error:
                  code: INSUFFICIENT_CREDITS
                  message: Your credit balance is 0. Top up to create a computer.
                  type: https://docs.miosa.ai/errors/insufficient-credits
              schema:
                $ref: "#/components/schemas/ErrorResponse"
          description: Insufficient credits
        "422":
          $ref: "#/components/responses/ValidationError"
        "429":
          $ref: "#/components/responses/RateLimited"
      summary: Create a computer
      tags:
        - Computers
  /computers/{id}:
    delete:
      description: "Stops and permanently destroys the computer. This action is irreversible. All data on the computer's disk is lost.\n"
      operationId: deleteComputer
      responses:
        "200":
          content:
            application/json:
              schema:
                properties:
                  deleted:
                    example: true
                    type: boolean
                  id:
                    format: uuid
                    type: string
                required:
                  - id
                  - deleted
                type: object
          description: Computer deleted
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
      summary: Delete a computer
      tags:
        - Computers
    get:
      operationId: getComputer
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Computer"
          description: Computer object
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
      summary: Get a computer
      tags:
        - Computers
    parameters:
      - $ref: "#/components/parameters/ComputerId"
    patch:
      description: Update the name or settings of a computer.
      operationId: updateComputer
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ComputerUpdate"
        required: true
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Computer"
          description: Updated computer
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
        "422":
          $ref: "#/components/responses/ValidationError"
      summary: Update a computer
      tags:
        - Computers
    put:
      operationId: putComputersId
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Computer — Update
      tags:
        - Computer
  /computers/{id}/agent/events:
    get:
      operationId: getComputersIdAgentEvents
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: SSE — Stream Events
      tags:
        - SSE
  /computers/{id}/apps:
    get:
      description: "Returns the apps that are installed inside the computer and can be launched via `POST /computers/{id}/desktop/launch`. Each entry carries a launch identifier, display name, and (when available) an icon URL.\n"
      operationId: listApps
      responses:
        "200":
          content:
            application/json:
              example:
                apps:
                  - icon_url: https://cdn.miosa.ai/icons/vscode.png
                    id: code
                    name: Visual Studio Code
                  - icon_url: null
                    id: firefox
                    name: Firefox
              schema:
                $ref: "#/components/schemas/AppsList"
          description: List of apps
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
        "409":
          $ref: "#/components/responses/ComputerNotRunning"
        "502":
          $ref: "#/components/responses/AgentUnavailable"
      summary: List installed apps
      tags:
        - Desktop
    parameters:
      - $ref: "#/components/parameters/ComputerId"
  /computers/{id}/auto-stop:
    get:
      description: Returns the current auto-stop timeout for this computer.
      operationId: getAutoStop
      responses:
        "200":
          content:
            application/json:
              example:
                auto_stop_seconds: 3600
                enabled: true
              schema:
                $ref: "#/components/schemas/AutoStopConfig"
          description: Auto-stop configuration
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
      summary: Get auto-stop configuration
      tags:
        - Config
    parameters:
      - $ref: "#/components/parameters/ComputerId"
    patch:
      description: "Sets the auto-stop timeout. Pass `seconds: 0` or `seconds: null` to disable auto-stop.\n"
      operationId: updateAutoStop
      requestBody:
        content:
          application/json:
            schema:
              properties:
                seconds:
                  description: "Auto-stop timeout in seconds. `0` or `null` disables auto-stop. Minimum non-zero value is 60.\n"
                  example: 3600
                  minimum: 0
                  type:
                    - integer
                    - "null"
              required:
                - seconds
              type: object
        required: true
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AutoStopConfig"
          description: Auto-stop updated
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
        "422":
          $ref: "#/components/responses/ValidationError"
      summary: Update auto-stop configuration
      tags:
        - Config
  /computers/{id}/branches:
    post:
      operationId: postComputersIdBranches
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "201":
          description: Created
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Branches — Create
      tags:
        - Branches
  /computers/{id}/clone:
    parameters:
      - $ref: "#/components/parameters/ComputerId"
    post:
      description: "Creates a new computer from the current disk state of the source computer. The source must be `running` or `stopped`. The clone is provisioned with `status: creating` and transitions to `running` within 30–90 seconds.\n"
      operationId: cloneComputer
      requestBody:
        content:
          application/json:
            example:
              name: My Dev Computer (clone)
              size: small
            schema:
              $ref: "#/components/schemas/CloneRequest"
        required: true
      responses:
        "201":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Computer"
          description: Clone created and provisioning started
        "401":
          $ref: "#/components/responses/Unauthorized"
        "402":
          content:
            application/json:
              example:
                error:
                  code: INSUFFICIENT_CREDITS
                  message: Your credit balance is 0. Top up to clone a computer.
                  type: https://docs.miosa.ai/errors/insufficient-credits
              schema:
                $ref: "#/components/schemas/ErrorResponse"
          description: Insufficient credits
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
        "422":
          $ref: "#/components/responses/ValidationError"
        "429":
          $ref: "#/components/responses/RateLimited"
      summary: Clone a computer
      tags:
        - Computers
  /computers/{id}/connectors:
    get:
      operationId: getComputersIdConnectors
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: ComputerConnector — Index
      tags:
        - ComputerConnector
    post:
      operationId: postComputersIdConnectors
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "201":
          description: Created
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: ComputerConnector — Attach
      tags:
        - ComputerConnector
  /computers/{id}/connectors/preflight:
    post:
      operationId: postComputersIdConnectorsPreflight
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "201":
          description: Created
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: ComputerConnector — Preflight
      tags:
        - ComputerConnector
  /computers/{id}/connectors/sync:
    post:
      operationId: postComputersIdConnectorsSync
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "201":
          description: Created
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: ComputerConnector — Sync
      tags:
        - ComputerConnector
  /computers/{id}/connectors/{binding}:
    delete:
      operationId: deleteComputersIdConnectorsBinding
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
        - in: path
          name: binding
          required: true
          schema:
            type: string
      responses:
        "204":
          description: Deleted
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: ComputerConnector — Detach
      tags:
        - ComputerConnector
  /computers/{id}/control/sessions:
    get:
      operationId: getComputersIdControlSessions
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: ComputerControl — Index
      tags:
        - ComputerControl
    post:
      operationId: postComputersIdControlSessions
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "201":
          description: Created
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: ComputerControl — Create
      tags:
        - ComputerControl
  /computers/{id}/control/sessions/{session_id}:
    delete:
      operationId: deleteComputersIdControlSessionsSessionId
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
        - in: path
          name: session_id
          required: true
          schema:
            type: string
      responses:
        "204":
          description: Deleted
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: ComputerControl — Cancel
      tags:
        - ComputerControl
    get:
      operationId: getComputersIdControlSessionsSessionId
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
        - in: path
          name: session_id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: ComputerControl — Show
      tags:
        - ComputerControl
  /computers/{id}/control/sessions/{session_id}/approve:
    post:
      operationId: postComputersIdControlSessionsSessionIdApprove
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
        - in: path
          name: session_id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "201":
          description: Created
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: ComputerControl — Approve
      tags:
        - ComputerControl
  /computers/{id}/control/sessions/{session_id}/events:
    get:
      operationId: getComputersIdControlSessionsSessionIdEvents
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
        - in: path
          name: session_id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: ComputerControl — Events
      tags:
        - ComputerControl
  /computers/{id}/control/sessions/{session_id}/pause:
    post:
      operationId: postComputersIdControlSessionsSessionIdPause
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
        - in: path
          name: session_id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "201":
          description: Created
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: ComputerControl — Pause
      tags:
        - ComputerControl
  /computers/{id}/control/sessions/{session_id}/resume:
    post:
      operationId: postComputersIdControlSessionsSessionIdResume
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
        - in: path
          name: session_id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "201":
          description: Created
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: ComputerControl — Resume
      tags:
        - ComputerControl
  /computers/{id}/control/sessions/{session_id}/sse-ticket:
    post:
      operationId: postComputersIdControlSessionsSessionIdSseTicket
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
        - in: path
          name: session_id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "201":
          description: Created
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: ComputerControl — Issue Sse Ticket
      tags:
        - ComputerControl
  /computers/{id}/control/sessions/{session_id}/task:
    post:
      operationId: postComputersIdControlSessionsSessionIdTask
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
        - in: path
          name: session_id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "201":
          description: Created
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: ComputerControl — Task
      tags:
        - ComputerControl
  /computers/{id}/desktop/accessibility-tree:
    get:
      operationId: getComputersIdDesktopAccessibilityTree
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Desktop — Desktop Accessibility Tree
      tags:
        - Desktop
  /computers/{id}/desktop/branding/reapply:
    post:
      operationId: postComputersIdDesktopBrandingReapply
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "201":
          description: Created
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Desktop — Desktop Reapply Branding
      tags:
        - Desktop
  /computers/{id}/desktop/click:
    parameters:
      - $ref: "#/components/parameters/ComputerId"
    post:
      description: Performs a mouse click at the specified desktop coordinates.
      operationId: desktopClick
      requestBody:
        content:
          application/json:
            schema:
              properties:
                button:
                  default: left
                  description: Mouse button to click (defaults to `left`)
                  enum:
                    - left
                    - right
                    - middle
                  type: string
                double:
                  default: false
                  description: Whether to perform a double-click
                  type: boolean
                x:
                  description: Horizontal coordinate in pixels
                  example: 960
                  minimum: 0
                  type: integer
                y:
                  description: Vertical coordinate in pixels
                  example: 540
                  minimum: 0
                  type: integer
              required:
                - x
                - y
              type: object
        required: true
      responses:
        "200":
          content:
            application/json:
              schema:
                properties:
                  success:
                    example: true
                    type: boolean
                type: object
          description: Click executed
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
        "409":
          $ref: "#/components/responses/ComputerNotRunning"
        "502":
          $ref: "#/components/responses/AgentUnavailable"
      summary: Click the mouse
      tags:
        - Desktop
  /computers/{id}/desktop/clipboard:
    get:
      operationId: getComputersIdDesktopClipboard
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Desktop — Desktop Get Clipboard
      tags:
        - Desktop
    post:
      operationId: postComputersIdDesktopClipboard
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "201":
          description: Created
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Desktop — Desktop Set Clipboard
      tags:
        - Desktop
  /computers/{id}/desktop/cursor:
    get:
      description: Returns the current mouse cursor coordinates on the desktop.
      operationId: desktopCursor
      responses:
        "200":
          content:
            application/json:
              schema:
                properties:
                  x:
                    description: Horizontal position in pixels
                    example: 960
                    type: integer
                  y:
                    description: Vertical position in pixels
                    example: 540
                    type: integer
                required:
                  - x
                  - y
                type: object
          description: Cursor coordinates
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
        "409":
          $ref: "#/components/responses/ComputerNotRunning"
        "502":
          $ref: "#/components/responses/AgentUnavailable"
      summary: Get cursor position
      tags:
        - Desktop
    parameters:
      - $ref: "#/components/parameters/ComputerId"
  /computers/{id}/desktop/double-click:
    parameters:
      - $ref: "#/components/parameters/ComputerId"
    post:
      description: Performs a double-click at the specified coordinates.
      operationId: desktopDoubleClick
      requestBody:
        content:
          application/json:
            schema:
              properties:
                x:
                  example: 960
                  minimum: 0
                  type: integer
                y:
                  example: 540
                  minimum: 0
                  type: integer
              required:
                - x
                - y
              type: object
        required: true
      responses:
        "200":
          content:
            application/json:
              schema:
                properties:
                  success:
                    example: true
                    type: boolean
                type: object
          description: Double-click executed
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
        "409":
          $ref: "#/components/responses/ComputerNotRunning"
        "502":
          $ref: "#/components/responses/AgentUnavailable"
      summary: Double-click the mouse
      tags:
        - Desktop
  /computers/{id}/desktop/drag:
    parameters:
      - $ref: "#/components/parameters/ComputerId"
    post:
      description: Performs a mouse drag from one coordinate to another.
      operationId: desktopDrag
      requestBody:
        content:
          application/json:
            schema:
              properties:
                from_x:
                  description: Starting X coordinate
                  example: 100
                  minimum: 0
                  type: integer
                from_y:
                  description: Starting Y coordinate
                  example: 200
                  minimum: 0
                  type: integer
                to_x:
                  description: Ending X coordinate
                  example: 500
                  minimum: 0
                  type: integer
                to_y:
                  description: Ending Y coordinate
                  example: 400
                  minimum: 0
                  type: integer
              required:
                - from_x
                - from_y
                - to_x
                - to_y
              type: object
        required: true
      responses:
        "200":
          content:
            application/json:
              schema:
                properties:
                  success:
                    example: true
                    type: boolean
                type: object
          description: Drag executed
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
        "409":
          $ref: "#/components/responses/ComputerNotRunning"
        "502":
          $ref: "#/components/responses/AgentUnavailable"
      summary: Click and drag
      tags:
        - Desktop
  /computers/{id}/desktop/environment:
    get:
      operationId: getComputersIdDesktopEnvironment
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Desktop — Desktop Environment
      tags:
        - Desktop
  /computers/{id}/desktop/hotkey:
    post:
      operationId: postComputersIdDesktopHotkey
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "201":
          description: Created
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Desktop — Desktop Hotkey
      tags:
        - Desktop
  /computers/{id}/desktop/key:
    parameters:
      - $ref: "#/components/parameters/ComputerId"
    post:
      description: "Sends one or more key events using X11 key notation. Combinations are expressed with `+` as separator.\n**Examples:** `Enter`, `Escape`, `ctrl+c`, `ctrl+shift+t`, `super+d`, `alt+F4`, `ctrl+alt+Delete`\n"
      operationId: desktopKey
      requestBody:
        content:
          application/json:
            schema:
              properties:
                key:
                  description: Key name or combination in X11 notation
                  example: ctrl+c
                  type: string
              required:
                - key
              type: object
        required: true
      responses:
        "200":
          content:
            application/json:
              schema:
                properties:
                  success:
                    example: true
                    type: boolean
                type: object
          description: Key sent
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
        "409":
          $ref: "#/components/responses/ComputerNotRunning"
        "502":
          $ref: "#/components/responses/AgentUnavailable"
      summary: Send a key combination
      tags:
        - Desktop
  /computers/{id}/desktop/key-down:
    post:
      operationId: postComputersIdDesktopKeyDown
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "201":
          description: Created
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Desktop — Desktop Key Down
      tags:
        - Desktop
  /computers/{id}/desktop/key-up:
    post:
      operationId: postComputersIdDesktopKeyUp
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "201":
          description: Created
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Desktop — Desktop Key Up
      tags:
        - Desktop
  /computers/{id}/desktop/launch:
    parameters:
      - $ref: "#/components/parameters/ComputerId"
    post:
      description: Launches the named application on the desktop.
      operationId: desktopLaunch
      requestBody:
        content:
          application/json:
            schema:
              properties:
                app_name:
                  description: Application name or command to launch
                  example: firefox
                  type: string
              required:
                - app_name
              type: object
        required: true
      responses:
        "200":
          content:
            application/json:
              schema:
                properties:
                  success:
                    example: true
                    type: boolean
                type: object
          description: Application launched
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
        "409":
          $ref: "#/components/responses/ComputerNotRunning"
        "502":
          $ref: "#/components/responses/AgentUnavailable"
      summary: Launch an application
      tags:
        - Desktop
  /computers/{id}/desktop/mouse-down:
    post:
      operationId: postComputersIdDesktopMouseDown
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "201":
          description: Created
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Desktop — Desktop Mouse Down
      tags:
        - Desktop
  /computers/{id}/desktop/mouse-up:
    post:
      operationId: postComputersIdDesktopMouseUp
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "201":
          description: Created
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Desktop — Desktop Mouse Up
      tags:
        - Desktop
  /computers/{id}/desktop/move:
    post:
      operationId: postComputersIdDesktopMove
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "201":
          description: Created
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Desktop — Desktop Move
      tags:
        - Desktop
  /computers/{id}/desktop/screen-size:
    get:
      operationId: getComputersIdDesktopScreenSize
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Desktop — Desktop Screen Size
      tags:
        - Desktop
  /computers/{id}/desktop/screenshot:
    get:
      description: "Captures the current desktop state and returns a PNG image. The `Content-Type` is `image/png`.\n"
      operationId: desktopScreenshot
      responses:
        "200":
          content:
            image/png:
              schema:
                format: binary
                type: string
          description: PNG screenshot of the desktop
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
        "409":
          $ref: "#/components/responses/ComputerNotRunning"
        "502":
          $ref: "#/components/responses/AgentUnavailable"
      summary: Take a screenshot
      tags:
        - Desktop
    parameters:
      - $ref: "#/components/parameters/ComputerId"
  /computers/{id}/desktop/screenshot/region:
    parameters:
      - $ref: "#/components/parameters/ComputerId"
    post:
      description: Captures a rectangular region of the desktop as a PNG image.
      operationId: desktopScreenshotRegion
      requestBody:
        content:
          application/json:
            schema:
              properties:
                height:
                  description: Height of the region in pixels
                  example: 600
                  minimum: 1
                  type: integer
                width:
                  description: Width of the region in pixels
                  example: 800
                  minimum: 1
                  type: integer
                x:
                  description: Left edge of the region in pixels
                  example: 100
                  minimum: 0
                  type: integer
                y:
                  description: Top edge of the region in pixels
                  example: 200
                  minimum: 0
                  type: integer
              required:
                - x
                - y
                - width
                - height
              type: object
        required: true
      responses:
        "200":
          content:
            image/png:
              schema:
                format: binary
                type: string
          description: PNG screenshot of the requested region
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
        "409":
          $ref: "#/components/responses/ComputerNotRunning"
        "502":
          $ref: "#/components/responses/AgentUnavailable"
      summary: Screenshot a region
      tags:
        - Desktop
  /computers/{id}/desktop/scroll:
    parameters:
      - $ref: "#/components/parameters/ComputerId"
    post:
      description: Scrolls at the given coordinates in the specified direction.
      operationId: desktopScroll
      requestBody:
        content:
          application/json:
            schema:
              properties:
                clicks:
                  default: 3
                  description: Number of scroll clicks (default 3)
                  example: 3
                  maximum: 20
                  minimum: 1
                  type: integer
                direction:
                  description: Scroll direction
                  enum:
                    - up
                    - down
                    - left
                    - right
                  example: down
                  type: string
                x:
                  description: "Horizontal coordinate to scroll at (defaults to current cursor position)\n"
                  example: 960
                  minimum: 0
                  type: integer
                y:
                  description: "Vertical coordinate to scroll at (defaults to current cursor position)\n"
                  example: 540
                  minimum: 0
                  type: integer
              required:
                - direction
              type: object
        required: true
      responses:
        "200":
          content:
            application/json:
              schema:
                properties:
                  success:
                    example: true
                    type: boolean
                type: object
          description: Scroll executed
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
        "409":
          $ref: "#/components/responses/ComputerNotRunning"
        "502":
          $ref: "#/components/responses/AgentUnavailable"
      summary: Scroll the mouse wheel
      tags:
        - Desktop
  /computers/{id}/desktop/type:
    parameters:
      - $ref: "#/components/parameters/ComputerId"
    post:
      description: "Types the given text as keyboard input. Text is sent character by character to the active window. Use `delay` to slow down fast typing if the target application cannot keep up.\n"
      operationId: desktopType
      requestBody:
        content:
          application/json:
            schema:
              properties:
                delay:
                  default: 0
                  description: Milliseconds to wait between each character (default 0)
                  example: 50
                  maximum: 1000
                  minimum: 0
                  type: integer
                text:
                  description: Text to type
                  example: Hello, World!
                  type: string
              required:
                - text
              type: object
        required: true
      responses:
        "200":
          content:
            application/json:
              schema:
                properties:
                  success:
                    example: true
                    type: boolean
                type: object
          description: Text typed
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
        "409":
          $ref: "#/components/responses/ComputerNotRunning"
        "502":
          $ref: "#/components/responses/AgentUnavailable"
      summary: Type text
      tags:
        - Desktop
  /computers/{id}/desktop/wait:
    parameters:
      - $ref: "#/components/parameters/ComputerId"
    post:
      description: "Pauses your automation for the specified number of seconds. Maximum wait is 30 seconds. Useful when polling for UI changes.\n"
      operationId: desktopWait
      requestBody:
        content:
          application/json:
            schema:
              properties:
                seconds:
                  description: Seconds to wait (fractional values accepted)
                  example: 2
                  maximum: 30
                  minimum: 0.1
                  type: number
              required:
                - seconds
              type: object
        required: true
      responses:
        "200":
          content:
            application/json:
              schema:
                properties:
                  success:
                    example: true
                    type: boolean
                  waited_seconds:
                    example: 2
                    type: number
                required:
                  - success
                  - waited_seconds
                type: object
          description: Wait completed
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
        "409":
          $ref: "#/components/responses/ComputerNotRunning"
      summary: Wait (pause execution)
      tags:
        - Desktop
  /computers/{id}/desktop/wallpaper:
    post:
      operationId: postComputersIdDesktopWallpaper
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "201":
          description: Created
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Desktop — Desktop Wallpaper
      tags:
        - Desktop
  /computers/{id}/desktop/window/focus:
    parameters:
      - $ref: "#/components/parameters/ComputerId"
    post:
      description: Brings the specified window to the foreground and gives it keyboard focus.
      operationId: desktopWindowFocus
      requestBody:
        content:
          application/json:
            schema:
              properties:
                window_id:
                  description: Window ID from `GET /desktop/windows`
                  example: 65011716
                  type: string
              required:
                - window_id
              type: object
        required: true
      responses:
        "200":
          content:
            application/json:
              schema:
                properties:
                  success:
                    example: true
                    type: boolean
                type: object
          description: Window focused
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
        "409":
          $ref: "#/components/responses/ComputerNotRunning"
        "502":
          $ref: "#/components/responses/AgentUnavailable"
      summary: Focus a window
      tags:
        - Desktop
  /computers/{id}/desktop/window/{window_id}/close:
    post:
      operationId: postComputersIdDesktopWindowWindowIdClose
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
        - in: path
          name: window_id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "201":
          description: Created
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Desktop — Desktop Window Close
      tags:
        - Desktop
  /computers/{id}/desktop/window/{window_id}/maximize:
    post:
      operationId: postComputersIdDesktopWindowWindowIdMaximize
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
        - in: path
          name: window_id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "201":
          description: Created
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Desktop — Desktop Window Maximize
      tags:
        - Desktop
  /computers/{id}/desktop/window/{window_id}/minimize:
    post:
      operationId: postComputersIdDesktopWindowWindowIdMinimize
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
        - in: path
          name: window_id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "201":
          description: Created
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Desktop — Desktop Window Minimize
      tags:
        - Desktop
  /computers/{id}/desktop/window/{window_id}/move:
    post:
      operationId: postComputersIdDesktopWindowWindowIdMove
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
        - in: path
          name: window_id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "201":
          description: Created
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Desktop — Desktop Window Move
      tags:
        - Desktop
  /computers/{id}/desktop/window/{window_id}/position:
    get:
      operationId: getComputersIdDesktopWindowWindowIdPosition
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
        - in: path
          name: window_id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Desktop — Desktop Window Position
      tags:
        - Desktop
  /computers/{id}/desktop/window/{window_id}/resize:
    post:
      operationId: postComputersIdDesktopWindowWindowIdResize
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
        - in: path
          name: window_id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "201":
          description: Created
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Desktop — Desktop Window Resize
      tags:
        - Desktop
  /computers/{id}/desktop/window/{window_id}/size:
    get:
      operationId: getComputersIdDesktopWindowWindowIdSize
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
        - in: path
          name: window_id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Desktop — Desktop Window Size
      tags:
        - Desktop
  /computers/{id}/desktop/windows:
    get:
      description: Returns all currently open windows on the desktop.
      operationId: desktopWindows
      responses:
        "200":
          content:
            application/json:
              schema:
                properties:
                  windows:
                    items:
                      $ref: "#/components/schemas/WindowInfo"
                    type: array
                required:
                  - windows
                type: object
          description: List of windows
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
        "409":
          $ref: "#/components/responses/ComputerNotRunning"
        "502":
          $ref: "#/components/responses/AgentUnavailable"
      summary: List open windows
      tags:
        - Desktop
    parameters:
      - $ref: "#/components/parameters/ComputerId"
  /computers/{id}/domains:
    get:
      description: Returns all custom domains attached to the computer.
      operationId: listDomains
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CustomDomainListResponse"
          description: List of custom domains
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
      summary: List custom domains
      tags:
        - CustomDomains
    parameters:
      - $ref: "#/components/parameters/ComputerId"
    post:
      description: "Attaches a custom hostname to the computer and issues a verification challenge. The domain is not live until verification succeeds — call `POST /computers/{id}/domains/{domain_id}/verify` after placing the DNS record or HTTP file.\n"
      operationId: createDomain
      requestBody:
        content:
          application/json:
            example:
              hostname: app.example.com
              target_port: 3000
              verification_method: dns_txt
            schema:
              $ref: "#/components/schemas/CustomDomainCreateRequest"
        required: true
      responses:
        "201":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CustomDomain"
          description: Domain attached, verification pending
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
        "409":
          content:
            application/json:
              example:
                error:
                  code: DOMAIN_CONFLICT
                  message: app.example.com is already attached to another computer
                  type: https://docs.miosa.ai/errors/domain-conflict
              schema:
                $ref: "#/components/schemas/ErrorResponse"
          description: This hostname is already attached to a computer
        "422":
          $ref: "#/components/responses/ValidationError"
      summary: Attach a custom domain
      tags:
        - CustomDomains
  /computers/{id}/domains/{domain_id}:
    delete:
      description: "Removes the custom domain from the computer and deprovisions the routing rule. Active traffic to the hostname will receive `502` until DNS is updated.\n"
      operationId: deleteDomain
      responses:
        "200":
          content:
            application/json:
              schema:
                properties:
                  deleted:
                    example: true
                    type: boolean
                  id:
                    format: uuid
                    type: string
                required:
                  - id
                  - deleted
                type: object
          description: Domain detached
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
      summary: Detach a custom domain
      tags:
        - CustomDomains
    parameters:
      - $ref: "#/components/parameters/ComputerId"
      - $ref: "#/components/parameters/DomainId"
  /computers/{id}/domains/{domain_id}/verify:
    parameters:
      - $ref: "#/components/parameters/ComputerId"
      - $ref: "#/components/parameters/DomainId"
    post:
      description: "Checks that the DNS TXT record or HTTP file challenge is in place for the domain. On success the domain transitions to `active`. Returns the updated domain object with the current `status`.\n"
      operationId: verifyDomain
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CustomDomain"
          description: Verification attempted — check `status` in the response
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
        "422":
          content:
            application/json:
              example:
                error:
                  code: DOMAIN_VERIFICATION_FAILED
                  message: DNS TXT record not found for app.example.com
                  type: https://docs.miosa.ai/errors/domain-verification-failed
              schema:
                $ref: "#/components/schemas/ErrorResponse"
          description: Verification failed — challenge not found
      summary: Trigger domain verification
      tags:
        - CustomDomains
  /computers/{id}/embed:
    get:
      operationId: getComputersIdEmbed
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Connection — Embed
      tags:
        - Connection
  /computers/{id}/enter:
    post:
      operationId: postComputersIdEnter
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "201":
          description: Created
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Connection — Enter
      tags:
        - Connection
  /computers/{id}/env:
    get:
      operationId: getComputersIdEnv
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: EnvVars — Index
      tags:
        - EnvVars
    post:
      operationId: postComputersIdEnv
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "201":
          description: Created
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: EnvVars — Create
      tags:
        - EnvVars
  /computers/{id}/env/{name}:
    delete:
      operationId: deleteComputersIdEnvName
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
        - in: path
          name: name
          required: true
          schema:
            type: string
      responses:
        "204":
          description: Deleted
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: EnvVars — Delete
      tags:
        - EnvVars
    patch:
      operationId: patchComputersIdEnvName
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
        - in: path
          name: name
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: EnvVars — Update
      tags:
        - EnvVars
  /computers/{id}/events:
    get:
      description: "Opens a WebSocket that emits real-time lifecycle and status events for the computer. The connection requires an HTTP `Upgrade: websocket` handshake.\n**Authentication:** Pass `?auth=<stream_token>` — obtain the token from `POST /computers/{id}/stream-token`.\n**Server-to-client message format (JSON text frames):**\n```json {\n  \"event\": \"status_changed\",\n  \"data\": {\n    \"computer_id\": \"3fa85f64-...\",\n    \"status\": \"running\",\n    \"previous_status\": \"provisioning\",\n    \"timestamp\": \"2026-04-11T14:30:00Z\"\n  }\n} ```\n**Event types:**\n| Event | When | |-------|------| | `status_changed` | Computer transitions to a new lifecycle state | | `agent_status_changed` | In-VM OSA agent status changes | | `credits_low` | Credit balance falls below 10% of plan allowance | | `credits_exhausted` | Credit balance reaches 0; computer will be paused | | `auto_stop_warning` | Computer will auto-stop in 5 minutes | | `auto_stop` | Computer auto-stopped due to inactivity timeout |\nThe server closes the WebSocket with code `1000` when the computer is deleted.\n"
      operationId: streamComputerEvents
      parameters:
        - description: Short-lived stream token from `POST /computers/{id}/stream-token`
          in: query
          name: auth
          required: true
          schema:
            example: tok_aBcDeFgHiJkLmNoPqRsT
            type: string
      responses:
        "101":
          description: Switching protocols — WebSocket connection established
        "200":
          content:
            application/json:
              schema:
                properties:
                  message:
                    example: WebSocket upgrade required
                    type: string
                type: object
          description: "Not returned in practice — the server always upgrades to WebSocket (101). Included to satisfy tooling that requires a 2XX response.\n"
        "401":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
          description: Missing or invalid auth token
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
      summary: Stream computer events (WebSocket)
      tags:
        - Streaming
      x-websocket: true
    parameters:
      - $ref: "#/components/parameters/ComputerId"
  /computers/{id}/exec:
    parameters:
      - $ref: "#/components/parameters/ComputerId"
    post:
      description: "Runs a shell command inside the computer and returns the output. Commands run as the `ubuntu` user in the home directory. The default timeout is 30 seconds; maximum is 300 seconds.\n"
      operationId: exec
      requestBody:
        content:
          application/json:
            schema:
              properties:
                command:
                  description: Shell command to execute
                  example: ls -la /home/user
                  type: string
                timeout:
                  default: 30
                  description: Timeout in seconds (default 30, max 300)
                  example: 30
                  maximum: 300
                  minimum: 1
                  type: integer
              required:
                - command
              type: object
        required: true
      responses:
        "200":
          content:
            application/json:
              example:
                exit_code: 0
                output: "total 12\ndrwxr-xr-x 2 ubuntu ubuntu 4096 Apr 11 14:30 .\n"
                success: true
              schema:
                $ref: "#/components/schemas/ExecResult"
          description: Command executed
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
        "409":
          $ref: "#/components/responses/ComputerNotRunning"
        "502":
          $ref: "#/components/responses/AgentUnavailable"
      summary: Execute a shell command
      tags:
        - Exec
  /computers/{id}/exec/python:
    parameters:
      - $ref: "#/components/parameters/ComputerId"
    post:
      description: "Runs Python 3 code inside the computer. The code is written to a temporary file and executed with `python3`. The default timeout is 30 seconds; maximum is 300 seconds.\n"
      operationId: execPython
      requestBody:
        content:
          application/json:
            schema:
              properties:
                code:
                  description: Python source code to execute
                  example: "import os\nprint(os.getcwd())\n"
                  type: string
                timeout:
                  default: 30
                  description: Timeout in seconds (default 30, max 300)
                  example: 30
                  maximum: 300
                  minimum: 1
                  type: integer
              required:
                - code
              type: object
        required: true
      responses:
        "200":
          content:
            application/json:
              example:
                exit_code: 0
                output: "/home/ubuntu\n"
                success: true
              schema:
                $ref: "#/components/schemas/ExecResult"
          description: Python executed
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
        "409":
          $ref: "#/components/responses/ComputerNotRunning"
        "502":
          $ref: "#/components/responses/AgentUnavailable"
      summary: Execute Python code
      tags:
        - Exec
  /computers/{id}/exec/stream:
    get:
      description: "Opens a bidirectional WebSocket for interactive shell execution inside the computer. The connection requires an HTTP `Upgrade: websocket` handshake.\n**Authentication:** Pass `?auth=<stream_token>` — obtain the token from `POST /computers/{id}/stream-token`.\n**Frame protocol (binary frames):**\n| Byte 0 | Direction | Payload | |--------|-----------|---------| | `0x01` | client→server | UTF-8 stdin data | | `0x02` | client→server | JSON control: `{\"type\":\"resize\",\"cols\":N,\"rows\":N}` | | `0x11` | server→client | UTF-8 stdout data | | `0x12` | server→client | UTF-8 stderr data | | `0x13` | server→client | JSON control: `{\"type\":\"exit\",\"code\":N}` |\nText frames may also be used; in that case the byte-prefix convention is omitted and the frame is treated as raw stdin.\nThe server closes the WebSocket with code `1000` when the process exits.\n"
      operationId: execStream
      parameters:
        - description: Short-lived stream token from `POST /computers/{id}/stream-token`
          in: query
          name: auth
          required: true
          schema:
            example: tok_aBcDeFgHiJkLmNoPqRsT
            type: string
        - description: "Initial command to run. Defaults to the user's login shell.\n"
          in: query
          name: command
          required: false
          schema:
            example: bash
            type: string
        - description: Initial terminal width in columns (default 80)
          in: query
          name: cols
          required: false
          schema:
            default: 80
            minimum: 1
            type: integer
        - description: Initial terminal height in rows (default 24)
          in: query
          name: rows
          required: false
          schema:
            default: 24
            minimum: 1
            type: integer
      responses:
        "101":
          description: Switching protocols — WebSocket connection established
        "200":
          content:
            application/json:
              schema:
                properties:
                  message:
                    example: WebSocket upgrade required
                    type: string
                type: object
          description: "Not returned in practice — the server always upgrades to WebSocket (101). Included to satisfy tooling that requires a 2XX response.\n"
        "401":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
          description: Missing or invalid auth token
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
        "409":
          $ref: "#/components/responses/ComputerNotRunning"
      summary: Exec streaming session (WebSocket)
      tags:
        - Streaming
      x-websocket: true
    parameters:
      - $ref: "#/components/parameters/ComputerId"
  /computers/{id}/files:
    delete:
      description: Deletes a file at the given path inside the computer.
      operationId: deleteFile
      requestBody:
        content:
          application/json:
            schema:
              properties:
                path:
                  description: Absolute path to the file to delete
                  example: /home/user/old-script.py
                  type: string
              required:
                - path
              type: object
        required: true
      responses:
        "200":
          content:
            application/json:
              schema:
                properties:
                  path:
                    example: /home/user/old-script.py
                    type: string
                  success:
                    example: true
                    type: boolean
                required:
                  - success
                  - path
                type: object
          description: File deleted
        "400":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
          description: Path is missing or forbidden
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
        "409":
          $ref: "#/components/responses/ComputerNotRunning"
        "502":
          $ref: "#/components/responses/AgentUnavailable"
      summary: Delete a file
      tags:
        - Files
    get:
      description: "Lists files and directories at the given path inside the computer. Paths must be under `/home/user`, `/home/ubuntu`, or `/tmp`.\n"
      operationId: listFiles
      parameters:
        - description: Directory path to list (defaults to `/home/user`)
          in: query
          name: path
          required: false
          schema:
            default: /home/user
            example: /home/user/projects
            type: string
      responses:
        "200":
          content:
            application/json:
              example:
                files:
                  - modified_at: 2026-04-11T12:00:00Z
                    name: app.py
                    size_bytes: 2048
                    type: file
                  - modified_at: 2026-04-10T09:00:00Z
                    name: data
                    size_bytes: 0
                    type: directory
                path: /home/user/projects
              schema:
                properties:
                  files:
                    items:
                      $ref: "#/components/schemas/FileInfo"
                    type: array
                  path:
                    description: The directory that was listed
                    example: /home/user/projects
                    type: string
                required:
                  - files
                  - path
                type: object
          description: File listing
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
        "409":
          $ref: "#/components/responses/ComputerNotRunning"
        "502":
          $ref: "#/components/responses/AgentUnavailable"
      summary: List files
      tags:
        - Files
    parameters:
      - $ref: "#/components/parameters/ComputerId"
  /computers/{id}/files/chmod:
    parameters:
      - $ref: "#/components/parameters/ComputerId"
    post:
      description: Changes the Unix permission bits of a file or directory.
      operationId: chmodFile
      requestBody:
        content:
          application/json:
            schema:
              properties:
                mode:
                  description: Unix file mode in octal notation
                  example: "0755"
                  pattern: ^[0-7]{3,4}$
                  type: string
                path:
                  description: Absolute path to the file or directory
                  example: /home/user/app/run.sh
                  type: string
                recursive:
                  default: false
                  description: Apply recursively to directories
                  type: boolean
              required:
                - path
                - mode
              type: object
        required: true
      responses:
        "200":
          content:
            application/json:
              schema:
                properties:
                  mode:
                    example: "0755"
                    type: string
                  path:
                    example: /home/user/app/run.sh
                    type: string
                required:
                  - path
                  - mode
                type: object
          description: Permissions changed
        "400":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
          description: Path does not exist or mode is invalid
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
        "409":
          $ref: "#/components/responses/ComputerNotRunning"
        "502":
          $ref: "#/components/responses/AgentUnavailable"
      summary: Change file permissions
      tags:
        - Files
  /computers/{id}/files/copy:
    parameters:
      - $ref: "#/components/parameters/ComputerId"
    post:
      description: Copies a file or directory to a new path inside the computer.
      operationId: copyFile
      requestBody:
        content:
          application/json:
            example:
              destination: /home/user/copy.py
              source: /home/user/template.py
            schema:
              $ref: "#/components/schemas/CopyRequest"
        required: true
      responses:
        "200":
          content:
            application/json:
              schema:
                properties:
                  destination:
                    example: /home/user/copy.py
                    type: string
                  source:
                    example: /home/user/template.py
                    type: string
                required:
                  - source
                  - destination
                type: object
          description: File copied
        "400":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
          description: Source does not exist or destination conflict
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
        "409":
          $ref: "#/components/responses/ComputerNotRunning"
        "502":
          $ref: "#/components/responses/AgentUnavailable"
      summary: Copy a file or directory
      tags:
        - Files
  /computers/{id}/files/download:
    get:
      description: "Downloads a file from the computer. The response `Content-Type` is inferred from the file extension. The `Content-Disposition` header includes the filename for browser downloads.\n"
      operationId: downloadFile
      parameters:
        - description: Absolute path to the file inside the computer
          in: query
          name: path
          required: true
          schema:
            example: /home/user/report.pdf
            type: string
      responses:
        "200":
          content:
            application/octet-stream:
              schema:
                format: binary
                type: string
          description: File content
          headers:
            Content-Disposition:
              example: attachment; filename="report.pdf"
              schema:
                type: string
            Content-Type:
              example: application/pdf
              schema:
                type: string
        "400":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
          description: Path parameter missing or forbidden
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
        "409":
          $ref: "#/components/responses/ComputerNotRunning"
        "502":
          $ref: "#/components/responses/AgentUnavailable"
      summary: Download a file
      tags:
        - Files
    parameters:
      - $ref: "#/components/parameters/ComputerId"
  /computers/{id}/files/export:
    parameters:
      - $ref: "#/components/parameters/ComputerId"
    post:
      description: "Exports a file from the computer as a base64-encoded JSON payload. Useful when you need the file content inline without a streaming download. For large files prefer `GET /files/download`.\n"
      operationId: exportFile
      requestBody:
        content:
          application/json:
            schema:
              properties:
                path:
                  description: Absolute path to the file inside the computer
                  example: /home/user/output.json
                  type: string
              required:
                - path
              type: object
        required: true
      responses:
        "200":
          content:
            application/json:
              schema:
                properties:
                  content_base64:
                    description: Base64-encoded file content
                    example: eyJyZXN1bHQiOiAib2sifQ==
                    type: string
                  file:
                    properties:
                      content_type:
                        example: application/json
                        type: string
                      filename:
                        example: output.json
                        type: string
                      modified_at:
                        format: date-time
                        type: string
                      path:
                        example: /home/user/output.json
                        type: string
                      size_bytes:
                        example: 512
                        type: integer
                    required:
                      - path
                      - filename
                      - size_bytes
                      - content_type
                    type: object
                  success:
                    example: true
                    type: boolean
                required:
                  - success
                  - file
                  - content_base64
                type: object
          description: File exported as base64
        "400":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
          description: Path missing or forbidden
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
          description: File not found or empty
        "409":
          $ref: "#/components/responses/ComputerNotRunning"
        "502":
          $ref: "#/components/responses/AgentUnavailable"
      summary: Export a file (base64)
      tags:
        - Files
  /computers/{id}/files/mkdir:
    parameters:
      - $ref: "#/components/parameters/ComputerId"
    post:
      description: Creates a directory at the given path inside the computer.
      operationId: mkdir
      requestBody:
        content:
          application/json:
            example:
              parents: true
              path: /home/user/projects/new-dir
            schema:
              $ref: "#/components/schemas/MkdirRequest"
        required: true
      responses:
        "200":
          content:
            application/json:
              schema:
                properties:
                  created:
                    example: true
                    type: boolean
                  path:
                    example: /home/user/projects/new-dir
                    type: string
                required:
                  - path
                  - created
                type: object
          description: Directory created
        "400":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
          description: Path already exists and `exist_ok` is false
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
        "409":
          $ref: "#/components/responses/ComputerNotRunning"
        "502":
          $ref: "#/components/responses/AgentUnavailable"
      summary: Create a directory
      tags:
        - Files
  /computers/{id}/files/readdir:
    get:
      description: "Returns the immediate children of a directory, including their type, size, and modification time. Use `POST /computers/{id}/files/stat` for detailed metadata on individual entries.\n"
      operationId: readdir
      parameters:
        - description: Absolute path of the directory to list
          in: query
          name: path
          required: true
          schema:
            example: /home/user/app
            type: string
      responses:
        "200":
          content:
            application/json:
              example:
                entries:
                  - modified_at: 2026-04-11T12:00:00Z
                    name: server.py
                    path: /home/user/app/server.py
                    size_bytes: 2048
                    type: file
                  - modified_at: 2026-04-10T09:00:00Z
                    name: static
                    path: /home/user/app/static
                    size_bytes: 0
                    type: directory
                path: /home/user/app
              schema:
                properties:
                  entries:
                    items:
                      $ref: "#/components/schemas/DirEntry"
                    type: array
                  path:
                    description: The directory that was listed
                    example: /home/user/app
                    type: string
                required:
                  - path
                  - entries
                type: object
          description: Directory entries
        "400":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
          description: Path is not a directory
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
        "409":
          $ref: "#/components/responses/ComputerNotRunning"
        "502":
          $ref: "#/components/responses/AgentUnavailable"
      summary: Read a directory
      tags:
        - Files
    parameters:
      - $ref: "#/components/parameters/ComputerId"
  /computers/{id}/files/rename:
    parameters:
      - $ref: "#/components/parameters/ComputerId"
    post:
      description: Renames or moves a file or directory to a new path.
      operationId: renameFile
      requestBody:
        content:
          application/json:
            example:
              destination: /home/user/new-name.py
              source: /home/user/old-name.py
            schema:
              $ref: "#/components/schemas/RenameRequest"
        required: true
      responses:
        "200":
          content:
            application/json:
              schema:
                properties:
                  destination:
                    example: /home/user/new-name.py
                    type: string
                  source:
                    example: /home/user/old-name.py
                    type: string
                required:
                  - source
                  - destination
                type: object
          description: File renamed
        "400":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
          description: Source does not exist or destination conflict
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
        "409":
          $ref: "#/components/responses/ComputerNotRunning"
        "502":
          $ref: "#/components/responses/AgentUnavailable"
      summary: Rename or move a file
      tags:
        - Files
  /computers/{id}/files/stat:
    parameters:
      - $ref: "#/components/parameters/ComputerId"
    post:
      description: "Returns detailed metadata (type, size, permissions, timestamps) for a file, directory, or symlink inside the computer.\n"
      operationId: statFile
      requestBody:
        content:
          application/json:
            schema:
              properties:
                path:
                  description: Absolute path to stat
                  example: /home/user/app/server.py
                  type: string
              required:
                - path
              type: object
        required: true
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/FileStat"
          description: File stat information
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
        "409":
          $ref: "#/components/responses/ComputerNotRunning"
        "502":
          $ref: "#/components/responses/AgentUnavailable"
      summary: Stat a path
      tags:
        - Files
  /computers/{id}/files/upload:
    parameters:
      - $ref: "#/components/parameters/ComputerId"
    post:
      description: "Uploads a file into the computer via `multipart/form-data`. Maximum file size is **10 MB**. The destination path must be under `/home/user`, `/home/ubuntu`, or `/tmp`.\nIf `path` ends with `/` the filename is appended automatically.\n"
      operationId: uploadFile
      requestBody:
        content:
          multipart/form-data:
            schema:
              properties:
                file:
                  description: File to upload
                  format: binary
                  type: string
                path:
                  description: Destination path inside the computer (default `/home/user/`)
                  example: /home/user/uploads/
                  type: string
              required:
                - file
              type: object
        required: true
      responses:
        "201":
          content:
            application/json:
              schema:
                properties:
                  file:
                    properties:
                      filename:
                        example: script.py
                        type: string
                      path:
                        example: /home/user/uploads/script.py
                        type: string
                      size_bytes:
                        example: 2048
                        type: integer
                    required:
                      - path
                      - filename
                      - size_bytes
                    type: object
                  success:
                    example: true
                    type: boolean
                required:
                  - file
                  - success
                type: object
          description: File uploaded successfully
        "400":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
          description: File field missing or path forbidden
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
        "409":
          $ref: "#/components/responses/ComputerNotRunning"
        "413":
          $ref: "#/components/responses/FileTooLarge"
        "502":
          $ref: "#/components/responses/AgentUnavailable"
      summary: Upload a file
      tags:
        - Files
  /computers/{id}/files/write:
    parameters:
      - $ref: "#/components/parameters/ComputerId"
    post:
      description: "Writes text or binary content to a path inside the computer. The file is created if it does not exist; existing content is replaced unless `append` is true. Parent directories are created automatically.\nFor binary payloads encode the content as Base64 and set `encoding: base64`.\n"
      operationId: writeFile
      requestBody:
        content:
          application/json:
            schema:
              properties:
                append:
                  default: false
                  description: Append to the file instead of overwriting it
                  type: boolean
                content:
                  description: "File content. Plain UTF-8 text by default; Base64-encoded bytes when `encoding` is `base64`.\n"
                  example: "{\"port\": 3000}"
                  type: string
                encoding:
                  default: utf8
                  description: Encoding of the `content` field
                  enum:
                    - utf8
                    - base64
                  type: string
                mode:
                  description: "Optional Unix permissions to set on a newly created file. Ignored if the file already exists.\n"
                  example: "0644"
                  pattern: ^[0-7]{3,4}$
                  type: string
                path:
                  description: Absolute destination path inside the computer
                  example: /home/user/app/config.json
                  type: string
              required:
                - path
                - content
              type: object
        required: true
      responses:
        "200":
          content:
            application/json:
              schema:
                properties:
                  path:
                    example: /home/user/app/config.json
                    type: string
                  size_bytes:
                    description: Final file size after write
                    example: 14
                    type: integer
                required:
                  - path
                  - size_bytes
                type: object
          description: File written
        "400":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
          description: Path is forbidden or content encoding is invalid
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
        "409":
          $ref: "#/components/responses/ComputerNotRunning"
        "413":
          $ref: "#/components/responses/FileTooLarge"
        "502":
          $ref: "#/components/responses/AgentUnavailable"
      summary: Write a file
      tags:
        - Files
  /computers/{id}/inbox:
    get:
      operationId: getComputersIdInbox
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: ComputerInboxes — Show
      tags:
        - ComputerInboxes
    patch:
      operationId: patchComputersIdInbox
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: ComputerInboxes — Update
      tags:
        - ComputerInboxes
  /computers/{id}/launch-tasks:
    get:
      operationId: getComputersIdLaunchTasks
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: LaunchTasks — List Launch Tasks
      tags:
        - LaunchTasks
    post:
      operationId: postComputersIdLaunchTasks
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "201":
          description: Created
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: LaunchTasks — Create Launch Task
      tags:
        - LaunchTasks
  /computers/{id}/launch-tasks/{tid}:
    delete:
      operationId: deleteComputersIdLaunchTasksTid
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
        - in: path
          name: tid
          required: true
          schema:
            type: string
      responses:
        "204":
          description: Deleted
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: LaunchTasks — Delete Launch Task
      tags:
        - LaunchTasks
    get:
      operationId: getComputersIdLaunchTasksTid
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
        - in: path
          name: tid
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: LaunchTasks — Get Launch Task
      tags:
        - LaunchTasks
    put:
      operationId: putComputersIdLaunchTasksTid
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
        - in: path
          name: tid
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: LaunchTasks — Update Launch Task
      tags:
        - LaunchTasks
  /computers/{id}/launch-tasks/{tid}/pause:
    post:
      operationId: postComputersIdLaunchTasksTidPause
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
        - in: path
          name: tid
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "201":
          description: Created
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: LaunchTasks — Pause Launch Task
      tags:
        - LaunchTasks
  /computers/{id}/launch-tasks/{tid}/resume:
    post:
      operationId: postComputersIdLaunchTasksTidResume
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
        - in: path
          name: tid
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "201":
          description: Created
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: LaunchTasks — Resume Launch Task
      tags:
        - LaunchTasks
  /computers/{id}/launch-tasks/{tid}/runs:
    get:
      operationId: getComputersIdLaunchTasksTidRuns
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
        - in: path
          name: tid
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: LaunchTasks — List Launch Task Runs
      tags:
        - LaunchTasks
  /computers/{id}/logs:
    get:
      operationId: getComputersIdLogs
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Logs — Show
      tags:
        - Logs
  /computers/{id}/logs/stream:
    get:
      operationId: getComputersIdLogsStream
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Logs — Stream Computer
      tags:
        - Logs
  /computers/{id}/members:
    get:
      operationId: getComputersIdMembers
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Members — List Members
      tags:
        - Members
    post:
      operationId: postComputersIdMembers
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "201":
          description: Created
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Members — Add Member
      tags:
        - Members
  /computers/{id}/members/{uid}:
    delete:
      operationId: deleteComputersIdMembersUid
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
        - in: path
          name: uid
          required: true
          schema:
            type: string
      responses:
        "204":
          description: Deleted
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Members — Remove Member
      tags:
        - Members
  /computers/{id}/metrics:
    get:
      operationId: getComputersIdMetrics
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Metrics — Show
      tags:
        - Metrics
  /computers/{id}/move:
    parameters:
      - $ref: "#/components/parameters/ComputerId"
    post:
      description: "Moves the computer to a different workspace. The computer can be in any lifecycle state. The caller must have write access to both the source and destination workspaces.\n"
      operationId: moveComputer
      requestBody:
        content:
          application/json:
            example:
              workspace_id: 1b2c3d4e-5f6a-7890-abcd-ef1234567890
            schema:
              $ref: "#/components/schemas/MoveRequest"
        required: true
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Computer"
          description: Computer moved
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
        "422":
          $ref: "#/components/responses/ValidationError"
      summary: Move computer to a workspace
      tags:
        - Computers
  /computers/{id}/network-policy:
    delete:
      description: "Removes the custom network policy and reverts the computer to platform defaults (all outbound allowed, inbound denied except established).\n"
      operationId: deleteNetworkPolicy
      responses:
        "200":
          content:
            application/json:
              schema:
                properties:
                  deleted:
                    example: true
                    type: boolean
                required:
                  - deleted
                type: object
          description: Network policy removed
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
      summary: Delete network policy
      tags:
        - NetworkPolicy
    get:
      description: "Returns the current firewall policy for the computer. Returns `404` if no policy has been set (the computer uses platform defaults — all outbound allowed, all inbound denied except established connections).\n"
      operationId: getNetworkPolicy
      responses:
        "200":
          content:
            application/json:
              example:
                computer_id: 3fa85f64-5717-4562-b3fc-2c963f66afa6
                default_inbound: deny
                default_outbound: allow
                rules:
                  - action: allow
                    description: Allow HTTPS
                    direction: inbound
                    port: 443
                    protocol: tcp
                  - action: allow
                    description: Allow HTTP
                    direction: inbound
                    port: 80
                    protocol: tcp
                updated_at: 2026-04-11T14:30:00Z
              schema:
                $ref: "#/components/schemas/NetworkPolicy"
          description: Current network policy
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
      summary: Get network policy
      tags:
        - NetworkPolicy
    parameters:
      - $ref: "#/components/parameters/ComputerId"
    put:
      description: "Fully replaces the computer's network policy. The new rule set is applied atomically — partial updates are not supported. Pass an empty `rules` array to clear all rules while keeping the default actions.\n"
      operationId: updateNetworkPolicy
      requestBody:
        content:
          application/json:
            example:
              default_inbound: deny
              default_outbound: allow
              rules:
                - action: allow
                  description: Allow HTTPS from anywhere
                  direction: inbound
                  port: 443
                  protocol: tcp
            schema:
              $ref: "#/components/schemas/NetworkPolicyUpdateRequest"
        required: true
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/NetworkPolicy"
          description: Updated network policy
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
        "422":
          $ref: "#/components/responses/ValidationError"
      summary: Replace network policy
      tags:
        - NetworkPolicy
  /computers/{id}/osa/configure:
    parameters:
      - $ref: "#/components/parameters/ComputerId"
    post:
      description: "Updates the OSA agent's configuration inside the computer. Configuration keys and values are agent-specific; consult the OSA documentation for supported fields.\n"
      operationId: configureOsa
      requestBody:
        content:
          application/json:
            schema:
              additionalProperties: true
              description: Configuration key-value map
              example:
                max_tokens: 4096
                model: nemotron-3-super
                tool_approval_required: true
              type: object
        required: true
      responses:
        "200":
          content:
            application/json:
              schema:
                additionalProperties: true
                type: object
          description: Configuration updated
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
        "409":
          $ref: "#/components/responses/ComputerNotRunning"
        "502":
          $ref: "#/components/responses/AgentUnavailable"
      summary: Configure the OSA agent
      tags:
        - OSA
  /computers/{id}/osa/status:
    get:
      description: "Returns the current status of the OSA agent running inside the computer. Use this to poll task progress after calling `POST /osa/task`.\n"
      operationId: getOsaStatus
      responses:
        "200":
          content:
            application/json:
              schema:
                additionalProperties: true
                properties:
                  current_task:
                    description: Description of the task currently being executed
                    example: Installing Node.js 20…
                    type:
                      - string
                      - "null"
                  last_error:
                    description: Error from the most recent failed task
                    type:
                      - string
                      - "null"
                  progress:
                    description: Estimated completion percentage (0–100)
                    example: 42
                    type:
                      - integer
                      - "null"
                  status:
                    enum:
                      - idle
                      - running
                      - error
                    example: running
                    type: string
                type: object
          description: OSA agent status
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
        "409":
          $ref: "#/components/responses/ComputerNotRunning"
        "502":
          $ref: "#/components/responses/AgentUnavailable"
      summary: Get OSA agent status
      tags:
        - OSA
    parameters:
      - $ref: "#/components/parameters/ComputerId"
  /computers/{id}/osa/task:
    delete:
      description: "Requests cancellation of the OSA agent's in-flight task. The agent may take up to a few seconds to halt cleanly. Calling this when no task is running is a no-op.\n"
      operationId: cancelOsaTask
      responses:
        "200":
          content:
            application/json:
              schema:
                additionalProperties: true
                type: object
          description: Cancellation requested
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
        "409":
          $ref: "#/components/responses/ComputerNotRunning"
        "502":
          $ref: "#/components/responses/AgentUnavailable"
      summary: Cancel the current OSA task
      tags:
        - OSA
    parameters:
      - $ref: "#/components/parameters/ComputerId"
    post:
      description: "Submits a task to the OSA (Operating System Agent) running inside the computer. The OSA agent runs as a system service and can perform file operations, run commands, and manage the desktop environment.\nUnlike CUA sessions, OSA tasks are fire-and-forget. Poll `GET /osa/status` to check progress.\n"
      operationId: submitOsaTask
      requestBody:
        content:
          application/json:
            schema:
              properties:
                context:
                  additionalProperties: true
                  description: Optional structured context passed to the agent
                  example:
                    prefer_pnpm: true
                    working_dir: /home/user/projects
                  type:
                    - object
                    - "null"
                task:
                  description: Natural-language task description
                  example: Install Node.js 20 and initialise a new Next.js project in ~/projects/myapp
                  type: string
              required:
                - task
              type: object
        required: true
      responses:
        "200":
          content:
            application/json:
              schema:
                additionalProperties: true
                type: object
          description: Task submitted
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
        "409":
          $ref: "#/components/responses/ComputerNotRunning"
        "502":
          $ref: "#/components/responses/AgentUnavailable"
      summary: Submit an OSA task
      tags:
        - OSA
  /computers/{id}/ports:
    get:
      operationId: getComputersIdPorts
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Ports — Index
      tags:
        - Ports
    post:
      operationId: postComputersIdPorts
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "201":
          description: Created
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Ports — Create
      tags:
        - Ports
  /computers/{id}/ports/{port}:
    delete:
      operationId: deleteComputersIdPortsPort
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
        - in: path
          name: port
          required: true
          schema:
            type: string
      responses:
        "204":
          description: Deleted
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Ports — Delete
      tags:
        - Ports
    patch:
      operationId: patchComputersIdPortsPort
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
        - in: path
          name: port
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Ports — Update
      tags:
        - Ports
  /computers/{id}/pty/{session_id}/resize:
    parameters:
      - $ref: "#/components/parameters/ComputerId"
      - $ref: "#/components/parameters/PtySessionId"
    post:
      description: "Updates the column and row dimensions of an existing PTY session. Call this whenever the client-side terminal UI is resized so the remote shell receives `SIGWINCH` and redraws at the new size.\n"
      operationId: resizeTerminal
      requestBody:
        content:
          application/json:
            schema:
              properties:
                cols:
                  example: 120
                  maximum: 500
                  minimum: 1
                  type: integer
                rows:
                  example: 30
                  maximum: 200
                  minimum: 1
                  type: integer
              required:
                - cols
                - rows
              type: object
        required: true
      responses:
        "200":
          content:
            application/json:
              schema:
                properties:
                  status:
                    enum:
                      - ok
                    example: ok
                    type: string
                type: object
          description: PTY resized
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
        "409":
          $ref: "#/components/responses/ComputerNotRunning"
        "502":
          $ref: "#/components/responses/AgentUnavailable"
      summary: Resize a PTY terminal session
      tags:
        - Terminal
  /computers/{id}/repo/clone:
    post:
      operationId: postComputersIdRepoClone
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "201":
          description: Created
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Repo — Repo Clone
      tags:
        - Repo
  /computers/{id}/repo/status:
    get:
      operationId: getComputersIdRepoStatus
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Repo — Repo Status
      tags:
        - Repo
  /computers/{id}/resize:
    parameters:
      - $ref: "#/components/parameters/ComputerId"
    post:
      description: "Changes the resource tier of a computer. The computer must be `stopped` before resizing. Credit adjustments take effect on the next billing cycle. Resize to a larger tier is always allowed; downsizing requires the new tier's disk limit to be larger than the used disk.\n"
      operationId: resizeComputer
      requestBody:
        content:
          application/json:
            example:
              size: medium
            schema:
              $ref: "#/components/schemas/ResizeRequest"
        required: true
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Computer"
          description: Computer resized
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
        "409":
          content:
            application/json:
              example:
                error:
                  code: COMPUTER_NOT_STOPPED
                  message: Computer must be stopped before it can be resized
                  type: https://docs.miosa.ai/errors/computer-not-stopped
              schema:
                $ref: "#/components/schemas/ErrorResponse"
          description: Computer must be stopped before resizing
        "422":
          $ref: "#/components/responses/ValidationError"
      summary: Resize a computer
      tags:
        - Computers
  /computers/{id}/restart:
    parameters:
      - $ref: "#/components/parameters/ComputerId"
    post:
      description: "Stops and then immediately restarts a running computer. Equivalent to calling stop then start. The computer must be in `running` status.\n"
      operationId: restartComputer
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Computer"
          description: Computer restarted
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
        "409":
          $ref: "#/components/responses/ComputerNotRunning"
      summary: Restart a computer
      tags:
        - Computers
  /computers/{id}/restore/{snap_id}:
    parameters:
      - $ref: "#/components/parameters/ComputerId"
      - $ref: "#/components/parameters/SnapshotId"
    post:
      description: "Restores the computer's disk to the state captured in the given snapshot. The computer is stopped before restoration and reboots automatically once the restore completes.\n**Warning:** All disk changes made after the snapshot was taken are permanently discarded.\n"
      operationId: restoreSnapshot
      responses:
        "202":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Computer"
          description: Restore initiated
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
        "409":
          content:
            application/json:
              example:
                error:
                  code: SNAPSHOT_NOT_AVAILABLE
                  message: Snapshot is not in available status
                  type: https://docs.miosa.ai/errors/snapshot-not-available
              schema:
                $ref: "#/components/schemas/ErrorResponse"
          description: Restore cannot be initiated in the current state
      summary: Restore from snapshot
      tags:
        - Snapshots
  /computers/{id}/screenshot:
    get:
      description: "Convenience alias for `GET /computers/{id}/desktop/screenshot`. Returns a PNG image of the current desktop state.\n"
      operationId: getScreenshot
      responses:
        "200":
          content:
            image/png:
              schema:
                format: binary
                type: string
          description: PNG screenshot of the desktop
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
        "409":
          $ref: "#/components/responses/ComputerNotRunning"
        "502":
          $ref: "#/components/responses/AgentUnavailable"
      summary: Take a screenshot (alias)
      tags:
        - Desktop
    parameters:
      - $ref: "#/components/parameters/ComputerId"
  /computers/{id}/services:
    get:
      description: Returns all managed services registered on the computer.
      operationId: listServices
      responses:
        "200":
          content:
            application/json:
              example:
                services:
                  - command: nginx -g "daemon off;"
                    created_at: 2026-04-11T14:30:00Z
                    name: nginx
                    pid: 1234
                    restart_policy: always
                    status: running
                    updated_at: 2026-04-11T14:30:00Z
              schema:
                $ref: "#/components/schemas/ServiceListResponse"
          description: List of services
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
        "409":
          $ref: "#/components/responses/ComputerNotRunning"
        "502":
          $ref: "#/components/responses/AgentUnavailable"
      summary: List services
      tags:
        - Services
    parameters:
      - $ref: "#/components/parameters/ComputerId"
    post:
      description: "Registers and immediately starts a new managed service on the computer. The service is restarted automatically based on `restart_policy`.\n"
      operationId: createService
      requestBody:
        content:
          application/json:
            example:
              command: python worker.py
              env:
                WORKERS: "4"
              name: my-worker
              restart_policy: on-failure
              working_dir: /home/user/app
            schema:
              $ref: "#/components/schemas/ServiceCreateRequest"
        required: true
      responses:
        "201":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Service"
          description: Service registered and started
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
        "409":
          content:
            application/json:
              example:
                error:
                  code: CONFLICT
                  message: A service named "my-worker" already exists on this computer
                  type: https://docs.miosa.ai/errors/conflict
              schema:
                $ref: "#/components/schemas/ErrorResponse"
          description: A service with this name already exists on the computer
        "422":
          $ref: "#/components/responses/ValidationError"
        "502":
          $ref: "#/components/responses/AgentUnavailable"
      summary: Register a service
      tags:
        - Services
  /computers/{id}/services/{name}:
    delete:
      description: Stops and unregisters a managed service from the computer.
      operationId: deleteService
      responses:
        "200":
          content:
            application/json:
              schema:
                properties:
                  deleted:
                    example: true
                    type: boolean
                  name:
                    example: my-worker
                    type: string
                required:
                  - name
                  - deleted
                type: object
          description: Service deleted
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
        "502":
          $ref: "#/components/responses/AgentUnavailable"
      summary: Delete a service
      tags:
        - Services
    get:
      description: Returns the current state of a named service.
      operationId: getService
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Service"
          description: Service object
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
        "502":
          $ref: "#/components/responses/AgentUnavailable"
      summary: Get a service
      tags:
        - Services
    parameters:
      - $ref: "#/components/parameters/ComputerId"
      - $ref: "#/components/parameters/ServiceName"
  /computers/{id}/services/{name}/logs:
    get:
      description: "Opens a Server-Sent Events stream of stdout and stderr lines from a service. Each SSE event is `event: log` with a JSON payload matching `ServiceLogEvent`.\nSet `follow=true` (default) to tail live output. Set `follow=false` to receive buffered lines from `tail` and close.\n**Authentication:** Use ticket-based auth — append `?ticket=<ticket>`.\n"
      operationId: streamServiceLogs
      parameters:
        - description: Short-lived SSE ticket
          in: query
          name: ticket
          required: true
          schema:
            example: sset_a1b2c3d4e5f6
            type: string
        - description: Tail live output (default `true`)
          in: query
          name: follow
          required: false
          schema:
            default: true
            type: boolean
        - description: Number of historical lines to emit before live output
          in: query
          name: tail
          required: false
          schema:
            default: 100
            maximum: 1000
            minimum: 0
            type: integer
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ServiceLogEvent"
                description: "Single buffered event — returned when the client requests a non-streaming response. The payload is a `ServiceLogEvent`.\n"
            text/event-stream:
              schema:
                description: "Newline-delimited SSE events. Each event:\n\n```\nevent: log\ndata: {\"timestamp\":\"2026-04-11T14:30:00Z\",\"stream\":\"stdout\",\"line\":\"Server started on :8080\"}\n\nevent: done\ndata: {}\n```\n"
                type: string
              x-event-schema:
                $ref: "#/components/schemas/ServiceLogEvent"
          description: SSE log stream
        "401":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
          description: Invalid or expired SSE ticket
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
        "502":
          $ref: "#/components/responses/AgentUnavailable"
      summary: Stream service logs (SSE)
      tags:
        - Services
    parameters:
      - $ref: "#/components/parameters/ComputerId"
      - $ref: "#/components/parameters/ServiceName"
  /computers/{id}/services/{name}/restart:
    parameters:
      - $ref: "#/components/parameters/ComputerId"
      - $ref: "#/components/parameters/ServiceName"
    post:
      description: Stops then immediately restarts the service.
      operationId: restartService
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Service"
          description: Service restarting
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
        "409":
          $ref: "#/components/responses/ComputerNotRunning"
        "502":
          $ref: "#/components/responses/AgentUnavailable"
      summary: Restart a service
      tags:
        - Services
  /computers/{id}/services/{name}/start:
    parameters:
      - $ref: "#/components/parameters/ComputerId"
      - $ref: "#/components/parameters/ServiceName"
    post:
      description: Starts a stopped service. No-op if already running.
      operationId: startService
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Service"
          description: Service started
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
        "409":
          $ref: "#/components/responses/ComputerNotRunning"
        "502":
          $ref: "#/components/responses/AgentUnavailable"
      summary: Start a service
      tags:
        - Services
  /computers/{id}/services/{name}/stop:
    parameters:
      - $ref: "#/components/parameters/ComputerId"
      - $ref: "#/components/parameters/ServiceName"
    post:
      description: "Sends SIGTERM to the service process and waits up to 10 seconds before sending SIGKILL. The service is not unregistered.\n"
      operationId: stopService
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Service"
          description: Service stopped
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
        "502":
          $ref: "#/components/responses/AgentUnavailable"
      summary: Stop a service
      tags:
        - Services
  /computers/{id}/shares:
    get:
      operationId: getComputersIdShares
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Shares — Index
      tags:
        - Shares
    post:
      operationId: postComputersIdShares
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "201":
          description: Created
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Shares — Create
      tags:
        - Shares
  /computers/{id}/shares/{share_id}:
    delete:
      operationId: deleteComputersIdSharesShareId
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
        - in: path
          name: share_id
          required: true
          schema:
            type: string
      responses:
        "204":
          description: Deleted
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Shares — Delete
      tags:
        - Shares
    patch:
      operationId: patchComputersIdSharesShareId
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
        - in: path
          name: share_id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Shares — Update
      tags:
        - Shares
  /computers/{id}/snapshots:
    get:
      description: Returns all snapshots for the given computer, newest first.
      operationId: listSnapshots
      parameters:
        - $ref: "#/components/parameters/LimitParam"
        - $ref: "#/components/parameters/CursorParam"
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SnapshotListResponse"
          description: Paginated list of snapshots
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
        "429":
          $ref: "#/components/responses/RateLimited"
      summary: List snapshots
      tags:
        - Snapshots
    parameters:
      - $ref: "#/components/parameters/ComputerId"
    post:
      description: "Initiates a point-in-time snapshot of the computer's disk. Returns `202 Accepted` immediately; poll the snapshot's `status` field until it reaches `available` or `error`.\nThe computer does not need to be stopped — a live snapshot is taken.\n"
      operationId: createSnapshot
      requestBody:
        content:
          application/json:
            example:
              description: Clean state before running npm update
              name: Before dependency upgrade
            schema:
              $ref: "#/components/schemas/SnapshotCreateRequest"
        required: true
      responses:
        "202":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Snapshot"
          description: Snapshot creation initiated
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
        "409":
          content:
            application/json:
              example:
                error:
                  code: SNAPSHOT_IN_PROGRESS
                  message: A snapshot is already being created for this computer
                  type: https://docs.miosa.ai/errors/snapshot-in-progress
              schema:
                $ref: "#/components/schemas/ErrorResponse"
          description: A snapshot operation is already in progress for this computer
        "422":
          $ref: "#/components/responses/ValidationError"
        "429":
          $ref: "#/components/responses/RateLimited"
      summary: Create a snapshot
      tags:
        - Snapshots
  /computers/{id}/snapshots/{snap_id}:
    delete:
      description: "Permanently deletes a snapshot. The snapshot must be in `available` or `error` status; deleting a snapshot in `creating` status returns `409 Conflict`.\n"
      operationId: deleteSnapshot
      responses:
        "200":
          content:
            application/json:
              schema:
                properties:
                  deleted:
                    example: true
                    type: boolean
                  id:
                    format: uuid
                    type: string
                required:
                  - id
                  - deleted
                type: object
          description: Snapshot deleted
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
        "409":
          content:
            application/json:
              example:
                error:
                  code: SNAPSHOT_IN_PROGRESS
                  message: Cannot delete a snapshot that is currently being created
                  type: https://docs.miosa.ai/errors/snapshot-in-progress
              schema:
                $ref: "#/components/schemas/ErrorResponse"
          description: Snapshot cannot be deleted in its current state
      summary: Delete a snapshot
      tags:
        - Snapshots
    get:
      description: Returns a single snapshot by ID.
      operationId: getSnapshot
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Snapshot"
          description: Snapshot object
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
      summary: Get a snapshot
      tags:
        - Snapshots
    parameters:
      - $ref: "#/components/parameters/ComputerId"
      - $ref: "#/components/parameters/SnapshotId"
  /computers/{id}/snapshots/{snap_id}/events:
    get:
      description: "Opens a Server-Sent Events stream that emits progress updates for a snapshot create or restore operation. The stream closes automatically when the snapshot reaches a terminal state (`available`, `error`, or `deleted`).\n**Authentication:** Use ticket-based auth — obtain a ticket from `POST /computers/{id}/sse-ticket` and append `?ticket=<ticket>`.\n"
      operationId: streamSnapshotEvents
      parameters:
        - description: Short-lived SSE ticket obtained from `/sse-ticket`
          in: query
          name: ticket
          required: true
          schema:
            example: sset_a1b2c3d4e5f6
            type: string
      responses:
        "200":
          content:
            text/event-stream:
              schema:
                description: "Newline-delimited SSE events. Each event has the form:\n\n```\nevent: snapshot_progress\ndata: {\"snapshot_id\":\"...\",\"status\":\"creating\",\"progress\":42}\n\nevent: snapshot_done\ndata: {\"snapshot_id\":\"...\",\"status\":\"available\"}\n```\n"
                type: string
          description: SSE event stream
        "401":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
          description: Invalid or expired SSE ticket
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
      summary: Stream snapshot events (SSE)
      tags:
        - Snapshots
    parameters:
      - $ref: "#/components/parameters/ComputerId"
      - $ref: "#/components/parameters/SnapshotId"
  /computers/{id}/start:
    parameters:
      - $ref: "#/components/parameters/ComputerId"
    post:
      description: "Resumes a stopped or paused computer. Returns immediately; the computer transitions to `running` within a few seconds.\n"
      operationId: startComputer
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Computer"
          description: Computer is starting
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
        "409":
          content:
            application/json:
              example:
                error:
                  code: INVALID_STATE_TRANSITION
                  message: Computer cannot be started from its current status (running)
                  type: https://docs.miosa.ai/errors/invalid-state-transition
              schema:
                $ref: "#/components/schemas/ErrorResponse"
          description: Computer cannot be started from its current status
      summary: Start a computer
      tags:
        - Computers
  /computers/{id}/stop:
    parameters:
      - $ref: "#/components/parameters/ComputerId"
    post:
      description: Gracefully stops the computer. Data on disk is preserved.
      operationId: stopComputer
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Computer"
          description: Computer is stopping
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
        "409":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
          description: Computer is not in a stoppable state
      summary: Stop a computer
      tags:
        - Computers
  /computers/{id}/stream:
    get:
      operationId: getComputersIdStream
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Connection — Stream Url
      tags:
        - Connection
  /computers/{id}/stream-token:
    parameters:
      - $ref: "#/components/parameters/ComputerId"
    post:
      description: "Issues a short-lived (1 hour) authentication token for the desktop stream WebSocket. This is the lightweight programmatic equivalent of `GET /computers/{id}/vnc-credentials`. Append the returned `token` as `?auth=<token>` when opening the VNC or terminal WebSocket.\n"
      operationId: createStreamToken
      responses:
        "200":
          content:
            application/json:
              example:
                expires_at: 1712703600
                token: tok_aBcDeFgHiJkLmNoPqRsT
              schema:
                $ref: "#/components/schemas/StreamToken"
          description: Stream token
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
      summary: Issue a desktop stream token
      tags:
        - Config
  /computers/{id}/tasks:
    get:
      operationId: getComputersIdTasks
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Tasks — List Tasks
      tags:
        - Tasks
    post:
      operationId: postComputersIdTasks
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "201":
          description: Created
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Tasks — Create Task
      tags:
        - Tasks
  /computers/{id}/tasks/{task_id}:
    delete:
      operationId: deleteComputersIdTasksTaskId
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
        - in: path
          name: task_id
          required: true
          schema:
            type: string
      responses:
        "204":
          description: Deleted
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Tasks — Delete Task
      tags:
        - Tasks
    get:
      operationId: getComputersIdTasksTaskId
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
        - in: path
          name: task_id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Tasks — Get Task
      tags:
        - Tasks
    put:
      operationId: putComputersIdTasksTaskId
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
        - in: path
          name: task_id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Tasks — Update Task
      tags:
        - Tasks
  /computers/{id}/tasks/{task_id}/checkout:
    post:
      operationId: postComputersIdTasksTaskIdCheckout
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
        - in: path
          name: task_id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "201":
          description: Created
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Tasks — Checkout Task
      tags:
        - Tasks
  /computers/{id}/terminal:
    parameters:
      - $ref: "#/components/parameters/ComputerId"
    post:
      description: "Opens a persistent pseudo-terminal (PTY) inside the computer and returns an authenticated WebSocket URL for streaming the bidirectional terminal I/O. Connect to `ws_url` with any WebSocket client to attach; write terminal input as UTF-8 text frames and read `stdout`/`stderr` as they arrive.\nThe session lives until the client disconnects or the computer stops. Resize the PTY at any time via `POST /computers/{id}/pty/{session_id}/resize`.\n"
      operationId: createTerminal
      requestBody:
        content:
          application/json:
            schema:
              properties:
                cols:
                  default: 80
                  description: Initial terminal width in columns
                  example: 120
                  maximum: 500
                  minimum: 1
                  type: integer
                rows:
                  default: 24
                  description: Initial terminal height in rows
                  example: 30
                  maximum: 200
                  minimum: 1
                  type: integer
                shell:
                  description: Shell to launch. Defaults to the VM user's login shell.
                  example: /bin/bash
                  type:
                    - string
                    - "null"
              type: object
        required: false
      responses:
        "201":
          content:
            application/json:
              schema:
                properties:
                  data:
                    $ref: "#/components/schemas/TerminalSession"
                required:
                  - data
                type: object
          description: PTY session created
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
        "409":
          $ref: "#/components/responses/ComputerNotRunning"
        "502":
          $ref: "#/components/responses/AgentUnavailable"
      summary: Create a PTY terminal session
      tags:
        - Terminal
  /computers/{id}/urls:
    get:
      description: "Returns the public URLs for connecting to this computer's desktop (VNC) and interactive terminal, along with the computer's canonical ID. Pair with `POST /computers/{id}/stream-token` or `GET /computers/{id}/vnc-credentials` to obtain the auth token that these URLs require.\n"
      operationId: getComputerUrls
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ComputerUrls"
          description: Connection URLs
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
      summary: Get connection URLs for a computer
      tags:
        - Config
    parameters:
      - $ref: "#/components/parameters/ComputerId"
  /computers/{id}/viewer-password:
    get:
      operationId: getComputersIdViewerPassword
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Viewer — Viewer Password
      tags:
        - Viewer
  /computers/{id}/viewer-password/rotate:
    post:
      operationId: postComputersIdViewerPasswordRotate
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "201":
          description: Created
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Viewer — Rotate Viewer Password
      tags:
        - Viewer
  /computers/{id}/viewer-session:
    post:
      operationId: postComputersIdViewerSession
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "201":
          description: Created
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Viewer — Create Viewer Session
      tags:
        - Viewer
  /computers/{id}/vnc-credentials:
    get:
      description: "Issues a short-lived VNC auth token (valid for 1 hour) and returns connection URLs for direct VNC access. The computer must be running.\nUse `vnc_url` to open the KasmVNC web client. Use `ws_url` for direct WebSocket VNC connections (e.g. from a native VNC viewer).\n"
      operationId: getVncCredentials
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/VncCredentials"
          description: VNC credentials and connection URLs
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
        "409":
          $ref: "#/components/responses/ComputerNotRunning"
      summary: Get VNC credentials
      tags:
        - Config
    parameters:
      - $ref: "#/components/parameters/ComputerId"
  /computers/{id}/volumes:
    get:
      operationId: listComputerAttachments
      responses:
        "200":
          content:
            application/json:
              schema:
                properties:
                  data:
                    items:
                      $ref: "#/components/schemas/VolumeAttachment"
                    type: array
                type: object
          description: Attachments
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
      summary: List a computer's attached volumes
      tags:
        - Volumes
    parameters:
      - $ref: "#/components/parameters/ComputerId"
    post:
      operationId: attachVolume
      requestBody:
        content:
          application/json:
            schema:
              properties:
                mount_path:
                  description: Absolute POSIX path, e.g. `/mnt/shared`
                  type: string
                read_only:
                  default: false
                  type: boolean
                volume_id:
                  format: uuid
                  type: string
              required:
                - volume_id
                - mount_path
              type: object
        required: true
      responses:
        "201":
          content:
            application/json:
              schema:
                properties:
                  data:
                    $ref: "#/components/schemas/VolumeAttachment"
                type: object
          description: Attachment created
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
        "422":
          $ref: "#/components/responses/ValidationError"
      summary: Attach a volume to a computer
      tags:
        - Volumes
  /computers/{id}/volumes/{aid}:
    delete:
      operationId: detachVolume
      responses:
        "200":
          content:
            application/json:
              schema:
                properties:
                  data:
                    $ref: "#/components/schemas/VolumeAttachment"
                type: object
          description: Detachment initiated
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
      summary: Detach a volume from a computer
      tags:
        - Volumes
    parameters:
      - $ref: "#/components/parameters/ComputerId"
      - description: Volume attachment id
        in: path
        name: aid
        required: true
        schema:
          format: uuid
          type: string
  /computers/{id}/webhooks:
    get:
      operationId: getComputersIdWebhooks
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Webhooks — Index
      tags:
        - Webhooks
    post:
      operationId: postComputersIdWebhooks
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "201":
          description: Created
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Webhooks — Create
      tags:
        - Webhooks
  /computers/{id}/webhooks/{hook_id}:
    delete:
      operationId: deleteComputersIdWebhooksHookId
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
        - in: path
          name: hook_id
          required: true
          schema:
            type: string
      responses:
        "204":
          description: Deleted
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Webhooks — Delete
      tags:
        - Webhooks
    patch:
      operationId: patchComputersIdWebhooksHookId
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
        - in: path
          name: hook_id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Webhooks — Update
      tags:
        - Webhooks
  /computers/{id}/webhooks/{hook_id}/test:
    post:
      operationId: postComputersIdWebhooksHookIdTest
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
        - in: path
          name: hook_id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "201":
          description: Created
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Webhooks — Test
      tags:
        - Webhooks
  /connect/connectors:
    get:
      operationId: getConnectConnectors
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Connect — Index
      tags:
        - Connect
    post:
      operationId: postConnectConnectors
      responses:
        "200":
          description: Success
        "201":
          description: Created
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Connect — Create
      tags:
        - Connect
  /connect/connectors/{connector}:
    get:
      operationId: getConnectConnectorsConnector
      parameters:
        - in: path
          name: connector
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Connect — Show
      tags:
        - Connect
  /connect/defaults:
    get:
      operationId: getConnectDefaults
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Connect — Defaults
      tags:
        - Connect
    post:
      operationId: postConnectDefaults
      responses:
        "200":
          description: Success
        "201":
          description: Created
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Connect — Create Default
      tags:
        - Connect
  /connect/defaults/applicable:
    get:
      operationId: getConnectDefaultsApplicable
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Connect — Applicable Defaults
      tags:
        - Connect
  /connect/defaults/materialize:
    post:
      operationId: postConnectDefaultsMaterialize
      responses:
        "200":
          description: Success
        "201":
          description: Created
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Connect — Materialize Defaults
      tags:
        - Connect
  /connect/defaults/{id}:
    delete:
      operationId: deleteConnectDefaultsId
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        "204":
          description: Deleted
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Connect — Delete Default
      tags:
        - Connect
  /connect/inbound:
    post:
      operationId: postConnectInbound
      responses:
        "200":
          description: Success
        "201":
          description: Created
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: ConnectWebhook — Receive
      tags:
        - ConnectWebhook
  /connect/installations:
    get:
      operationId: getConnectInstallations
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Connect — Installations
      tags:
        - Connect
  /connect/oauth/providers:
    get:
      operationId: getConnectOauthProviders
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Connect — Oauth Providers
      tags:
        - Connect
  /connect/oauth/start:
    post:
      operationId: postConnectOauthStart
      responses:
        "200":
          description: Success
        "201":
          description: Created
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Connect — Oauth Start
      tags:
        - Connect
  /connect/project-links:
    get:
      operationId: getConnectProjectLinks
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Connect — Project Links
      tags:
        - Connect
    post:
      operationId: postConnectProjectLinks
      responses:
        "200":
          description: Success
        "201":
          description: Created
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Connect — Create Project Link
      tags:
        - Connect
  /connect/project-links/{id}:
    delete:
      operationId: deleteConnectProjectLinksId
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        "204":
          description: Deleted
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Connect — Delete Project Link
      tags:
        - Connect
  /connect/token/{connector}:
    post:
      operationId: postConnectTokenConnector
      parameters:
        - in: path
          name: connector
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "201":
          description: Created
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Connect — Token
      tags:
        - Connect
  /connect/triggers:
    get:
      operationId: getConnectTriggers
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Connect — Triggers
      tags:
        - Connect
    post:
      operationId: postConnectTriggers
      responses:
        "200":
          description: Success
        "201":
          description: Created
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Connect — Create Trigger
      tags:
        - Connect
  /connect/triggers/{id}:
    delete:
      operationId: deleteConnectTriggersId
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        "204":
          description: Deleted
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Connect — Delete Trigger
      tags:
        - Connect
  /connect/triggers/{id}/deliveries:
    get:
      operationId: getConnectTriggersIdDeliveries
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Connect — Trigger Deliveries
      tags:
        - Connect
  /credits/balance:
    get:
      description: Returns the current credit balance for the authenticated tenant.
      operationId: getCreditsBalance
      responses:
        "200":
          content:
            application/json:
              example:
                balance: 2450
                tenant_id: 3fa85f64-5717-4562-b3fc-2c963f66afa6
              schema:
                $ref: "#/components/schemas/CreditBalance"
          description: Credit balance
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Get credit balance
      tags:
        - Credits
  /credits/breakdown:
    get:
      operationId: getCreditsBreakdown
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Credits — Breakdown
      tags:
        - Credits
  /credits/redeem:
    post:
      operationId: postCreditsRedeem
      responses:
        "200":
          description: Success
        "201":
          description: Created
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Credits — Redeem
      tags:
        - Credits
  /credits/transactions:
    get:
      description: "Returns a paginated history of credit transactions for the tenant. Results are ordered most-recent first.\n"
      operationId: listCreditTransactions
      parameters:
        - $ref: "#/components/parameters/LimitParam"
        - $ref: "#/components/parameters/CursorParam"
        - description: Filter by transaction type
          in: query
          name: type
          required: false
          schema:
            enum:
              - grant
              - purchase
              - compute_usage
              - ai_usage
              - refund
              - expiry
            type: string
      responses:
        "200":
          content:
            application/json:
              schema:
                properties:
                  pagination:
                    properties:
                      has_more:
                        type: boolean
                      next_cursor:
                        type:
                          - string
                          - "null"
                    type: object
                  transactions:
                    items:
                      $ref: "#/components/schemas/CreditTransaction"
                    type: array
                required:
                  - transactions
                type: object
          description: Transaction history
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: List credit transactions
      tags:
        - Credits
  /credits/usage:
    get:
      description: "Returns aggregated credit usage broken down by category (compute, AI, etc.) for the current billing period.\n"
      operationId: getCreditUsage
      responses:
        "200":
          content:
            application/json:
              schema:
                properties:
                  balance:
                    description: Current remaining balance
                    example: 2450
                    type: integer
                  by_category:
                    properties:
                      ai:
                        example: 350
                        type: integer
                      compute:
                        example: 1200
                        type: integer
                    type: object
                  period_end:
                    example: 2026-04-30T23:59:59Z
                    format: date-time
                    type: string
                  period_start:
                    example: 2026-04-01T00:00:00Z
                    format: date-time
                    type: string
                  total_used:
                    description: Total credits consumed this period
                    example: 1550
                    type: integer
                type: object
          description: Usage summary
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Get credit usage summary
      tags:
        - Credits
  /cron-jobs:
    get:
      operationId: getCronJobs
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: CronJobs — Index
      tags:
        - CronJobs
    post:
      operationId: postCronJobs
      responses:
        "200":
          description: Success
        "201":
          description: Created
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: CronJobs — Create
      tags:
        - CronJobs
  /cron-jobs/{id}:
    delete:
      operationId: deleteCronJobsId
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        "204":
          description: Deleted
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: CronJobs — Delete
      tags:
        - CronJobs
    get:
      operationId: getCronJobsId
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: CronJobs — Show
      tags:
        - CronJobs
    patch:
      operationId: patchCronJobsId
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: CronJobs — Update
      tags:
        - CronJobs
  /cron-jobs/{id}/executions:
    get:
      operationId: getCronJobsIdExecutions
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: CronJobs — List Executions
      tags:
        - CronJobs
  /cron-jobs/{id}/executions/{exec_id}:
    get:
      operationId: getCronJobsIdExecutionsExecId
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
        - in: path
          name: exec_id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: CronJobs — Show Execution
      tags:
        - CronJobs
  /cron-jobs/{id}/pause:
    post:
      operationId: postCronJobsIdPause
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "201":
          description: Created
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: CronJobs — Pause
      tags:
        - CronJobs
  /cron-jobs/{id}/resume:
    post:
      operationId: postCronJobsIdResume
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "201":
          description: Created
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: CronJobs — Resume
      tags:
        - CronJobs
  /cron-jobs/{id}/run-now:
    post:
      operationId: postCronJobsIdRunNow
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "201":
          description: Created
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: CronJobs — Run Now
      tags:
        - CronJobs
  /custom-domains:
    get:
      operationId: getCustomDomains
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: FlatCustomDomains — Index
      tags:
        - FlatCustomDomains
    post:
      operationId: postCustomDomains
      responses:
        "200":
          description: Success
        "201":
          description: Created
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: FlatCustomDomains — Create
      tags:
        - FlatCustomDomains
  /custom-domains/{id}:
    delete:
      operationId: deleteCustomDomainsId
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        "204":
          description: Deleted
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: FlatCustomDomains — Delete
      tags:
        - FlatCustomDomains
  /dashboard:
    get:
      operationId: getDashboard
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: UserDashboard — Show
      tags:
        - UserDashboard
  /databases:
    get:
      operationId: listDatabases
      parameters:
        - in: query
          name: external_workspace_id
          schema:
            type: string
        - in: query
          name: external_user_id
          schema:
            type: string
        - in: query
          name: external_project_id
          schema:
            type: string
      responses:
        "200":
          content:
            application/json:
              schema:
                properties:
                  data:
                    items:
                      $ref: "#/components/schemas/Database"
                    type: array
                type: object
          description: Managed database list
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: List managed databases
      tags:
        - Databases
    post:
      operationId: createDatabase
      parameters:
        - in: header
          name: Idempotency-Key
          required: false
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CreateDatabaseRequest"
        required: true
      responses:
        "201":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Database"
          description: Database accepted for provisioning
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "402":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
          description: Insufficient credits
        "422":
          $ref: "#/components/responses/ValidationError"
      summary: Create managed database
      tags:
        - Databases
  /databases/{database_id}/fs:
    delete:
      operationId: deleteDatabasesDatabaseIdFs
      parameters:
        - in: path
          name: database_id
          required: true
          schema:
            type: string
      responses:
        "204":
          description: Deleted
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: SandboxFiles — Delete
      tags:
        - SandboxFiles
    get:
      operationId: getDatabasesDatabaseIdFs
      parameters:
        - in: path
          name: database_id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: SandboxFiles — List
      tags:
        - SandboxFiles
  /databases/{database_id}/fs/chmod:
    post:
      operationId: postDatabasesDatabaseIdFsChmod
      parameters:
        - in: path
          name: database_id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "201":
          description: Created
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: SandboxFiles — Chmod
      tags:
        - SandboxFiles
  /databases/{database_id}/fs/copy:
    post:
      operationId: postDatabasesDatabaseIdFsCopy
      parameters:
        - in: path
          name: database_id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "201":
          description: Created
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: SandboxFiles — Copy File
      tags:
        - SandboxFiles
  /databases/{database_id}/fs/download:
    get:
      operationId: getDatabasesDatabaseIdFsDownload
      parameters:
        - in: path
          name: database_id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: SandboxFiles — Download
      tags:
        - SandboxFiles
  /databases/{database_id}/fs/mkdir:
    post:
      operationId: postDatabasesDatabaseIdFsMkdir
      parameters:
        - in: path
          name: database_id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "201":
          description: Created
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: SandboxFiles — Mkdir
      tags:
        - SandboxFiles
  /databases/{database_id}/fs/read:
    get:
      operationId: getDatabasesDatabaseIdFsRead
      parameters:
        - in: path
          name: database_id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: SandboxFiles — Read
      tags:
        - SandboxFiles
  /databases/{database_id}/fs/rename:
    post:
      operationId: postDatabasesDatabaseIdFsRename
      parameters:
        - in: path
          name: database_id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "201":
          description: Created
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: SandboxFiles — Rename
      tags:
        - SandboxFiles
  /databases/{database_id}/fs/stat:
    post:
      operationId: postDatabasesDatabaseIdFsStat
      parameters:
        - in: path
          name: database_id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "201":
          description: Created
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: SandboxFiles — Stat
      tags:
        - SandboxFiles
  /databases/{database_id}/fs/upload:
    post:
      operationId: postDatabasesDatabaseIdFsUpload
      parameters:
        - in: path
          name: database_id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "201":
          description: Created
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: SandboxFiles — Upload
      tags:
        - SandboxFiles
  /databases/{database_id}/fs/write:
    post:
      operationId: postDatabasesDatabaseIdFsWrite
      parameters:
        - in: path
          name: database_id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "201":
          description: Created
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: SandboxFiles — Write
      tags:
        - SandboxFiles
  /databases/{id}:
    delete:
      description: Preserves the persistent data volume; no silent data purge.
      operationId: deleteDatabase
      parameters:
        - in: path
          name: id
          required: true
          schema:
            format: uuid
            type: string
      responses:
        "200":
          content:
            application/json:
              schema:
                properties:
                  id:
                    format: uuid
                    type: string
                  state:
                    type: string
                type: object
          description: Database state after destroy request
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"
      summary: Destroy managed database VM
      tags:
        - Databases
    get:
      operationId: getDatabase
      parameters:
        - in: path
          name: id
          required: true
          schema:
            format: uuid
            type: string
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Database"
          description: Managed database
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"
      summary: Get managed database
      tags:
        - Databases
  /databases/{id}/backups:
    get:
      operationId: getDatabasesIdBackups
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Databases — List Backups
      tags:
        - Databases
    post:
      operationId: postDatabasesIdBackups
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "201":
          description: Created
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Databases — Create Backup
      tags:
        - Databases
  /databases/{id}/backups/{backup_id}:
    get:
      operationId: getDatabasesIdBackupsBackupId
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
        - in: path
          name: backup_id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Databases — Get Backup
      tags:
        - Databases
  /databases/{id}/branch:
    post:
      operationId: postDatabasesIdBranch
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "201":
          description: Created
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Databases — Branch
      tags:
        - Databases
  /databases/{id}/credentials:
    get:
      description: Returns decrypted credentials for the authenticated tenant only.
      operationId: getDatabaseCredentials
      parameters:
        - in: path
          name: id
          required: true
          schema:
            format: uuid
            type: string
      responses:
        "200":
          content:
            application/json:
              schema:
                properties:
                  data:
                    $ref: "#/components/schemas/DatabaseCredentials"
                type: object
          description: Database credentials
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"
      summary: Get database credentials
      tags:
        - Databases
  /databases/{id}/logs:
    get:
      operationId: getDatabasesIdLogs
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Logs — Show Database
      tags:
        - Logs
  /databases/{id}/logs/stream:
    get:
      operationId: getDatabasesIdLogsStream
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Logs — Stream Database
      tags:
        - Logs
  /databases/{id}/metrics:
    get:
      operationId: getDatabasesIdMetrics
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Metrics — Show Database
      tags:
        - Metrics
  /databases/{id}/move:
    post:
      operationId: postDatabasesIdMove
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "201":
          description: Created
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Databases — Move
      tags:
        - Databases
  /databases/{id}/replicas:
    post:
      operationId: postDatabasesIdReplicas
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "201":
          description: Created
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Databases — Create Replica
      tags:
        - Databases
  /databases/{id}/resize-compute:
    post:
      operationId: postDatabasesIdResizeCompute
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "201":
          description: Created
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Databases — Resize Compute
      tags:
        - Databases
  /databases/{id}/restart:
    post:
      operationId: restartDatabase
      parameters:
        - in: path
          name: id
          required: true
          schema:
            format: uuid
            type: string
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Database"
          description: Database after restart request
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"
      summary: Restart managed database
      tags:
        - Databases
  /databases/{id}/restore:
    post:
      operationId: postDatabasesIdRestore
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "201":
          description: Created
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Databases — Restore
      tags:
        - Databases
  /databases/{id}/restores:
    get:
      operationId: getDatabasesIdRestores
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Databases — List Restores
      tags:
        - Databases
  /databases/{id}/start:
    post:
      operationId: startDatabase
      parameters:
        - in: path
          name: id
          required: true
          schema:
            format: uuid
            type: string
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Database"
          description: Database after start request
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"
        "409":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
          description: Database is not in a startable state
      summary: Start managed database
      tags:
        - Databases
  /databases/{id}/stop:
    post:
      operationId: stopDatabase
      parameters:
        - in: path
          name: id
          required: true
          schema:
            format: uuid
            type: string
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Database"
          description: Database after stop request
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"
        "409":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
          description: Database is not in a stoppable state
      summary: Stop managed database
      tags:
        - Databases
  /databases/{id}/wake:
    post:
      operationId: postDatabasesIdWake
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "201":
          description: Created
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Databases — Wake
      tags:
        - Databases
  /deployments:
    get:
      description: "List all deployments for the authenticated tenant, most-recent first. Optional external attribution filters are scoped under that tenant and cannot cross tenant boundaries.\n"
      operationId: listDeployments
      parameters:
        - $ref: "#/components/parameters/ExternalWorkspaceId"
        - $ref: "#/components/parameters/ExternalUserId"
        - $ref: "#/components/parameters/ExternalProjectId"
      responses:
        "200":
          content:
            application/json:
              schema:
                properties:
                  data:
                    items:
                      $ref: "#/components/schemas/Deployment"
                    type: array
                type: object
          description: List of deployments
        "401":
          $ref: "#/components/responses/Unauthorized"
      security:
        - BearerToken: []
      summary: List deployments
      tags:
        - Deployments
    post:
      description: "Connect a GitHub repository to create a deployment. The platform will\nwatch for pushes and automatically rebuild on every push to the\nconfigured branch.\n\n**Webhook secret:** The `webhook_secret` field in the response is\nreturned **exactly once**. Add it to your GitHub repo webhook\n(`Settings → Webhooks → Add webhook`) with:\n- Payload URL: `https://api.miosa.ai/api/v1/integrations/github/webhook`\n- Content type: `application/json`\n- Secret: the returned `webhook_secret`\n- Events: `push` (and optionally `pull_request`)\n\nIf the secret is lost, delete and recreate the deployment.\n\n**Build pipeline:** v1 skeleton — build is queued but immediately\nfails with a stub error. Wire-up happens in the next sprint.\n"
      operationId: createDeployment
      requestBody:
        content:
          application/json:
            examples:
              full:
                summary: Full — explicit branch, commands, env vars
                value:
                  auto_deploy: true
                  branch: production
                  build_command: npm run build
                  env:
                    DATABASE_URL: postgres://...
                    NODE_ENV: production
                  external_project_id: landing-page-789
                  external_user_id: dr-smith-456
                  external_workspace_id: dental-office-123
                  name: my-api
                  repo_url: https://github.com/acme/my-api
                  run_command: npm start
              minimal:
                summary: Minimal — just repo URL and name
                value:
                  name: my-app
                  repo_url: https://github.com/acme/my-app
            schema:
              $ref: "#/components/schemas/CreateDeploymentRequest"
        required: true
      responses:
        "201":
          content:
            application/json:
              schema:
                properties:
                  data:
                    $ref: "#/components/schemas/Deployment"
                  webhook_secret:
                    description: "HMAC secret for GitHub webhook verification. Returned **once only** — store it immediately.\n"
                    example: a3f8b2c1d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9
                    type: string
                required:
                  - data
                  - webhook_secret
                type: object
          description: Deployment created
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "422":
          $ref: "#/components/responses/UnprocessableEntity"
      security:
        - BearerToken: []
      summary: Create a deployment (connect a repo)
      tags:
        - Deployments
  /deployments/{deployment_id}/previews:
    get:
      operationId: getDeploymentsDeploymentIdPreviews
      parameters:
        - in: path
          name: deployment_id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: PreviewEnvironments — Index
      tags:
        - PreviewEnvironments
  /deployments/{deployment_id}/previews/{id}:
    delete:
      operationId: deleteDeploymentsDeploymentIdPreviewsId
      parameters:
        - in: path
          name: deployment_id
          required: true
          schema:
            type: string
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        "204":
          description: Deleted
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: PreviewEnvironments — Destroy
      tags:
        - PreviewEnvironments
    get:
      operationId: getDeploymentsDeploymentIdPreviewsId
      parameters:
        - in: path
          name: deployment_id
          required: true
          schema:
            type: string
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: PreviewEnvironments — Show
      tags:
        - PreviewEnvironments
  /deployments/{id}:
    delete:
      description: "Delete a deployment, all its build history, and all env vars. Hard-delete — this action is irreversible. The runtime VM (if running) should be stopped first (TODO: auto-stop on delete in a future sprint).\n"
      operationId: deleteDeployment
      parameters:
        - $ref: "#/components/parameters/DeploymentId"
      responses:
        "200":
          content:
            application/json:
              schema:
                properties:
                  deleted:
                    example: true
                    type: boolean
                  id:
                    format: uuid
                    type: string
                type: object
          description: Deployment deleted
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"
      security:
        - BearerToken: []
      summary: Delete a deployment
      tags:
        - Deployments
    get:
      description: Fetch a single deployment by ID.
      operationId: getDeployment
      parameters:
        - $ref: "#/components/parameters/DeploymentId"
      responses:
        "200":
          content:
            application/json:
              schema:
                properties:
                  data:
                    $ref: "#/components/schemas/Deployment"
                type: object
          description: Deployment object
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"
      security:
        - BearerToken: []
      summary: Get a deployment
      tags:
        - Deployments
    patch:
      description: Update mutable deployment settings. `repo_url`, `webhook_secret`, and `state` are immutable through this endpoint.
      operationId: updateDeployment
      parameters:
        - $ref: "#/components/parameters/DeploymentId"
      requestBody:
        content:
          application/json:
            schema:
              properties:
                auto_deploy:
                  type: boolean
                branch:
                  type: string
                build_command:
                  nullable: true
                  type: string
                name:
                  type: string
                run_command:
                  nullable: true
                  type: string
              type: object
        required: true
      responses:
        "200":
          content:
            application/json:
              schema:
                properties:
                  data:
                    $ref: "#/components/schemas/Deployment"
                type: object
          description: Updated deployment
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"
        "422":
          $ref: "#/components/responses/UnprocessableEntity"
      security:
        - BearerToken: []
      summary: Update a deployment
      tags:
        - Deployments
  /deployments/{id}/builds:
    get:
      description: List all build runs for a deployment, most-recent first.
      operationId: listDeploymentBuilds
      parameters:
        - $ref: "#/components/parameters/DeploymentId"
      responses:
        "200":
          content:
            application/json:
              schema:
                properties:
                  data:
                    items:
                      $ref: "#/components/schemas/DeploymentBuild"
                    type: array
                type: object
          description: List of builds
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"
      security:
        - BearerToken: []
      summary: List build history
      tags:
        - Deployments
  /deployments/{id}/builds/{bid}:
    get:
      description: Fetch one build run by ID.
      operationId: getDeploymentBuild
      parameters:
        - $ref: "#/components/parameters/DeploymentId"
        - description: Build ID
          in: path
          name: bid
          required: true
          schema:
            format: uuid
            type: string
      responses:
        "200":
          content:
            application/json:
              schema:
                properties:
                  data:
                    $ref: "#/components/schemas/DeploymentBuild"
                type: object
          description: Build object
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"
      security:
        - BearerToken: []
      summary: Get a single build
      tags:
        - Deployments
  /deployments/{id}/cold-start-rate:
    get:
      operationId: getDeploymentsIdColdStartRate
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: DeploymentObservability — Cold Start Rate
      tags:
        - DeploymentObservability
  /deployments/{id}/connectors:
    get:
      operationId: getDeploymentsIdConnectors
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: DeploymentConnector — Index
      tags:
        - DeploymentConnector
    post:
      operationId: postDeploymentsIdConnectors
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "201":
          description: Created
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: DeploymentConnector — Attach
      tags:
        - DeploymentConnector
  /deployments/{id}/connectors/preflight:
    post:
      operationId: postDeploymentsIdConnectorsPreflight
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "201":
          description: Created
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: DeploymentConnector — Preflight
      tags:
        - DeploymentConnector
  /deployments/{id}/connectors/sync:
    post:
      operationId: postDeploymentsIdConnectorsSync
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "201":
          description: Created
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: DeploymentConnector — Sync
      tags:
        - DeploymentConnector
  /deployments/{id}/connectors/{binding}:
    delete:
      operationId: deleteDeploymentsIdConnectorsBinding
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
        - in: path
          name: binding
          required: true
          schema:
            type: string
      responses:
        "204":
          description: Deleted
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: DeploymentConnector — Detach
      tags:
        - DeploymentConnector
  /deployments/{id}/database:
    post:
      operationId: postDeploymentsIdDatabase
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "201":
          description: Created
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Deployments — Attach Database
      tags:
        - Deployments
  /deployments/{id}/domains:
    get:
      operationId: listDeploymentDomains
      parameters:
        - $ref: "#/components/parameters/DeploymentId"
      responses:
        "200":
          content:
            application/json:
              schema:
                properties:
                  data:
                    items:
                      $ref: "#/components/schemas/CustomDomain"
                    type: array
                type: object
          description: Domain list
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"
      security:
        - BearerToken: []
      summary: List deployment domains
      tags:
        - Deployments
        - Domains
    post:
      operationId: createDeploymentDomain
      parameters:
        - $ref: "#/components/parameters/DeploymentId"
      requestBody:
        content:
          application/json:
            schema:
              properties:
                fqdn:
                  example: app.customer.com
                  type: string
              required:
                - fqdn
              type: object
        required: true
      responses:
        "201":
          content:
            application/json:
              schema:
                properties:
                  data:
                    $ref: "#/components/schemas/CustomDomain"
                type: object
          description: Domain created
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"
      security:
        - BearerToken: []
      summary: Attach custom domain to deployment
      tags:
        - Deployments
        - Domains
  /deployments/{id}/domains/{domain_id}:
    delete:
      operationId: deleteDeploymentDomain
      parameters:
        - $ref: "#/components/parameters/DeploymentId"
        - in: path
          name: domain_id
          required: true
          schema:
            format: uuid
            type: string
      responses:
        "200":
          content:
            application/json:
              schema:
                properties:
                  data:
                    $ref: "#/components/schemas/CustomDomain"
                type: object
          description: Domain deleted
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"
      security:
        - BearerToken: []
      summary: Delete deployment domain
      tags:
        - Deployments
        - Domains
  /deployments/{id}/domains/{domain_id}/verify:
    post:
      operationId: verifyDeploymentDomain
      parameters:
        - $ref: "#/components/parameters/DeploymentId"
        - in: path
          name: domain_id
          required: true
          schema:
            format: uuid
            type: string
      responses:
        "200":
          content:
            application/json:
              schema:
                properties:
                  data:
                    $ref: "#/components/schemas/CustomDomain"
                type: object
          description: Domain verification result
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"
      security:
        - BearerToken: []
      summary: Verify deployment domain DNS
      tags:
        - Deployments
        - Domains
  /deployments/{id}/drop/sessions:
    post:
      operationId: postDeploymentsIdDropSessions
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "201":
          description: Created
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: DropSessions — Create
      tags:
        - DropSessions
  /deployments/{id}/drop/sessions/{sid}:
    delete:
      operationId: deleteDeploymentsIdDropSessionsSid
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
        - in: path
          name: sid
          required: true
          schema:
            type: string
      responses:
        "204":
          description: Deleted
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: DropSessions — Cancel
      tags:
        - DropSessions
  /deployments/{id}/drop/sessions/{sid}/chunks:
    post:
      operationId: postDeploymentsIdDropSessionsSidChunks
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
        - in: path
          name: sid
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "201":
          description: Created
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: DropSessions — Upload Chunk
      tags:
        - DropSessions
  /deployments/{id}/drop/sessions/{sid}/complete:
    post:
      operationId: postDeploymentsIdDropSessionsSidComplete
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
        - in: path
          name: sid
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "201":
          description: Created
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: DropSessions — Complete
      tags:
        - DropSessions
  /deployments/{id}/env:
    get:
      description: "Return the names and previews (first 3 + last 3 chars, or asterisks) of all env vars set for a deployment. Plaintext values are never returned by any endpoint.\n"
      operationId: getDeploymentEnv
      parameters:
        - $ref: "#/components/parameters/DeploymentId"
      responses:
        "200":
          content:
            application/json:
              schema:
                properties:
                  data:
                    items:
                      $ref: "#/components/schemas/EnvVarPreview"
                    type: array
                type: object
          description: Env var list
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"
      security:
        - BearerToken: []
      summary: List env var names + previews
      tags:
        - Deployments
    post:
      description: "Upsert one or more environment variables for a deployment. Values are encrypted at rest with ChaCha20-Poly1305. Returns names + previews (never plaintext). Existing vars with the same name are overwritten.\n"
      operationId: setDeploymentEnv
      parameters:
        - $ref: "#/components/parameters/DeploymentId"
      requestBody:
        content:
          application/json:
            schema:
              properties:
                env:
                  additionalProperties:
                    type: string
                  description: Key-value map of env vars (keys must be UPPER_SNAKE_CASE)
                  example:
                    DATABASE_URL: postgres://localhost/mydb
                    NODE_ENV: production
                  type: object
              required:
                - env
              type: object
        required: true
      responses:
        "200":
          content:
            application/json:
              schema:
                properties:
                  data:
                    items:
                      $ref: "#/components/schemas/EnvVarPreview"
                    type: array
                type: object
          description: Vars set
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"
      security:
        - BearerToken: []
      summary: Set env vars
      tags:
        - Deployments
  /deployments/{id}/logs:
    get:
      description: "Server-Sent Events stream of build log output for the current build.\n\n**Auth:** Requires a short-lived ticket from `POST /auth/sse-ticket`\nsupplied as `?ticket=<value>` (browsers cannot set Authorization on\nEventSource connections).\n\n**PubSub topic:** `deployment:{id}:logs`\n\n**TODO (build-pipeline sprint):** Full SSE streaming is not yet\nimplemented. The endpoint returns a placeholder SSE comment frame.\n"
      operationId: streamDeploymentLogs
      parameters:
        - $ref: "#/components/parameters/DeploymentId"
        - description: Short-lived SSE ticket from `POST /auth/sse-ticket`
          in: query
          name: ticket
          required: false
          schema:
            type: string
      responses:
        "200":
          content:
            text/event-stream:
              schema:
                example: "id: build-01\nevent: log_line\ndata: {\"stream\":\"stdout\",\"line\":\"npm run build\",\"ts\":\"2026-04-25T10:01:00Z\"}\n"
                type: string
          description: SSE stream opened
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"
      security:
        - BearerToken: []
      summary: Stream build logs (SSE)
      tags:
        - Deployments
  /deployments/{id}/metrics:
    get:
      operationId: getDeploymentsIdMetrics
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Metrics — Show Deployment
      tags:
        - Metrics
  /deployments/{id}/move:
    post:
      operationId: postDeploymentsIdMove
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "201":
          description: Created
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Deployments — Move
      tags:
        - Deployments
  /deployments/{id}/observability:
    get:
      operationId: getDeploymentsIdObservability
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: DeploymentObservability — Observability
      tags:
        - DeploymentObservability
  /deployments/{id}/plans:
    post:
      operationId: postDeploymentsIdPlans
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "201":
          description: Created
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: ApplicationPlans — Create
      tags:
        - ApplicationPlans
  /deployments/{id}/proof:
    get:
      operationId: getDeploymentsIdProof
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Deployments — Proof
      tags:
        - Deployments
  /deployments/{id}/publish:
    post:
      description: "Publish a sandbox output directory into a new immutable deployment version/release. By default production is unchanged.\n"
      operationId: publishDeploymentFromSandbox
      parameters:
        - $ref: "#/components/parameters/DeploymentId"
        - in: header
          name: Idempotency-Key
          required: false
          schema:
            type: string
      requestBody:
        content:
          application/json:
            example:
              entrypoint: index.html
              output_path: /workspace/dist
              promote: false
              source_sandbox_id: 3fa85f64-5717-4562-b3fc-2c963f66afa6
            schema:
              $ref: "#/components/schemas/PublishDeploymentRequest"
        required: true
      responses:
        "201":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PublishDeploymentResponse"
          description: Publish completed
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"
        "409":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
          description: Source sandbox is not running or output is empty.
      security:
        - BearerToken: []
      summary: Publish deployment from sandbox
      tags:
        - Deployments
  /deployments/{id}/redeploy:
    post:
      description: "Queue a new build for the deployment regardless of any pending push events. Returns 202 with the queued `DeploymentBuild` record. The actual build is processed asynchronously by Oban.\n"
      operationId: redeployDeployment
      parameters:
        - $ref: "#/components/parameters/DeploymentId"
      responses:
        "202":
          content:
            application/json:
              schema:
                properties:
                  data:
                    $ref: "#/components/schemas/DeploymentBuild"
                type: object
          description: Build queued
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"
      security:
        - BearerToken: []
      summary: Manually trigger a rebuild
      tags:
        - Deployments
  /deployments/{id}/releases:
    get:
      description: List immutable release artifacts for this deployment.
      operationId: listDeploymentReleases
      parameters:
        - $ref: "#/components/parameters/DeploymentId"
      responses:
        "200":
          content:
            application/json:
              schema:
                properties:
                  data:
                    items:
                      $ref: "#/components/schemas/DeploymentRelease"
                    type: array
                  total:
                    type: integer
                type: object
          description: Release list
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"
      security:
        - BearerToken: []
      summary: List deployment releases
      tags:
        - Deployments
  /deployments/{id}/releases/{release_id}:
    get:
      operationId: getDeploymentRelease
      parameters:
        - $ref: "#/components/parameters/DeploymentId"
        - in: path
          name: release_id
          required: true
          schema:
            format: uuid
            type: string
      responses:
        "200":
          content:
            application/json:
              schema:
                properties:
                  data:
                    $ref: "#/components/schemas/DeploymentRelease"
                type: object
          description: Release
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"
      security:
        - BearerToken: []
      summary: Get deployment release
      tags:
        - Deployments
  /deployments/{id}/releases/{release_id}/promote:
    post:
      description: "Atomically activate the specified ready release. Repeating the same Idempotency-Key returns the same durable operation.\n"
      operationId: promoteDeploymentRelease
      parameters:
        - $ref: "#/components/parameters/DeploymentId"
        - in: path
          name: release_id
          required: true
          schema:
            format: uuid
            type: string
        - in: header
          name: Idempotency-Key
          required: true
          schema:
            maxLength: 128
            minLength: 8
            type: string
      responses:
        "200":
          description: Release activation completed or was replayed
        "202":
          description: The original activation operation is still running
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"
        "409":
          description: Another mutation is running or the key payload differs
      security:
        - BearerToken: []
      summary: Promote one exact immutable release
      tags:
        - Deployments
  /deployments/{id}/request-logs:
    get:
      operationId: getDeploymentsIdRequestLogs
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: DeploymentObservability — Request Logs
      tags:
        - DeploymentObservability
  /deployments/{id}/rollback:
    post:
      description: "Promote an older ready version (or an exact release) back to production. Repeating the same Idempotency-Key returns the same durable operation.\n"
      operationId: rollbackDeployment
      parameters:
        - $ref: "#/components/parameters/DeploymentId"
        - in: header
          name: Idempotency-Key
          required: true
          schema:
            maxLength: 128
            minLength: 8
            type: string
      requestBody:
        content:
          application/json:
            schema:
              properties:
                release_id:
                  format: uuid
                  type: string
                version_id:
                  format: uuid
                  type: string
              type: object
        required: true
      responses:
        "200":
          description: Rollback completed or was replayed
        "202":
          description: The original rollback operation is still running
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"
        "409":
          description: Another mutation is running or the key payload differs
      security:
        - BearerToken: []
      summary: Roll back deployment
      tags:
        - Deployments
  /deployments/{id}/routes:
    get:
      operationId: getDeploymentsIdRoutes
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: DeploymentObservability — Routes
      tags:
        - DeploymentObservability
  /deployments/{id}/runtime-instances:
    get:
      description: "List production runtime VMs for dynamic releases. Static deployments can return an empty list because no per-app runtime VM is needed.\n"
      operationId: listDeploymentRuntimeInstances
      parameters:
        - $ref: "#/components/parameters/DeploymentId"
      responses:
        "200":
          content:
            application/json:
              schema:
                properties:
                  data:
                    items:
                      $ref: "#/components/schemas/RuntimeInstance"
                    type: array
                  total:
                    type: integer
                type: object
          description: Runtime instance list
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"
      security:
        - BearerToken: []
      summary: List deployment runtime instances
      tags:
        - Deployments
  /deployments/{id}/runtime-instances/{instance_id}:
    get:
      operationId: getDeploymentRuntimeInstance
      parameters:
        - $ref: "#/components/parameters/DeploymentId"
        - in: path
          name: instance_id
          required: true
          schema:
            format: uuid
            type: string
      responses:
        "200":
          content:
            application/json:
              schema:
                properties:
                  data:
                    $ref: "#/components/schemas/RuntimeInstance"
                type: object
          description: Runtime instance
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"
      security:
        - BearerToken: []
      summary: Get deployment runtime instance
      tags:
        - Deployments
  /deployments/{id}/runtime-instances/{instance_id}/logs:
    get:
      description: Fetch the tail of `/var/log/miosa-runtime.log` from a healthy runtime VM.
      operationId: getDeploymentRuntimeInstanceLogs
      parameters:
        - $ref: "#/components/parameters/DeploymentId"
        - in: path
          name: instance_id
          required: true
          schema:
            format: uuid
            type: string
        - in: query
          name: lines
          required: false
          schema:
            default: 100
            maximum: 500
            minimum: 1
            type: integer
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RuntimeLogsResponse"
          description: Runtime logs
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"
        "409":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
          description: Runtime instance does not have a reachable target.
      security:
        - BearerToken: []
      summary: Get deployment runtime logs
      tags:
        - Deployments
  /deployments/{id}/runtime-logs:
    get:
      operationId: getDeploymentsIdRuntimeLogs
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Logs — Show Deployment Runtime
      tags:
        - Logs
  /deployments/{id}/runtime-logs/stream:
    get:
      operationId: getDeploymentsIdRuntimeLogsStream
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Logs — Stream Deployment Runtime
      tags:
        - Logs
  /deployments/{id}/start-type-summary:
    get:
      operationId: getDeploymentsIdStartTypeSummary
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: DeploymentObservability — Start Type Summary
      tags:
        - DeploymentObservability
  /deployments/{id}/versions:
    get:
      description: List immutable versions produced by publishes/builds.
      operationId: listDeploymentVersions
      parameters:
        - $ref: "#/components/parameters/DeploymentId"
      responses:
        "200":
          content:
            application/json:
              schema:
                properties:
                  data:
                    items:
                      $ref: "#/components/schemas/DeploymentVersion"
                    type: array
                  total:
                    type: integer
                type: object
          description: Version list
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"
      security:
        - BearerToken: []
      summary: List deployment versions
      tags:
        - Deployments
  /deployments/{id}/versions/{version_id}:
    get:
      operationId: getDeploymentVersion
      parameters:
        - $ref: "#/components/parameters/DeploymentId"
        - in: path
          name: version_id
          required: true
          schema:
            format: uuid
            type: string
      responses:
        "200":
          content:
            application/json:
              schema:
                properties:
                  data:
                    $ref: "#/components/schemas/DeploymentVersion"
                type: object
          description: Version
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"
      security:
        - BearerToken: []
      summary: Get deployment version
      tags:
        - Deployments
  /deployments/{id}/versions/{version_id}/logs:
    get:
      operationId: getDeploymentsIdVersionsVersionIdLogs
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
        - in: path
          name: version_id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: DeploymentLogs — Show
      tags:
        - DeploymentLogs
  /deployments/{id}/versions/{version_id}/logs/stream:
    get:
      operationId: getDeploymentsIdVersionsVersionIdLogsStream
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
        - in: path
          name: version_id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: DeploymentLogs — Stream
      tags:
        - DeploymentLogs
  /deployments/{id}/versions/{version_id}/migration-backup:
    post:
      operationId: postDeploymentsIdVersionsVersionIdMigrationBackup
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
        - in: path
          name: version_id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "201":
          description: Created
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Deployments — Prepare Migration Backup
      tags:
        - Deployments
  /deployments/{id}/versions/{version_id}/promote:
    post:
      description: Promote a ready version to production.
      operationId: promoteDeploymentVersion
      parameters:
        - $ref: "#/components/parameters/DeploymentId"
        - in: path
          name: version_id
          required: true
          schema:
            format: uuid
            type: string
      responses:
        "200":
          content:
            application/json:
              schema:
                properties:
                  data:
                    $ref: "#/components/schemas/Deployment"
                type: object
          description: Deployment after promotion
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"
      security:
        - BearerToken: []
      summary: Promote deployment version
      tags:
        - Deployments
  /deployments/{id}/webhook-secret:
    post:
      description: Generate a new GitHub webhook secret. The plaintext secret is returned once and must be stored by the caller.
      operationId: rotateDeploymentWebhookSecret
      parameters:
        - $ref: "#/components/parameters/DeploymentId"
      responses:
        "200":
          content:
            application/json:
              schema:
                properties:
                  webhook_secret:
                    description: Plaintext secret returned once.
                    type: string
                required:
                  - webhook_secret
                type: object
          description: Webhook secret rotated
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"
      security:
        - BearerToken: []
      summary: Rotate deployment webhook secret
      tags:
        - Deployments
  /devices:
    get:
      operationId: getDevices
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Devices — Index
      tags:
        - Devices
  /devices/{id}:
    delete:
      operationId: deleteDevicesId
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        "204":
          description: Deleted
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Devices — Destroy
      tags:
        - Devices
    get:
      operationId: getDevicesId
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Devices — Show
      tags:
        - Devices
  /devices/{id}/browser:
    get:
      operationId: getDevicesIdBrowser
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Devices — Browser
      tags:
        - Devices
  /devices/{id}/capabilities:
    get:
      operationId: getDevicesIdCapabilities
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Devices — Capabilities
      tags:
        - Devices
  /devices/{id}/exec:
    post:
      operationId: postDevicesIdExec
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "201":
          description: Created
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Devices — Exec
      tags:
        - Devices
  /devices/{id}/expose:
    post:
      operationId: postDevicesIdExpose
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "201":
          description: Created
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Devices — Expose
      tags:
        - Devices
  /devices/{id}/extend:
    post:
      operationId: postDevicesIdExtend
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "201":
          description: Created
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Devices — Extend
      tags:
        - Devices
  /devices/{id}/files:
    get:
      operationId: getDevicesIdFiles
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Devices — List Files
      tags:
        - Devices
  /devices/{id}/files/read:
    get:
      operationId: getDevicesIdFilesRead
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Devices — Read File
      tags:
        - Devices
  /devices/{id}/files/write:
    post:
      operationId: postDevicesIdFilesWrite
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "201":
          description: Created
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Devices — Write File
      tags:
        - Devices
  /devices/{id}/pause:
    post:
      operationId: postDevicesIdPause
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "201":
          description: Created
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Devices — Pause
      tags:
        - Devices
  /devices/{id}/resume:
    post:
      operationId: postDevicesIdResume
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "201":
          description: Created
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Devices — Resume
      tags:
        - Devices
  /devices/{id}/stop:
    post:
      operationId: postDevicesIdStop
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "201":
          description: Created
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Devices — Stop
      tags:
        - Devices
  /docker-deploy/hosts:
    get:
      operationId: getDockerDeployHosts
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: DockerDeployHosts — Index
      tags:
        - DockerDeployHosts
  /docker-deploy/hosts/ensure:
    post:
      operationId: postDockerDeployHostsEnsure
      responses:
        "200":
          description: Success
        "201":
          description: Created
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: DockerDeployHosts — Ensure
      tags:
        - DockerDeployHosts
  /docker-deploy/hosts/{id}:
    get:
      operationId: getDockerDeployHostsId
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: DockerDeployHosts — Show
      tags:
        - DockerDeployHosts
  /docker-deploy/hosts/{id}/images/{kind}:
    get:
      operationId: getDockerDeployHostsIdImagesKind
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
        - in: path
          name: kind
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: DockerDeployHosts — Image
      tags:
        - DockerDeployHosts
  /docker-deploy/hosts/{id}/portal-sso:
    get:
      operationId: getDockerDeployHostsIdPortalSso
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: DockerDeployHosts — Portal Sso
      tags:
        - DockerDeployHosts
  /docker-deploy/hosts/{id}/provision:
    post:
      operationId: postDockerDeployHostsIdProvision
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "201":
          description: Created
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: DockerDeployHosts — Provision
      tags:
        - DockerDeployHosts
  /docker-deploy/hosts/{id}/restart:
    post:
      operationId: postDockerDeployHostsIdRestart
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "201":
          description: Created
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: DockerDeployHosts — Restart
      tags:
        - DockerDeployHosts
  /docker-deploy/hosts/{id}/upgrade:
    post:
      operationId: postDockerDeployHostsIdUpgrade
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "201":
          description: Created
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: DockerDeployHosts — Upgrade
      tags:
        - DockerDeployHosts
  /docker-deploy/templates:
    get:
      operationId: getDockerDeployTemplates
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: DockerDeployTemplates — Index
      tags:
        - DockerDeployTemplates
  /docker-deploy/templates/{id}:
    get:
      operationId: getDockerDeployTemplatesId
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: DockerDeployTemplates — Show
      tags:
        - DockerDeployTemplates
  /domains:
    post:
      operationId: postDomains
      responses:
        "200":
          description: Success
        "201":
          description: Created
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: FlatCustomDomains — Create Domain
      tags:
        - FlatCustomDomains
  /domains/{hostname}:
    delete:
      operationId: deleteDomainsHostname
      parameters:
        - in: path
          name: hostname
          required: true
          schema:
            type: string
      responses:
        "204":
          description: Deleted
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: FlatCustomDomains — Delete Domain By Hostname
      tags:
        - FlatCustomDomains
    get:
      operationId: getDomainsHostname
      parameters:
        - in: path
          name: hostname
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: FlatCustomDomains — Show Domain
      tags:
        - FlatCustomDomains
  /domains/{hostname}/assign:
    post:
      operationId: postDomainsHostnameAssign
      parameters:
        - in: path
          name: hostname
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "201":
          description: Created
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: FlatCustomDomains — Assign Domain
      tags:
        - FlatCustomDomains
  /domains/{hostname}/verify:
    post:
      operationId: postDomainsHostnameVerify
      parameters:
        - in: path
          name: hostname
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "201":
          description: Created
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: FlatCustomDomains — Verify Domain
      tags:
        - FlatCustomDomains
  /egress/allowlist:
    get:
      operationId: getEgressAllowlist
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: EgressAllowlist — Index
      tags:
        - EgressAllowlist
    post:
      operationId: postEgressAllowlist
      responses:
        "200":
          description: Success
        "201":
          description: Created
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: EgressAllowlist — Create
      tags:
        - EgressAllowlist
  /egress/allowlist/{id}:
    delete:
      operationId: deleteEgressAllowlistId
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        "204":
          description: Deleted
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: EgressAllowlist — Delete
      tags:
        - EgressAllowlist
  /egress/audit:
    get:
      operationId: getEgressAudit
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: EgressAudit — Index
      tags:
        - EgressAudit
  /egress/audit/suggestions:
    get:
      operationId: getEgressAuditSuggestions
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: EgressAudit — Suggestions
      tags:
        - EgressAudit
  /egress/audit/{id}:
    get:
      operationId: getEgressAuditId
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: EgressAudit — Show
      tags:
        - EgressAudit
  /egress/bindings:
    get:
      operationId: getEgressBindings
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: EgressBinding — Index
      tags:
        - EgressBinding
    post:
      operationId: postEgressBindings
      responses:
        "200":
          description: Success
        "201":
          description: Created
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: EgressBinding — Create
      tags:
        - EgressBinding
  /egress/bindings/{id}:
    delete:
      operationId: deleteEgressBindingsId
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        "204":
          description: Deleted
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: EgressBinding — Delete
      tags:
        - EgressBinding
  /egress/oauth/admin/providers:
    post:
      operationId: postEgressOauthAdminProviders
      responses:
        "200":
          description: Success
        "201":
          description: Created
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: EgressOauthProvider — Admin Create
      tags:
        - EgressOauthProvider
  /egress/oauth/admin/providers/{id}:
    delete:
      operationId: deleteEgressOauthAdminProvidersId
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        "204":
          description: Deleted
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: EgressOauthProvider — Admin Delete
      tags:
        - EgressOauthProvider
  /egress/oauth/callback:
    get:
      operationId: getEgressOauthCallback
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: EgressOauthProvider — Callback
      tags:
        - EgressOauthProvider
  /egress/oauth/providers:
    get:
      operationId: getEgressOauthProviders
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: EgressOauthProvider — List Providers
      tags:
        - EgressOauthProvider
  /egress/oauth/start:
    post:
      operationId: postEgressOauthStart
      responses:
        "200":
          description: Success
        "201":
          description: Created
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: EgressOauthProvider — Start
      tags:
        - EgressOauthProvider
  /egress/policies:
    get:
      operationId: getEgressPolicies
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: EgressPolicy — Index
      tags:
        - EgressPolicy
    post:
      operationId: postEgressPolicies
      responses:
        "200":
          description: Success
        "201":
          description: Created
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: EgressPolicy — Create
      tags:
        - EgressPolicy
  /egress/policies/{id}:
    get:
      operationId: getEgressPoliciesId
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: EgressPolicy — Show
      tags:
        - EgressPolicy
    patch:
      operationId: patchEgressPoliciesId
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: EgressPolicy — Update
      tags:
        - EgressPolicy
    put:
      operationId: putEgressPoliciesId
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: EgressPolicy — Update
      tags:
        - EgressPolicy
  /egress/secrets:
    get:
      operationId: getEgressSecrets
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: EgressSecret — Index
      tags:
        - EgressSecret
    post:
      operationId: postEgressSecrets
      responses:
        "200":
          description: Success
        "201":
          description: Created
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: EgressSecret — Create
      tags:
        - EgressSecret
  /egress/secrets/{id}:
    delete:
      operationId: deleteEgressSecretsId
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        "204":
          description: Deleted
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: EgressSecret — Delete
      tags:
        - EgressSecret
    get:
      operationId: getEgressSecretsId
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: EgressSecret — Show
      tags:
        - EgressSecret
    patch:
      operationId: patchEgressSecretsId
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: EgressSecret — Update
      tags:
        - EgressSecret
    put:
      operationId: putEgressSecretsId
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: EgressSecret — Update
      tags:
        - EgressSecret
  /events/stream:
    get:
      operationId: getEventsStream
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: EventsStream — Stream
      tags:
        - EventsStream
  /external-keys:
    get:
      operationId: getExternalKeys
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: ExternalKeys — Index
      tags:
        - ExternalKeys
    post:
      operationId: postExternalKeys
      responses:
        "200":
          description: Success
        "201":
          description: Created
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: ExternalKeys — Create
      tags:
        - ExternalKeys
  /external-keys/{provider}:
    delete:
      operationId: deleteExternalKeysProvider
      parameters:
        - in: path
          name: provider
          required: true
          schema:
            type: string
      responses:
        "204":
          description: Deleted
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: ExternalKeys — Delete
      tags:
        - ExternalKeys
  /external-keys/{provider}/resolve:
    get:
      operationId: getExternalKeysProviderResolve
      parameters:
        - in: path
          name: provider
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: ExternalKeys — Resolve
      tags:
        - ExternalKeys
  /external-users/{external_user_id}/effective-policy:
    get:
      operationId: getExternalUsersExternalUserIdEffectivePolicy
      parameters:
        - in: path
          name: external_user_id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: ExternalUserPolicy — Effective Policy
      tags:
        - ExternalUserPolicy
  /external-users/{external_user_id}/policy:
    delete:
      operationId: deleteExternalUsersExternalUserIdPolicy
      parameters:
        - in: path
          name: external_user_id
          required: true
          schema:
            type: string
      responses:
        "204":
          description: Deleted
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: ExternalUserPolicy — Delete
      tags:
        - ExternalUserPolicy
    get:
      operationId: getExternalUsersExternalUserIdPolicy
      parameters:
        - in: path
          name: external_user_id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: ExternalUserPolicy — Show
      tags:
        - ExternalUserPolicy
    put:
      operationId: putExternalUsersExternalUserIdPolicy
      parameters:
        - in: path
          name: external_user_id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: ExternalUserPolicy — Upsert
      tags:
        - ExternalUserPolicy
  /feedback:
    post:
      operationId: postFeedback
      responses:
        "200":
          description: Success
        "201":
          description: Created
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Feedback — Submit
      tags:
        - Feedback
  /fleet/computers:
    get:
      operationId: getFleetComputers
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Fleet — Computers
      tags:
        - Fleet
  /fleet/status:
    get:
      operationId: getFleetStatus
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Fleet — Status
      tags:
        - Fleet
  /functions:
    get:
      operationId: getFunctions
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: EdgeFunctions — Index
      tags:
        - EdgeFunctions
    post:
      operationId: postFunctions
      responses:
        "200":
          description: Success
        "201":
          description: Created
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: EdgeFunctions — Create
      tags:
        - EdgeFunctions
  /functions/{id}:
    delete:
      operationId: deleteFunctionsId
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        "204":
          description: Deleted
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: EdgeFunctions — Delete
      tags:
        - EdgeFunctions
    get:
      operationId: getFunctionsId
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: EdgeFunctions — Show
      tags:
        - EdgeFunctions
    patch:
      operationId: patchFunctionsId
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: EdgeFunctions — Update
      tags:
        - EdgeFunctions
  /functions/{id}/invoke:
    post:
      operationId: postFunctionsIdInvoke
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "201":
          description: Created
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: EdgeFunctions — Invoke
      tags:
        - EdgeFunctions
  /grants:
    get:
      operationId: getGrants
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Grants — Index
      tags:
        - Grants
    post:
      operationId: postGrants
      responses:
        "200":
          description: Success
        "201":
          description: Created
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Grants — Create
      tags:
        - Grants
  /grants/{id}:
    delete:
      operationId: deleteGrantsId
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        "204":
          description: Deleted
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Grants — Delete
      tags:
        - Grants
    get:
      operationId: getGrantsId
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Grants — Show
      tags:
        - Grants
    patch:
      operationId: patchGrantsId
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Grants — Update
      tags:
        - Grants
    put:
      operationId: putGrantsId
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Grants — Update
      tags:
        - Grants
  /health-checks:
    get:
      operationId: getHealthChecks
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: HealthChecks — Index
      tags:
        - HealthChecks
    post:
      operationId: postHealthChecks
      responses:
        "200":
          description: Success
        "201":
          description: Created
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: HealthChecks — Create
      tags:
        - HealthChecks
  /health-checks/{id}:
    delete:
      operationId: deleteHealthChecksId
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        "204":
          description: Deleted
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: HealthChecks — Delete
      tags:
        - HealthChecks
    get:
      operationId: getHealthChecksId
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: HealthChecks — Show
      tags:
        - HealthChecks
    patch:
      operationId: patchHealthChecksId
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: HealthChecks — Update
      tags:
        - HealthChecks
  /integrations:
    get:
      operationId: getIntegrations
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Integrations — Index
      tags:
        - Integrations
  /integrations/bitbucket/webhook:
    post:
      operationId: postIntegrationsBitbucketWebhook
      responses:
        "200":
          description: Success
        "201":
          description: Created
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: BitbucketWebhook — Receive
      tags:
        - BitbucketWebhook
  /integrations/catalog:
    get:
      operationId: getIntegrationsCatalog
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Integrations — Catalog
      tags:
        - Integrations
  /integrations/discord/send-test:
    post:
      operationId: postIntegrationsDiscordSendTest
      responses:
        "200":
          description: Success
        "201":
          description: Created
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Integrations — Discord Send Test
      tags:
        - Integrations
  /integrations/github/repos:
    get:
      operationId: getIntegrationsGithubRepos
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Integrations — Github Repos
      tags:
        - Integrations
  /integrations/github/ssh-keys:
    get:
      operationId: getIntegrationsGithubSshKeys
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Integrations — Github Ssh Keys
      tags:
        - Integrations
  /integrations/github/webhook:
    post:
      description: "Receives inbound GitHub App webhook events (`push`, `pull_request`, `ping`).\n\n**Auth:** No JWT or API key required. Payloads are authenticated via\nHMAC-SHA256 (`X-Hub-Signature-256` header) using the per-deployment\n`webhook_secret` returned at deployment creation time.\n\n**Idempotency:** The `X-GitHub-Delivery` UUID is logged for tracing.\nDuplicate build prevention via delivery ID is a v2 feature.\n\nAlways returns **204** immediately. Build triggering is async (Oban).\nGitHub enforces a 10-second response deadline — we do not block.\n"
      operationId: githubWebhook
      parameters:
        - in: header
          name: X-GitHub-Event
          required: true
          schema:
            enum:
              - push
              - pull_request
              - ping
            type: string
        - description: HMAC-SHA256 signature of the request body
          in: header
          name: X-Hub-Signature-256
          required: true
          schema:
            example: sha256=abc123...
            type: string
        - description: Unique delivery UUID from GitHub
          in: header
          name: X-GitHub-Delivery
          required: false
          schema:
            format: uuid
            type: string
      requestBody:
        content:
          application/json:
            schema:
              description: GitHub webhook payload (event-specific shape)
              type: object
        required: true
      responses:
        "204":
          description: Event accepted (processing is async)
        "400":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
          description: Missing X-GitHub-Event header
      summary: GitHub webhook receiver
      tags:
        - Deployments
  /integrations/gitlab/webhook:
    post:
      operationId: postIntegrationsGitlabWebhook
      responses:
        "200":
          description: Success
        "201":
          description: Created
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: GitlabWebhook — Receive
      tags:
        - GitlabWebhook
  /integrations/linear/create-issue:
    post:
      operationId: postIntegrationsLinearCreateIssue
      responses:
        "200":
          description: Success
        "201":
          description: Created
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Integrations — Linear Create Issue
      tags:
        - Integrations
  /integrations/slack/send-test:
    post:
      operationId: postIntegrationsSlackSendTest
      responses:
        "200":
          description: Success
        "201":
          description: Created
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Integrations — Slack Send Test
      tags:
        - Integrations
  /integrations/{provider}:
    delete:
      operationId: deleteIntegrationsProvider
      parameters:
        - in: path
          name: provider
          required: true
          schema:
            type: string
      responses:
        "204":
          description: Deleted
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Integrations — Delete
      tags:
        - Integrations
  /integrations/{provider}/callback:
    get:
      operationId: getIntegrationsProviderCallback
      parameters:
        - in: path
          name: provider
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Integrations — Callback
      tags:
        - Integrations
  /integrations/{provider}/refresh:
    post:
      operationId: postIntegrationsProviderRefresh
      parameters:
        - in: path
          name: provider
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "201":
          description: Created
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Integrations — Force Refresh
      tags:
        - Integrations
  /integrations/{provider}/start:
    get:
      operationId: getIntegrationsProviderStart
      parameters:
        - in: path
          name: provider
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Integrations — Start Flow
      tags:
        - Integrations
  /intelligence/agent-model-assignments:
    get:
      operationId: listIntelligenceAgentModelAssignments
      responses:
        "200":
          content:
            application/json:
              schema:
                properties:
                  data:
                    items:
                      $ref: "#/components/schemas/IntelligenceAgentModelAssignment"
                    type: array
                type: object
          description: Assignments
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
      summary: List agent-to-model assignments
      tags:
        - Intelligence Assignments
  /intelligence/agent-model-assignments/{agent_id}:
    delete:
      operationId: deleteIntelligenceAgentModelAssignment
      responses:
        "204":
          description: Assignment deleted
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
      summary: Delete an agent-to-model assignment
      tags:
        - Intelligence Assignments
    get:
      operationId: getIntelligenceAgentModelAssignment
      responses:
        "200":
          content:
            application/json:
              schema:
                properties:
                  data:
                    $ref: "#/components/schemas/IntelligenceAgentModelAssignment"
                type: object
          description: Assignment
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
      summary: Get an agent-to-model assignment
      tags:
        - Intelligence Assignments
    parameters:
      - in: path
        name: agent_id
        required: true
        schema:
          type: string
    put:
      operationId: putIntelligenceAgentModelAssignment
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/IntelligenceAgentModelAssignment"
        required: true
      responses:
        "200":
          content:
            application/json:
              schema:
                properties:
                  data:
                    $ref: "#/components/schemas/IntelligenceAgentModelAssignment"
                type: object
          description: Assignment
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "422":
          $ref: "#/components/responses/ValidationError"
      summary: Create or replace an agent-to-model assignment
      tags:
        - Intelligence Assignments
  /intelligence/chat/completions:
    post:
      operationId: postIntelligenceChatCompletions
      responses:
        "200":
          description: Success
        "201":
          description: Created
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Chat — Create
      tags:
        - Chat
  /intelligence/completions:
    post:
      operationId: postIntelligenceCompletions
      responses:
        "200":
          description: Success
        "201":
          description: Created
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Completions — Create
      tags:
        - Completions
  /intelligence/embeddings:
    post:
      operationId: postIntelligenceEmbeddings
      responses:
        "200":
          description: Success
        "201":
          description: Created
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Embeddings — Create
      tags:
        - Embeddings
  /intelligence/evaluations:
    get:
      operationId: listIntelligenceEvaluationPolicies
      responses:
        "200":
          content:
            application/json:
              schema:
                properties:
                  data:
                    items:
                      $ref: "#/components/schemas/IntelligenceEvaluationPolicy"
                    type: array
                type: object
          description: Policies
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
      summary: List evaluation policies
      tags:
        - Intelligence Evaluations
    post:
      operationId: createIntelligenceEvaluationPolicy
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/IntelligenceEvaluationPolicy"
        required: true
      responses:
        "201":
          content:
            application/json:
              schema:
                properties:
                  data:
                    $ref: "#/components/schemas/IntelligenceEvaluationPolicy"
                type: object
          description: Policy created
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "422":
          $ref: "#/components/responses/ValidationError"
      summary: Create an evaluation policy
      tags:
        - Intelligence Evaluations
  /intelligence/evaluations/runs:
    get:
      operationId: listIntelligenceEvaluationRuns
      parameters:
        - in: query
          name: policy_id
          required: false
          schema:
            format: uuid
            type: string
      responses:
        "200":
          content:
            application/json:
              schema:
                properties:
                  data:
                    items:
                      $ref: "#/components/schemas/IntelligenceEvaluationRun"
                    type: array
                type: object
          description: Runs
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
      summary: List evaluation runs
      tags:
        - Intelligence Evaluations
  /intelligence/evaluations/runs/{id}:
    get:
      operationId: getIntelligenceEvaluationRun
      parameters:
        - in: path
          name: id
          required: true
          schema:
            format: uuid
            type: string
      responses:
        "200":
          content:
            application/json:
              schema:
                properties:
                  data:
                    $ref: "#/components/schemas/IntelligenceEvaluationRun"
                type: object
          description: Run
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
      summary: Get an evaluation run
      tags:
        - Intelligence Evaluations
  /intelligence/evaluations/runs/{id}/cancel:
    post:
      operationId: cancelIntelligenceEvaluationRun
      parameters:
        - in: path
          name: id
          required: true
          schema:
            format: uuid
            type: string
      responses:
        "200":
          content:
            application/json:
              schema:
                properties:
                  data:
                    $ref: "#/components/schemas/IntelligenceEvaluationRun"
                type: object
          description: Cancelled run
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
        "409":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
          description: Run is already terminal
      summary: Cancel a queued or running evaluation
      tags:
        - Intelligence Evaluations
  /intelligence/evaluations/runs/{id}/claim:
    post:
      operationId: claimIntelligenceEvaluationRun
      parameters:
        - in: path
          name: id
          required: true
          schema:
            format: uuid
            type: string
      responses:
        "200":
          content:
            application/json:
              schema:
                properties:
                  data:
                    $ref: "#/components/schemas/IntelligenceEvaluationRun"
                type: object
          description: Running evaluation
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
        "409":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
          description: Run is not queued
      summary: Atomically claim a queued evaluation run
      tags:
        - Intelligence Evaluations
  /intelligence/evaluations/runs/{id}/result:
    post:
      operationId: reportIntelligenceEvaluationRun
      parameters:
        - in: path
          name: id
          required: true
          schema:
            format: uuid
            type: string
      requestBody:
        content:
          application/json:
            schema:
              properties:
                error:
                  additionalProperties: true
                  type: object
                results:
                  items:
                    additionalProperties: true
                    type: object
                  type: array
                status:
                  enum:
                    - completed
                    - failed
                  type: string
                summary:
                  additionalProperties: true
                  type: object
              required:
                - status
              type: object
        required: true
      responses:
        "200":
          content:
            application/json:
              schema:
                properties:
                  data:
                    $ref: "#/components/schemas/IntelligenceEvaluationRun"
                type: object
          description: Terminal evaluation run
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
        "409":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
          description: Run is not running
        "422":
          $ref: "#/components/responses/ValidationError"
      summary: Report a completed or failed evaluation
      tags:
        - Intelligence Evaluations
  /intelligence/evaluations/{id}:
    delete:
      operationId: deleteIntelligenceEvaluationPolicy
      responses:
        "204":
          description: Policy deleted
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
      summary: Delete an evaluation policy
      tags:
        - Intelligence Evaluations
    get:
      operationId: getIntelligenceEvaluationPolicy
      responses:
        "200":
          content:
            application/json:
              schema:
                properties:
                  data:
                    $ref: "#/components/schemas/IntelligenceEvaluationPolicy"
                type: object
          description: Policy
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
      summary: Get an evaluation policy
      tags:
        - Intelligence Evaluations
    parameters:
      - in: path
        name: id
        required: true
        schema:
          format: uuid
          type: string
    patch:
      operationId: updateIntelligenceEvaluationPolicy
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/IntelligenceEvaluationPolicy"
        required: true
      responses:
        "200":
          content:
            application/json:
              schema:
                properties:
                  data:
                    $ref: "#/components/schemas/IntelligenceEvaluationPolicy"
                type: object
          description: Updated policy
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
        "422":
          $ref: "#/components/responses/ValidationError"
      summary: Update an evaluation policy
      tags:
        - Intelligence Evaluations
  /intelligence/evaluations/{id}/runs:
    post:
      operationId: executeIntelligenceEvaluation
      parameters:
        - in: path
          name: id
          required: true
          schema:
            format: uuid
            type: string
      requestBody:
        content:
          application/json:
            schema:
              properties:
                idempotency_key:
                  type: string
              required:
                - idempotency_key
              type: object
        required: true
      responses:
        "202":
          content:
            application/json:
              schema:
                properties:
                  data:
                    $ref: "#/components/schemas/IntelligenceEvaluationRun"
                type: object
          description: Run queued or existing idempotent run returned
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
        "409":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
          description: Policy disabled
      summary: Queue an evaluation run idempotently
      tags:
        - Intelligence Evaluations
  /intelligence/gateway/budget:
    get:
      operationId: getIntelligenceGatewayBudget
      responses:
        "200":
          content:
            application/json:
              schema:
                properties:
                  data:
                    oneOf:
                      - $ref: "#/components/schemas/IntelligenceGatewayBudget"
                      - type: "null"
                type: object
          description: Budget or null when unconfigured
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
      summary: Get gateway limits and consumption
      tags:
        - Intelligence Gateway
    put:
      operationId: putIntelligenceGatewayBudget
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/IntelligenceGatewayBudget"
        required: true
      responses:
        "200":
          content:
            application/json:
              schema:
                properties:
                  data:
                    $ref: "#/components/schemas/IntelligenceGatewayBudget"
                type: object
          description: Budget configuration
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "422":
          $ref: "#/components/responses/ValidationError"
      summary: Configure gateway limits and enforcement
      tags:
        - Intelligence Gateway
  /intelligence/gateway/health:
    get:
      operationId: getIntelligenceGatewayHealth
      responses:
        "200":
          content:
            application/json:
              schema:
                properties:
                  data:
                    additionalProperties: true
                    type: object
                type: object
          description: Tenant-scoped routing, provider, and budget health
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
      summary: Get gateway provider and budget health
      tags:
        - Intelligence Gateway
  /intelligence/gateway/policies:
    get:
      operationId: listIntelligenceGatewayPolicies
      responses:
        "200":
          content:
            application/json:
              schema:
                properties:
                  data:
                    items:
                      $ref: "#/components/schemas/IntelligenceGatewayPolicy"
                    type: array
                type: object
          description: Tenant-scoped policies in priority order
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
      summary: List routing and fallback policies
      tags:
        - Intelligence Gateway
    post:
      operationId: createIntelligenceGatewayPolicy
      requestBody:
        content:
          application/json:
            schema:
              allOf:
                - $ref: "#/components/schemas/IntelligenceGatewayPolicy"
              required:
                - name
                - primary_model
        required: true
      responses:
        "201":
          content:
            application/json:
              schema:
                properties:
                  data:
                    $ref: "#/components/schemas/IntelligenceGatewayPolicy"
                type: object
          description: Policy created
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "422":
          $ref: "#/components/responses/ValidationError"
      summary: Create a routing and fallback policy
      tags:
        - Intelligence Gateway
  /intelligence/gateway/policies/{id}:
    delete:
      operationId: deleteIntelligenceGatewayPolicy
      responses:
        "204":
          description: Policy deleted
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
      summary: Delete a routing and fallback policy
      tags:
        - Intelligence Gateway
    get:
      operationId: getIntelligenceGatewayPolicy
      responses:
        "200":
          content:
            application/json:
              schema:
                properties:
                  data:
                    $ref: "#/components/schemas/IntelligenceGatewayPolicy"
                type: object
          description: Policy
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
      summary: Get a routing and fallback policy
      tags:
        - Intelligence Gateway
    parameters:
      - in: path
        name: id
        required: true
        schema:
          format: uuid
          type: string
    patch:
      operationId: updateIntelligenceGatewayPolicy
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/IntelligenceGatewayPolicy"
        required: true
      responses:
        "200":
          content:
            application/json:
              schema:
                properties:
                  data:
                    $ref: "#/components/schemas/IntelligenceGatewayPolicy"
                type: object
          description: Updated policy
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
        "422":
          $ref: "#/components/responses/ValidationError"
      summary: Update a routing and fallback policy
      tags:
        - Intelligence Gateway
  /intelligence/keys:
    get:
      operationId: getIntelligenceKeys
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Keys — Index
      tags:
        - Keys
    post:
      operationId: postIntelligenceKeys
      responses:
        "200":
          description: Success
        "201":
          description: Created
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Keys — Create
      tags:
        - Keys
  /intelligence/keys/{id}:
    delete:
      operationId: deleteIntelligenceKeysId
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        "204":
          description: Deleted
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Keys — Delete
      tags:
        - Keys
    get:
      operationId: getIntelligenceKeysId
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Keys — Show
      tags:
        - Keys
  /intelligence/models:
    get:
      operationId: getIntelligenceModels
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Models — Index
      tags:
        - Models
  /intelligence/provider-credentials:
    get:
      description: Raw and encrypted credentials are never returned.
      operationId: listIntelligenceProviderCredentials
      responses:
        "200":
          content:
            application/json:
              schema:
                properties:
                  data:
                    items:
                      $ref: "#/components/schemas/IntelligenceProviderCredential"
                    type: array
                  providers_supported:
                    items:
                      type: string
                    type: array
                type: object
          description: Credentials and supported provider identifiers
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
      summary: List safe provider credential metadata
      tags:
        - Intelligence Provider Credentials
  /intelligence/provider-credentials/{provider}:
    delete:
      operationId: deleteIntelligenceProviderCredential
      responses:
        "204":
          description: Credential deleted
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
      summary: Delete a provider credential
      tags:
        - Intelligence Provider Credentials
    get:
      operationId: getIntelligenceProviderCredential
      responses:
        "200":
          content:
            application/json:
              schema:
                properties:
                  data:
                    $ref: "#/components/schemas/IntelligenceProviderCredential"
                type: object
          description: Credential metadata
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
      summary: Get safe provider credential metadata
      tags:
        - Intelligence Provider Credentials
    parameters:
      - in: path
        name: provider
        required: true
        schema:
          enum:
            - anthropic
            - openai
            - groq
            - together
            - openrouter
            - google
            - mistral
          type: string
    patch:
      operationId: updateIntelligenceProviderCredentialMetadata
      requestBody:
        content:
          application/json:
            schema:
              properties:
                metadata:
                  additionalProperties: true
                  type: object
                name:
                  type: string
              type: object
        required: true
      responses:
        "200":
          content:
            application/json:
              schema:
                properties:
                  data:
                    $ref: "#/components/schemas/IntelligenceProviderCredential"
                type: object
          description: Updated safe metadata
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
        "422":
          $ref: "#/components/responses/ValidationError"
      summary: Update non-secret credential metadata
      tags:
        - Intelligence Provider Credentials
    put:
      description: The raw API key is encrypted at rest and never returned.
      operationId: replaceIntelligenceProviderCredential
      requestBody:
        content:
          application/json:
            schema:
              properties:
                api_key:
                  minLength: 1
                  type: string
                  writeOnly: true
                metadata:
                  additionalProperties: true
                  type: object
                name:
                  type: string
              required:
                - api_key
              type: object
        required: true
      responses:
        "200":
          content:
            application/json:
              schema:
                properties:
                  data:
                    $ref: "#/components/schemas/IntelligenceProviderCredential"
                type: object
          description: Safe replacement metadata
        "400":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
          description: Unsupported provider
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "422":
          $ref: "#/components/responses/ValidationError"
      summary: Atomically create or replace a provider credential
      tags:
        - Intelligence Provider Credentials
  /intelligence/provider-credentials/{provider}/validate-storage:
    post:
      description: "This checks storage integrity only. It does not call the external provider and therefore does not claim the credential is provider-valid.\n"
      operationId: validateIntelligenceProviderCredentialStorage
      parameters:
        - in: path
          name: provider
          required: true
          schema:
            enum:
              - anthropic
              - openai
              - groq
              - together
              - openrouter
              - google
              - mistral
            type: string
      responses:
        "200":
          content:
            application/json:
              schema:
                properties:
                  data:
                    $ref: "#/components/schemas/IntelligenceProviderCredential"
                type: object
          description: Storage validation metadata
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
        "409":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
          description: Stored ciphertext is not decryptable
      summary: Verify encrypted credential storage can be decrypted
      tags:
        - Intelligence Provider Credentials
  /intelligence/usage:
    get:
      operationId: getIntelligenceUsage
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Usage — Index
      tags:
        - Usage
  /internal/agent/callback/{task_id}:
    post:
      operationId: postInternalAgentCallbackTaskId
      parameters:
        - in: path
          name: task_id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "201":
          description: Created
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Internal — Agent Callback
      tags:
        - Internal
  /internal/agent/metrics:
    post:
      operationId: postInternalAgentMetrics
      responses:
        "200":
          description: Success
        "201":
          description: Created
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Internal — Agent Metrics
      tags:
        - Internal
  /internal/api-keys/{id}/decrypt:
    get:
      operationId: getInternalApiKeysIdDecrypt
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Internal — Decrypt Api Key
      tags:
        - Internal
  /internal/audit_log:
    post:
      operationId: postInternalAuditLog
      responses:
        "200":
          description: Success
        "201":
          description: Created
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: AuditLog — Create
      tags:
        - AuditLog
  /internal/cloud/host-acceptance:
    post:
      operationId: postInternalCloudHostAcceptance
      responses:
        "200":
          description: Success
        "201":
          description: Created
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: HostAcceptanceRuns — Create
      tags:
        - HostAcceptanceRuns
  /internal/cloud/host-acceptance/{id}:
    get:
      operationId: getInternalCloudHostAcceptanceId
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: HostAcceptanceRuns — Show
      tags:
        - HostAcceptanceRuns
    patch:
      operationId: patchInternalCloudHostAcceptanceId
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: HostAcceptanceRuns — Update
      tags:
        - HostAcceptanceRuns
  /internal/cloud/host-acceptance/{id}/bootstrap-credentials:
    post:
      operationId: postInternalCloudHostAcceptanceIdBootstrapCredentials
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "201":
          description: Created
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: HostAcceptanceRuns — Bootstrap Credentials
      tags:
        - HostAcceptanceRuns
  /internal/cloud/host-acceptance/{run_id}/report:
    post:
      operationId: postInternalCloudHostAcceptanceRunIdReport
      parameters:
        - in: path
          name: run_id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "201":
          description: Created
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: CloudHost — Report
      tags:
        - CloudHost
  /internal/cloud/host-fleets/{pool_id}/bootstrap:
    post:
      operationId: postInternalCloudHostFleetsPoolIdBootstrap
      parameters:
        - in: path
          name: pool_id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "201":
          description: Created
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: CloudHost — Fleet Bootstrap
      tags:
        - CloudHost
  /internal/cloud/pools/{pool_id}/provision:
    post:
      operationId: postInternalCloudPoolsPoolIdProvision
      parameters:
        - in: path
          name: pool_id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "201":
          description: Created
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: CloudHost — Provision
      tags:
        - CloudHost
  /internal/computers:
    get:
      operationId: getInternalComputers
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Internal — List Computers
      tags:
        - Internal
  /internal/computers/{id}:
    get:
      operationId: getInternalComputersId
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Internal — Get Computer
      tags:
        - Internal
  /internal/computers/{id}/heartbeat:
    post:
      operationId: postInternalComputersIdHeartbeat
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "201":
          description: Created
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Internal — Heartbeat
      tags:
        - Internal
  /internal/computers/{id}/ip:
    get:
      operationId: getInternalComputersIdIp
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Internal — Get Computer Ip
      tags:
        - Internal
  /internal/computers/{id}/ready:
    post:
      operationId: postInternalComputersIdReady
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "201":
          description: Created
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Internal — Ready
      tags:
        - Internal
  /internal/computers/{id}/status:
    post:
      operationId: postInternalComputersIdStatus
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "201":
          description: Created
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Internal — Update Status
      tags:
        - Internal
  /internal/credits/record:
    post:
      operationId: postInternalCreditsRecord
      responses:
        "200":
          description: Success
        "201":
          description: Created
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Credits — Record Api Call
      tags:
        - Credits
  /internal/host-sessions/v1/{id}/commands:
    get:
      operationId: getInternalHostSessionsV1IdCommands
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: HostSessions — Commands
      tags:
        - HostSessions
    post:
      operationId: postInternalHostSessionsV1IdCommands
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "201":
          description: Created
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: HostSessions — Commands
      tags:
        - HostSessions
  /internal/host-sessions/v1/{id}/commands/{command_id}/ack:
    post:
      operationId: postInternalHostSessionsV1IdCommandsCommandIdAck
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
        - in: path
          name: command_id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "201":
          description: Created
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: HostSessions — Acknowledge
      tags:
        - HostSessions
  /internal/host-sessions/v1/{id}/open:
    post:
      operationId: postInternalHostSessionsV1IdOpen
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "201":
          description: Created
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: HostSessions — Open
      tags:
        - HostSessions
  /internal/host-sessions/v1/{id}/reconcile:
    post:
      operationId: postInternalHostSessionsV1IdReconcile
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "201":
          description: Created
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: HostSessions — Reconcile
      tags:
        - HostSessions
  /internal/host-sessions/v1/{id}/reconnect:
    post:
      operationId: postInternalHostSessionsV1IdReconnect
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "201":
          description: Created
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: HostSessions — Reconnect
      tags:
        - HostSessions
  /internal/host-sessions/v1/{id}/runtime-usage:
    post:
      operationId: postInternalHostSessionsV1IdRuntimeUsage
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "201":
          description: Created
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: HostSessions — Runtime Usage
      tags:
        - HostSessions
  /internal/host-sessions/{id}/commands:
    post:
      operationId: postInternalHostSessionsIdCommands
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "201":
          description: Created
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: HostSessions — Enqueue
      tags:
        - HostSessions
  /internal/host-sessions/{id}/revoke:
    post:
      operationId: postInternalHostSessionsIdRevoke
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "201":
          description: Created
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: HostSessions — Revoke
      tags:
        - HostSessions
  /internal/metering:
    post:
      operationId: postInternalMetering
      responses:
        "200":
          description: Success
        "201":
          description: Created
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Metering — Record
      tags:
        - Metering
  /internal/model_route:
    get:
      operationId: getInternalModelRoute
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: ModelRoute — Resolve
      tags:
        - ModelRoute
  /internal/opencomputers/hosts/{id}/apps:
    get:
      operationId: getInternalOpencomputersHostsIdApps
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: OpenComputersDispatch — List Apps
      tags:
        - OpenComputersDispatch
  /internal/opencomputers/hosts/{id}/apps/{app_id}/install:
    post:
      operationId: postInternalOpencomputersHostsIdAppsAppIdInstall
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
        - in: path
          name: app_id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "201":
          description: Created
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: OpenComputersDispatch — Install App
      tags:
        - OpenComputersDispatch
  /internal/opencomputers/hosts/{id}/exec:
    post:
      operationId: postInternalOpencomputersHostsIdExec
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "201":
          description: Created
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: OpenComputersDispatch — Exec
      tags:
        - OpenComputersDispatch
  /internal/opencomputers/hosts/{id}/fs/list:
    post:
      operationId: postInternalOpencomputersHostsIdFsList
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "201":
          description: Created
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: OpenComputersDispatch — Fs List
      tags:
        - OpenComputersDispatch
  /internal/opencomputers/hosts/{id}/fs/read:
    post:
      operationId: postInternalOpencomputersHostsIdFsRead
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "201":
          description: Created
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: OpenComputersDispatch — Fs Read
      tags:
        - OpenComputersDispatch
  /internal/opencomputers/hosts/{id}/fs/stat:
    post:
      operationId: postInternalOpencomputersHostsIdFsStat
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "201":
          description: Created
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: OpenComputersDispatch — Fs Stat
      tags:
        - OpenComputersDispatch
  /internal/opencomputers/hosts/{id}/fs/write:
    post:
      operationId: postInternalOpencomputersHostsIdFsWrite
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "201":
          description: Created
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: OpenComputersDispatch — Fs Write
      tags:
        - OpenComputersDispatch
  /internal/purge-stale-instances:
    post:
      operationId: postInternalPurgeStaleInstances
      responses:
        "200":
          description: Success
        "201":
          description: Created
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Internal — Purge Stale
      tags:
        - Internal
  /internal/tenant_limits/{tenant_id}:
    get:
      operationId: getInternalTenantLimitsTenantId
      parameters:
        - in: path
          name: tenant_id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: TenantLimits — Show
      tags:
        - TenantLimits
    put:
      operationId: putInternalTenantLimitsTenantId
      parameters:
        - in: path
          name: tenant_id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: TenantLimits — Update
      tags:
        - TenantLimits
  /internal/tenants/{id}/provider-config:
    get:
      operationId: getInternalTenantsIdProviderConfig
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Internal — Tenant Provider Config
      tags:
        - Internal
  /internal/tenants/{id}/provider-keys:
    get:
      operationId: getInternalTenantsIdProviderKeys
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Internal — Tenant Provider Keys
      tags:
        - Internal
  /internal/usage/record:
    post:
      operationId: postInternalUsageRecord
      responses:
        "200":
          description: Success
        "201":
          description: Created
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Internal — Usage Record
      tags:
        - Internal
  /internal/usage/report:
    post:
      operationId: postInternalUsageReport
      responses:
        "200":
          description: Success
        "201":
          description: Created
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Internal — Usage Report
      tags:
        - Internal
  /invitations/accept:
    post:
      operationId: postInvitationsAccept
      responses:
        "200":
          description: Success
        "201":
          description: Created
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: HostShares — Accept Invitation
      tags:
        - HostShares
  /invites/{token}:
    get:
      description: "Returns a public preview of the org invite — org name, role, expiry — without authentication. Use this to render the pre-auth invite landing page. Returns `404` when the token is unknown or has been revoked.\n"
      operationId: previewOrgInvite
      responses:
        "200":
          content:
            application/json:
              schema:
                properties:
                  data:
                    $ref: "#/components/schemas/OrgInvitePreview"
                required:
                  - data
                type: object
          description: Invite preview.
        "404":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
          description: Invite not found or has been revoked.
      security: []
      summary: Preview an org invite (public)
      tags:
        - Org Invites
    parameters:
      - description: Opaque invite token (hex-encoded 32 bytes, 64 chars).
        in: path
        name: token
        required: true
        schema:
          type: string
  /invites/{token}/accept:
    parameters:
      - description: Opaque invite token.
        in: path
        name: token
        required: true
        schema:
          type: string
    post:
      description: "Claims an org invite on behalf of the authenticated user. The caller's JWT email must match the invite email (case-insensitive enforcement). On success inserts a `tenant_members` row.\nError codes: - `invalid or expired invite token` (400) — token not found or expired. - `EMAIL_MISMATCH` (422) — JWT email does not match invite email.\n"
      operationId: acceptOrgInvite
      responses:
        "200":
          content:
            application/json:
              schema:
                properties:
                  accepted:
                    example: true
                    type: boolean
                  tenant:
                    $ref: "#/components/schemas/Tenant"
                    nullable: true
                  tenant_id:
                    format: uuid
                    type: string
                required:
                  - accepted
                  - tenant_id
                type: object
          description: Invite accepted.
        "400":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
          description: Invalid or expired token.
        "401":
          $ref: "#/components/responses/Unauthorized"
        "422":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
          description: Email mismatch (`EMAIL_MISMATCH`).
      security:
        - BearerAuth: []
      summary: Accept an org invite
      tags:
        - Org Invites
  /managed-databases:
    get:
      operationId: getManagedDatabases
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: ManagedDatabases — Index
      tags:
        - ManagedDatabases
    post:
      operationId: postManagedDatabases
      responses:
        "200":
          description: Success
        "201":
          description: Created
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: ManagedDatabases — Create
      tags:
        - ManagedDatabases
  /managed-databases/{id}:
    delete:
      operationId: deleteManagedDatabasesId
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        "204":
          description: Deleted
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: ManagedDatabases — Destroy
      tags:
        - ManagedDatabases
    get:
      operationId: getManagedDatabasesId
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: ManagedDatabases — Show
      tags:
        - ManagedDatabases
    patch:
      operationId: patchManagedDatabasesId
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: ManagedDatabases — Resize
      tags:
        - ManagedDatabases
  /managed-databases/{id}/credentials/rotate:
    post:
      operationId: postManagedDatabasesIdCredentialsRotate
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "201":
          description: Created
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: ManagedDatabases — Rotate Credentials
      tags:
        - ManagedDatabases
  /mcp:
    delete:
      description: Reserved for explicit session termination. Returns 405 for now.
      operationId: mcpTerminate
      responses:
        "405":
          content:
            application/json:
              schema:
                properties:
                  error:
                    type: string
                type: object
          description: Session termination not supported (server is stateless)
      summary: (Not implemented) MCP session termination
      tags:
        - MCP
    get:
      description: Reserved for the optional SSE listen channel. Returns 405 for now.
      operationId: mcpListen
      responses:
        "405":
          content:
            application/json:
              schema:
                properties:
                  error:
                    type: string
                type: object
          description: SSE listen stream not supported
      summary: (Not implemented) MCP server-push SSE stream
      tags:
        - MCP
    post:
      description: "Handles MCP (Model Context Protocol) JSON-RPC 2.0 requests over Streamable HTTP (spec 2025-03-26). Accepts a single request, a batch, or a pure-notification batch; returns the matching JSON-RPC response (200), or `202 Accepted` with empty body for notifications that have no response.\nSupported methods: `initialize`, `notifications/initialized`, `ping`, `tools/list`, `tools/call`.\nTool catalogue: `create_sandbox`, `create_desktop`, `destroy_sandbox`, `exec`, `exec_python`, `read_file`, `write_file`, `list_files`, `list_sandboxes`.\n"
      operationId: mcpDispatch
      requestBody:
        content:
          application/json:
            schema:
              description: JSON-RPC 2.0 request, notification, or batch
              oneOf:
                - additionalProperties: true
                  type: object
                - items:
                    additionalProperties: true
                    type: object
                  type: array
        required: true
      responses:
        "200":
          content:
            application/json:
              schema:
                oneOf:
                  - additionalProperties: true
                    type: object
                  - items:
                      additionalProperties: true
                      type: object
                    type: array
          description: JSON-RPC response (single or batch)
        "202":
          description: Notifications-only batch; no body
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
      summary: MCP JSON-RPC dispatch
      tags:
        - MCP
  /notifications:
    get:
      operationId: getNotifications
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Notifications — Index
      tags:
        - Notifications
  /notifications/mark-all-read:
    post:
      operationId: postNotificationsMarkAllRead
      responses:
        "200":
          description: Success
        "201":
          description: Created
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Notifications — Mark All Read
      tags:
        - Notifications
  /notifications/read-all:
    post:
      operationId: postNotificationsReadAll
      responses:
        "200":
          description: Success
        "201":
          description: Created
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Notifications — Mark All Read
      tags:
        - Notifications
  /notifications/stream:
    get:
      operationId: getNotificationsStream
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Notifications — Stream
      tags:
        - Notifications
  /notifications/unread-count:
    get:
      operationId: getNotificationsUnreadCount
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Notifications — Unread Count
      tags:
        - Notifications
  /notifications/{id}/mark-read:
    post:
      operationId: postNotificationsIdMarkRead
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "201":
          description: Created
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Notifications — Mark Read
      tags:
        - Notifications
  /notifications/{id}/read:
    post:
      operationId: postNotificationsIdRead
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "201":
          description: Created
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Notifications — Mark Read
      tags:
        - Notifications
  /opencomputers/alerts/channels:
    get:
      operationId: getOpencomputersAlertsChannels
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Alerts — List Channels
      tags:
        - Alerts
    post:
      operationId: postOpencomputersAlertsChannels
      responses:
        "200":
          description: Success
        "201":
          description: Created
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Alerts — Create Channel
      tags:
        - Alerts
  /opencomputers/alerts/channels/{id}:
    delete:
      operationId: deleteOpencomputersAlertsChannelsId
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        "204":
          description: Deleted
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Alerts — Delete Channel
      tags:
        - Alerts
    patch:
      operationId: patchOpencomputersAlertsChannelsId
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Alerts — Update Channel
      tags:
        - Alerts
  /opencomputers/alerts/channels/{id}/verify:
    post:
      operationId: postOpencomputersAlertsChannelsIdVerify
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "201":
          description: Created
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Alerts — Verify Channel
      tags:
        - Alerts
  /opencomputers/alerts/fires:
    get:
      operationId: getOpencomputersAlertsFires
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Alerts — List Fires
      tags:
        - Alerts
  /opencomputers/alerts/fires/{id}/ack:
    post:
      operationId: postOpencomputersAlertsFiresIdAck
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "201":
          description: Created
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Alerts — Ack Fire
      tags:
        - Alerts
  /opencomputers/alerts/rules:
    get:
      operationId: getOpencomputersAlertsRules
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Alerts — List Rules
      tags:
        - Alerts
    post:
      operationId: postOpencomputersAlertsRules
      responses:
        "200":
          description: Success
        "201":
          description: Created
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Alerts — Create Rule
      tags:
        - Alerts
  /opencomputers/alerts/rules/{id}:
    delete:
      operationId: deleteOpencomputersAlertsRulesId
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        "204":
          description: Deleted
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Alerts — Delete Rule
      tags:
        - Alerts
    patch:
      operationId: patchOpencomputersAlertsRulesId
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Alerts — Update Rule
      tags:
        - Alerts
  /opencomputers/alerts/rules/{id}/fire-test:
    post:
      operationId: postOpencomputersAlertsRulesIdFireTest
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "201":
          description: Created
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Alerts — Fire Test
      tags:
        - Alerts
  /opencomputers/apps:
    get:
      operationId: getOpencomputersApps
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Apps — Catalog
      tags:
        - Apps
  /opencomputers/audit:
    get:
      operationId: getOpencomputersAudit
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Audit — Index
      tags:
        - Audit
  /opencomputers/audit/export:
    get:
      operationId: getOpencomputersAuditExport
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Audit — Export
      tags:
        - Audit
  /opencomputers/audit/live:
    get:
      operationId: getOpencomputersAuditLive
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Audit — Live
      tags:
        - Audit
  /opencomputers/audit/verify:
    get:
      operationId: getOpencomputersAuditVerify
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Audit — Verify
      tags:
        - Audit
  /opencomputers/audit/{id}:
    get:
      operationId: getOpencomputersAuditId
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Audit — Show
      tags:
        - Audit
  /opencomputers/clusters:
    get:
      operationId: getOpencomputersClusters
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Clusters — Index
      tags:
        - Clusters
    post:
      operationId: postOpencomputersClusters
      responses:
        "200":
          description: Success
        "201":
          description: Created
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Clusters — Create
      tags:
        - Clusters
  /opencomputers/clusters/{id}:
    delete:
      operationId: deleteOpencomputersClustersId
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        "204":
          description: Deleted
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Clusters — Delete
      tags:
        - Clusters
    get:
      operationId: getOpencomputersClustersId
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Clusters — Show
      tags:
        - Clusters
  /opencomputers/clusters/{id}/events:
    get:
      operationId: getOpencomputersClustersIdEvents
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Clusters — Events
      tags:
        - Clusters
  /opencomputers/clusters/{id}/start:
    post:
      operationId: postOpencomputersClustersIdStart
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "201":
          description: Created
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Clusters — Start
      tags:
        - Clusters
  /opencomputers/clusters/{id}/stop:
    post:
      operationId: postOpencomputersClustersIdStop
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "201":
          description: Created
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Clusters — Stop
      tags:
        - Clusters
  /opencomputers/groups:
    get:
      operationId: getOpencomputersGroups
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: HostGroups — Index
      tags:
        - HostGroups
    post:
      operationId: postOpencomputersGroups
      responses:
        "200":
          description: Success
        "201":
          description: Created
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: HostGroups — Create
      tags:
        - HostGroups
  /opencomputers/groups/{id}:
    delete:
      operationId: deleteOpencomputersGroupsId
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        "204":
          description: Deleted
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: HostGroups — Delete
      tags:
        - HostGroups
    get:
      operationId: getOpencomputersGroupsId
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: HostGroups — Show
      tags:
        - HostGroups
    patch:
      operationId: patchOpencomputersGroupsId
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: HostGroups — Update
      tags:
        - HostGroups
  /opencomputers/groups/{id}/apps/{app_id}/install:
    post:
      operationId: postOpencomputersGroupsIdAppsAppIdInstall
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
        - in: path
          name: app_id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "201":
          description: Created
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: HostGroups — Bulk Install App
      tags:
        - HostGroups
  /opencomputers/groups/{id}/exec:
    post:
      operationId: postOpencomputersGroupsIdExec
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "201":
          description: Created
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: HostGroups — Bulk Exec
      tags:
        - HostGroups
  /opencomputers/groups/{id}/members:
    post:
      operationId: postOpencomputersGroupsIdMembers
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "201":
          description: Created
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: HostGroups — Bulk Add Members
      tags:
        - HostGroups
  /opencomputers/groups/{id}/members/{host_id}:
    delete:
      operationId: deleteOpencomputersGroupsIdMembersHostId
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
        - in: path
          name: host_id
          required: true
          schema:
            type: string
      responses:
        "204":
          description: Deleted
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: HostGroups — Remove Member
      tags:
        - HostGroups
    post:
      operationId: postOpencomputersGroupsIdMembersHostId
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
        - in: path
          name: host_id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "201":
          description: Created
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: HostGroups — Add Member
      tags:
        - HostGroups
  /opencomputers/hosts:
    get:
      operationId: getOpencomputersHosts
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Index — Index
      tags:
        - Index
    post:
      operationId: postOpencomputersHosts
      responses:
        "200":
          description: Success
        "201":
          description: Created
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Index — Create
      tags:
        - Index
  /opencomputers/hosts/events:
    get:
      operationId: getOpencomputersHostsEvents
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: SSE — Stream Host Events
      tags:
        - SSE
  /opencomputers/hosts/events/sse-ticket:
    post:
      operationId: postOpencomputersHostsEventsSseTicket
      responses:
        "200":
          description: Success
        "201":
          description: Created
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: SSE — Issue Host Sse Ticket
      tags:
        - SSE
  /opencomputers/hosts/registration-status:
    post:
      operationId: postOpencomputersHostsRegistrationStatus
      responses:
        "200":
          description: Success
        "201":
          description: Created
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Index — Registration Status
      tags:
        - Index
  /opencomputers/hosts/{host_id}/backup-configs:
    get:
      operationId: getOpencomputersHostsHostIdBackupConfigs
      parameters:
        - in: path
          name: host_id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Backups — Index
      tags:
        - Backups
    post:
      operationId: postOpencomputersHostsHostIdBackupConfigs
      parameters:
        - in: path
          name: host_id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "201":
          description: Created
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Backups — Create
      tags:
        - Backups
  /opencomputers/hosts/{host_id}/backup-configs/{config_id}:
    delete:
      operationId: deleteOpencomputersHostsHostIdBackupConfigsConfigId
      parameters:
        - in: path
          name: host_id
          required: true
          schema:
            type: string
        - in: path
          name: config_id
          required: true
          schema:
            type: string
      responses:
        "204":
          description: Deleted
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Backups — Delete
      tags:
        - Backups
    patch:
      operationId: patchOpencomputersHostsHostIdBackupConfigsConfigId
      parameters:
        - in: path
          name: host_id
          required: true
          schema:
            type: string
        - in: path
          name: config_id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Backups — Update
      tags:
        - Backups
  /opencomputers/hosts/{host_id}/backup-configs/{config_id}/pause:
    post:
      operationId: postOpencomputersHostsHostIdBackupConfigsConfigIdPause
      parameters:
        - in: path
          name: host_id
          required: true
          schema:
            type: string
        - in: path
          name: config_id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "201":
          description: Created
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Backups — Pause
      tags:
        - Backups
  /opencomputers/hosts/{host_id}/backup-configs/{config_id}/resume:
    post:
      operationId: postOpencomputersHostsHostIdBackupConfigsConfigIdResume
      parameters:
        - in: path
          name: host_id
          required: true
          schema:
            type: string
        - in: path
          name: config_id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "201":
          description: Created
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Backups — Resume
      tags:
        - Backups
  /opencomputers/hosts/{host_id}/backup-configs/{config_id}/snapshots:
    get:
      operationId: getOpencomputersHostsHostIdBackupConfigsConfigIdSnapshots
      parameters:
        - in: path
          name: host_id
          required: true
          schema:
            type: string
        - in: path
          name: config_id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Backups — Snapshots
      tags:
        - Backups
  /opencomputers/hosts/{host_id}/backup-configs/{config_id}/trigger:
    post:
      operationId: postOpencomputersHostsHostIdBackupConfigsConfigIdTrigger
      parameters:
        - in: path
          name: host_id
          required: true
          schema:
            type: string
        - in: path
          name: config_id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "201":
          description: Created
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Backups — Trigger
      tags:
        - Backups
  /opencomputers/hosts/{host_id}/containers:
    get:
      operationId: getOpencomputersHostsHostIdContainers
      parameters:
        - in: path
          name: host_id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Containers — Index
      tags:
        - Containers
    post:
      operationId: postOpencomputersHostsHostIdContainers
      parameters:
        - in: path
          name: host_id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "201":
          description: Created
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Containers — Create
      tags:
        - Containers
  /opencomputers/hosts/{host_id}/containers/{id}:
    delete:
      operationId: deleteOpencomputersHostsHostIdContainersId
      parameters:
        - in: path
          name: host_id
          required: true
          schema:
            type: string
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        "204":
          description: Deleted
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Containers — Delete
      tags:
        - Containers
    get:
      operationId: getOpencomputersHostsHostIdContainersId
      parameters:
        - in: path
          name: host_id
          required: true
          schema:
            type: string
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Containers — Show
      tags:
        - Containers
    patch:
      operationId: patchOpencomputersHostsHostIdContainersId
      parameters:
        - in: path
          name: host_id
          required: true
          schema:
            type: string
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Containers — Update
      tags:
        - Containers
  /opencomputers/hosts/{host_id}/containers/{id}/logs:
    get:
      operationId: getOpencomputersHostsHostIdContainersIdLogs
      parameters:
        - in: path
          name: host_id
          required: true
          schema:
            type: string
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Containers — Logs
      tags:
        - Containers
  /opencomputers/hosts/{host_id}/containers/{id}/restart:
    post:
      operationId: postOpencomputersHostsHostIdContainersIdRestart
      parameters:
        - in: path
          name: host_id
          required: true
          schema:
            type: string
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "201":
          description: Created
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Containers — Restart
      tags:
        - Containers
  /opencomputers/hosts/{host_id}/containers/{id}/start:
    post:
      operationId: postOpencomputersHostsHostIdContainersIdStart
      parameters:
        - in: path
          name: host_id
          required: true
          schema:
            type: string
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "201":
          description: Created
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Containers — Start
      tags:
        - Containers
  /opencomputers/hosts/{host_id}/containers/{id}/stats:
    get:
      operationId: getOpencomputersHostsHostIdContainersIdStats
      parameters:
        - in: path
          name: host_id
          required: true
          schema:
            type: string
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Containers — Stats
      tags:
        - Containers
  /opencomputers/hosts/{host_id}/containers/{id}/stop:
    post:
      operationId: postOpencomputersHostsHostIdContainersIdStop
      parameters:
        - in: path
          name: host_id
          required: true
          schema:
            type: string
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "201":
          description: Created
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Containers — Stop
      tags:
        - Containers
  /opencomputers/hosts/{host_id}/schedules:
    get:
      operationId: getOpencomputersHostsHostIdSchedules
      parameters:
        - in: path
          name: host_id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Schedules — Index
      tags:
        - Schedules
    post:
      operationId: postOpencomputersHostsHostIdSchedules
      parameters:
        - in: path
          name: host_id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "201":
          description: Created
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Schedules — Create
      tags:
        - Schedules
  /opencomputers/hosts/{host_id}/schedules/{id}:
    delete:
      operationId: deleteOpencomputersHostsHostIdSchedulesId
      parameters:
        - in: path
          name: host_id
          required: true
          schema:
            type: string
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        "204":
          description: Deleted
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Schedules — Delete
      tags:
        - Schedules
    get:
      operationId: getOpencomputersHostsHostIdSchedulesId
      parameters:
        - in: path
          name: host_id
          required: true
          schema:
            type: string
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Schedules — Show
      tags:
        - Schedules
    patch:
      operationId: patchOpencomputersHostsHostIdSchedulesId
      parameters:
        - in: path
          name: host_id
          required: true
          schema:
            type: string
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Schedules — Update
      tags:
        - Schedules
  /opencomputers/hosts/{host_id}/schedules/{id}/pause:
    post:
      operationId: postOpencomputersHostsHostIdSchedulesIdPause
      parameters:
        - in: path
          name: host_id
          required: true
          schema:
            type: string
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "201":
          description: Created
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Schedules — Pause
      tags:
        - Schedules
  /opencomputers/hosts/{host_id}/schedules/{id}/resume:
    post:
      operationId: postOpencomputersHostsHostIdSchedulesIdResume
      parameters:
        - in: path
          name: host_id
          required: true
          schema:
            type: string
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "201":
          description: Created
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Schedules — Resume
      tags:
        - Schedules
  /opencomputers/hosts/{host_id}/schedules/{id}/runs:
    get:
      operationId: getOpencomputersHostsHostIdSchedulesIdRuns
      parameters:
        - in: path
          name: host_id
          required: true
          schema:
            type: string
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Schedules — Runs
      tags:
        - Schedules
  /opencomputers/hosts/{host_id}/schedules/{id}/trigger:
    post:
      operationId: postOpencomputersHostsHostIdSchedulesIdTrigger
      parameters:
        - in: path
          name: host_id
          required: true
          schema:
            type: string
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "201":
          description: Created
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Schedules — Trigger
      tags:
        - Schedules
  /opencomputers/hosts/{host_id}/tunnels:
    get:
      operationId: getOpencomputersHostsHostIdTunnels
      parameters:
        - in: path
          name: host_id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Tunnels — Index
      tags:
        - Tunnels
    post:
      operationId: postOpencomputersHostsHostIdTunnels
      parameters:
        - in: path
          name: host_id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "201":
          description: Created
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Tunnels — Create
      tags:
        - Tunnels
  /opencomputers/hosts/{host_id}/tunnels/{id}:
    delete:
      operationId: deleteOpencomputersHostsHostIdTunnelsId
      parameters:
        - in: path
          name: host_id
          required: true
          schema:
            type: string
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        "204":
          description: Deleted
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Tunnels — Delete
      tags:
        - Tunnels
    get:
      operationId: getOpencomputersHostsHostIdTunnelsId
      parameters:
        - in: path
          name: host_id
          required: true
          schema:
            type: string
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Tunnels — Show
      tags:
        - Tunnels
    patch:
      operationId: patchOpencomputersHostsHostIdTunnelsId
      parameters:
        - in: path
          name: host_id
          required: true
          schema:
            type: string
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Tunnels — Update
      tags:
        - Tunnels
  /opencomputers/hosts/{id}:
    delete:
      operationId: deleteOpencomputersHostsId
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        "204":
          description: Deleted
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Index — Delete
      tags:
        - Index
    get:
      operationId: getOpencomputersHostsId
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Index — Show
      tags:
        - Index
  /opencomputers/hosts/{id}/agent/dispatch:
    post:
      operationId: postOpencomputersHostsIdAgentDispatch
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "201":
          description: Created
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Agent — Dispatch
      tags:
        - Agent
  /opencomputers/hosts/{id}/agent/sessions:
    get:
      operationId: getOpencomputersHostsIdAgentSessions
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Agent — List Sessions
      tags:
        - Agent
  /opencomputers/hosts/{id}/agent/sessions/{session_id}:
    delete:
      operationId: deleteOpencomputersHostsIdAgentSessionsSessionId
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
        - in: path
          name: session_id
          required: true
          schema:
            type: string
      responses:
        "204":
          description: Deleted
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Agent — Cancel
      tags:
        - Agent
    get:
      operationId: getOpencomputersHostsIdAgentSessionsSessionId
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
        - in: path
          name: session_id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Agent — Show Session
      tags:
        - Agent
  /opencomputers/hosts/{id}/agent/sessions/{session_id}/events:
    get:
      operationId: getOpencomputersHostsIdAgentSessionsSessionIdEvents
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
        - in: path
          name: session_id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Agent — Stream Events
      tags:
        - Agent
  /opencomputers/hosts/{id}/apps:
    get:
      operationId: getOpencomputersHostsIdApps
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Apps — List Installed
      tags:
        - Apps
  /opencomputers/hosts/{id}/apps/installs/{install_id}:
    get:
      operationId: getOpencomputersHostsIdAppsInstallsInstallId
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
        - in: path
          name: install_id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Apps — Show Install
      tags:
        - Apps
  /opencomputers/hosts/{id}/apps/installs/{install_id}/events:
    get:
      operationId: getOpencomputersHostsIdAppsInstallsInstallIdEvents
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
        - in: path
          name: install_id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Apps — Install Events
      tags:
        - Apps
  /opencomputers/hosts/{id}/apps/{app_id}:
    delete:
      operationId: deleteOpencomputersHostsIdAppsAppId
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
        - in: path
          name: app_id
          required: true
          schema:
            type: string
      responses:
        "204":
          description: Deleted
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Apps — Uninstall
      tags:
        - Apps
  /opencomputers/hosts/{id}/apps/{app_id}/health:
    post:
      operationId: postOpencomputersHostsIdAppsAppIdHealth
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
        - in: path
          name: app_id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "201":
          description: Created
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Apps — Health Check
      tags:
        - Apps
  /opencomputers/hosts/{id}/apps/{app_id}/install:
    post:
      operationId: postOpencomputersHostsIdAppsAppIdInstall
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
        - in: path
          name: app_id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "201":
          description: Created
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Apps — Install
      tags:
        - Apps
  /opencomputers/hosts/{id}/apps/{app_id}/start:
    post:
      operationId: postOpencomputersHostsIdAppsAppIdStart
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
        - in: path
          name: app_id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "201":
          description: Created
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Apps — Start App
      tags:
        - Apps
  /opencomputers/hosts/{id}/clipboard:
    get:
      operationId: getOpencomputersHostsIdClipboard
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Clipboard — Pull
      tags:
        - Clipboard
    post:
      operationId: postOpencomputersHostsIdClipboard
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "201":
          description: Created
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Clipboard — Push
      tags:
        - Clipboard
  /opencomputers/hosts/{id}/desktop/ticket:
    post:
      operationId: postOpencomputersHostsIdDesktopTicket
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "201":
          description: Created
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Index — Desktop Ticket
      tags:
        - Index
  /opencomputers/hosts/{id}/exec:
    post:
      operationId: postOpencomputersHostsIdExec
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "201":
          description: Created
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Index — Exec Job
      tags:
        - Index
  /opencomputers/hosts/{id}/exec/{job_id}:
    delete:
      operationId: deleteOpencomputersHostsIdExecJobId
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
        - in: path
          name: job_id
          required: true
          schema:
            type: string
      responses:
        "204":
          description: Deleted
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Index — Cancel Job
      tags:
        - Index
    get:
      operationId: getOpencomputersHostsIdExecJobId
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
        - in: path
          name: job_id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Index — Show Job
      tags:
        - Index
  /opencomputers/hosts/{id}/exec/{job_id}/stream:
    get:
      operationId: getOpencomputersHostsIdExecJobIdStream
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
        - in: path
          name: job_id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Index — Stream Job
      tags:
        - Index
  /opencomputers/hosts/{id}/fs:
    delete:
      operationId: deleteOpencomputersHostsIdFs
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        "204":
          description: Deleted
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Index — Fs Delete
      tags:
        - Index
    get:
      operationId: getOpencomputersHostsIdFs
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Index — Fs List
      tags:
        - Index
  /opencomputers/hosts/{id}/fs/download:
    get:
      operationId: getOpencomputersHostsIdFsDownload
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Index — Fs Download
      tags:
        - Index
  /opencomputers/hosts/{id}/fs/mkdir:
    post:
      operationId: postOpencomputersHostsIdFsMkdir
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "201":
          description: Created
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Index — Fs Mkdir
      tags:
        - Index
  /opencomputers/hosts/{id}/fs/stat:
    get:
      operationId: getOpencomputersHostsIdFsStat
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Index — Fs Stat
      tags:
        - Index
  /opencomputers/hosts/{id}/fs/upload:
    post:
      operationId: postOpencomputersHostsIdFsUpload
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "201":
          description: Created
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Index — Fs Upload
      tags:
        - Index
  /opencomputers/hosts/{id}/gha-runners:
    get:
      operationId: getOpencomputersHostsIdGhaRunners
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: GhaRunners — Index
      tags:
        - GhaRunners
    post:
      operationId: postOpencomputersHostsIdGhaRunners
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "201":
          description: Created
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: GhaRunners — Create
      tags:
        - GhaRunners
  /opencomputers/hosts/{id}/gha-runners/{runner_id}:
    delete:
      operationId: deleteOpencomputersHostsIdGhaRunnersRunnerId
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
        - in: path
          name: runner_id
          required: true
          schema:
            type: string
      responses:
        "204":
          description: Deleted
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: GhaRunners — Delete
      tags:
        - GhaRunners
    get:
      operationId: getOpencomputersHostsIdGhaRunnersRunnerId
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
        - in: path
          name: runner_id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: GhaRunners — Show
      tags:
        - GhaRunners
  /opencomputers/hosts/{id}/gha-runners/{runner_id}/events:
    get:
      operationId: getOpencomputersHostsIdGhaRunnersRunnerIdEvents
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
        - in: path
          name: runner_id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: GhaRunners — Events
      tags:
        - GhaRunners
  /opencomputers/hosts/{id}/gha-runners/{runner_id}/refresh:
    post:
      operationId: postOpencomputersHostsIdGhaRunnersRunnerIdRefresh
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
        - in: path
          name: runner_id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "201":
          description: Created
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: GhaRunners — Refresh
      tags:
        - GhaRunners
  /opencomputers/hosts/{id}/jobs:
    get:
      operationId: getOpencomputersHostsIdJobs
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Index — Jobs
      tags:
        - Index
  /opencomputers/hosts/{id}/secrets:
    get:
      operationId: getOpencomputersHostsIdSecrets
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Secrets — Index For Host
      tags:
        - Secrets
    post:
      operationId: postOpencomputersHostsIdSecrets
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "201":
          description: Created
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Secrets — Create For Host
      tags:
        - Secrets
  /opencomputers/hosts/{id}/secrets/{secret_id}:
    delete:
      operationId: deleteOpencomputersHostsIdSecretsSecretId
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
        - in: path
          name: secret_id
          required: true
          schema:
            type: string
      responses:
        "204":
          description: Deleted
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Secrets — Delete For Host
      tags:
        - Secrets
    patch:
      operationId: patchOpencomputersHostsIdSecretsSecretId
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
        - in: path
          name: secret_id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Secrets — Update For Host
      tags:
        - Secrets
  /opencomputers/hosts/{id}/secrets/{secret_id}/reveal:
    post:
      operationId: postOpencomputersHostsIdSecretsSecretIdReveal
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
        - in: path
          name: secret_id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "201":
          description: Created
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Secrets — Reveal
      tags:
        - Secrets
  /opencomputers/hosts/{id}/services:
    get:
      operationId: getOpencomputersHostsIdServices
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Apps — Services
      tags:
        - Apps
  /opencomputers/hosts/{id}/shares:
    get:
      operationId: getOpencomputersHostsIdShares
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: HostShares — Index
      tags:
        - HostShares
    post:
      operationId: postOpencomputersHostsIdShares
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "201":
          description: Created
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: HostShares — Create
      tags:
        - HostShares
  /opencomputers/hosts/{id}/shares/{share_id}:
    delete:
      operationId: deleteOpencomputersHostsIdSharesShareId
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
        - in: path
          name: share_id
          required: true
          schema:
            type: string
      responses:
        "204":
          description: Deleted
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: HostShares — Delete
      tags:
        - HostShares
    patch:
      operationId: patchOpencomputersHostsIdSharesShareId
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
        - in: path
          name: share_id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: HostShares — Update
      tags:
        - HostShares
  /opencomputers/hosts/{id}/ssh-keys:
    get:
      operationId: getOpencomputersHostsIdSshKeys
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: SshKeys — Index
      tags:
        - SshKeys
    post:
      operationId: postOpencomputersHostsIdSshKeys
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "201":
          description: Created
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: SshKeys — Create
      tags:
        - SshKeys
  /opencomputers/hosts/{id}/ssh-keys/import/github:
    post:
      operationId: postOpencomputersHostsIdSshKeysImportGithub
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "201":
          description: Created
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: SshKeys — Import Github
      tags:
        - SshKeys
  /opencomputers/hosts/{id}/ssh-keys/{key_id}:
    delete:
      operationId: deleteOpencomputersHostsIdSshKeysKeyId
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
        - in: path
          name: key_id
          required: true
          schema:
            type: string
      responses:
        "204":
          description: Deleted
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: SshKeys — Delete
      tags:
        - SshKeys
  /opencomputers/hosts/{id}/tags:
    patch:
      operationId: patchOpencomputersHostsIdTags
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: HostTags — Replace
      tags:
        - HostTags
  /opencomputers/hosts/{id}/tags/{tag}:
    delete:
      operationId: deleteOpencomputersHostsIdTagsTag
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
        - in: path
          name: tag
          required: true
          schema:
            type: string
      responses:
        "204":
          description: Deleted
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: HostTags — Remove
      tags:
        - HostTags
    post:
      operationId: postOpencomputersHostsIdTagsTag
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
        - in: path
          name: tag
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "201":
          description: Created
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: HostTags — Add
      tags:
        - HostTags
  /opencomputers/hosts/{id}/terminal/ticket:
    post:
      operationId: postOpencomputersHostsIdTerminalTicket
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "201":
          description: Created
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Index — Terminal Ticket
      tags:
        - Index
  /opencomputers/hosts/{id}/workspaces:
    get:
      operationId: getOpencomputersHostsIdWorkspaces
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Workspaces — Index
      tags:
        - Workspaces
    post:
      operationId: postOpencomputersHostsIdWorkspaces
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "201":
          description: Created
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Workspaces — Create
      tags:
        - Workspaces
  /opencomputers/hosts/{id}/workspaces/{wid}:
    delete:
      operationId: deleteOpencomputersHostsIdWorkspacesWid
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
        - in: path
          name: wid
          required: true
          schema:
            type: string
      responses:
        "204":
          description: Deleted
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Workspaces — Delete
      tags:
        - Workspaces
    get:
      operationId: getOpencomputersHostsIdWorkspacesWid
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
        - in: path
          name: wid
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Workspaces — Show
      tags:
        - Workspaces
    patch:
      operationId: patchOpencomputersHostsIdWorkspacesWid
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
        - in: path
          name: wid
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Workspaces — Update
      tags:
        - Workspaces
  /opencomputers/hosts/{id}/workspaces/{wid}/events:
    get:
      operationId: getOpencomputersHostsIdWorkspacesWidEvents
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
        - in: path
          name: wid
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Workspaces — Events
      tags:
        - Workspaces
  /opencomputers/hosts/{id}/workspaces/{wid}/expose:
    post:
      operationId: postOpencomputersHostsIdWorkspacesWidExpose
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
        - in: path
          name: wid
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "201":
          description: Created
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Workspaces — Expose
      tags:
        - Workspaces
  /opencomputers/hosts/{id}/workspaces/{wid}/open-terminal:
    post:
      operationId: postOpencomputersHostsIdWorkspacesWidOpenTerminal
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
        - in: path
          name: wid
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "201":
          description: Created
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Workspaces — Open Terminal
      tags:
        - Workspaces
  /opencomputers/hosts/{id}/workspaces/{wid}/pull:
    post:
      operationId: postOpencomputersHostsIdWorkspacesWidPull
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
        - in: path
          name: wid
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "201":
          description: Created
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Workspaces — Pull
      tags:
        - Workspaces
  /opencomputers/hosts/{id}/workspaces/{wid}/run:
    post:
      operationId: postOpencomputersHostsIdWorkspacesWidRun
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
        - in: path
          name: wid
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "201":
          description: Created
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Workspaces — Run
      tags:
        - Workspaces
  /opencomputers/internal/backup-chunks/{snapshot_id}/{seq}:
    post:
      operationId: postOpencomputersInternalBackupChunksSnapshotIdSeq
      parameters:
        - in: path
          name: snapshot_id
          required: true
          schema:
            type: string
        - in: path
          name: seq
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "201":
          description: Created
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: BackupUploads — Create
      tags:
        - BackupUploads
  /opencomputers/meshes:
    get:
      operationId: getOpencomputersMeshes
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Mesh — Index
      tags:
        - Mesh
    post:
      operationId: postOpencomputersMeshes
      responses:
        "200":
          description: Success
        "201":
          description: Created
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Mesh — Create
      tags:
        - Mesh
  /opencomputers/meshes/{id}:
    delete:
      operationId: deleteOpencomputersMeshesId
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        "204":
          description: Deleted
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Mesh — Delete
      tags:
        - Mesh
    get:
      operationId: getOpencomputersMeshesId
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Mesh — Show
      tags:
        - Mesh
  /opencomputers/meshes/{id}/events:
    get:
      operationId: getOpencomputersMeshesIdEvents
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Mesh — Events
      tags:
        - Mesh
  /opencomputers/meshes/{id}/hosts/{host_id}:
    delete:
      operationId: deleteOpencomputersMeshesIdHostsHostId
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
        - in: path
          name: host_id
          required: true
          schema:
            type: string
      responses:
        "204":
          description: Deleted
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Mesh — Remove Host
      tags:
        - Mesh
    post:
      operationId: postOpencomputersMeshesIdHostsHostId
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
        - in: path
          name: host_id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "201":
          description: Created
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Mesh — Add Host
      tags:
        - Mesh
  /opencomputers/osa/latest:
    get:
      operationId: getOpencomputersOsaLatest
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Osa — Latest
      tags:
        - Osa
  /opencomputers/schedules/trigger/{token}:
    post:
      operationId: postOpencomputersSchedulesTriggerToken
      parameters:
        - in: path
          name: token
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "201":
          description: Created
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Schedules — Webhook Trigger
      tags:
        - Schedules
  /opencomputers/secrets:
    get:
      operationId: getOpencomputersSecrets
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Secrets — Index For Tenant
      tags:
        - Secrets
    post:
      operationId: postOpencomputersSecrets
      responses:
        "200":
          description: Success
        "201":
          description: Created
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Secrets — Create For Tenant
      tags:
        - Secrets
  /opencomputers/snapshots/{id}:
    delete:
      operationId: deleteOpencomputersSnapshotsId
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        "204":
          description: Deleted
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Backups — Delete Snapshot
      tags:
        - Backups
    get:
      operationId: getOpencomputersSnapshotsId
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Backups — Show Snapshot
      tags:
        - Backups
  /opencomputers/snapshots/{id}/restore:
    post:
      operationId: postOpencomputersSnapshotsIdRestore
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "201":
          description: Created
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Backups — Restore
      tags:
        - Backups
  /opencomputers/tags:
    get:
      operationId: getOpencomputersTags
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: HostTags — List Tags
      tags:
        - HostTags
  /opencomputers/tunnels/{tunnel_id}/domains:
    get:
      operationId: getOpencomputersTunnelsTunnelIdDomains
      parameters:
        - in: path
          name: tunnel_id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: CustomDomains — Index
      tags:
        - CustomDomains
    post:
      operationId: postOpencomputersTunnelsTunnelIdDomains
      parameters:
        - in: path
          name: tunnel_id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "201":
          description: Created
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: CustomDomains — Create
      tags:
        - CustomDomains
  /opencomputers/tunnels/{tunnel_id}/domains/{id}:
    delete:
      operationId: deleteOpencomputersTunnelsTunnelIdDomainsId
      parameters:
        - in: path
          name: tunnel_id
          required: true
          schema:
            type: string
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        "204":
          description: Deleted
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: CustomDomains — Delete
      tags:
        - CustomDomains
    get:
      operationId: getOpencomputersTunnelsTunnelIdDomainsId
      parameters:
        - in: path
          name: tunnel_id
          required: true
          schema:
            type: string
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: CustomDomains — Show
      tags:
        - CustomDomains
  /opencomputers/tunnels/{tunnel_id}/domains/{id}/verify:
    post:
      operationId: postOpencomputersTunnelsTunnelIdDomainsIdVerify
      parameters:
        - in: path
          name: tunnel_id
          required: true
          schema:
            type: string
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "201":
          description: Created
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: CustomDomains — Verify
      tags:
        - CustomDomains
  /opencomputers/webhooks:
    get:
      operationId: getOpencomputersWebhooks
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Webhooks — Index
      tags:
        - Webhooks
    post:
      operationId: postOpencomputersWebhooks
      responses:
        "200":
          description: Success
        "201":
          description: Created
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Webhooks — Create
      tags:
        - Webhooks
  /opencomputers/webhooks/{id}:
    delete:
      operationId: deleteOpencomputersWebhooksId
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        "204":
          description: Deleted
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Webhooks — Delete
      tags:
        - Webhooks
    patch:
      operationId: patchOpencomputersWebhooksId
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Webhooks — Update
      tags:
        - Webhooks
  /opencomputers/webhooks/{id}/deliveries:
    get:
      operationId: getOpencomputersWebhooksIdDeliveries
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Webhooks — Deliveries
      tags:
        - Webhooks
  /opencomputers/webhooks/{id}/test:
    post:
      operationId: postOpencomputersWebhooksIdTest
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "201":
          description: Created
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Webhooks — Test
      tags:
        - Webhooks
  /opencomputers/workspaces:
    get:
      operationId: getOpencomputersWorkspaces
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Workspaces — Tenant Index
      tags:
        - Workspaces
  /operations/{id}:
    get:
      operationId: getOperationsId
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Operations — Show
      tags:
        - Operations
  /operations/{id}/cancel:
    post:
      operationId: postOperationsIdCancel
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "201":
          description: Created
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Operations — Cancel
      tags:
        - Operations
  /operations/{id}/events:
    get:
      operationId: getOperationsIdEvents
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Operations — Events
      tags:
        - Operations
  /os/templates:
    get:
      operationId: getOsTemplates
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Compat — Os Templates
      tags:
        - Compat
  /osa-projects:
    get:
      operationId: getOsaProjects
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: OsaProjects — Index
      tags:
        - OsaProjects
    post:
      operationId: postOsaProjects
      responses:
        "200":
          description: Success
        "201":
          description: Created
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: OsaProjects — Create
      tags:
        - OsaProjects
  /osa-projects/{id}:
    get:
      operationId: getOsaProjectsId
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: OsaProjects — Show
      tags:
        - OsaProjects
    patch:
      operationId: patchOsaProjectsId
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: OsaProjects — Update
      tags:
        - OsaProjects
    put:
      operationId: putOsaProjectsId
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: OsaProjects — Update
      tags:
        - OsaProjects
  /osa-projects/{osa_project_id}/deployments:
    get:
      operationId: getOsaProjectsOsaProjectIdDeployments
      parameters:
        - in: path
          name: osa_project_id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: OsaProjectDeployments — Index
      tags:
        - OsaProjectDeployments
    post:
      operationId: postOsaProjectsOsaProjectIdDeployments
      parameters:
        - in: path
          name: osa_project_id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "201":
          description: Created
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: OsaProjectDeployments — Create
      tags:
        - OsaProjectDeployments
  /osa-projects/{osa_project_id}/deployments/{id}:
    get:
      operationId: getOsaProjectsOsaProjectIdDeploymentsId
      parameters:
        - in: path
          name: osa_project_id
          required: true
          schema:
            type: string
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: OsaProjectDeployments — Show
      tags:
        - OsaProjectDeployments
  /osa-projects/{osa_project_id}/deployments/{id}/cancel:
    post:
      operationId: postOsaProjectsOsaProjectIdDeploymentsIdCancel
      parameters:
        - in: path
          name: osa_project_id
          required: true
          schema:
            type: string
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "201":
          description: Created
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: OsaProjectDeployments — Cancel
      tags:
        - OsaProjectDeployments
  /osa-projects/{osa_project_id}/deployments/{id}/retry:
    post:
      operationId: postOsaProjectsOsaProjectIdDeploymentsIdRetry
      parameters:
        - in: path
          name: osa_project_id
          required: true
          schema:
            type: string
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "201":
          description: Created
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: OsaProjectDeployments — Retry
      tags:
        - OsaProjectDeployments
  /platform/tenants:
    get:
      operationId: getPlatformTenants
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Tenant — List
      tags:
        - Tenant
  /platform/tenants/current:
    get:
      operationId: getPlatformTenantsCurrent
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Tenant — Current
      tags:
        - Tenant
  /platform/tenants/{id}/switch:
    post:
      operationId: postPlatformTenantsIdSwitch
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "201":
          description: Created
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Tenant — Switch
      tags:
        - Tenant
  /project-auth/config:
    patch:
      operationId: updateProjectAuthConfig
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ProjectAuthMutationRequest"
        required: true
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ProjectAuthStatus"
          description: Updated auth status
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"
      summary: Update generated-app auth config
      tags:
        - Project Auth
  /project-auth/disable:
    post:
      operationId: disableProjectAuth
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ProjectAuthMutationRequest"
        required: true
      responses:
        "200":
          content:
            application/json:
              schema:
                additionalProperties: true
                type: object
          description: Auth disabled
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Disable generated-app auth
      tags:
        - Project Auth
  /project-auth/enable:
    post:
      description: Requires a linked managed database on the sandbox or deployment.
      operationId: enableProjectAuth
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ProjectAuthMutationRequest"
        required: true
      responses:
        "200":
          content:
            application/json:
              schema:
                additionalProperties: true
                type: object
          description: Auth env vars to inject on next boot/restart
        "401":
          $ref: "#/components/responses/Unauthorized"
        "422":
          $ref: "#/components/responses/ValidationError"
      summary: Enable generated-app auth
      tags:
        - Project Auth
  /project-auth/status:
    get:
      operationId: getProjectAuthStatus
      parameters:
        - in: query
          name: resource_type
          required: true
          schema:
            enum:
              - sandbox
              - deployment
            type: string
        - in: query
          name: resource_id
          required: true
          schema:
            format: uuid
            type: string
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ProjectAuthStatus"
          description: Project auth status
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"
      summary: Get generated-app auth status
      tags:
        - Project Auth
  /project-integrations:
    get:
      operationId: getProjectIntegrations
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: ProjectIntegrations — Index
      tags:
        - ProjectIntegrations
    post:
      operationId: postProjectIntegrations
      responses:
        "200":
          description: Success
        "201":
          description: Created
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: ProjectIntegrations — Create
      tags:
        - ProjectIntegrations
  /project-integrations/catalog:
    get:
      operationId: getProjectIntegrationsCatalog
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: ProjectIntegrations — Catalog
      tags:
        - ProjectIntegrations
  /project-integrations/{id}:
    delete:
      operationId: deleteProjectIntegrationsId
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        "204":
          description: Deleted
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: ProjectIntegrations — Delete
      tags:
        - ProjectIntegrations
    get:
      operationId: getProjectIntegrationsId
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: ProjectIntegrations — Show
      tags:
        - ProjectIntegrations
    patch:
      operationId: patchProjectIntegrationsId
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: ProjectIntegrations — Update
      tags:
        - ProjectIntegrations
  /projects:
    get:
      operationId: getProjects
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Projects — Index
      tags:
        - Projects
    post:
      operationId: postProjects
      responses:
        "200":
          description: Success
        "201":
          description: Created
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Projects — Create
      tags:
        - Projects
  /projects/{id}:
    delete:
      operationId: deleteProjectsId
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        "204":
          description: Deleted
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Projects — Destroy
      tags:
        - Projects
    get:
      operationId: getProjectsId
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Projects — Show
      tags:
        - Projects
    patch:
      operationId: patchProjectsId
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Projects — Update
      tags:
        - Projects
  /projects/{id}/members:
    get:
      operationId: getProjectsIdMembers
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: ProjectMembers — Index
      tags:
        - ProjectMembers
    post:
      operationId: postProjectsIdMembers
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "201":
          description: Created
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: ProjectMembers — Create
      tags:
        - ProjectMembers
  /projects/{id}/members/{user_id}:
    delete:
      operationId: deleteProjectsIdMembersUserId
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
        - in: path
          name: user_id
          required: true
          schema:
            type: string
      responses:
        "204":
          description: Deleted
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: ProjectMembers — Delete
      tags:
        - ProjectMembers
    patch:
      operationId: patchProjectsIdMembersUserId
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
        - in: path
          name: user_id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: ProjectMembers — Update Role
      tags:
        - ProjectMembers
  /projects/{id}/move:
    post:
      operationId: postProjectsIdMove
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "201":
          description: Created
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Projects — Move
      tags:
        - Projects
  /projects/{project_id}/managed-databases:
    get:
      operationId: getProjectsProjectIdManagedDatabases
      parameters:
        - in: path
          name: project_id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: ManagedDatabases — Index
      tags:
        - ManagedDatabases
    post:
      operationId: postProjectsProjectIdManagedDatabases
      parameters:
        - in: path
          name: project_id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "201":
          description: Created
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: ManagedDatabases — Create
      tags:
        - ManagedDatabases
  /public/branding-assets/{tenant_id}/{kind}/{asset_id}/{filename}:
    get:
      operationId: getPublicBrandingAssetsTenantIdKindAssetIdFilename
      parameters:
        - in: path
          name: tenant_id
          required: true
          schema:
            type: string
        - in: path
          name: kind
          required: true
          schema:
            type: string
        - in: path
          name: asset_id
          required: true
          schema:
            type: string
        - in: path
          name: filename
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: BrandingAssets — Show
      tags:
        - BrandingAssets
  /quotas/external/{external_user_id}:
    delete:
      operationId: deleteQuotasExternalExternalUserId
      parameters:
        - in: path
          name: external_user_id
          required: true
          schema:
            type: string
      responses:
        "204":
          description: Deleted
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Quotas — Delete
      tags:
        - Quotas
    get:
      operationId: getQuotasExternalExternalUserId
      parameters:
        - in: path
          name: external_user_id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Quotas — Show
      tags:
        - Quotas
    put:
      operationId: putQuotasExternalExternalUserId
      parameters:
        - in: path
          name: external_user_id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Quotas — Upsert
      tags:
        - Quotas
  /regions:
    get:
      operationId: getRegions
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Regions — Index
      tags:
        - Regions
  /run-groups:
    get:
      operationId: getRunGroups
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: RunGroups — Index
      tags:
        - RunGroups
    post:
      operationId: postRunGroups
      responses:
        "200":
          description: Success
        "201":
          description: Created
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: RunGroups — Create
      tags:
        - RunGroups
  /run-groups/{id}:
    get:
      operationId: getRunGroupsId
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: RunGroups — Show
      tags:
        - RunGroups
  /run-groups/{id}/activity:
    get:
      operationId: getRunGroupsIdActivity
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: RunGroups — Activity
      tags:
        - RunGroups
  /run-groups/{id}/cancel:
    post:
      operationId: postRunGroupsIdCancel
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "201":
          description: Created
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: RunGroups — Cancel
      tags:
        - RunGroups
  /run-groups/{id}/dispatch:
    post:
      operationId: postRunGroupsIdDispatch
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "201":
          description: Created
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: RunGroups — Dispatch
      tags:
        - RunGroups
  /runs:
    get:
      operationId: listRuns
      parameters:
        - in: query
          name: workspace_id
          required: false
          schema:
            format: uuid
            type: string
        - in: query
          name: target_kind
          required: false
          schema:
            enum:
              - sandbox
              - computer
            type: string
        - in: query
          name: target_id
          required: false
          schema:
            type: string
        - in: query
          name: status
          required: false
          schema:
            type: string
        - $ref: "#/components/parameters/LimitParam"
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RunListResponse"
          description: Run list
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: List runs
      tags:
        - Runs
    post:
      description: "Create a canonical run against a sandbox or computer. Use `Idempotency-Key` to retry safely without dispatching twice.\n"
      operationId: createRun
      parameters:
        - in: header
          name: Idempotency-Key
          required: false
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CreateRunRequest"
        required: true
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RunResponse"
          description: Run accepted or completed.
        "201":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RunResponse"
          description: Run created.
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "409":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
          description: Target precondition failed, such as stopped computer.
        "422":
          $ref: "#/components/responses/ValidationError"
      summary: Create a run
      tags:
        - Runs
  /runs/{id}:
    get:
      operationId: getRun
      parameters:
        - in: path
          name: id
          required: true
          schema:
            format: uuid
            type: string
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RunResponse"
          description: Run
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"
      summary: Get a run
      tags:
        - Runs
  /runs/{id}/activity:
    get:
      operationId: listRunActivity
      parameters:
        - in: path
          name: id
          required: true
          schema:
            format: uuid
            type: string
      responses:
        "200":
          content:
            application/json:
              schema:
                properties:
                  data:
                    items:
                      $ref: "#/components/schemas/RunActivity"
                    type: array
                type: object
          description: Run activity
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: List run activity
      tags:
        - Runs
  /runs/{id}/cancel:
    post:
      operationId: cancelRun
      parameters:
        - in: path
          name: id
          required: true
          schema:
            format: uuid
            type: string
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RunResponse"
          description: Canceled run
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"
      summary: Cancel a run
      tags:
        - Runs
  /runs/{id}/command-output:
    get:
      operationId: getRunCommandOutput
      parameters:
        - in: path
          name: id
          required: true
          schema:
            format: uuid
            type: string
      responses:
        "200":
          content:
            application/json:
              schema:
                properties:
                  data:
                    $ref: "#/components/schemas/RunCommandOutput"
                type: object
          description: Run command output
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Get run command output
      tags:
        - Runs
  /runs/{id}/diagnostics:
    get:
      operationId: listRunDiagnostics
      parameters:
        - in: path
          name: id
          required: true
          schema:
            format: uuid
            type: string
      responses:
        "200":
          content:
            application/json:
              schema:
                properties:
                  data:
                    items:
                      $ref: "#/components/schemas/RunDiagnostic"
                    type: array
                type: object
          description: Run diagnostics
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: List run diagnostics
      tags:
        - Runs
  /runs/{id}/events:
    get:
      operationId: listRunEvents
      parameters:
        - in: path
          name: id
          required: true
          schema:
            format: uuid
            type: string
        - in: query
          name: after_id
          required: false
          schema:
            format: uuid
            type: string
        - in: query
          name: limit
          required: false
          schema:
            maximum: 500
            minimum: 1
            type: integer
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RunEventsResponse"
          description: Run lifecycle events
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: List durable run lifecycle events
      tags:
        - Runs
  /runs/{id}/files:
    get:
      operationId: listRunFiles
      parameters:
        - in: path
          name: id
          required: true
          schema:
            format: uuid
            type: string
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RunFilesResponse"
          description: Run files
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: List run files
      tags:
        - Runs
  /runs/{id}/files/{file_id}/download:
    get:
      operationId: downloadRunFile
      parameters:
        - in: path
          name: id
          required: true
          schema:
            format: uuid
            type: string
        - in: path
          name: file_id
          required: true
          schema:
            format: uuid
            type: string
      responses:
        "200":
          content:
            application/octet-stream:
              schema:
                format: binary
                type: string
          description: File bytes
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"
      summary: Download a run file
      tags:
        - Runs
  /runs/{id}/messages:
    get:
      operationId: listRunMessages
      parameters:
        - in: path
          name: id
          required: true
          schema:
            format: uuid
            type: string
      responses:
        "200":
          content:
            application/json:
              schema:
                properties:
                  data:
                    items:
                      $ref: "#/components/schemas/RunMessage"
                    type: array
                type: object
          description: Run messages
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: List run messages
      tags:
        - Runs
  /runs/{id}/outputs:
    get:
      operationId: getRunOutputs
      parameters:
        - in: path
          name: id
          required: true
          schema:
            format: uuid
            type: string
      responses:
        "200":
          content:
            application/json:
              schema:
                properties:
                  data:
                    $ref: "#/components/schemas/RunOutputs"
                type: object
          description: Aggregated run outputs
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"
      summary: Get all run output buckets
      tags:
        - Runs
  /runs/{id}/previews:
    get:
      operationId: listRunPreviews
      parameters:
        - in: path
          name: id
          required: true
          schema:
            format: uuid
            type: string
      responses:
        "200":
          content:
            application/json:
              schema:
                properties:
                  data:
                    items:
                      $ref: "#/components/schemas/RunPreview"
                    type: array
                type: object
          description: Run previews
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: List run previews
      tags:
        - Runs
  /runtime-env:
    get:
      operationId: getRuntimeEnv
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: RuntimeEnvVars — Index
      tags:
        - RuntimeEnvVars
    post:
      operationId: postRuntimeEnv
      responses:
        "200":
          description: Success
        "201":
          description: Created
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: RuntimeEnvVars — Create
      tags:
        - RuntimeEnvVars
  /runtime-env/{id}:
    delete:
      operationId: deleteRuntimeEnvId
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        "204":
          description: Deleted
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: RuntimeEnvVars — Delete
      tags:
        - RuntimeEnvVars
    get:
      operationId: getRuntimeEnvId
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: RuntimeEnvVars — Show
      tags:
        - RuntimeEnvVars
    patch:
      operationId: patchRuntimeEnvId
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: RuntimeEnvVars — Update
      tags:
        - RuntimeEnvVars
    put:
      operationId: putRuntimeEnvId
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: RuntimeEnvVars — Update
      tags:
        - RuntimeEnvVars
  /sandbox-template-builds/{build_id}:
    get:
      operationId: getSandboxTemplateBuildsBuildId
      parameters:
        - in: path
          name: build_id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: SandboxTemplates — Show Build
      tags:
        - SandboxTemplates
  /sandbox-template-builds/{build_id}/cancel:
    post:
      operationId: postSandboxTemplateBuildsBuildIdCancel
      parameters:
        - in: path
          name: build_id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "201":
          description: Created
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: SandboxTemplates — Cancel Build
      tags:
        - SandboxTemplates
  /sandbox-template-builds/{build_id}/logs:
    get:
      operationId: getSandboxTemplateBuildsBuildIdLogs
      parameters:
        - in: path
          name: build_id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: SandboxTemplates — Build Logs
      tags:
        - SandboxTemplates
  /sandbox-template-builds/{build_id}/logs/stream:
    get:
      operationId: getSandboxTemplateBuildsBuildIdLogsStream
      parameters:
        - in: path
          name: build_id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: SandboxTemplates — Stream Build Logs
      tags:
        - SandboxTemplates
  /sandbox-template-builds/{build_id}/retry:
    post:
      operationId: postSandboxTemplateBuildsBuildIdRetry
      parameters:
        - in: path
          name: build_id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "201":
          description: Created
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: SandboxTemplates — Retry Build
      tags:
        - SandboxTemplates
  /sandbox-templates:
    get:
      description: "Return the platform-managed sandbox template catalog. Pass one of these\nIDs as `template_id` when creating a sandbox.\n\nTemplates describe the developer-facing profile: base image, default\nresources, workspace path, install/start commands, preview port, and\nreadiness probe. Use `POST /sandboxes/{id}/template/start` after\nwriting files, or set `auto_start: true` on create when the template\ncan start immediately. Today the built-ins resolve to\n`debian-12-sandbox-v8`; future template builds can attach per-template\nsnapshots without changing the public `template_id`.\n"
      operationId: listSandboxTemplates
      parameters:
        - description: Include legacy aliases such as `python-3.12` and `react-vite`.
          in: query
          name: include_aliases
          required: false
          schema:
            default: false
            type: boolean
      responses:
        "200":
          content:
            application/json:
              example:
                data:
                  - category: web
                    cpu_count: 2
                    disk_mb: 4096
                    id: nextjs
                    image_id: debian-12-sandbox-v8
                    install_command: npm install
                    memory_mb: 2048
                    name: Next.js
                    preview_port: 3000
                    readiness_probe:
                      type: http
                      url: http://127.0.0.1:3000
                    start_command: npm run dev -- --hostname 0.0.0.0 --port 3000
                    workdir: /workspace
                default_template_id: miosa-sandbox
              schema:
                properties:
                  data:
                    items:
                      additionalProperties: true
                      type: object
                    type: array
                  default_template_id:
                    example: miosa-sandbox
                    type: string
                required:
                  - data
                  - default_template_id
                type: object
          description: Template catalog
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: List sandbox templates
      tags:
        - Sandboxes
    post:
      operationId: postSandboxTemplates
      responses:
        "200":
          description: Success
        "201":
          description: Created
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: SandboxTemplates — Create
      tags:
        - SandboxTemplates
  /sandbox-templates/build-spec:
    get:
      operationId: getSandboxTemplatesBuildSpec
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: SandboxTemplates — Build Spec
      tags:
        - SandboxTemplates
  /sandbox-templates/validate:
    post:
      operationId: postSandboxTemplatesValidate
      responses:
        "200":
          description: Success
        "201":
          description: Created
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: SandboxTemplates — Validate
      tags:
        - SandboxTemplates
  /sandbox-templates/{id}:
    get:
      description: Return one sandbox template by ID or alias.
      operationId: getSandboxTemplate
      parameters:
        - example: nextjs
          in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        "200":
          content:
            application/json:
              schema:
                additionalProperties: true
                type: object
          description: Sandbox template
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"
      summary: Get sandbox template
      tags:
        - Sandboxes
  /sandbox-templates/{id}/builds:
    get:
      operationId: getSandboxTemplatesIdBuilds
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: SandboxTemplates — List Builds
      tags:
        - SandboxTemplates
    post:
      operationId: postSandboxTemplatesIdBuilds
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "201":
          description: Created
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: SandboxTemplates — Create Build
      tags:
        - SandboxTemplates
  /sandboxes:
    get:
      description: "List sandboxes owned by the authenticated MIOSA tenant. Optional external attribution filters are scoped under that tenant and cannot cross tenant boundaries.\n"
      operationId: listSandboxes
      parameters:
        - $ref: "#/components/parameters/ExternalWorkspaceId"
        - $ref: "#/components/parameters/ExternalUserId"
        - $ref: "#/components/parameters/ExternalProjectId"
      responses:
        "200":
          content:
            application/json:
              schema:
                properties:
                  data:
                    items:
                      $ref: "#/components/schemas/Sandbox"
                    type: array
                type: object
          description: List of sandboxes
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: List sandboxes
      tags:
        - Sandboxes
    post:
      description: "Spawn a persistent-by-default Firecracker microVM from an immutable,\npromoted artifact generation. The control plane resolves `size` into\none versioned resource contract before admission and placement.\n\n**Idempotency:** Supply an `Idempotency-Key` header to prevent duplicate\nsandboxes on client retry. The same key within 24 h returns the existing\nsandbox with HTTP 200 instead of creating a new one.\n\n**Billing:** Starts when the sandbox enters `running` state. Billed\nper-second. Maximum charge is `timeout_sec` seconds even if destruction\nis triggered externally.\n"
      operationId: createSandbox
      parameters:
        - description: "Client-generated unique string (UUID recommended). Prevents duplicate sandboxes when the client retries a timed-out request.\n"
          in: header
          name: Idempotency-Key
          required: false
          schema:
            example: 01HX2K3M4N5P6Q7R8S9T0UVWXY
            maxLength: 255
            type: string
      requestBody:
        content:
          application/json:
            examples:
              full:
                summary: Full request using the named small contract
                value:
                  env:
                    API_KEY: sk-abc123
                    DEBUG: "true"
                  external_project_id: landing-page-789
                  external_user_id: dr-smith-456
                  external_workspace_id: dental-office-123
                  metadata:
                    agent_run_id: run_01HX2K3M
                    task: code_review
                  size: small
                  template_id: miosa-sandbox
                  timeout_sec: 600
              minimal:
                summary: Minimal request using the default small contract
                value:
                  template_id: miosa-sandbox
            schema:
              $ref: "#/components/schemas/CreateSandboxRequest"
        required: true
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Sandbox"
          description: Existing sandbox returned for an idempotent replay
        "201":
          content:
            application/json:
              example:
                boot_ms: null
                boot_path: null
                cpu_count: 2
                created_at: 2026-04-25T10:00:00.000000Z
                destroyed_at: null
                disk_size_mb: 10240
                external_project_id: landing-page-789
                external_user_id: dr-smith-456
                external_workspace_id: dental-office-123
                id: 3fa85f64-5717-4562-b3fc-2c963f66afa6
                image_id: miosa-sandbox-prod-1
                memory_mb: 4096
                metadata: {}
                owner_id: a1b2c3d4-e5f6-7890-abcd-ef1234567890
                preview_url: https://3fa85f64.sandbox.miosa.app
                ready: false
                ready_at: null
                resource_contract:
                  disk_size_mb: 10240
                  id: sandbox/small@v1
                  memory_mb: 4096
                  product: sandbox
                  size: small
                  vcpus: 2
                  version: v1
                size: small
                started_at: null
                state: provisioning
                template_id: miosa-sandbox
                tenant_id: 1b2c3d4e-5f6a-7890-abcd-ef1234567890
                timeout_sec: 3600
                total_runtime_sec: null
              schema:
                $ref: "#/components/schemas/Sandbox"
          description: Sandbox created (VM provisioning started)
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "409":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
          description: The idempotency key is in progress, terminal, or bound to a different request.
        "422":
          $ref: "#/components/responses/UnprocessableEntity"
      summary: Create a sandbox
      tags:
        - Sandboxes
  /sandboxes/by-name/{name}:
    get:
      description: Return a running sandbox by its tenant-scoped name.
      operationId: getSandboxByName
      parameters:
        - in: path
          name: name
          required: true
          schema:
            type: string
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Sandbox"
          description: Sandbox found
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"
        "422":
          $ref: "#/components/responses/UnprocessableEntity"
      summary: Get sandbox by tenant-scoped name
      tags:
        - Sandboxes
  /sandboxes/run:
    post:
      operationId: postSandboxesRun
      responses:
        "200":
          description: Success
        "201":
          description: Created
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Sandboxes — Run
      tags:
        - Sandboxes
  /sandboxes/{id}:
    delete:
      description: "Terminate the VM, compute `total_runtime_sec`, and write the billing record.\n\n**Idempotent** — destroying an already-destroyed sandbox returns `200`.\n\nThe per-second credit charge is settled at this point. If the sandbox\nnever reached `running` state, `total_runtime_sec` is 0.\n"
      operationId: destroySandbox
      parameters:
        - $ref: "#/components/parameters/SandboxId"
      responses:
        "200":
          content:
            application/json:
              example:
                id: 3fa85f64-5717-4562-b3fc-2c963f66afa6
                state: destroyed
                total_runtime_sec: 47
              schema:
                properties:
                  id:
                    format: uuid
                    type: string
                  state:
                    enum:
                      - destroyed
                    type: string
                  total_runtime_sec:
                    description: Total seconds the sandbox was in `running` state
                    example: 47
                    type: integer
                type: object
          description: Sandbox destroyed
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"
      summary: Destroy sandbox
      tags:
        - Sandboxes
    get:
      description: Return the current state and metadata of a sandbox.
      operationId: getSandbox
      parameters:
        - $ref: "#/components/parameters/SandboxId"
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Sandbox"
          description: Sandbox found
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"
      summary: Get sandbox
      tags:
        - Sandboxes
    patch:
      description: "Update mutable sandbox fields such as name, agent session ID, tags,\nmetadata, timeout, idle timeout, and always-on state.\n"
      operationId: updateSandbox
      parameters:
        - $ref: "#/components/parameters/SandboxId"
      requestBody:
        content:
          application/json:
            schema:
              properties:
                agent_session_id:
                  nullable: true
                  type: string
                always_on:
                  type: boolean
                idle_timeout_sec:
                  nullable: true
                  type: integer
                metadata:
                  additionalProperties: true
                  type: object
                name:
                  nullable: true
                  type: string
                tags:
                  additionalProperties:
                    type: string
                  type: object
                timeout_sec:
                  type: integer
              type: object
        required: true
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Sandbox"
          description: Updated sandbox
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"
        "422":
          $ref: "#/components/responses/UnprocessableEntity"
      summary: Update sandbox metadata
      tags:
        - Sandboxes
  /sandboxes/{id}/artifacts:
    get:
      description: "Return the artifact and preview contract for a sandbox. The response\nincludes template artifact paths, the selected preview URL/port, and\ntemplate lifecycle metadata such as log and PID paths.\n"
      operationId: getSandboxArtifacts
      parameters:
        - $ref: "#/components/parameters/SandboxId"
      responses:
        "200":
          content:
            application/json:
              example:
                data:
                  artifacts:
                    logs_path: /workspace/.miosa/template.log
                    paths:
                      - /workspace
                  preview:
                    port: 3000
                    url: https://3fa85f64.sandbox.miosa.app
                  sandbox_id: 3fa85f64-5717-4562-b3fc-2c963f66afa6
                  template_id: nextjs
                  workdir: /workspace
              schema:
                additionalProperties: true
                type: object
          description: Sandbox artifact manifest
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"
      summary: Get sandbox artifacts
      tags:
        - Sandboxes
  /sandboxes/{id}/commands:
    get:
      operationId: getSandboxesIdCommands
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: SandboxProcesses — Index
      tags:
        - SandboxProcesses
    post:
      operationId: postSandboxesIdCommands
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "201":
          description: Created
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: SandboxProcesses — Create
      tags:
        - SandboxProcesses
  /sandboxes/{id}/commands/{pid}:
    get:
      operationId: getSandboxesIdCommandsPid
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
        - in: path
          name: pid
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: SandboxProcesses — Show
      tags:
        - SandboxProcesses
  /sandboxes/{id}/commands/{pid}/kill:
    post:
      operationId: postSandboxesIdCommandsPidKill
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
        - in: path
          name: pid
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "201":
          description: Created
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: SandboxProcesses — Delete
      tags:
        - SandboxProcesses
  /sandboxes/{id}/commands/{pid}/logs:
    get:
      operationId: getSandboxesIdCommandsPidLogs
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
        - in: path
          name: pid
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: SandboxProcesses — Logs
      tags:
        - SandboxProcesses
  /sandboxes/{id}/compose:
    post:
      operationId: postSandboxesIdCompose
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "201":
          description: Created
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Sandboxes — Compose
      tags:
        - Sandboxes
  /sandboxes/{id}/connectors:
    get:
      operationId: getSandboxesIdConnectors
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: SandboxConnector — Index
      tags:
        - SandboxConnector
    post:
      operationId: postSandboxesIdConnectors
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "201":
          description: Created
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: SandboxConnector — Attach
      tags:
        - SandboxConnector
  /sandboxes/{id}/connectors/preflight:
    post:
      operationId: postSandboxesIdConnectorsPreflight
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "201":
          description: Created
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: SandboxConnector — Preflight
      tags:
        - SandboxConnector
  /sandboxes/{id}/connectors/sync:
    post:
      operationId: postSandboxesIdConnectorsSync
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "201":
          description: Created
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: SandboxConnector — Sync
      tags:
        - SandboxConnector
  /sandboxes/{id}/connectors/{binding}:
    delete:
      operationId: deleteSandboxesIdConnectorsBinding
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
        - in: path
          name: binding
          required: true
          schema:
            type: string
      responses:
        "204":
          description: Deleted
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: SandboxConnector — Detach
      tags:
        - SandboxConnector
  /sandboxes/{id}/database:
    post:
      operationId: postSandboxesIdDatabase
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "201":
          description: Created
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: SandboxDatabase — Attach
      tags:
        - SandboxDatabase
  /sandboxes/{id}/deploy:
    post:
      description: "Publish the current sandbox output into an immutable production\ndeployment. The sandbox remains editable and preview-only; production\nreceives a Deployment, Version, and Release. Publishing again creates a\nnew immutable version and promotes it.\n"
      operationId: deploySandbox
      parameters:
        - $ref: "#/components/parameters/SandboxId"
        - in: header
          name: Idempotency-Key
          required: false
          schema:
            type: string
      requestBody:
        content:
          application/json:
            example:
              entrypoint: index.html
              name: clinic-landing-page
              output_path: /workspace/dist
            schema:
              $ref: "#/components/schemas/SandboxDeployRequest"
        required: true
      responses:
        "201":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SandboxDeployResponse"
          description: Published deployment
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"
        "409":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
          description: Sandbox is not running or output is not publishable.
      summary: Publish sandbox to deployment
      tags:
        - Sandboxes
        - Deployments
  /sandboxes/{id}/desktop:
    get:
      operationId: getSandboxesIdDesktop
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Sandboxes — Get Desktop
      tags:
        - Sandboxes
    post:
      operationId: postSandboxesIdDesktop
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "201":
          description: Created
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Sandboxes — Start Desktop
      tags:
        - Sandboxes
  /sandboxes/{id}/env:
    get:
      description: Return the environment variable map stored on the sandbox record.
      operationId: getSandboxEnv
      parameters:
        - $ref: "#/components/parameters/SandboxId"
      responses:
        "200":
          content:
            application/json:
              schema:
                properties:
                  data:
                    additionalProperties:
                      type: string
                    type: object
                type: object
          description: Sandbox environment variables
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"
      summary: Get sandbox environment
      tags:
        - Sandboxes
    put:
      operationId: putSandboxesIdEnv
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: SandboxEnv — Upsert
      tags:
        - SandboxEnv
  /sandboxes/{id}/env/sync:
    post:
      operationId: postSandboxesIdEnvSync
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "201":
          description: Created
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: SandboxEnv — Sync
      tags:
        - SandboxEnv
  /sandboxes/{id}/env/{key}:
    delete:
      operationId: deleteSandboxesIdEnvKey
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
        - in: path
          name: key
          required: true
          schema:
            type: string
      responses:
        "204":
          description: Deleted
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: SandboxEnv — Delete
      tags:
        - SandboxEnv
  /sandboxes/{id}/events:
    get:
      description: "Server-Sent Events stream for sandbox lifecycle events.\n\n**Auth:** Browsers cannot set `Authorization` on `EventSource` connections.\nInstead, obtain a short-lived ticket from `POST /auth/sse-ticket` and\nsupply it as `?ticket=<value>`.\n\n**Event types:**\n\n| Type | Payload | Description |\n|------|---------|-------------|\n| `state_changed` | `{state, previous_state}` | Sandbox moved to a new state |\n| `exec_output` | `{stream, data, exec_id}` | stdout/stderr chunk |\n| (comment) | `: heartbeat` | Sent every 15 s to keep the connection alive |\n\nThe server closes the stream when the sandbox reaches `destroyed` state.\n\n**PubSub topic:** `sandbox:{id}`\n"
      operationId: streamSandboxEvents
      parameters:
        - $ref: "#/components/parameters/SandboxId"
        - description: Short-lived SSE ticket from `POST /auth/sse-ticket`
          in: query
          name: ticket
          required: true
          schema:
            type: string
      responses:
        "200":
          content:
            text/event-stream:
              schema:
                example: "id: 3fa85f64-5717-4562-b3fc-2c963f66afa6\nevent: state_changed\ndata: {\"state\":\"running\",\"previous_state\":\"provisioning\"}\n\n: heartbeat\n"
                type: string
          description: SSE stream opened
        "401":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
          description: Missing or invalid SSE ticket
        "404":
          $ref: "#/components/responses/NotFound"
      summary: Stream sandbox events (SSE)
      tags:
        - Sandboxes
  /sandboxes/{id}/exec:
    post:
      description: "Run a shell command inside the sandbox and return stdout, stderr, and exit code.\n\nThe command is proxied to the in-VM `envd` agent at port 49983, the same\ntransport used by `POST /computers/{id}/exec`. The sandbox must be in\n`running` state.\n"
      operationId: execInSandbox
      parameters:
        - $ref: "#/components/parameters/SandboxId"
      requestBody:
        content:
          application/json:
            example:
              command: python3 -c "print(1+1)"
              timeout: 30
            schema:
              $ref: "#/components/schemas/SandboxExecRequest"
        required: true
      responses:
        "200":
          content:
            application/json:
              example:
                data:
                  exit_code: 0
                  sandbox_id: 3fa85f64-5717-4562-b3fc-2c963f66afa6
                  stderr: ""
                  stdout: "2"
              schema:
                properties:
                  data:
                    $ref: "#/components/schemas/SandboxExecResult"
                type: object
          description: Command executed
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"
        "409":
          content:
            application/json:
              example:
                error:
                  code: SANDBOX_NOT_RUNNING
                  message: sandbox must be in running state to exec
              schema:
                $ref: "#/components/schemas/ErrorResponse"
          description: Sandbox is not in `running` state
        "502":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
          description: In-VM agent unreachable
      summary: Execute command
      tags:
        - Sandboxes
  /sandboxes/{id}/exec/stream:
    post:
      description: "Run a command inside the sandbox and stream stdout/stderr chunks as the\ncommand runs. SDKs should prefer this endpoint for long-running build,\ninstall, and agent tasks where incremental output is required.\n"
      operationId: streamExecInSandbox
      parameters:
        - $ref: "#/components/parameters/SandboxId"
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/SandboxExecRequest"
        required: true
      responses:
        "200":
          content:
            application/x-ndjson:
              schema:
                type: string
            text/event-stream:
              example: "event: stdout\ndata: {\"data\":\"Installing dependencies...\"}\n\nevent: exit\ndata: {\"exit_code\":0}\n"
              schema:
                type: string
          description: Streaming command output
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"
        "409":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
          description: Sandbox is not in `running` state
        "502":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
          description: In-VM agent unreachable
      summary: Execute command with streaming output
      tags:
        - Sandboxes
  /sandboxes/{id}/exports:
    post:
      operationId: postSandboxesIdExports
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "201":
          description: Created
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: SandboxExports — Create
      tags:
        - SandboxExports
  /sandboxes/{id}/exports/download:
    get:
      operationId: getSandboxesIdExportsDownload
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: SandboxExports — Download
      tags:
        - SandboxExports
  /sandboxes/{id}/exports/signed-download:
    get:
      operationId: getSandboxesIdExportsSignedDownload
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: SandboxExports — Download Signed
      tags:
        - SandboxExports
  /sandboxes/{id}/expose:
    post:
      description: "Return a public preview URL for a process listening on a port inside the\nsandbox. The URL is tenant-aware: if the tenant has configured a\nwhite-label preview domain, that domain is used; otherwise MIOSA uses\nthe platform default preview domain.\n\nStart dev servers inside the sandbox on `0.0.0.0`, not `localhost`.\nFor example: `npm run dev -- --host 0.0.0.0 --port 5173`.\n"
      operationId: exposeSandboxPort
      parameters:
        - $ref: "#/components/parameters/SandboxId"
      requestBody:
        content:
          application/json:
            example:
              port: 5173
            schema:
              properties:
                port:
                  description: Port inside the sandbox to expose
                  maximum: 65535
                  minimum: 1
                  type: integer
              required:
                - port
              type: object
        required: true
      responses:
        "200":
          content:
            application/json:
              example:
                url: https://5173-3fa85f64.sandbox.miosa.app
              schema:
                properties:
                  url:
                    example: https://5173-3fa85f64.sandbox.miosa.app
                    format: uri
                    type: string
                required:
                  - url
                type: object
          description: Preview URL created
        "400":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
          description: Missing or invalid request body
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"
        "409":
          content:
            application/json:
              example:
                error:
                  code: SANDBOX_NOT_RUNNING
                  message: sandbox must be running to expose a port
              schema:
                $ref: "#/components/schemas/ErrorResponse"
          description: Sandbox is not in `running` state
        "422":
          content:
            application/json:
              example:
                error:
                  code: INVALID_PORT
                  message: port must be an integer between 1 and 65535
              schema:
                $ref: "#/components/schemas/ErrorResponse"
          description: Invalid port
      summary: Expose sandbox port
      tags:
        - Sandboxes
  /sandboxes/{id}/extend:
    post:
      description: Set the sandbox active-session timeout. Omitting the body preserves the current value.
      operationId: extendSandbox
      parameters:
        - $ref: "#/components/parameters/SandboxId"
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ExtendSandboxRequest"
        required: false
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Sandbox"
          description: Updated sandbox
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"
        "422":
          $ref: "#/components/responses/UnprocessableEntity"
      summary: Replace the sandbox timeout
      tags:
        - Sandboxes
  /sandboxes/{id}/files:
    delete:
      operationId: deleteSandboxesIdFiles
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        "204":
          description: Deleted
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: SandboxFiles — Delete
      tags:
        - SandboxFiles
    get:
      description: List files under a directory inside the sandbox filesystem.
      operationId: listSandboxFiles
      parameters:
        - $ref: "#/components/parameters/SandboxId"
        - in: query
          name: path
          required: false
          schema:
            default: /workspace
            type: string
        - in: query
          name: recursive
          required: false
          schema:
            default: false
            type: boolean
      responses:
        "200":
          content:
            application/json:
              schema:
                properties:
                  data:
                    $ref: "#/components/schemas/IntelligenceGatewayHealth"
                type: object
          description: File list
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"
        "409":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
          description: Sandbox is not in `running` state
      summary: List sandbox files
      tags:
        - Sandboxes
    post:
      description: "Write a file into the sandbox filesystem.\n\nSupply `path` (required, absolute VM path) and `content` (base64-encoded\nbytes). Alternatively, POST a `multipart/form-data` body. Proxied to\nenvd `/fs/write`.\n"
      operationId: uploadFileToSandbox
      parameters:
        - $ref: "#/components/parameters/SandboxId"
      requestBody:
        content:
          application/json:
            example:
              content: cHJpbnQoImhlbGxvIik=
              path: /workspace/hello.py
            schema:
              $ref: "#/components/schemas/SandboxUploadRequest"
        required: true
      responses:
        "201":
          content:
            application/json:
              schema:
                properties:
                  data:
                    properties:
                      path:
                        type: string
                      sandbox_id:
                        format: uuid
                        type: string
                      size:
                        description: File size in bytes
                        type: integer
                    type: object
                type: object
          description: File written
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"
        "409":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
          description: Sandbox is not in `running` state
      summary: Upload file
      tags:
        - Sandboxes
  /sandboxes/{id}/files/list:
    get:
      description: Compatibility endpoint for SDKs that call `/files/list`.
      operationId: listSandboxFilesCompat
      parameters:
        - $ref: "#/components/parameters/SandboxId"
        - in: query
          name: path
          required: false
          schema:
            default: /workspace
            type: string
        - in: query
          name: recursive
          required: false
          schema:
            default: false
            type: boolean
      responses:
        "200":
          content:
            application/json:
              schema:
                additionalProperties: true
                type: object
          description: File list
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"
      summary: List sandbox files (compat)
      tags:
        - Sandboxes
  /sandboxes/{id}/files/read:
    get:
      description: Read a file from the sandbox filesystem using a query parameter path.
      operationId: readSandboxFile
      parameters:
        - $ref: "#/components/parameters/SandboxId"
        - in: query
          name: path
          required: true
          schema:
            example: /workspace/package.json
            type: string
      responses:
        "200":
          content:
            application/json:
              schema:
                additionalProperties: true
                type: object
            application/octet-stream:
              schema:
                format: binary
                type: string
          description: File contents
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"
        "409":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
          description: Sandbox is not in `running` state
      summary: Read sandbox file
      tags:
        - Sandboxes
  /sandboxes/{id}/files/stat:
    post:
      description: Return metadata for a file or directory inside the sandbox.
      operationId: statSandboxFile
      parameters:
        - $ref: "#/components/parameters/SandboxId"
      requestBody:
        content:
          application/json:
            schema:
              properties:
                path:
                  example: /workspace/package.json
                  type: string
              required:
                - path
              type: object
        required: true
      responses:
        "200":
          content:
            application/json:
              schema:
                additionalProperties: true
                type: object
          description: File metadata
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"
      summary: Stat sandbox file
      tags:
        - Sandboxes
  /sandboxes/{id}/files/write:
    post:
      description: Write or overwrite a file inside the sandbox filesystem.
      operationId: writeSandboxFile
      parameters:
        - $ref: "#/components/parameters/SandboxId"
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/SandboxUploadRequest"
        required: true
      responses:
        "200":
          content:
            application/json:
              schema:
                additionalProperties: true
                type: object
          description: File written
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"
        "409":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
          description: Sandbox is not in `running` state
      summary: Write sandbox file
      tags:
        - Sandboxes
  /sandboxes/{id}/files/write-batch:
    post:
      operationId: postSandboxesIdFilesWriteBatch
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "201":
          description: Created
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: SandboxFiles — Write Many
      tags:
        - SandboxFiles
  /sandboxes/{id}/files/write-many:
    post:
      operationId: postSandboxesIdFilesWriteMany
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "201":
          description: Created
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: SandboxFiles — Write Many
      tags:
        - SandboxFiles
  /sandboxes/{id}/files/{path}:
    get:
      description: "Read a file from the sandbox filesystem.\n\n`{path}` is the URL-encoded absolute path inside the VM (e.g.\n`/workspace/output.json` → `/sandboxes/{id}/files/%2Fworkspace%2Foutput.json`).\nReturns raw bytes with an appropriate `Content-Type`. Proxied to envd `/fs/read`.\n"
      operationId: downloadFileFromSandbox
      parameters:
        - $ref: "#/components/parameters/SandboxId"
        - description: URL-encoded absolute path inside the VM
          in: path
          name: path
          required: true
          schema:
            example: workspace/output.json
            type: string
      responses:
        "200":
          content:
            application/json:
              schema:
                type: object
            application/octet-stream:
              schema:
                format: binary
                type: string
          description: File contents
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"
        "409":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
          description: Sandbox is not in `running` state
      summary: Download file
      tags:
        - Sandboxes
  /sandboxes/{id}/fork:
    post:
      description: Create a new sandbox from a copy-on-write snapshot of a running sandbox.
      operationId: forkSandbox
      parameters:
        - $ref: "#/components/parameters/SandboxId"
        - in: header
          name: Idempotency-Key
          required: false
          schema:
            maxLength: 255
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ForkSandboxRequest"
        required: false
      responses:
        "201":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Sandbox"
          description: Forked sandbox created
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"
        "409":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
          description: Source sandbox is not running.
      summary: Fork a running sandbox
      tags:
        - Sandboxes
  /sandboxes/{id}/logs:
    get:
      description: Return the last N lines from the sandbox VM log stream.
      operationId: getSandboxLogs
      parameters:
        - $ref: "#/components/parameters/SandboxId"
        - in: query
          name: lines
          required: false
          schema:
            default: 200
            type: integer
      responses:
        "200":
          content:
            application/json:
              schema:
                additionalProperties: true
                type: object
          description: Sandbox logs
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"
        "502":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
          description: Log source unavailable
      summary: Get sandbox logs
      tags:
        - Sandboxes
  /sandboxes/{id}/logs/stream:
    get:
      description: Server-Sent Events stream for live sandbox logs.
      operationId: streamSandboxLogs
      parameters:
        - $ref: "#/components/parameters/SandboxId"
        - in: query
          name: ticket
          required: false
          schema:
            type: string
      responses:
        "200":
          content:
            text/event-stream:
              schema:
                type: string
          description: Sandbox log stream
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"
      summary: Stream sandbox logs
      tags:
        - Sandboxes
  /sandboxes/{id}/metrics:
    get:
      operationId: getSandboxesIdMetrics
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Metrics — Show Sandbox
      tags:
        - Metrics
  /sandboxes/{id}/move:
    post:
      operationId: postSandboxesIdMove
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "201":
          description: Created
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Sandboxes — Move
      tags:
        - Sandboxes
  /sandboxes/{id}/pause:
    post:
      description: "Suspend guest vCPU execution for a running persistent sandbox while preserving its workspace. Command and file operations automatically resume a paused persistent sandbox before dispatch.\n"
      operationId: pauseSandbox
      parameters:
        - $ref: "#/components/parameters/SandboxId"
      responses:
        "200":
          content:
            application/json:
              schema:
                properties:
                  id:
                    format: uuid
                    type: string
                  state:
                    enum:
                      - paused
                    type: string
                type: object
          description: Sandbox paused
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"
        "409":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
          description: Sandbox is not running
      summary: Pause sandbox
      tags:
        - Sandboxes
  /sandboxes/{id}/ports:
    get:
      operationId: getSandboxesIdPorts
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: SandboxPorts — Index
      tags:
        - SandboxPorts
  /sandboxes/{id}/preview-token:
    post:
      operationId: postSandboxesIdPreviewToken
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "201":
          description: Created
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: PreviewTokens — Create
      tags:
        - PreviewTokens
  /sandboxes/{id}/previews:
    get:
      description: List first-class preview URLs for this sandbox.
      operationId: listSandboxPreviews
      parameters:
        - $ref: "#/components/parameters/SandboxId"
      responses:
        "200":
          content:
            application/json:
              schema:
                properties:
                  data:
                    items:
                      $ref: "#/components/schemas/SandboxPreview"
                    type: array
                type: object
          description: Preview list
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"
      summary: List sandbox previews
      tags:
        - Sandboxes
    post:
      description: "Create a preview URL for a process listening inside the sandbox. Use this for the right-side live iframe in generated-app builders.\n"
      operationId: createSandboxPreview
      parameters:
        - $ref: "#/components/parameters/SandboxId"
      requestBody:
        content:
          application/json:
            example:
              name: dev-server
              port: 5173
              visibility: private
            schema:
              properties:
                metadata:
                  additionalProperties: true
                  type: object
                name:
                  type: string
                port:
                  maximum: 65535
                  minimum: 1
                  type: integer
                ttl_seconds:
                  nullable: true
                  type: integer
                visibility:
                  default: private
                  enum:
                    - private
                    - public
                  type: string
              required:
                - port
              type: object
        required: true
      responses:
        "201":
          content:
            application/json:
              schema:
                properties:
                  data:
                    $ref: "#/components/schemas/SandboxPreview"
                  url:
                    format: uri
                    type: string
                type: object
          description: Preview created
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"
        "409":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
          description: Sandbox is not running.
      summary: Create sandbox preview
      tags:
        - Sandboxes
  /sandboxes/{id}/previews/{preview_id}:
    delete:
      operationId: deleteSandboxPreview
      parameters:
        - $ref: "#/components/parameters/SandboxId"
        - in: path
          name: preview_id
          required: true
          schema:
            format: uuid
            type: string
      responses:
        "200":
          content:
            application/json:
              schema:
                properties:
                  data:
                    $ref: "#/components/schemas/SandboxPreview"
                type: object
          description: Deleted preview record
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"
      summary: Delete sandbox preview
      tags:
        - Sandboxes
    get:
      operationId: getSandboxPreview
      parameters:
        - $ref: "#/components/parameters/SandboxId"
        - in: path
          name: preview_id
          required: true
          schema:
            format: uuid
            type: string
      responses:
        "200":
          content:
            application/json:
              schema:
                properties:
                  data:
                    $ref: "#/components/schemas/SandboxPreview"
                type: object
          description: Preview
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"
      summary: Get sandbox preview
      tags:
        - Sandboxes
  /sandboxes/{id}/previews/{preview_id}/share:
    delete:
      operationId: revokeSandboxPreviewShare
      parameters:
        - $ref: "#/components/parameters/SandboxId"
        - in: path
          name: preview_id
          required: true
          schema:
            format: uuid
            type: string
      responses:
        "200":
          content:
            application/json:
              schema:
                properties:
                  data:
                    $ref: "#/components/schemas/SandboxPreview"
                type: object
          description: Updated preview
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"
      summary: Revoke public sharing for a sandbox preview
      tags:
        - Sandboxes
    post:
      operationId: shareSandboxPreview
      parameters:
        - $ref: "#/components/parameters/SandboxId"
        - in: path
          name: preview_id
          required: true
          schema:
            format: uuid
            type: string
      requestBody:
        content:
          application/json:
            schema:
              properties:
                ttl_seconds:
                  nullable: true
                  type: integer
              type: object
        required: false
      responses:
        "201":
          content:
            application/json:
              schema:
                properties:
                  data:
                    $ref: "#/components/schemas/SandboxPreview"
                  preview_token:
                    description: Short-lived token required to open the public share URL.
                    type: string
                  share_url:
                    description: Preview URL with the share token attached.
                    format: uri
                    type: string
                type: object
          description: Preview share token created
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"
      summary: Make sandbox preview shareable
      tags:
        - Sandboxes
  /sandboxes/{id}/previews/{preview_id}/status:
    get:
      operationId: getSandboxesIdPreviewsPreviewIdStatus
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
        - in: path
          name: preview_id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Sandboxes — Preview Status
      tags:
        - Sandboxes
  /sandboxes/{id}/processes:
    get:
      operationId: getSandboxesIdProcesses
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: SandboxProcesses — Index
      tags:
        - SandboxProcesses
    post:
      operationId: postSandboxesIdProcesses
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "201":
          description: Created
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: SandboxProcesses — Create
      tags:
        - SandboxProcesses
  /sandboxes/{id}/processes/{pid}:
    delete:
      operationId: deleteSandboxesIdProcessesPid
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
        - in: path
          name: pid
          required: true
          schema:
            type: string
      responses:
        "204":
          description: Deleted
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: SandboxProcesses — Delete
      tags:
        - SandboxProcesses
    get:
      operationId: getSandboxesIdProcessesPid
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
        - in: path
          name: pid
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: SandboxProcesses — Show
      tags:
        - SandboxProcesses
  /sandboxes/{id}/processes/{pid}/logs:
    get:
      operationId: getSandboxesIdProcessesPidLogs
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
        - in: path
          name: pid
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: SandboxProcesses — Logs
      tags:
        - SandboxProcesses
  /sandboxes/{id}/publish:
    post:
      operationId: postSandboxesIdPublish
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "201":
          description: Created
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Sandboxes — Publish
      tags:
        - Sandboxes
  /sandboxes/{id}/readiness:
    get:
      description: Return the readiness state used by agents before exec/file/terminal operations.
      operationId: getSandboxReadiness
      parameters:
        - $ref: "#/components/parameters/SandboxId"
      responses:
        "200":
          content:
            application/json:
              schema:
                properties:
                  id:
                    format: uuid
                    type: string
                  readiness_probe:
                    additionalProperties: true
                    nullable: true
                    type: object
                  ready:
                    type: boolean
                  ready_at:
                    format: date-time
                    nullable: true
                    type: string
                  state:
                    type: string
                type: object
          description: Sandbox readiness
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"
      summary: Get sandbox readiness
      tags:
        - Sandboxes
  /sandboxes/{id}/restore/{snap_id}:
    post:
      description: Restore a ready checkpoint into a new sandbox record.
      operationId: restoreSandboxSnapshot
      parameters:
        - $ref: "#/components/parameters/SandboxId"
        - in: path
          name: snap_id
          required: true
          schema:
            format: uuid
            type: string
      requestBody:
        content:
          application/json:
            schema:
              properties:
                template_id:
                  nullable: true
                  type: string
                timeout_sec:
                  nullable: true
                  type: integer
              type: object
        required: false
      responses:
        "201":
          content:
            application/json:
              schema:
                properties:
                  data:
                    $ref: "#/components/schemas/Sandbox"
                  snapshot:
                    additionalProperties: true
                    type: object
                type: object
          description: Restored sandbox
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
        "409":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
          description: Snapshot is not ready
        "422":
          $ref: "#/components/responses/UnprocessableEntity"
      summary: Restore sandbox from snapshot
      tags:
        - Sandboxes
  /sandboxes/{id}/resume:
    post:
      description: Resume a paused sandbox and transition it back to running.
      operationId: resumeSandbox
      parameters:
        - $ref: "#/components/parameters/SandboxId"
        - in: header
          name: Idempotency-Key
          required: false
          schema:
            maxLength: 255
            type: string
      responses:
        "200":
          content:
            application/json:
              schema:
                properties:
                  id:
                    format: uuid
                    type: string
                  state:
                    enum:
                      - running
                    type: string
                type: object
          description: Sandbox resumed
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"
        "409":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
          description: Sandbox is not paused
      summary: Resume sandbox
      tags:
        - Sandboxes
  /sandboxes/{id}/services:
    get:
      operationId: getSandboxesIdServices
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: SandboxServices — Index
      tags:
        - SandboxServices
    post:
      operationId: postSandboxesIdServices
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "201":
          description: Created
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: SandboxServices — Create
      tags:
        - SandboxServices
  /sandboxes/{id}/services/{name}:
    get:
      operationId: getSandboxesIdServicesName
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
        - in: path
          name: name
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: SandboxServices — Show
      tags:
        - SandboxServices
  /sandboxes/{id}/services/{name}/logs:
    get:
      operationId: getSandboxesIdServicesNameLogs
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
        - in: path
          name: name
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: SandboxServices — Logs
      tags:
        - SandboxServices
  /sandboxes/{id}/services/{name}/restart:
    post:
      operationId: postSandboxesIdServicesNameRestart
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
        - in: path
          name: name
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "201":
          description: Created
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: SandboxServices — Restart
      tags:
        - SandboxServices
  /sandboxes/{id}/shares:
    get:
      operationId: getSandboxesIdShares
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: SandboxShares — Index
      tags:
        - SandboxShares
    post:
      operationId: postSandboxesIdShares
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "201":
          description: Created
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: SandboxShares — Create
      tags:
        - SandboxShares
  /sandboxes/{id}/shares/{share_id}:
    delete:
      operationId: deleteSandboxesIdSharesShareId
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
        - in: path
          name: share_id
          required: true
          schema:
            type: string
      responses:
        "204":
          description: Deleted
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: SandboxShares — Delete
      tags:
        - SandboxShares
  /sandboxes/{id}/snapshot:
    post:
      description: Compatibility endpoint that creates a sandbox checkpoint and returns its ID.
      operationId: createSandboxSnapshotCompat
      parameters:
        - $ref: "#/components/parameters/SandboxId"
      requestBody:
        content:
          application/json:
            schema:
              additionalProperties: true
              type: object
        required: false
      responses:
        "200":
          content:
            application/json:
              schema:
                additionalProperties: true
                type: object
          description: Snapshot created
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"
        "409":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
          description: Sandbox is not in `running` state
      summary: Create sandbox snapshot (compat)
      tags:
        - Sandboxes
  /sandboxes/{id}/snapshots:
    get:
      description: List Firecracker checkpoints for a sandbox, most recent first.
      operationId: listSandboxSnapshots
      parameters:
        - $ref: "#/components/parameters/SandboxId"
      responses:
        "200":
          content:
            application/json:
              schema:
                properties:
                  data:
                    items:
                      additionalProperties: true
                      type: object
                    type: array
                type: object
          description: Snapshot list
        "401":
          $ref: "#/components/responses/Unauthorized"
        "422":
          $ref: "#/components/responses/UnprocessableEntity"
      summary: List sandbox snapshots
      tags:
        - Sandboxes
    post:
      description: "Create a Firecracker checkpoint for a running sandbox. The snapshot job\nis asynchronous; poll the returned snapshot or listen to sandbox events.\n"
      operationId: createSandboxSnapshot
      parameters:
        - $ref: "#/components/parameters/SandboxId"
      requestBody:
        content:
          application/json:
            schema:
              properties:
                comment:
                  maxLength: 500
                  type: string
              type: object
        required: false
      responses:
        "201":
          content:
            application/json:
              schema:
                properties:
                  data:
                    additionalProperties: true
                    type: object
                type: object
          description: Snapshot record created
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"
        "422":
          $ref: "#/components/responses/UnprocessableEntity"
      summary: Create sandbox snapshot
      tags:
        - Sandboxes
  /sandboxes/{id}/snapshots/{snap_id}:
    delete:
      operationId: deleteSandboxSnapshot
      parameters:
        - $ref: "#/components/parameters/SandboxId"
        - in: path
          name: snap_id
          required: true
          schema:
            format: uuid
            type: string
      responses:
        "200":
          content:
            application/json:
              schema:
                properties:
                  data:
                    additionalProperties: true
                    type: object
                type: object
          description: Deleted snapshot
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
        "409":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
          description: Snapshot already deleted
      summary: Delete sandbox snapshot
      tags:
        - Sandboxes
    get:
      operationId: getSandboxSnapshot
      parameters:
        - $ref: "#/components/parameters/SandboxId"
        - in: path
          name: snap_id
          required: true
          schema:
            format: uuid
            type: string
      responses:
        "200":
          content:
            application/json:
              schema:
                properties:
                  data:
                    additionalProperties: true
                    type: object
                type: object
          description: Snapshot
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
      summary: Get sandbox snapshot
      tags:
        - Sandboxes
  /sandboxes/{id}/ssh-info:
    get:
      operationId: getSandboxesIdSshInfo
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Sandboxes — Ssh Info
      tags:
        - Sandboxes
  /sandboxes/{id}/ssh-keys:
    post:
      operationId: postSandboxesIdSshKeys
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "201":
          description: Created
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Sandboxes — Add Ssh Key
      tags:
        - Sandboxes
  /sandboxes/{id}/ssh-tunnel:
    get:
      operationId: getSandboxesIdSshTunnel
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Sandboxes — Ssh Tunnel Upgrade Hint
      tags:
        - Sandboxes
  /sandboxes/{id}/stop:
    post:
      operationId: postSandboxesIdStop
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "201":
          description: Created
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Sandboxes — Stop
      tags:
        - Sandboxes
  /sandboxes/{id}/tags:
    patch:
      description: Merge tags into a sandbox and return the updated sandbox.
      operationId: setSandboxTags
      parameters:
        - $ref: "#/components/parameters/SandboxId"
      requestBody:
        content:
          application/json:
            schema:
              properties:
                tags:
                  additionalProperties:
                    type: string
                  type: object
              required:
                - tags
              type: object
        required: true
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Sandbox"
          description: Updated sandbox
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"
        "422":
          $ref: "#/components/responses/UnprocessableEntity"
      summary: Set sandbox tags
      tags:
        - Sandboxes
  /sandboxes/{id}/template/start:
    post:
      description: "Run the selected template lifecycle inside a running sandbox. This is\nthe app-preview workflow for generated projects: create a sandbox,\nwrite files into `/workspace`, then start the template. MIOSA runs the\ninstall command synchronously, launches the start command in the\nbackground, stores PID/log paths, and returns preview/artifact metadata.\n"
      operationId: startSandboxTemplate
      parameters:
        - $ref: "#/components/parameters/SandboxId"
      requestBody:
        content:
          application/json:
            example:
              install: true
            schema:
              properties:
                install:
                  default: true
                  description: Run the template install command before starting.
                  type: boolean
                install_command:
                  description: Override the template install command.
                  type: string
                port:
                  description: Override the template preview port.
                  maximum: 65535
                  minimum: 1
                  type: integer
                start_command:
                  description: Override the template start command.
                  type: string
                workdir:
                  description: Override the template working directory.
                  type: string
              type: object
        required: false
      responses:
        "200":
          content:
            application/json:
              example:
                data:
                  artifact_paths:
                    - /workspace
                  logs_path: /workspace/.miosa/template.log
                  pid_path: /workspace/.miosa/template.pid
                  preview_port: 3000
                  preview_url: https://3fa85f64.sandbox.miosa.app
                  status: started
                  template_id: nextjs
                  workdir: /workspace
              schema:
                additionalProperties: true
                type: object
          description: Template lifecycle started
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"
        "409":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
          description: Sandbox is not in `running` state
        "422":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
          description: Template command failed or request is invalid
      summary: Start sandbox template
      tags:
        - Sandboxes
  /sandboxes/{id}/terminal:
    post:
      description: Create an interactive PTY session and return a short-lived WebSocket URL.
      operationId: createSandboxTerminal
      parameters:
        - $ref: "#/components/parameters/SandboxId"
      requestBody:
        content:
          application/json:
            schema:
              properties:
                cols:
                  default: 80
                  type: integer
                rows:
                  default: 24
                  type: integer
              type: object
        required: false
      responses:
        "201":
          content:
            application/json:
              schema:
                properties:
                  expires_at:
                    type: integer
                  session_id:
                    type: string
                  stream_auth:
                    type: string
                  stream_auth_expires_at:
                    type: integer
                  ws_url:
                    format: uri
                    type: string
                type: object
          description: Terminal session
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"
        "409":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
          description: Sandbox is not running
        "502":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
          description: In-VM agent unavailable
      summary: Create sandbox terminal session
      tags:
        - Sandboxes
  /sandboxes/{id}/terminal/stream:
    get:
      description: "WebSocket endpoint for bidirectional PTY streaming. A plain HTTP request\nreturns `426 Upgrade Required`; browsers should connect with the\n`session_id`, `cols`, `rows`, and short-lived `token` returned by\n`POST /sandboxes/{id}/terminal`.\n"
      operationId: streamSandboxTerminal
      parameters:
        - $ref: "#/components/parameters/SandboxId"
        - in: query
          name: session_id
          required: true
          schema:
            type: string
        - in: query
          name: token
          required: true
          schema:
            type: string
        - in: query
          name: cols
          required: false
          schema:
            default: 80
            type: integer
        - in: query
          name: rows
          required: false
          schema:
            default: 24
            type: integer
      responses:
        "101":
          description: WebSocket upgrade
        "426":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
          description: Upgrade required for plain HTTP requests
          headers:
            Upgrade:
              schema:
                example: websocket
                type: string
      summary: Stream sandbox terminal WebSocket
      tags:
        - Sandboxes
  /sandboxes/{id}/terminal/{session_id}:
    delete:
      operationId: deleteSandboxTerminal
      parameters:
        - $ref: "#/components/parameters/SandboxId"
        - in: path
          name: session_id
          required: true
          schema:
            type: string
      responses:
        "200":
          content:
            application/json:
              schema:
                properties:
                  ok:
                    type: boolean
                type: object
          description: Terminal session closed
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"
      summary: Close sandbox terminal session
      tags:
        - Sandboxes
  /sandboxes/{id}/usage:
    get:
      description: Return measured runtime usage, provisioned vCPU time, cost estimate, and timeout visibility.
      operationId: getSandboxUsage
      parameters:
        - $ref: "#/components/parameters/SandboxId"
      responses:
        "200":
          content:
            application/json:
              schema:
                additionalProperties: false
                properties:
                  data:
                    $ref: "#/components/schemas/SandboxUsage"
                required:
                  - data
                type: object
          description: Sandbox usage
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"
        "422":
          $ref: "#/components/responses/UnprocessableEntity"
      summary: Get sandbox usage
      tags:
        - Sandboxes
  /sandboxes/{sandbox_id}/fs:
    delete:
      operationId: deleteSandboxesSandboxIdFs
      parameters:
        - in: path
          name: sandbox_id
          required: true
          schema:
            type: string
      responses:
        "204":
          description: Deleted
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: SandboxFiles — Delete
      tags:
        - SandboxFiles
    get:
      operationId: getSandboxesSandboxIdFs
      parameters:
        - in: path
          name: sandbox_id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: SandboxFiles — List
      tags:
        - SandboxFiles
  /sandboxes/{sandbox_id}/fs/chmod:
    post:
      operationId: postSandboxesSandboxIdFsChmod
      parameters:
        - in: path
          name: sandbox_id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "201":
          description: Created
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: SandboxFiles — Chmod
      tags:
        - SandboxFiles
  /sandboxes/{sandbox_id}/fs/copy:
    post:
      operationId: postSandboxesSandboxIdFsCopy
      parameters:
        - in: path
          name: sandbox_id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "201":
          description: Created
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: SandboxFiles — Copy File
      tags:
        - SandboxFiles
  /sandboxes/{sandbox_id}/fs/download:
    get:
      operationId: getSandboxesSandboxIdFsDownload
      parameters:
        - in: path
          name: sandbox_id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: SandboxFiles — Download
      tags:
        - SandboxFiles
  /sandboxes/{sandbox_id}/fs/mkdir:
    post:
      operationId: postSandboxesSandboxIdFsMkdir
      parameters:
        - in: path
          name: sandbox_id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "201":
          description: Created
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: SandboxFiles — Mkdir
      tags:
        - SandboxFiles
  /sandboxes/{sandbox_id}/fs/read:
    get:
      operationId: getSandboxesSandboxIdFsRead
      parameters:
        - in: path
          name: sandbox_id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: SandboxFiles — Read
      tags:
        - SandboxFiles
  /sandboxes/{sandbox_id}/fs/rename:
    post:
      operationId: postSandboxesSandboxIdFsRename
      parameters:
        - in: path
          name: sandbox_id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "201":
          description: Created
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: SandboxFiles — Rename
      tags:
        - SandboxFiles
  /sandboxes/{sandbox_id}/fs/stat:
    post:
      operationId: postSandboxesSandboxIdFsStat
      parameters:
        - in: path
          name: sandbox_id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "201":
          description: Created
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: SandboxFiles — Stat
      tags:
        - SandboxFiles
  /sandboxes/{sandbox_id}/fs/upload:
    post:
      operationId: postSandboxesSandboxIdFsUpload
      parameters:
        - in: path
          name: sandbox_id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "201":
          description: Created
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: SandboxFiles — Upload
      tags:
        - SandboxFiles
  /sandboxes/{sandbox_id}/fs/write:
    post:
      operationId: postSandboxesSandboxIdFsWrite
      parameters:
        - in: path
          name: sandbox_id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "201":
          description: Created
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: SandboxFiles — Write
      tags:
        - SandboxFiles
  /sandboxes/{sandbox_id}/fs/write-batch:
    post:
      operationId: postSandboxesSandboxIdFsWriteBatch
      parameters:
        - in: path
          name: sandbox_id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "201":
          description: Created
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: SandboxFiles — Write Many
      tags:
        - SandboxFiles
  /sandboxes/{sandbox_id}/fs/write-many:
    post:
      operationId: postSandboxesSandboxIdFsWriteMany
      parameters:
        - in: path
          name: sandbox_id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "201":
          description: Created
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: SandboxFiles — Write Many
      tags:
        - SandboxFiles
  /selector:
    get:
      operationId: getSelector
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Compat — Selector
      tags:
        - Compat
  /settings:
    get:
      operationId: getSettings
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Settings — Show
      tags:
        - Settings
    put:
      operationId: putSettings
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Settings — Update
      tags:
        - Settings
  /settings/available-models:
    get:
      operationId: getSettingsAvailableModels
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Settings — Available Models
      tags:
        - Settings
  /settings/branding:
    get:
      operationId: getSettingsBranding
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Settings — Show Branding
      tags:
        - Settings
    put:
      operationId: putSettingsBranding
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Settings — Update Branding
      tags:
        - Settings
  /settings/branding/assets/{kind}:
    post:
      operationId: postSettingsBrandingAssetsKind
      parameters:
        - in: path
          name: kind
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "201":
          description: Created
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: BrandingAssets — Upload
      tags:
        - BrandingAssets
  /settings/compute-pricing:
    get:
      operationId: getSettingsComputePricing
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Settings — Compute Pricing
      tags:
        - Settings
  /settings/gpu-pricing:
    get:
      operationId: getSettingsGpuPricing
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Settings — Gpu Pricing
      tags:
        - Settings
  /settings/provider-keys:
    get:
      operationId: getSettingsProviderKeys
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: ProviderKeys — Index
      tags:
        - ProviderKeys
  /settings/provider-keys/{provider}:
    delete:
      operationId: deleteSettingsProviderKeysProvider
      parameters:
        - in: path
          name: provider
          required: true
          schema:
            type: string
      responses:
        "204":
          description: Deleted
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: ProviderKeys — Delete
      tags:
        - ProviderKeys
    put:
      operationId: putSettingsProviderKeysProvider
      parameters:
        - in: path
          name: provider
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: ProviderKeys — Upsert
      tags:
        - ProviderKeys
  /settings/regions:
    get:
      operationId: getSettingsRegions
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Settings — Regions
      tags:
        - Settings
  /shared/{token}:
    get:
      operationId: getSharedToken
      parameters:
        - in: path
          name: token
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: PublicShares — Show
      tags:
        - PublicShares
  /shared/{token}/accept:
    post:
      operationId: postSharedTokenAccept
      parameters:
        - in: path
          name: token
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "201":
          description: Created
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: PublicShares — Accept
      tags:
        - PublicShares
  /sse/ticket:
    post:
      operationId: postSseTicket
      responses:
        "200":
          description: Success
        "201":
          description: Created
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: SSE — Issue Public Ticket
      tags:
        - SSE
  /status/incidents:
    get:
      operationId: getStatusIncidents
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Status — Incidents
      tags:
        - Status
  /status/incidents/{id}:
    get:
      operationId: getStatusIncidentsId
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Status — Incident
      tags:
        - Status
  /status/overview:
    get:
      operationId: getStatusOverview
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Status — Overview
      tags:
        - Status
  /status/subscribe:
    post:
      operationId: postStatusSubscribe
      responses:
        "200":
          description: Success
        "201":
          description: Created
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Status — Subscribe
      tags:
        - Status
  /status/subscribe/unsubscribe:
    get:
      operationId: getStatusSubscribeUnsubscribe
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Status — Unsubscribe
      tags:
        - Status
  /status/subscribe/verify:
    get:
      operationId: getStatusSubscribeVerify
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Status — Verify Subscription
      tags:
        - Status
  /status/uptime:
    get:
      operationId: getStatusUptime
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Status — Uptime
      tags:
        - Status
  /storage/buckets:
    get:
      operationId: listStorageBuckets
      responses:
        "200":
          content:
            application/json:
              schema:
                properties:
                  data:
                    items:
                      $ref: "#/components/schemas/StorageBucket"
                    type: array
                type: object
          description: Bucket list
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: List storage buckets
      tags:
        - Storage
    post:
      operationId: createStorageBucket
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CreateStorageBucketRequest"
        required: true
      responses:
        "201":
          content:
            application/json:
              schema:
                properties:
                  data:
                    $ref: "#/components/schemas/StorageBucket"
                type: object
          description: Bucket created
        "401":
          $ref: "#/components/responses/Unauthorized"
        "422":
          $ref: "#/components/responses/ValidationError"
      summary: Create storage bucket
      tags:
        - Storage
  /storage/buckets/{id}:
    delete:
      operationId: deleteStorageBucket
      parameters:
        - in: path
          name: id
          required: true
          schema:
            format: uuid
            type: string
      responses:
        "200":
          content:
            application/json:
              schema:
                properties:
                  ok:
                    type: boolean
                type: object
          description: Bucket deleted
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"
      summary: Delete storage bucket
      tags:
        - Storage
    get:
      operationId: getStorageBucket
      parameters:
        - in: path
          name: id
          required: true
          schema:
            format: uuid
            type: string
      responses:
        "200":
          content:
            application/json:
              schema:
                properties:
                  data:
                    $ref: "#/components/schemas/StorageBucket"
                type: object
          description: Bucket
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"
      summary: Get storage bucket
      tags:
        - Storage
  /storage/buckets/{id}/objects:
    get:
      operationId: listStorageObjects
      parameters:
        - in: path
          name: id
          required: true
          schema:
            format: uuid
            type: string
        - in: query
          name: prefix
          schema:
            type: string
        - in: query
          name: marker
          schema:
            type: string
        - in: query
          name: max_keys
          schema:
            maximum: 1000
            minimum: 1
            type: integer
      responses:
        "200":
          content:
            application/json:
              schema:
                properties:
                  data:
                    $ref: "#/components/schemas/StorageObjectList"
                type: object
          description: Object list
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"
      summary: List storage objects
      tags:
        - Storage
  /storage/buckets/{id}/objects/{key}:
    delete:
      operationId: deleteStorageObject
      parameters:
        - in: path
          name: id
          required: true
          schema:
            format: uuid
            type: string
        - in: path
          name: key
          required: true
          schema:
            type: string
      responses:
        "200":
          content:
            application/json:
              schema:
                properties:
                  ok:
                    type: boolean
                type: object
          description: Object deleted
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"
      summary: Delete storage object
      tags:
        - Storage
    get:
      operationId: getStorageObject
      parameters:
        - in: path
          name: id
          required: true
          schema:
            format: uuid
            type: string
        - in: path
          name: key
          required: true
          schema:
            type: string
      responses:
        "200":
          content:
            application/octet-stream:
              schema:
                format: binary
                type: string
          description: Object bytes
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"
      summary: Download storage object
      tags:
        - Storage
    put:
      operationId: putStorageObject
      parameters:
        - in: path
          name: id
          required: true
          schema:
            format: uuid
            type: string
        - in: path
          name: key
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/octet-stream:
            schema:
              format: binary
              type: string
        required: true
      responses:
        "200":
          content:
            application/json:
              schema:
                properties:
                  key:
                    type: string
                  ok:
                    type: boolean
                  size:
                    type: integer
                type: object
          description: Object uploaded
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"
        "413":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
          description: Bucket quota exceeded
      summary: Upload storage object
      tags:
        - Storage
  /storage/buckets/{id}/presign:
    post:
      operationId: presignStorageObject
      parameters:
        - in: path
          name: id
          required: true
          schema:
            format: uuid
            type: string
      requestBody:
        content:
          application/json:
            schema:
              properties:
                expires_in:
                  maximum: 604800
                  minimum: 1
                  type: integer
                key:
                  type: string
                method:
                  default: GET
                  enum:
                    - GET
                    - PUT
                  type: string
              required:
                - key
              type: object
        required: true
      responses:
        "200":
          content:
            application/json:
              schema:
                properties:
                  expires_in:
                    type: integer
                  method:
                    type: string
                  url:
                    format: uri
                    type: string
                type: object
          description: Signed URL
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"
      summary: Create pre-signed object URL
      tags:
        - Storage
  /templates:
    get:
      description: "Return the SDK and CLI catalog of product templates, readiness states, sizes, and exact versioned resource contracts. This route is public and does not expose artifact locations or provider placement data.\n"
      operationId: listTemplates
      responses:
        "200":
          content:
            application/json:
              schema:
                properties:
                  data:
                    items:
                      $ref: "#/components/schemas/PublicTemplate"
                    type: array
                  products:
                    items:
                      additionalProperties: true
                      type: object
                    type: array
                  readiness_states:
                    items:
                      enum:
                        - fast_ready
                        - cold_boot_only
                        - missing
                      type: string
                    type: array
                  rules:
                    additionalProperties:
                      type: boolean
                    type: object
                  shape_contracts:
                    properties:
                      computer:
                        items:
                          $ref: "#/components/schemas/CatalogResourceContract"
                        type: array
                      sandbox:
                        items:
                          $ref: "#/components/schemas/CatalogResourceContract"
                        type: array
                    required:
                      - sandbox
                      - computer
                    type: object
                  sizes:
                    items:
                      additionalProperties: true
                      type: object
                    type: array
                  templates:
                    items:
                      $ref: "#/components/schemas/PublicTemplate"
                    type: array
                required:
                  - data
                  - templates
                  - products
                  - sizes
                  - shape_contracts
                  - readiness_states
                  - rules
                type: object
          description: Public template catalog
      summary: List bootable templates and resource contracts
      tags:
        - Sandboxes
  /tenant-settings/onboarding:
    patch:
      operationId: patchTenantSettingsOnboarding
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: TenantOnboarding — Update
      tags:
        - TenantOnboarding
  /tenant/branding:
    delete:
      operationId: deleteTenantBranding
      responses:
        "204":
          description: Deleted
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Tenant — Delete Branding
      tags:
        - Tenant
    get:
      operationId: getTenantBranding
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Tenant — Get Branding
      tags:
        - Tenant
    put:
      operationId: putTenantBranding
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Tenant — Set Branding
      tags:
        - Tenant
  /tenant/events/stream:
    get:
      operationId: getTenantEventsStream
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: TenantEventsStream — Stream
      tags:
        - TenantEventsStream
  /tenant/members:
    get:
      operationId: getTenantMembers
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: TenantMembers — Index
      tags:
        - TenantMembers
    post:
      operationId: postTenantMembers
      responses:
        "200":
          description: Success
        "201":
          description: Created
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: TenantMembers — Create
      tags:
        - TenantMembers
  /tenant/members/{member_id}:
    delete:
      operationId: deleteTenantMembersMemberId
      parameters:
        - in: path
          name: member_id
          required: true
          schema:
            type: string
      responses:
        "204":
          description: Deleted
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: TenantMembers — Delete
      tags:
        - TenantMembers
  /tenant/members/{member_id}/role:
    patch:
      operationId: patchTenantMembersMemberIdRole
      parameters:
        - in: path
          name: member_id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: TenantMembers — Update Role
      tags:
        - TenantMembers
  /tenant/plan:
    get:
      operationId: getTenantPlan
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Tenant — Plan And Usage
      tags:
        - Tenant
  /tenant/policy:
    delete:
      operationId: deleteTenantPolicy
      responses:
        "204":
          description: Deleted
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: TenantPolicy — Delete
      tags:
        - TenantPolicy
    get:
      operationId: getTenantPolicy
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: TenantPolicy — Show
      tags:
        - TenantPolicy
    put:
      operationId: putTenantPolicy
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: TenantPolicy — Upsert
      tags:
        - TenantPolicy
  /tenant/preview-domain:
    delete:
      operationId: deleteTenantPreviewDomain
      responses:
        "204":
          description: Deleted
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Tenant — Delete Preview Domain
      tags:
        - Tenant
    get:
      operationId: getTenantPreviewDomain
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Tenant — Get Preview Domain
      tags:
        - Tenant
    put:
      operationId: putTenantPreviewDomain
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Tenant — Set Preview Domain
      tags:
        - Tenant
  /tenant/preview-domain/verify:
    post:
      operationId: postTenantPreviewDomainVerify
      responses:
        "200":
          description: Success
        "201":
          description: Created
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Tenant — Verify Preview Domain
      tags:
        - Tenant
  /tenant/transfer-ownership:
    post:
      operationId: postTenantTransferOwnership
      responses:
        "200":
          description: Success
        "201":
          description: Created
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: TenantMembers — Transfer Ownership
      tags:
        - TenantMembers
  /tenants:
    get:
      operationId: getTenants
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Tenant — Index
      tags:
        - Tenant
    post:
      operationId: postTenants
      responses:
        "200":
          description: Success
        "201":
          description: Created
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Tenant — Create
      tags:
        - Tenant
  /tenants/invite/accept:
    post:
      operationId: postTenantsInviteAccept
      responses:
        "200":
          description: Success
        "201":
          description: Created
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Tenant — Accept Invite
      tags:
        - Tenant
  /tenants/{id}:
    delete:
      operationId: deleteTenantsId
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        "204":
          description: Deleted
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Tenant — Delete
      tags:
        - Tenant
    get:
      operationId: getTenantsId
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Tenant — Show
      tags:
        - Tenant
    patch:
      operationId: patchTenantsId
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Tenant — Update
      tags:
        - Tenant
    put:
      operationId: putTenantsId
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Tenant — Update
      tags:
        - Tenant
  /tenants/{tenant_id}/invite:
    post:
      operationId: postTenantsTenantIdInvite
      parameters:
        - in: path
          name: tenant_id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "201":
          description: Created
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Tenant — Invite
      tags:
        - Tenant
  /tenants/{tenant_id}/invites:
    get:
      operationId: getTenantsTenantIdInvites
      parameters:
        - in: path
          name: tenant_id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Tenant — List Invites
      tags:
        - Tenant
    post:
      operationId: postTenantsTenantIdInvites
      parameters:
        - in: path
          name: tenant_id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "201":
          description: Created
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Tenant — Create Invite
      tags:
        - Tenant
  /tenants/{tenant_id}/invites/{invite_id}:
    delete:
      operationId: deleteTenantsTenantIdInvitesInviteId
      parameters:
        - in: path
          name: tenant_id
          required: true
          schema:
            type: string
        - in: path
          name: invite_id
          required: true
          schema:
            type: string
      responses:
        "204":
          description: Deleted
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Tenant — Revoke Invite
      tags:
        - Tenant
  /tenants/{tenant_id}/members:
    get:
      operationId: getTenantsTenantIdMembers
      parameters:
        - in: path
          name: tenant_id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Tenant — List Members
      tags:
        - Tenant
    post:
      operationId: postTenantsTenantIdMembers
      parameters:
        - in: path
          name: tenant_id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "201":
          description: Created
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Tenant — Add Member
      tags:
        - Tenant
  /tenants/{tenant_id}/members/{user_id}:
    delete:
      operationId: deleteTenantsTenantIdMembersUserId
      parameters:
        - in: path
          name: tenant_id
          required: true
          schema:
            type: string
        - in: path
          name: user_id
          required: true
          schema:
            type: string
      responses:
        "204":
          description: Deleted
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Tenant — Remove Member
      tags:
        - Tenant
  /tenants/{tenant_id}/sandbox-spend:
    get:
      operationId: getSandboxSpendSettings
      responses:
        "200":
          content:
            application/json:
              schema:
                properties:
                  data:
                    $ref: "#/components/schemas/SandboxSpendSummary"
                required:
                  - data
                type: object
          description: Current spend configuration and durable current-period accounting.
        "400":
          description: Invalid tenant UUID.
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
      security:
        - BearerAuth: []
      summary: Get hosted sandbox spend settings and current-period usage
      tags:
        - Sandboxes
    parameters:
      - description: Tenant UUID. The authenticated user must be an owner or admin of this tenant.
        in: path
        name: tenant_id
        required: true
        schema:
          format: uuid
          type: string
    patch:
      description: "Updates settings under the same tenant lock used by admission and settlement. Lowered caps enqueue durable enforcement for running hosted sandboxes and do not affect sandboxes whose immutable placement is in a customer BYOC pool.\n"
      operationId: updateSandboxSpendSettings
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/UpdateSandboxSpendSettingsRequest"
        required: true
      responses:
        "200":
          content:
            application/json:
              schema:
                properties:
                  data:
                    $ref: "#/components/schemas/SandboxSpendSummary"
                required:
                  - data
                type: object
          description: Updated settings and current-period accounting.
        "400":
          description: Invalid tenant UUID.
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "422":
          description: Empty, ambiguous, or invalid spend settings update.
      security:
        - BearerAuth: []
      summary: Update hosted sandbox spend cap and alert thresholds
      tags:
        - Sandboxes
  /tokens/scoped:
    post:
      operationId: postTokensScoped
      responses:
        "200":
          description: Success
        "201":
          description: Created
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: ScopedTokens — Create
      tags:
        - ScopedTokens
  /usage:
    get:
      operationId: getUsage
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: UsageRollup — Index
      tags:
        - UsageRollup
  /usage/sessions:
    get:
      operationId: getUsageSessions
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Usage — Sessions
      tags:
        - Usage
  /usage/summary:
    get:
      operationId: getUsageSummary
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Usage — Summary
      tags:
        - Usage
  /volumes:
    get:
      description: Returns every volume owned by the caller's tenant.
      operationId: listVolumes
      responses:
        "200":
          content:
            application/json:
              schema:
                properties:
                  data:
                    items:
                      $ref: "#/components/schemas/Volume"
                    type: array
                type: object
          description: Volume list
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: List persistent volumes
      tags:
        - Volumes
    post:
      description: "Volumes are decoupled from any single computer; attach them to one or more sandboxes via `POST /computers/{id}/volumes`. `backend: \"s3\"` stores data in an S3-compatible bucket, `backend: \"local\"` bind-mounts a host path (single-host only).\n"
      operationId: createVolume
      requestBody:
        content:
          application/json:
            schema:
              properties:
                backend:
                  enum:
                    - s3
                    - local
                  type: string
                config:
                  description: Backend-specific connection info
                  type: object
                metadata:
                  additionalProperties: true
                  type: object
                name:
                  description: Lowercase alphanumeric + `-` and `_`, 1-120 chars
                  type: string
                size_bytes:
                  minimum: 1
                  type: integer
              required:
                - name
                - size_bytes
                - backend
                - config
              type: object
        required: true
      responses:
        "201":
          content:
            application/json:
              schema:
                properties:
                  data:
                    $ref: "#/components/schemas/Volume"
                type: object
          description: Volume created
        "401":
          $ref: "#/components/responses/Unauthorized"
        "422":
          $ref: "#/components/responses/ValidationError"
      summary: Create a persistent volume
      tags:
        - Volumes
  /volumes/{id}:
    delete:
      description: "Detaches active attachments and flips the volume to `status: \"deleting\"`. The backing storage (S3 bucket contents, host directory) is NOT erased — that's an ops responsibility.\n"
      operationId: deleteVolume
      responses:
        "200":
          content:
            application/json:
              schema:
                properties:
                  data:
                    $ref: "#/components/schemas/Volume"
                type: object
          description: Volume deletion initiated
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
      summary: Mark a volume as deleting
      tags:
        - Volumes
    get:
      operationId: getVolume
      responses:
        "200":
          content:
            application/json:
              schema:
                properties:
                  data:
                    $ref: "#/components/schemas/Volume"
                type: object
          description: Volume
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
      summary: Get a volume by id
      tags:
        - Volumes
    parameters:
      - in: path
        name: id
        required: true
        schema:
          format: uuid
          type: string
  /webhooks:
    get:
      operationId: getWebhooks
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: TenantWebhooks — Index
      tags:
        - TenantWebhooks
    post:
      operationId: postWebhooks
      responses:
        "200":
          description: Success
        "201":
          description: Created
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: TenantWebhooks — Create
      tags:
        - TenantWebhooks
  /webhooks/events:
    get:
      operationId: getWebhooksEvents
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: TenantWebhooks — Events
      tags:
        - TenantWebhooks
  /webhooks/fanbasis:
    post:
      operationId: postWebhooksFanbasis
      responses:
        "200":
          description: Success
        "201":
          description: Created
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: FanbasisWebhook — Handle
      tags:
        - FanbasisWebhook
  /webhooks/inbound-email:
    post:
      operationId: postWebhooksInboundEmail
      responses:
        "200":
          description: Success
        "201":
          description: Created
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: InboundEmailWebhook — Handle
      tags:
        - InboundEmailWebhook
  /webhooks/stripe:
    post:
      operationId: postWebhooksStripe
      responses:
        "200":
          description: Success
        "201":
          description: Created
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: StripeWebhook — Webhook
      tags:
        - StripeWebhook
  /webhooks/{id}:
    delete:
      operationId: deleteWebhooksId
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        "204":
          description: Deleted
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: TenantWebhooks — Delete
      tags:
        - TenantWebhooks
    get:
      operationId: getWebhooksId
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: TenantWebhooks — Show
      tags:
        - TenantWebhooks
    patch:
      operationId: patchWebhooksId
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: TenantWebhooks — Update
      tags:
        - TenantWebhooks
  /webhooks/{id}/deliveries:
    get:
      operationId: getWebhooksIdDeliveries
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: TenantWebhooks — Deliveries
      tags:
        - TenantWebhooks
  /webhooks/{id}/test:
    post:
      operationId: postWebhooksIdTest
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "201":
          description: Created
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: TenantWebhooks — Test
      tags:
        - TenantWebhooks
  /workspace-invites/{token}:
    get:
      description: "Returns a public preview of the invite — workspace name, org name, role, and expiry — without requiring authentication. Revoked invites return `404`. Use this to render the invite landing page before prompting the user to log in or sign up.\n"
      operationId: previewWorkspaceInvite
      responses:
        "200":
          content:
            application/json:
              schema:
                properties:
                  data:
                    $ref: "#/components/schemas/WorkspaceInvitePreview"
                required:
                  - data
                type: object
          description: Invite preview
        "404":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
          description: Invite not found or has been revoked.
      security: []
      summary: Preview a workspace invite (public)
      tags:
        - Workspace Invites
    parameters:
      - description: Opaque 32-byte URL-safe base64 invite token (43 chars).
        in: path
        name: token
        required: true
        schema:
          example: Aq3Bx9kTmZpLvRwYeUoNsC8fHdJiGqVtXb0yEuPa6c
          type: string
  /workspace-invites/{token}/accept:
    parameters:
      - description: Opaque 32-byte URL-safe base64 invite token (43 chars).
        in: path
        name: token
        required: true
        schema:
          type: string
    post:
      description: "Claims a workspace invite on behalf of the authenticated user. The caller's JWT email must match the invite email (case-insensitive). On success, both a `tenant_members` and a `workspace_members` row are created atomically when the user is not yet a tenant member.\nError codes: - `INVALID_TOKEN` (404) — token not found. - `EXPIRED` (410) — invite has passed its 7-day TTL. - `REVOKED` (409) — invite was revoked by an admin. - `ALREADY_ACCEPTED` (409) — invite was already used. - `EMAIL_MISMATCH` (422) — JWT email does not match invite email.\n"
      operationId: acceptWorkspaceInvite
      responses:
        "200":
          content:
            application/json:
              schema:
                properties:
                  accepted:
                    example: true
                    type: boolean
                  role:
                    enum:
                      - owner
                      - admin
                      - member
                      - viewer
                    type: string
                  tenant_id:
                    format: uuid
                    type: string
                  workspace_id:
                    format: uuid
                    type: string
                required:
                  - accepted
                  - workspace_id
                  - tenant_id
                  - role
                type: object
          description: Invite accepted.
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
          description: Token not found (`INVALID_TOKEN`).
        "409":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
          description: Conflict — invite revoked or already accepted.
        "410":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
          description: Invite expired (`EXPIRED`).
        "422":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
          description: Email mismatch (`EMAIL_MISMATCH`).
      security:
        - BearerAuth: []
      summary: Accept a workspace invite
      tags:
        - Workspace Invites
  /workspaces:
    get:
      description: Returns all workspaces belonging to the authenticated tenant.
      operationId: listWorkspaces
      parameters:
        - $ref: "#/components/parameters/LimitParam"
        - $ref: "#/components/parameters/CursorParam"
      responses:
        "200":
          content:
            application/json:
              example:
                cursor: null
                total: 1
                workspaces:
                  - computer_count: 3
                    created_at: 2026-04-11T14:30:00Z
                    id: 1b2c3d4e-5f6a-7890-abcd-ef1234567890
                    name: Production Environment
                    slug: production-environment
                    updated_at: 2026-04-11T15:00:00Z
              schema:
                $ref: "#/components/schemas/WorkspaceListResponse"
          description: Paginated list of workspaces
        "401":
          $ref: "#/components/responses/Unauthorized"
        "429":
          $ref: "#/components/responses/RateLimited"
      summary: List workspaces
      tags:
        - Workspaces
    post:
      description: Creates a new workspace for grouping computers.
      operationId: createWorkspace
      requestBody:
        content:
          application/json:
            example:
              description: Hosts all production compute
              name: Production Environment
            schema:
              $ref: "#/components/schemas/WorkspaceCreateRequest"
        required: true
      responses:
        "201":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Workspace"
          description: Workspace created
        "401":
          $ref: "#/components/responses/Unauthorized"
        "409":
          content:
            application/json:
              example:
                error:
                  code: CONFLICT
                  message: A workspace named "Production Environment" already exists
                  type: https://docs.miosa.ai/errors/conflict
              schema:
                $ref: "#/components/schemas/ErrorResponse"
          description: A workspace with this name already exists
        "422":
          $ref: "#/components/responses/ValidationError"
        "429":
          $ref: "#/components/responses/RateLimited"
      summary: Create a workspace
      tags:
        - Workspaces
  /workspaces/{id}:
    delete:
      description: "Permanently deletes a workspace. Computers inside the workspace are moved to the tenant's default workspace rather than deleted.\n"
      operationId: deleteWorkspace
      responses:
        "200":
          content:
            application/json:
              schema:
                properties:
                  deleted:
                    example: true
                    type: boolean
                  id:
                    format: uuid
                    type: string
                required:
                  - id
                  - deleted
                type: object
          description: Workspace deleted
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
      summary: Delete a workspace
      tags:
        - Workspaces
    get:
      description: Returns a single workspace by ID.
      operationId: getWorkspace
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Workspace"
          description: Workspace object
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
      summary: Get a workspace
      tags:
        - Workspaces
    parameters:
      - $ref: "#/components/parameters/WorkspaceId"
    patch:
      description: Update the name, description, or metadata of a workspace.
      operationId: updateWorkspace
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/WorkspaceUpdateRequest"
        required: true
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Workspace"
          description: Updated workspace
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
        "422":
          $ref: "#/components/responses/ValidationError"
      summary: Update a workspace
      tags:
        - Workspaces
  /workspaces/{id}/activity:
    get:
      operationId: getWorkspacesIdActivity
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Workspaces — Activity
      tags:
        - Workspaces
  /workspaces/{id}/cleanup:
    post:
      operationId: postWorkspacesIdCleanup
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "201":
          description: Created
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Workspaces — Cleanup
      tags:
        - Workspaces
  /workspaces/{id}/computer-templates:
    get:
      operationId: getWorkspacesIdComputerTemplates
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Workspaces — List Computer Templates
      tags:
        - Workspaces
    post:
      operationId: postWorkspacesIdComputerTemplates
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "201":
          description: Created
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Workspaces — Create Computer Template
      tags:
        - Workspaces
  /workspaces/{id}/computer-templates/{tid}:
    delete:
      operationId: deleteWorkspacesIdComputerTemplatesTid
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
        - in: path
          name: tid
          required: true
          schema:
            type: string
      responses:
        "204":
          description: Deleted
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Workspaces — Delete Computer Template
      tags:
        - Workspaces
  /workspaces/{id}/computers:
    get:
      description: Returns all computers belonging to the given workspace.
      operationId: listWorkspaceComputers
      parameters:
        - $ref: "#/components/parameters/LimitParam"
        - $ref: "#/components/parameters/CursorParam"
      responses:
        "200":
          content:
            application/json:
              schema:
                properties:
                  computers:
                    items:
                      $ref: "#/components/schemas/Computer"
                    type: array
                  cursor:
                    type:
                      - string
                      - "null"
                  total:
                    example: 3
                    type: integer
                required:
                  - computers
                  - total
                type: object
          description: Paginated list of computers in the workspace
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
        "429":
          $ref: "#/components/responses/RateLimited"
      summary: List computers in a workspace
      tags:
        - Workspaces
    parameters:
      - $ref: "#/components/parameters/WorkspaceId"
  /workspaces/{id}/databases:
    get:
      operationId: getWorkspacesIdDatabases
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Workspaces — List Databases
      tags:
        - Workspaces
  /workspaces/{id}/deployments:
    get:
      operationId: getWorkspacesIdDeployments
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Workspaces — List Deployments
      tags:
        - Workspaces
  /workspaces/{id}/inventory:
    get:
      operationId: getWorkspacesIdInventory
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Workspaces — Inventory
      tags:
        - Workspaces
  /workspaces/{id}/invites:
    get:
      description: "Returns all pending (non-expired, non-accepted, non-revoked) invites for the workspace.\n"
      operationId: listWorkspaceInvites
      responses:
        "200":
          content:
            application/json:
              schema:
                properties:
                  data:
                    items:
                      $ref: "#/components/schemas/WorkspaceInvite"
                    type: array
                  total:
                    type: integer
                required:
                  - data
                  - total
                type: object
          description: Pending invite list
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
          description: Workspace not found.
      security:
        - BearerAuth: []
      summary: List pending workspace invites
      tags:
        - Workspace Invites
    parameters:
      - $ref: "#/components/parameters/WorkspaceId"
    post:
      description: "Sends an email invite to `email`. If the address already belongs to a tenant member, the user is added directly (returns `200` + `type: \"added\"`). Otherwise an invite row is created (returns `201` + `type: \"invited\"`). On acceptance, both a `tenant_members` and a `workspace_members` row are created atomically if the user is not yet in the org.\n"
      operationId: createWorkspaceInvite
      requestBody:
        content:
          application/json:
            example:
              email: alice@example.com
              role: member
            schema:
              properties:
                email:
                  description: Email address to invite.
                  format: email
                  type: string
                role:
                  default: member
                  description: Role to grant on acceptance.
                  enum:
                    - owner
                    - admin
                    - member
                    - viewer
                  type: string
              required:
                - email
              type: object
        required: true
      responses:
        "200":
          content:
            application/json:
              schema:
                properties:
                  data:
                    $ref: "#/components/schemas/WorkspaceMemberRecord"
                  type:
                    enum:
                      - added
                    type: string
                required:
                  - data
                  - type
                type: object
          description: User was already a tenant member and has been added directly.
        "201":
          content:
            application/json:
              schema:
                properties:
                  data:
                    $ref: "#/components/schemas/WorkspaceInvite"
                  type:
                    enum:
                      - invited
                    type: string
                required:
                  - data
                  - type
                type: object
          description: Invite created and email dispatched.
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
          description: Workspace not found.
        "422":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
          description: "Validation error. `error.code` = `MISSING_EMAIL` when the `email` field is absent or blank; `VALIDATION_FAILED` for other changeset errors.\n"
      security:
        - BearerAuth: []
      summary: Create a workspace invite
      tags:
        - Workspace Invites
  /workspaces/{id}/invites/{invite_id}:
    delete:
      description: "Revokes a pending invite by setting `accepted_at` to an epoch sentinel. Already-revoked invites return `200` (idempotent). An invite that has been legitimately accepted returns `409 ALREADY_ACCEPTED`.\n"
      operationId: revokeWorkspaceInvite
      responses:
        "200":
          content:
            application/json:
              schema:
                properties:
                  invite_id:
                    format: uuid
                    type: string
                  revoked:
                    example: true
                    type: boolean
                required:
                  - invite_id
                  - revoked
                type: object
          description: Invite revoked (or was already revoked — idempotent).
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
          description: Invite not found in this workspace.
        "409":
          content:
            application/json:
              example:
                error:
                  code: ALREADY_ACCEPTED
                  message: invite has already been accepted
              schema:
                $ref: "#/components/schemas/ErrorResponse"
          description: Invite was already accepted and cannot be revoked.
      security:
        - BearerAuth: []
      summary: Revoke a workspace invite
      tags:
        - Workspace Invites
    parameters:
      - $ref: "#/components/parameters/WorkspaceId"
      - description: UUID of the workspace invite to revoke.
        in: path
        name: invite_id
        required: true
        schema:
          format: uuid
          type: string
  /workspaces/{id}/members:
    get:
      description: "Returns all members of the given workspace. Requires the caller to be authenticated and a member of the parent tenant. The workspace must belong to the caller's tenant.\n"
      operationId: listWorkspaceMembers
      responses:
        "200":
          content:
            application/json:
              schema:
                properties:
                  data:
                    items:
                      $ref: "#/components/schemas/WorkspaceMember"
                    type: array
                required:
                  - data
                type: object
          description: Workspace member list
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
      security:
        - BearerAuth: []
      summary: List workspace members
      tags:
        - Workspace Members
    parameters:
      - $ref: "#/components/parameters/WorkspaceId"
    post:
      description: "Adds an existing tenant user to the workspace. The `user_id` must already be a member of the parent tenant (`tenant_members`). To invite someone who is not yet a tenant member use `POST /workspaces/{id}/invites`.\n"
      operationId: addWorkspaceMember
      requestBody:
        content:
          application/json:
            example:
              role: member
              user_id: 3fa85f64-5717-4562-b3fc-2c963f66afa6
            schema:
              properties:
                role:
                  default: member
                  description: Role to assign in this workspace.
                  enum:
                    - owner
                    - admin
                    - member
                    - viewer
                  type: string
                user_id:
                  description: UUID of the tenant user to add.
                  format: uuid
                  type: string
              required:
                - user_id
              type: object
        required: true
      responses:
        "201":
          content:
            application/json:
              schema:
                properties:
                  data:
                    $ref: "#/components/schemas/WorkspaceMemberRecord"
                required:
                  - data
                type: object
          description: Member added
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
          description: Workspace not found
        "422":
          content:
            application/json:
              examples:
                notTenantMember:
                  summary: User not in org
                  value:
                    error:
                      code: NOT_TENANT_MEMBER
                      message: user is not a member of this tenant — invite them to the org first
              schema:
                $ref: "#/components/schemas/ErrorResponse"
          description: "Validation error. Possible `error.code` values: `MISSING_USER_ID` — `user_id` body field absent. `NOT_TENANT_MEMBER` — the user is not yet an org member; invite them first. `VALIDATION_FAILED` — changeset error (e.g. duplicate member).\n"
      security:
        - BearerAuth: []
      summary: Add a member to a workspace
      tags:
        - Workspace Members
  /workspaces/{id}/members/{user_id}:
    delete:
      description: "Removes a user from the workspace. The last `owner` cannot be removed; promote another member to `owner` first using `PATCH /workspaces/{id}/members/{user_id}`.\n"
      operationId: removeWorkspaceMember
      responses:
        "200":
          content:
            application/json:
              schema:
                properties:
                  deleted:
                    example: true
                    type: boolean
                required:
                  - deleted
                type: object
          description: Member removed
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
          description: Member not found
        "409":
          content:
            application/json:
              example:
                error:
                  code: LAST_OWNER
                  message: cannot remove the last owner of a workspace — promote another member first
              schema:
                $ref: "#/components/schemas/ErrorResponse"
          description: "Conflict. `error.code` = `LAST_OWNER` — cannot remove the last owner of a workspace.\n"
      security:
        - BearerAuth: []
      summary: Remove a workspace member
      tags:
        - Workspace Members
    parameters:
      - $ref: "#/components/parameters/WorkspaceId"
      - description: UUID of the workspace member to update or remove.
        in: path
        name: user_id
        required: true
        schema:
          format: uuid
          type: string
    patch:
      description: "Updates the role of an existing workspace member. Valid roles are `owner`, `admin`, `member`, and `viewer`.\n"
      operationId: updateWorkspaceMemberRole
      requestBody:
        content:
          application/json:
            example:
              role: admin
            schema:
              properties:
                role:
                  enum:
                    - owner
                    - admin
                    - member
                    - viewer
                  type: string
              required:
                - role
              type: object
        required: true
      responses:
        "200":
          content:
            application/json:
              schema:
                properties:
                  data:
                    $ref: "#/components/schemas/WorkspaceMemberRecord"
                required:
                  - data
                type: object
          description: Role updated
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
          description: Member not found
        "422":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
          description: "Validation error. Possible `error.code` values: `MISSING_ROLE` — `role` body field absent. `VALIDATION_FAILED` — role value not in allowed enum.\n"
      security:
        - BearerAuth: []
      summary: Change a workspace member's role
      tags:
        - Workspace Members
  /workspaces/{id}/policy:
    delete:
      operationId: deleteWorkspacesIdPolicy
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        "204":
          description: Deleted
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: WorkspacePolicy — Delete
      tags:
        - WorkspacePolicy
    get:
      operationId: getWorkspacesIdPolicy
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: WorkspacePolicy — Show
      tags:
        - WorkspacePolicy
    put:
      operationId: putWorkspacesIdPolicy
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: WorkspacePolicy — Upsert
      tags:
        - WorkspacePolicy
  /workspaces/{id}/projects:
    get:
      operationId: getWorkspacesIdProjects
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Workspaces — List Projects
      tags:
        - Workspaces
  /workspaces/{id}/sandboxes:
    get:
      operationId: getWorkspacesIdSandboxes
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Workspaces — List Sandboxes
      tags:
        - Workspaces
  /workspaces/{id}/settings:
    put:
      operationId: putWorkspacesIdSettings
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Workspaces — Update Settings
      tags:
        - Workspaces
  /workspaces/{id}/stats:
    get:
      operationId: getWorkspacesIdStats
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Workspaces — Stats
      tags:
        - Workspaces
  /workspaces/{id}/transfer:
    post:
      operationId: postWorkspacesIdTransfer
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "201":
          description: Created
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Workspaces — Transfer
      tags:
        - Workspaces
  /workspaces/{id}/usage:
    get:
      operationId: getWorkspacesIdUsage
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: Workspaces — Usage
      tags:
        - Workspaces
security:
  - BearerAuth: []
servers:
  - description: Production
    url: https://api.miosa.ai/api/v1
tags:
  - description: "MIOSA Deploy — publish sandbox or source output into an immutable deployment version, then serve it from static artifact storage or from production runtime instances behind managed/custom domains. Preview routes point to live sandboxes; production routes point to active deployment versions.\n"
    name: Deployments
  - description: "Ephemeral AI-agent development environments backed by isolated Firecracker microVMs. Sandboxes are editable, expose preview URLs for running dev servers, and are billed by active resource usage. Production deployments are created by publishing sandbox/source output into immutable versions.\n"
    name: Sandboxes
  - description: "Canonical instruction-in, result-out execution contract for command, Claude Code, Codex, and custom runners targeting sandboxes or computers. Runs expose status, messages, command output, files, previews, activity, diagnostics, cancellation, and authenticated file downloads.\n"
    name: Runs
  - description: Create and manage cloud computers
    name: Computers
  - description: "Interact with the graphical desktop inside a running computer. All desktop actions require the computer to be in `running` status.\n"
    name: Desktop
  - description: Execute shell commands and Python code inside computers
    name: Exec
  - description: "Interactive pseudo-terminal (PTY) sessions inside computers. Sessions are created over HTTP and streamed bidirectionally over an authenticated WebSocket returned in the create response.\n"
    name: Terminal
  - description: Upload, download, list, and delete files inside computers
    name: Files
  - description: "Computer Use Agent sessions — autonomous AI agents that operate the desktop on your behalf. Sessions stream progress via Server-Sent Events.\n"
    name: Agent (CUA)
  - description: In-VM OSA agent — submit tasks and query status
    name: OSA
  - description: Per-computer configuration (auto-stop, VNC credentials)
    name: Config
  - description: Credit balance, transactions, and usage
    name: Credits
  - description: Create and revoke developer API keys
    name: API Keys
  - description: Tenant-scoped model routing, fallback policy, budgets, limits, and health
    name: Intelligence Gateway
  - description: Evaluation policy configuration and durable evaluation execution lifecycle
    name: Intelligence Evaluations
  - description: Agent-to-model routing assignments
    name: Intelligence Assignments
  - description: Integration-facing provider credential replacement and safe metadata
    name: Intelligence Provider Credentials
  - description: "MIOSA-managed database lifecycle. Databases are durable services with encrypted credentials, tenant scoping, and optional links to sandboxes or deployments so generated apps can receive `DATABASE_URL`.\n"
    name: Databases
  - description: "Generated-app authentication for sandboxes and deployments. This is separate from MIOSA platform/API authentication and is scoped to a resource's linked managed database.\n"
    name: Project Auth
  - description: "Tenant-scoped object storage buckets, objects, and pre-signed URLs backed by S3-compatible storage.\n"
    name: Storage
  - description: "Operational control surface under `/api/v1/admin/*`. Requires an admin or platform credential — either `msk_a_*` / `msk_p_*` API key or an admin JWT. All endpoints return `403 Forbidden` for non-admin callers.\n"
    name: Admin
  - description: User lifecycle, suspension, bans, roles, tags, login attempts.
    name: Admin / Users
  - description: Tenant listing, suspension, plan changes, provider config.
    name: Admin / Tenants
  - description: Grant, deduct, refund, and inspect credit balances for any tenant.
    name: Admin / Credits
  - description: Operational visibility and lifecycle control across all tenants.
    name: Admin / Computers
  - description: List, inspect, bulk-revoke, and rotate API keys across the platform.
    name: Admin / API Keys
  - description: Inspect and switch the AI/LLM model backing Optimal.
    name: Admin / Optimal
  - description: Manage the platform team (super-admin only).
    name: Admin / Team
  - description: Install + list Firecracker rootfs templates (OCI-distributed).
    name: Admin / Templates
  - description: "Persistent shared storage that can be attached to one or more computers simultaneously. Matches Daytona's shared-volume shape.\n"
    name: Volumes
  - description: "Model Context Protocol endpoint. Streamable-HTTP transport; clients like Claude Code, Cursor, Gemini CLI, and Copilot can point at this URL with a `msk_*` Bearer token.\n"
    name: MCP
  - description: "Logical groups that organize computers and shared resources. A workspace maps to a project, environment, or team namespace.\n"
    name: Workspaces
  - description: "Per-workspace user roster. A workspace member must already be an org (tenant) member. The last owner of a workspace cannot be removed without first promoting another member to owner.\n"
    name: Workspace Members
  - description: "Email invite flow for workspace access. Sending an invite to an email that already belongs to a tenant member short-circuits to directly adding that user to the workspace. Accepting a workspace invite for an unknown email auto-creates a tenant_members row in the same transaction.\n"
    name: Workspace Invites
  - description: "Email invite flow for org (tenant) membership. Invites are scoped to a tenant and carry a role. The accept endpoint is public-accessible by token but requires a valid JWT so the platform knows which user is claiming the invite. Email-match is enforced case-insensitively.\n"
    name: Org Invites
  - description: "Point-in-time disk snapshots of a running or stopped computer. Snapshots can be used to restore a computer or fork a new one.\n"
    name: Snapshots
  - description: "Long-running processes (daemons) managed inside a computer. Services can be started, stopped, and restarted independently of the computer lifecycle.\n"
    name: Services
  - description: "Attach and verify custom hostnames that route to a computer's exposed port. Verification uses DNS TXT record or HTTP file challenge.\n"
    name: CustomDomains
  - description: "Per-computer firewall rules that control inbound and outbound traffic. Rules are evaluated top-to-bottom; an explicit deny-all default applies when a policy is active.\n"
    name: NetworkPolicy
  - description: "WebSocket endpoints for real-time bidirectional communication. All WebSocket endpoints require an HTTP Upgrade and accept a short-lived auth token as the `auth` query parameter.\n"
    name: Streaming
webhooks:
  cuaSessionEvent:
    post:
      description: "Documents the JSON payload emitted on each Server-Sent Event from a CUA session stream (`GET /computers/{id}/cua/sessions/{session_id}/events`). This webhook entry exists solely to anchor the CuaEvent schema for SDK generation and documentation tools.\n"
      operationId: cuaSessionEventWebhook
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CuaEvent"
        required: true
      responses:
        "200":
          description: Event received
      summary: CUA session event (SSE payload schema)