dashcaddy/dashcaddy-api/openapi.yaml

openapi: 3.0.3
info:
  title: DashCaddy API
  version: 1.15.0
  description: >
    Unified management API for Docker, Caddy, DNS, and Tailscale services.
    Covers container lifecycle, reverse proxy configuration, DNS record
    management, health monitoring, automated backups, app deployment from
    templates, Arr stack integration, TOTP/SSO authentication, multi-user
    administration, security event collection, and license-gated features.
  contact:
    name: DashCaddy Support
servers:
  - url: http://localhost:3001
    description: Local development server

tags:
  - name: API Keys
    description: Programmatic API key management and JWT exchange
  - name: Arr Stack Integration
    description: Radarr, Sonarr, Prowlarr, Overseerr integration
  - name: Assets & Branding
    description: Custom logos, favicons, and brand assets
  - name: Audit Log
    description: System audit trail
  - name: Authentication
    description: Login flows, CSRF tokens, and auth provider management
  - name: Auto-Restart
    description: Automatic service restart policies
  - name: Automated Backups
    description: Scheduled backups, cloud provider credentials, and history
  - name: Backup & Restore
    description: App-level backup points and restore operations
  - name: Billing
    description: Stripe checkout sessions for license purchase
  - name: Caddy Management
    description: Caddy reverse proxy configuration and reload
  - name: Certificate Authority
    description: DashCA certificate info, download, and install scripts
  - name: Config Drift
    description: Configuration drift detection and remediation
  - name: Configuration
    description: DashCaddy site configuration and config backup/restore
  - name: Container Management
    description: Docker container lifecycle (start, stop, restart, remove)
  - name: Container Stats & Logs
    description: Container metrics, log viewing, and log digests
  - name: Credential Management
    description: Encryption key rotation and credential listing
  - name: DNS Management
    description: DNS records, provider credentials, and propagation checking
  - name: Dependencies
    description: Service dependency graphs, chains, and ordered restarts
  - name: Disk Space
    description: Disk usage monitoring, breakdown, and cleanup
  - name: Docker App Deployment
    description: Deploy apps from templates, compose stacks, and port management
  - name: Docker Resources
    description: Docker volumes, networks, and disk usage
  - name: Documentation
    description: API documentation and OpenAPI spec serving
  - name: Error Logs
    description: System error log management
  - name: Events
    description: Server-sent events stream for real-time updates
  - name: Filesystem Browser
    description: Browse directories and detect media mounts
  - name: Health & Probes
    description: Root-level liveness and readiness probes (k8s/Docker compatible)
  - name: Health Checks
    description: Automated health-check configuration and incident tracking
  - name: License Management
    description: License activation, status, and feature gating
  - name: Notifications
    description: Notification channels, test dispatch, and history
  - name: OpenClaw
    description: OpenClaw platform deployment and management
  - name: Plex
    description: Plex media server integration
  - name: Recipes
    description: Multi-service recipe templates and deployment (premium)
  - name: Resource Monitoring
    description: CPU/memory monitoring, historical data, and alerts
  - name: SSL Monitor
    description: SSL certificate expiration monitoring
  - name: SSO Auth Gate
    description: Caddy forward-auth gate, app tokens, and SSO login pages
  - name: Security Center
    description: Multi-source security event collection and host management
  - name: Service Credentials
    description: Encrypted credential storage for registered services
  - name: Service Health
    description: Service health monitoring and cached status
  - name: Services Dashboard
    description: Dashboard service registration and status
  - name: Sharing
    description: Dashboard share links and Tailscale-mediated sharing
  - name: Site Management
    description: Manage proxied sites, domains, and external references
  - name: System
    description: System information, version, and metrics
  - name: TOTP Authentication
    description: Two-factor authentication setup, verification, and management
  - name: Tailscale
    description: Tailscale VPN integration, device sync, and access control
  - name: Themes
    description: Dashboard theme management
  - name: Update Management
    description: Container image updates and system self-update
  - name: User Management
    description: Multi-user administration, invites, and allowlist (opt-in)
  - name: Workflows
    description: Bundled automation workflow management

paths:

  /health:
    get:
      tags: [Health & Probes]
      summary: Liveness health check
      description: Returns process liveness status. Alias for /health/live.
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'

  /health/live:
    get:
      tags: [Health & Probes]
      summary: Liveness probe
      description: Pure process-alive check with no dependency queries. Returns uptime.
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'

  /health/ready:
    get:
      tags: [Health & Probes]
      summary: Readiness probe
      description: Checks critical dependencies (config file, services file, Docker daemon, Caddy admin). Returns 503 if any check fails.
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'

  /healthz:
    get:
      tags: [Health & Probes]
      summary: Kubernetes liveness probe
      description: Kubernetes-standard liveness alias for /health/live.
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'

  /readyz:
    get:
      tags: [Health & Probes]
      summary: Kubernetes readiness probe
      description: Kubernetes-standard readiness alias for /health/ready.
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'

  /probe/{id}:
    get:
      tags: [Health & Probes]
      summary: Service probe
      description: Lightweight HTTP probe of a service by ID. Probes the service URL directly, with Pylon relay and domain fallback.
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
          description: Service ID or 'internet'
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'

  /api/v1/version:
    get:
      tags: [System]
      summary: Get API version
      description: Returns the running API version, Node.js version, platform, and uptime.
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        '401':
          description: Unauthorized - authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /api/v1/csrf-token:
    get:
      tags: [Authentication]
      summary: Get CSRF token
      description: Returns a CSRF token and the header name to use for it.
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        '401':
          description: Unauthorized - authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /api/v1/metrics:
    get:
      tags: [System]
      summary: Get metrics summary
      description: Returns aggregated metrics summary from the metrics collector.
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        '401':
          description: Unauthorized - authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /api/v1/docs:
    get:
      tags: [Documentation]
      summary: API documentation UI
      description: Serves the Swagger UI HTML page for interactive API exploration.
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        '401':
          description: Unauthorized - authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /api/v1/docs/spec:
    get:
      tags: [Documentation]
      summary: OpenAPI specification
      description: Serves the raw openapi.yaml specification file.
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        '401':
          description: Unauthorized - authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /api/v1/network/ips:
    get:
      tags: [System]
      summary: Get network IPs
      description: Returns localhost, LAN, Tailscale, and all detected interface IPs.
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        '401':
          description: Unauthorized - authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /api/v1/totp/check-session:
    get:
      tags: [TOTP Authentication]
      summary: Check TOTP session status
      description: Returns whether the current session has a valid TOTP session.
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        '401':
          description: Unauthorized - authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /api/v1/totp/config:
    get:
      tags: [TOTP Authentication]
      summary: Get TOTP configuration
      description: Returns the current TOTP configuration (enabled, session duration, setup status).
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        '401':
          description: Unauthorized - authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    post:
      tags: [TOTP Authentication]
      summary: Update TOTP configuration
      description: Updates TOTP settings such as session duration.
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GenericObject'
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        '401':
          description: Unauthorized - authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /api/v1/totp/recovery-info:
    get:
      tags: [TOTP Authentication]
      summary: Get TOTP recovery info
      description: Returns recovery code information for the TOTP setup.
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        '401':
          description: Unauthorized - authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /api/v1/totp/setup:
    post:
      tags: [TOTP Authentication]
      summary: Begin TOTP setup
      description: Generates a new TOTP secret and returns the QR code / OTP auth URL.
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GenericObject'
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        '401':
          description: Unauthorized - authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /api/v1/totp/verify-setup:
    post:
      tags: [TOTP Authentication]
      summary: Verify TOTP setup
      description: Confirms TOTP setup by verifying a code from the authenticator app.
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GenericObject'
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        '401':
          description: Unauthorized - authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /api/v1/totp/verify:
    post:
      tags: [TOTP Authentication]
      summary: Verify TOTP login
      description: Verifies a TOTP code to complete two-factor login and establish a session.
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GenericObject'
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        '401':
          description: Unauthorized - authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /api/v1/totp/disable:
    post:
      tags: [TOTP Authentication]
      summary: Disable TOTP
      description: Disables two-factor authentication. Requires a valid TOTP code.
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GenericObject'
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        '401':
          description: Unauthorized - authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /api/v1/auth/keys:
    get:
      tags: [API Keys]
      summary: List API keys
      description: Returns all registered API keys.
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        '401':
          description: Unauthorized - authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    post:
      tags: [API Keys]
      summary: Create API key
      description: Creates a new API key for programmatic access.
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GenericObject'
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        '401':
          description: Unauthorized - authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /api/v1/auth/keys/{keyId}:
    delete:
      tags: [API Keys]
      summary: Delete API key
      description: Revokes and removes an API key by ID.
      parameters:
        - name: keyId
          in: path
          required: true
          schema:
            type: string
          description: API key ID
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        '401':
          description: Unauthorized - authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /api/v1/auth/jwt:
    post:
      tags: [API Keys]
      summary: Exchange API key for JWT
      description: Exchanges an API key for a JWT token for session-based access.
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GenericObject'
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        '401':
          description: Unauthorized - authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /api/v1/auth/gate/{serviceId}:
    get:
      tags: [SSO Auth Gate]
      summary: SSO gate check
      description: Forward-auth endpoint for Caddy. Returns 200 if the session is authorized for the service, 401 otherwise.
      parameters:
        - name: serviceId
          in: path
          required: true
          schema:
            type: string
          description: Service ID
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        '401':
          description: Unauthorized - authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /api/v1/auth/app-token/{serviceId}:
    get:
      tags: [SSO Auth Gate]
      summary: Get app token
      description: Returns an app session token for client-side auto-login flows.
      parameters:
        - name: serviceId
          in: path
          required: true
          schema:
            type: string
          description: Service ID
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        '401':
          description: Unauthorized - authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /api/v1/auth/login-page:
    get:
      tags: [SSO Auth Gate]
      summary: Get SSO login page
      description: Returns the HTML SSO login page for a service with auto-login JS.
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        '401':
          description: Unauthorized - authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /api/v1/auth/sso-exchange:
    get:
      tags: [SSO Auth Gate]
      summary: SSO token exchange
      description: Exchanges an SSO handoff token for a session cookie.
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        '401':
          description: Unauthorized - authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /api/v1/auth/login/methods:
    get:
      tags: [Authentication]
      summary: List login methods
      description: Returns available authentication providers (email, TOTP, etc.).
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        '401':
          description: Unauthorized - authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /api/v1/auth/login/recovery-info:
    get:
      tags: [Authentication]
      summary: Login recovery info
      description: Returns account recovery information for the login flow.
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        '401':
          description: Unauthorized - authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /api/v1/auth/login/{provider}/initiate:
    post:
      tags: [Authentication]
      summary: Initiate login
      description: Initiates a login flow for the specified provider (e.g., email magic link).
      parameters:
        - name: provider
          in: path
          required: true
          schema:
            type: string
          description: Auth provider name
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GenericObject'
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        '401':
          description: Unauthorized - authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /api/v1/auth/login/{provider}/verify:
    post:
      tags: [Authentication]
      summary: Verify login
      description: Verifies a login credential (e.g., magic-link token) for the specified provider.
      parameters:
        - name: provider
          in: path
          required: true
          schema:
            type: string
          description: Auth provider name
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GenericObject'
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        '401':
          description: Unauthorized - authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /api/v1/auth/disable/{provider}:
    post:
      tags: [Authentication]
      summary: Disable auth provider
      description: Disables an authentication provider.
      parameters:
        - name: provider
          in: path
          required: true
          schema:
            type: string
          description: Auth provider name
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GenericObject'
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        '401':
          description: Unauthorized - authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /api/v1/auth/me:
    get:
      tags: [User Management]
      summary: Get current user
      description: Returns the currently authenticated user's profile information.
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        '401':
          description: Unauthorized - authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /api/v1/auth/admin/users:
    get:
      tags: [User Management]
      summary: List users
      description: Returns all registered users. Requires admin privileges.
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        '401':
          description: Unauthorized - authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    post:
      tags: [User Management]
      summary: Create user
      description: Creates a new user account. Requires admin privileges.
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GenericObject'
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        '401':
          description: Unauthorized - authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /api/v1/auth/admin/users/{id}:
    patch:
      tags: [User Management]
      summary: Update user
      description: Updates a user's properties (role, status). Requires admin.
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
          description: User ID
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GenericObject'
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        '401':
          description: Unauthorized - authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    delete:
      tags: [User Management]
      summary: Delete user
      description: Removes a user account. Requires admin privileges.
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
          description: User ID
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        '401':
          description: Unauthorized - authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /api/v1/auth/admin/allowlist:
    get:
      tags: [User Management]
      summary: Get allowlist
      description: Returns the email allowlist for multi-user mode.
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        '401':
          description: Unauthorized - authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /api/v1/auth/admin/invites:
    get:
      tags: [User Management]
      summary: List invites
      description: Returns all pending invite tokens.
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        '401':
          description: Unauthorized - authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    post:
      tags: [User Management]
      summary: Create invite
      description: Generates a new invite token for onboarding users.
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GenericObject'
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        '401':
          description: Unauthorized - authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /api/v1/auth/admin/invites/{id}:
    delete:
      tags: [User Management]
      summary: Delete invite
      description: Revokes an invite token by ID.
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
          description: Invite ID
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        '401':
          description: Unauthorized - authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /api/v1/auth/invites/{token}:
    get:
      tags: [User Management]
      summary: Redeem invite preview
      description: Public endpoint that validates an invite token and returns invite metadata.
      parameters:
        - name: token
          in: path
          required: true
          schema:
            type: string
          description: Invite token
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'

  /api/v1/auth/invites/{token}/accept:
    post:
      tags: [User Management]
      summary: Accept invite
      description: Public endpoint that accepts an invite and creates a user account.
      parameters:
        - name: token
          in: path
          required: true
          schema:
            type: string
          description: Invite token
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GenericObject'
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'

  /api/v1/config:
    get:
      tags: [Configuration]
      summary: Get configuration
      description: Returns the full DashCaddy site configuration.
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        '401':
          description: Unauthorized - authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    post:
      tags: [Configuration]
      summary: Update configuration
      description: Updates the DashCaddy site configuration.
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GenericObject'
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        '401':
          description: Unauthorized - authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    delete:
      tags: [Configuration]
      summary: Reset configuration
      description: Resets the configuration to defaults.
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        '401':
          description: Unauthorized - authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /api/v1/logo:
    get:
      tags: [Assets & Branding]
      summary: Get logo
      description: Returns the custom logo image.
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        '401':
          description: Unauthorized - authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    post:
      tags: [Assets & Branding]
      summary: Upload logo
      description: Uploads a custom logo image.
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GenericObject'
          multipart/form-data:
            schema:
              type: object
              properties:
                file:
                  type: string
                  format: binary
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        '401':
          description: Unauthorized - authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    delete:
      tags: [Assets & Branding]
      summary: Delete logo
      description: Removes the custom logo, reverting to default.
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        '401':
          description: Unauthorized - authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /api/v1/favicon:
    get:
      tags: [Assets & Branding]
      summary: Get favicon
      description: Returns the custom favicon image.
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        '401':
          description: Unauthorized - authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    post:
      tags: [Assets & Branding]
      summary: Upload favicon
      description: Uploads a custom favicon image.
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GenericObject'
          multipart/form-data:
            schema:
              type: object
              properties:
                file:
                  type: string
                  format: binary
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        '401':
          description: Unauthorized - authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    delete:
      tags: [Assets & Branding]
      summary: Delete favicon
      description: Removes the custom favicon.
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        '401':
          description: Unauthorized - authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /api/v1/assets/upload:
    post:
      tags: [Assets & Branding]
      summary: Upload asset
      description: Uploads a generic brand asset (logo, favicon, etc.).
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GenericObject'
          multipart/form-data:
            schema:
              type: object
              properties:
                file:
                  type: string
                  format: binary
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        '401':
          description: Unauthorized - authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /api/v1/backup/export:
    get:
      tags: [Configuration]
      summary: Export config backup
      description: Exports the full configuration as a downloadable backup file.
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        '401':
          description: Unauthorized - authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /api/v1/backup/preview:
    post:
      tags: [Configuration]
      summary: Preview config restore
      description: Previews what would change if a backup file were restored.
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GenericObject'
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        '401':
          description: Unauthorized - authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /api/v1/backup/restore:
    post:
      tags: [Configuration]
      summary: Restore config backup
      description: Restores configuration from an uploaded backup file.
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GenericObject'
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        '401':
          description: Unauthorized - authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /api/v1/containers/{id}/start:
    post:
      tags: [Container Management]
      summary: Start container
      description: Starts a Docker container by ID.
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
          description: Container ID
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GenericObject'
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        '401':
          description: Unauthorized - authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /api/v1/containers/{id}/stop:
    post:
      tags: [Container Management]
      summary: Stop container
      description: Stops a Docker container by ID.
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
          description: Container ID
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GenericObject'
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        '401':
          description: Unauthorized - authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /api/v1/containers/{id}/restart:
    post:
      tags: [Container Management]
      summary: Restart container
      description: Restarts a Docker container by ID.
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
          description: Container ID
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GenericObject'
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        '401':
          description: Unauthorized - authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /api/v1/containers/{id}/update:
    post:
      tags: [Container Management]
      summary: Update container image
      description: Pulls the latest image and recreates the container.
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
          description: Container ID
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GenericObject'
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        '401':
          description: Unauthorized - authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /api/v1/containers/{id}/logs:
    get:
      tags: [Container Management]
      summary: Get container logs
      description: Returns recent log output for a container.
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
          description: Container ID
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        '401':
          description: Unauthorized - authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /api/v1/containers/{id}/resources:
    get:
      tags: [Container Management]
      summary: Get container resources
      description: Returns resource limits (CPU, memory) for a container.
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
          description: Container ID
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        '401':
          description: Unauthorized - authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    put:
      tags: [Container Management]
      summary: Update container resources
      description: Updates resource limits for a container.
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
          description: Container ID
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GenericObject'
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        '401':
          description: Unauthorized - authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /api/v1/containers/{id}/check-update:
    get:
      tags: [Container Management]
      summary: Check for image update
      description: Checks if a newer image is available for the container.
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
          description: Container ID
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        '401':
          description: Unauthorized - authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /api/v1/containers/{id}:
    delete:
      tags: [Container Management]
      summary: Remove container
      description: Removes a Docker container by ID.
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
          description: Container ID
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        '401':
          description: Unauthorized - authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /api/v1/containers/discover:
    get:
      tags: [Container Management]
      summary: Discover containers
      description: Returns all Docker containers on the host.
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        '401':
          description: Unauthorized - authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /api/v1/services:
    get:
      tags: [Services Dashboard]
      summary: List services
      description: Returns all registered dashboard services.
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        '401':
          description: Unauthorized - authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    post:
      tags: [Services Dashboard]
      summary: Create service
      description: Adds a new service to the dashboard.
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GenericObject'
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        '401':
          description: Unauthorized - authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    put:
      tags: [Services Dashboard]
      summary: Update services
      description: Updates the full services list (bulk replace).
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GenericObject'
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        '401':
          description: Unauthorized - authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /api/v1/services/{id}:
    delete:
      tags: [Services Dashboard]
      summary: Delete service
      description: Removes a service from the dashboard.
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
          description: Service ID
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        '401':
          description: Unauthorized - authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /api/v1/services/status:
    get:
      tags: [Services Dashboard]
      summary: Get services status
      description: Returns aggregated status for all services.
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        '401':
          description: Unauthorized - authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /api/v1/services/update:
    post:
      tags: [Services Dashboard]
      summary: Trigger services update
      description: Triggers an update check/apply across services.
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GenericObject'
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        '401':
          description: Unauthorized - authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /api/v1/services/{serviceId}/credentials:
    get:
      tags: [Service Credentials]
      summary: Get service credentials
      description: Returns stored credentials for a service.
      parameters:
        - name: serviceId
          in: path
          required: true
          schema:
            type: string
          description: Service ID
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        '401':
          description: Unauthorized - authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    post:
      tags: [Service Credentials]
      summary: Set service credentials
      description: Stores encrypted credentials for a service.
      parameters:
        - name: serviceId
          in: path
          required: true
          schema:
            type: string
          description: Service ID
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GenericObject'
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        '401':
          description: Unauthorized - authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    delete:
      tags: [Service Credentials]
      summary: Delete service credentials
      description: Removes stored credentials for a service.
      parameters:
        - name: serviceId
          in: path
          required: true
          schema:
            type: string
          description: Service ID
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        '401':
          description: Unauthorized - authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /api/v1/seedhost-creds:
    get:
      tags: [Service Credentials]
      summary: Get seedhost credentials
      description: Returns stored seedhost credentials.
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        '401':
          description: Unauthorized - authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    post:
      tags: [Service Credentials]
      summary: Set seedhost credentials
      description: Stores seedhost credentials.
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GenericObject'
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        '401':
          description: Unauthorized - authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    delete:
      tags: [Service Credentials]
      summary: Delete seedhost credentials
      description: Removes stored seedhost credentials.
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        '401':
          description: Unauthorized - authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /api/v1/credentials/list:
    get:
      tags: [Credential Management]
      summary: List credentials
      description: Returns a list of stored credential keys (without values).
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        '401':
          description: Unauthorized - authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /api/v1/credentials/rotate-key:
    post:
      tags: [Credential Management]
      summary: Rotate encryption key
      description: Rotates the master encryption key used for credential storage.
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GenericObject'
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        '401':
          description: Unauthorized - authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /api/v1/caddyfile:
    get:
      tags: [Caddy Management]
      summary: Get Caddyfile
      description: Returns the current Caddyfile content.
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        '401':
          description: Unauthorized - authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /api/v1/caddy/config:
    get:
      tags: [Caddy Management]
      summary: Get Caddy config
      description: Returns the current Caddy JSON configuration from the admin API.
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        '401':
          description: Unauthorized - authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /api/v1/caddy/reload:
    post:
      tags: [Caddy Management]
      summary: Reload Caddy
      description: Triggers a Caddy configuration reload.
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GenericObject'
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        '401':
          description: Unauthorized - authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /api/v1/caddy/cas:
    get:
      tags: [Caddy Management]
      summary: List Caddy CAs
      description: Returns certificate authorities configured in Caddy.
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        '401':
          description: Unauthorized - authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /api/v1/site:
    post:
      tags: [Site Management]
      summary: Create site
      description: Creates a new proxied site with Caddy configuration.
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GenericObject'
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        '401':
          description: Unauthorized - authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /api/v1/site/{domain}:
    delete:
      tags: [Site Management]
      summary: Delete site
      description: Removes a proxied site and its Caddy configuration.
      parameters:
        - name: domain
          in: path
          required: true
          schema:
            type: string
          description: Domain name
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        '401':
          description: Unauthorized - authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /api/v1/site/external:
    post:
      tags: [Site Management]
      summary: Add external site
      description: Adds an external (non-DashCaddy-managed) site reference.
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GenericObject'
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        '401':
          description: Unauthorized - authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /api/v1/dns/providers:
    get:
      tags: [DNS Management]
      summary: List DNS providers
      description: Returns available DNS provider types.
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        '401':
          description: Unauthorized - authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /api/v1/dns/provider/status:
    get:
      tags: [DNS Management]
      summary: Get DNS provider status
      description: Returns the status of the currently configured DNS provider.
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        '401':
          description: Unauthorized - authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /api/v1/dns/universal/record:
    post:
      tags: [DNS Management]
      summary: Create universal DNS record
      description: Creates a DNS record across all configured zones/providers.
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GenericObject'
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        '401':
          description: Unauthorized - authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    delete:
      tags: [DNS Management]
      summary: Delete universal DNS record
      description: Deletes a DNS record across all configured zones/providers.
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        '401':
          description: Unauthorized - authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /api/v1/dns/universal/resolve:
    get:
      tags: [DNS Management]
      summary: Resolve universal DNS record
      description: Resolves a DNS record across all providers.
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        '401':
          description: Unauthorized - authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /api/v1/dns/record:
    post:
      tags: [DNS Management]
      summary: Create DNS record
      description: Creates a DNS record in the configured provider.
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GenericObject'
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        '401':
          description: Unauthorized - authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    delete:
      tags: [DNS Management]
      summary: Delete DNS record
      description: Deletes a DNS record in the configured provider.
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        '401':
          description: Unauthorized - authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /api/v1/dns/resolve:
    get:
      tags: [DNS Management]
      summary: Resolve DNS record
      description: Resolves a DNS record using the configured provider.
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        '401':
          description: Unauthorized - authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /api/v1/dns/logs:
    get:
      tags: [DNS Management]
      summary: Get DNS logs
      description: Returns recent DNS server logs.
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        '401':
          description: Unauthorized - authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /api/v1/dns/token-status:
    get:
      tags: [DNS Management]
      summary: Get DNS token status
      description: Returns the status of the DNS provider API token.
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        '401':
          description: Unauthorized - authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /api/v1/dns/credentials:
    post:
      tags: [DNS Management]
      summary: Set DNS credentials
      description: Stores DNS provider API credentials.
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GenericObject'
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        '401':
          description: Unauthorized - authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    delete:
      tags: [DNS Management]
      summary: Delete DNS credentials
      description: Removes stored DNS provider credentials.
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        '401':
          description: Unauthorized - authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    get:
      tags: [DNS Management]
      summary: Get DNS credentials
      description: Returns stored DNS provider credential metadata.
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        '401':
          description: Unauthorized - authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /api/v1/dns/refresh-token:
    post:
      tags: [DNS Management]
      summary: Refresh DNS token
      description: Refreshes an expired DNS provider OAuth token.
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GenericObject'
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        '401':
          description: Unauthorized - authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /api/v1/dns/restart/{dnsId}:
    post:
      tags: [DNS Management]
      summary: Restart DNS server
      description: Restarts the DNS server container/service.
      parameters:
        - name: dnsId
          in: path
          required: true
          schema:
            type: string
          description: DNS server ID
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GenericObject'
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        '401':
          description: Unauthorized - authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /api/v1/dns/check-update:
    get:
      tags: [DNS Management]
      summary: Check DNS update
      description: Checks if a DNS update is available or in progress.
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        '401':
          description: Unauthorized - authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /api/v1/dns/update:
    post:
      tags: [DNS Management]
      summary: Apply DNS update
      description: Applies a pending DNS server update.
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GenericObject'
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        '401':
          description: Unauthorized - authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /api/v1/dns/propagation:
    get:
      tags: [DNS Management]
      summary: Check DNS propagation
      description: Returns propagation status for all tracked domains.
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        '401':
          description: Unauthorized - authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /api/v1/dns/propagation/{domain}:
    get:
      tags: [DNS Management]
      summary: Check domain propagation
      description: Returns propagation status for a specific domain.
      parameters:
        - name: domain
          in: path
          required: true
          schema:
            type: string
          description: Domain name
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        '401':
          description: Unauthorized - authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /api/v1/dns/propagation/verify:
    post:
      tags: [DNS Management]
      summary: Verify DNS propagation
      description: Triggers a propagation verification check.
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GenericObject'
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        '401':
          description: Unauthorized - authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /api/v1/health/services:
    get:
      tags: [Service Health]
      summary: List service health
      description: Returns health status for all monitored services.
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        '401':
          description: Unauthorized - authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /api/v1/health/service/{id}:
    get:
      tags: [Service Health]
      summary: Get service health
      description: Returns health status for a specific service.
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
          description: Service ID
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        '401':
          description: Unauthorized - authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /api/v1/health/cached:
    get:
      tags: [Service Health]
      summary: Get cached health
      description: Returns cached health status without re-probing.
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        '401':
          description: Unauthorized - authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /api/v1/health/probe:
    get:
      tags: [Service Health]
      summary: Health probe
      description: Triggers a fresh health probe across all services.
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        '401':
          description: Unauthorized - authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /api/v1/health/pylon:
    get:
      tags: [Service Health]
      summary: Pylon health
      description: Returns health status of the Pylon relay if configured.
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        '401':
          description: Unauthorized - authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /api/v1/health/ca:
    get:
      tags: [Service Health]
      summary: CA certificate health
      description: Returns CA certificate expiration health status.
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        '401':
          description: Unauthorized - authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /api/v1/health-checks/status:
    get:
      tags: [Health Checks]
      summary: Get health-check status
      description: Returns the overall health-check system status.
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        '401':
          description: Unauthorized - authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /api/v1/health-checks/{serviceId}/stats:
    get:
      tags: [Health Checks]
      summary: Get health-check stats
      description: Returns health-check statistics for a service.
      parameters:
        - name: serviceId
          in: path
          required: true
          schema:
            type: string
          description: Service ID
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        '401':
          description: Unauthorized - authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /api/v1/health-checks/{serviceId}/configure:
    post:
      tags: [Health Checks]
      summary: Configure health checks
      description: Configures automated health checks for a service.
      parameters:
        - name: serviceId
          in: path
          required: true
          schema:
            type: string
          description: Service ID
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GenericObject'
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        '401':
          description: Unauthorized - authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    delete:
      tags: [Health Checks]
      summary: Remove health-check config
      description: Removes automated health-check configuration for a service.
      parameters:
        - name: serviceId
          in: path
          required: true
          schema:
            type: string
          description: Service ID
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        '401':
          description: Unauthorized - authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /api/v1/health-checks/incidents:
    get:
      tags: [Health Checks]
      summary: List incidents
      description: Returns recent health-check incidents.
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        '401':
          description: Unauthorized - authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /api/v1/health-checks/incidents/history:
    get:
      tags: [Health Checks]
      summary: Incident history
      description: Returns historical health-check incidents.
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        '401':
          description: Unauthorized - authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /api/v1/monitoring/stats:
    get:
      tags: [Resource Monitoring]
      summary: Get monitoring stats
      description: Returns aggregated resource monitoring statistics.
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        '401':
          description: Unauthorized - authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /api/v1/monitoring/stats/{containerId}:
    get:
      tags: [Resource Monitoring]
      summary: Get container monitoring stats
      description: Returns resource monitoring stats for a container.
      parameters:
        - name: containerId
          in: path
          required: true
          schema:
            type: string
          description: Container ID
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        '401':
          description: Unauthorized - authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /api/v1/monitoring/history/{containerId}:
    get:
      tags: [Resource Monitoring]
      summary: Get monitoring history
      description: Returns historical resource data for a container.
      parameters:
        - name: containerId
          in: path
          required: true
          schema:
            type: string
          description: Container ID
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        '401':
          description: Unauthorized - authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /api/v1/monitoring/aggregated/{containerId}:
    get:
      tags: [Resource Monitoring]
      summary: Get aggregated stats
      description: Returns aggregated resource stats for a container over time.
      parameters:
        - name: containerId
          in: path
          required: true
          schema:
            type: string
          description: Container ID
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        '401':
          description: Unauthorized - authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /api/v1/monitoring/alerts/config:
    get:
      tags: [Resource Monitoring]
      summary: Get alert config
      description: Returns the resource alert configuration.
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        '401':
          description: Unauthorized - authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    post:
      tags: [Resource Monitoring]
      summary: Update alert config
      description: Updates the resource alert configuration.
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GenericObject'
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        '401':
          description: Unauthorized - authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /api/v1/monitoring/alerts:
    get:
      tags: [Resource Monitoring]
      summary: List alerts
      description: Returns all resource monitoring alerts.
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        '401':
          description: Unauthorized - authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /api/v1/monitoring/alerts/{containerId}/test:
    post:
      tags: [Resource Monitoring]
      summary: Test alert
      description: Triggers a test alert for a container.
      parameters:
        - name: containerId
          in: path
          required: true
          schema:
            type: string
          description: Container ID
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GenericObject'
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        '401':
          description: Unauthorized - authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /api/v1/monitoring/alerts/{containerId}:
    get:
      tags: [Resource Monitoring]
      summary: Get container alerts
      description: Returns alerts for a specific container.
      parameters:
        - name: containerId
          in: path
          required: true
          schema:
            type: string
          description: Container ID
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        '401':
          description: Unauthorized - authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    post:
      tags: [Resource Monitoring]
      summary: Create container alert
      description: Creates a resource alert for a container.
      parameters:
        - name: containerId
          in: path
          required: true
          schema:
            type: string
          description: Container ID
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GenericObject'
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        '401':
          description: Unauthorized - authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    delete:
      tags: [Resource Monitoring]
      summary: Delete container alert
      description: Removes a resource alert for a container.
      parameters:
        - name: containerId
          in: path
          required: true
          schema:
            type: string
          description: Container ID
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        '401':
          description: Unauthorized - authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /api/v1/stats/containers:
    get:
      tags: [Container Stats & Logs]
      summary: List container stats
      description: Returns resource stats for all containers.
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        '401':
          description: Unauthorized - authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /api/v1/stats/container/{id}:
    get:
      tags: [Container Stats & Logs]
      summary: Get container stats
      description: Returns resource stats for a single container.
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
          description: Container ID
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        '401':
          description: Unauthorized - authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /api/v1/updates/available:
    get:
      tags: [Update Management]
      summary: Check available updates
      description: Returns a list of containers with available image updates.
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        '401':
          description: Unauthorized - authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /api/v1/updates/check:
    post:
      tags: [Update Management]
      summary: Check for updates
      description: Triggers an update check across all containers.
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GenericObject'
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        '401':
          description: Unauthorized - authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /api/v1/updates/update/{containerId}:
    post:
      tags: [Update Management]
      summary: Update container
      description: Applies an image update to a specific container.
      parameters:
        - name: containerId
          in: path
          required: true
          schema:
            type: string
          description: Container ID
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GenericObject'
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        '401':
          description: Unauthorized - authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /api/v1/updates/rollback/{containerId}:
    post:
      tags: [Update Management]
      summary: Rollback container
      description: Rolls back a container to its previous image.
      parameters:
        - name: containerId
          in: path
          required: true
          schema:
            type: string
          description: Container ID
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GenericObject'
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        '401':
          description: Unauthorized - authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /api/v1/updates/auto-update:
    get:
      tags: [Update Management]
      summary: Get auto-update config
      description: Returns the automatic update configuration.
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        '401':
          description: Unauthorized - authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /api/v1/updates/auto-update/{containerId}:
    post:
      tags: [Update Management]
      summary: Set auto-update for container
      description: Configures automatic updates for a specific container.
      parameters:
        - name: containerId
          in: path
          required: true
          schema:
            type: string
          description: Container ID
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GenericObject'
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        '401':
          description: Unauthorized - authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /api/v1/updates/schedule/{containerId}:
    post:
      tags: [Update Management]
      summary: Schedule container update
      description: Schedules an update for a specific container.
      parameters:
        - name: containerId
          in: path
          required: true
          schema:
            type: string
          description: Container ID
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GenericObject'
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        '401':
          description: Unauthorized - authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /api/v1/updates/history:
    get:
      tags: [Update Management]
      summary: Get update history
      description: Returns the history of applied container updates.
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        '401':
          description: Unauthorized - authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /api/v1/system/version:
    get:
      tags: [Update Management]
      summary: Get system version
      description: Returns the DashCaddy system version.
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        '401':
          description: Unauthorized - authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /api/v1/system/update-check:
    get:
      tags: [Update Management]
      summary: Check system update
      description: Checks if a DashCaddy system update is available.
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        '401':
          description: Unauthorized - authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /api/v1/system/update-apply:
    post:
      tags: [Update Management]
      summary: Apply system update
      description: Applies a DashCaddy system update.
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GenericObject'
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        '401':
          description: Unauthorized - authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /api/v1/system/update-notify:
    post:
      tags: [Update Management]
      summary: Notify system update
      description: Sends a notification about an available system update.
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GenericObject'
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        '401':
          description: Unauthorized - authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /api/v1/system/update-status:
    get:
      tags: [Update Management]
      summary: Get system update status
      description: Returns the current system update status.
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        '401':
          description: Unauthorized - authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /api/v1/system/update-history:
    get:
      tags: [Update Management]
      summary: Get system update history
      description: Returns the history of DashCaddy system updates.
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        '401':
          description: Unauthorized - authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /api/v1/system/rollback-versions:
    get:
      tags: [Update Management]
      summary: List rollback versions
      description: Returns available system rollback versions.
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        '401':
          description: Unauthorized - authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /api/v1/system/rollback:
    post:
      tags: [Update Management]
      summary: Rollback system
      description: Rolls back the DashCaddy system to a previous version.
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GenericObject'
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        '401':
          description: Unauthorized - authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /api/v1/apps/templates:
    get:
      tags: [Docker App Deployment]
      summary: List app templates
      description: Returns all available Docker app templates.
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        '401':
          description: Unauthorized - authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /api/v1/apps/templates/{appId}:
    get:
      tags: [Docker App Deployment]
      summary: Get app template
      description: Returns details for a specific app template.
      parameters:
        - name: appId
          in: path
          required: true
          schema:
            type: string
          description: App template ID
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        '401':
          description: Unauthorized - authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /api/v1/apps/ports/{port}/check:
    get:
      tags: [Docker App Deployment]
      summary: Check port availability
      description: Checks if a port is available for a new app deployment.
      parameters:
        - name: port
          in: path
          required: true
          schema:
            type: string
          description: Port number
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        '401':
          description: Unauthorized - authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /api/v1/apps/ports/{basePort}/suggest:
    get:
      tags: [Docker App Deployment]
      summary: Suggest next port
      description: Suggests the next available port starting from a base.
      parameters:
        - name: basePort
          in: path
          required: true
          schema:
            type: string
          description: Base port number
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        '401':
          description: Unauthorized - authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /api/v1/apps/update-subdomain:
    post:
      tags: [Docker App Deployment]
      summary: Update app subdomain
      description: Updates the subdomain for a deployed app.
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GenericObject'
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        '401':
          description: Unauthorized - authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /api/v1/apps/check-existing:
    post:
      tags: [Docker App Deployment]
      summary: Check existing app
      description: Checks if an app with the given parameters already exists.
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GenericObject'
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        '401':
          description: Unauthorized - authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /api/v1/apps/deploy:
    post:
      tags: [Docker App Deployment]
      summary: Deploy app
      description: Deploys a new Docker app from a template.
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GenericObject'
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        '401':
          description: Unauthorized - authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /api/v1/apps/{appId}:
    delete:
      tags: [Docker App Deployment]
      summary: Remove app
      description: Removes a deployed app, its container, and configuration.
      parameters:
        - name: appId
          in: path
          required: true
          schema:
            type: string
          description: App ID
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        '401':
          description: Unauthorized - authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /api/v1/apps/restore-status:
    get:
      tags: [Backup & Restore]
      summary: Get restore status
      description: Returns the status of an ongoing app restore operation.
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        '401':
          description: Unauthorized - authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /api/v1/apps/{appId}/restore:
    post:
      tags: [Backup & Restore]
      summary: Restore app
      description: Restores an app from a backup point.
      parameters:
        - name: appId
          in: path
          required: true
          schema:
            type: string
          description: App ID
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GenericObject'
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        '401':
          description: Unauthorized - authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /api/v1/apps/restore-all:
    post:
      tags: [Backup & Restore]
      summary: Restore all apps
      description: Restores all apps from their latest backup points.
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GenericObject'
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        '401':
          description: Unauthorized - authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /api/v1/apps/{appId}/backup-points:
    get:
      tags: [Backup & Restore]
      summary: List backup points
      description: Returns available backup points for an app.
      parameters:
        - name: appId
          in: path
          required: true
          schema:
            type: string
          description: App ID
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        '401':
          description: Unauthorized - authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /api/v1/apps/{appId}/revert/{filename}:
    post:
      tags: [Backup & Restore]
      summary: Revert app to backup
      description: Reverts an app to a specific backup file.
      parameters:
        - name: appId
          in: path
          required: true
          schema:
            type: string
          description: App ID
        - name: filename
          in: path
          required: true
          schema:
            type: string
          description: Backup filename
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GenericObject'
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        '401':
          description: Unauthorized - authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /api/v1/apps/import-compose:
    post:
      tags: [Docker App Deployment]
      summary: Import compose file
      description: Imports a docker-compose file as a managed stack.
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GenericObject'
          multipart/form-data:
            schema:
              type: object
              properties:
                file:
                  type: string
                  format: binary
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        '401':
          description: Unauthorized - authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /api/v1/apps/deploy-compose:
    post:
      tags: [Docker App Deployment]
      summary: Deploy compose stack
      description: Deploys a docker-compose stack.
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GenericObject'
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        '401':
          description: Unauthorized - authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /api/v1/apps/compose-stack/{stackName}:
    delete:
      tags: [Docker App Deployment]
      summary: Remove compose stack
      description: Removes a deployed docker-compose stack.
      parameters:
        - name: stackName
          in: path
          required: true
          schema:
            type: string
          description: Stack name
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        '401':
          description: Unauthorized - authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /api/v1/arr/detect:
    get:
      tags: [Arr Stack Integration]
      summary: Detect Arr services
      description: Detects running Arr stack services (Radarr, Sonarr, etc.).
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        '401':
          description: Unauthorized - authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /api/v1/arr/smart-detect:
    get:
      tags: [Arr Stack Integration]
      summary: Smart detect Arr services
      description: Intelligently detects and identifies Arr services with metadata.
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        '401':
          description: Unauthorized - authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /api/v1/arr/smart-connect:
    post:
      tags: [Arr Stack Integration]
      summary: Smart connect Arr
      description: Auto-connects detected Arr services with credentials.
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GenericObject'
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        '401':
          description: Unauthorized - authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /api/v1/arr/credentials:
    get:
      tags: [Arr Stack Integration]
      summary: List Arr credentials
      description: Returns stored credentials for Arr services.
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        '401':
          description: Unauthorized - authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    post:
      tags: [Arr Stack Integration]
      summary: Set Arr credentials
      description: Stores credentials for an Arr service.
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GenericObject'
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        '401':
          description: Unauthorized - authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /api/v1/arr/credentials/{service}:
    delete:
      tags: [Arr Stack Integration]
      summary: Delete Arr credentials
      description: Removes credentials for an Arr service.
      parameters:
        - name: service
          in: path
          required: true
          schema:
            type: string
          description: Service name (radarr, sonarr, etc.)
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        '401':
          description: Unauthorized - authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /api/v1/arr/test-connection:
    post:
      tags: [Arr Stack Integration]
      summary: Test Arr connection
      description: Tests connectivity to a configured Arr service.
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GenericObject'
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        '401':
          description: Unauthorized - authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /api/v1/arr/auto-setup:
    post:
      tags: [Arr Stack Integration]
      summary: Auto-setup Arr stack
      description: Automatically configures the full Arr stack with optimal settings.
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GenericObject'
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        '401':
          description: Unauthorized - authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /api/v1/arr/configure-overseerr:
    post:
      tags: [Arr Stack Integration]
      summary: Configure Overseerr
      description: Configures Overseerr integration with Arr services.
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GenericObject'
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        '401':
          description: Unauthorized - authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /api/v1/arr/quality-profiles:
    get:
      tags: [Arr Stack Integration]
      summary: Get quality profiles
      description: Returns quality profiles from configured Arr services.
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        '401':
          description: Unauthorized - authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    post:
      tags: [Arr Stack Integration]
      summary: Set quality profiles
      description: Updates quality profiles on Arr services.
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GenericObject'
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        '401':
          description: Unauthorized - authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /api/v1/plex/libraries:
    get:
      tags: [Plex]
      summary: List Plex libraries
      description: Returns all libraries from the configured Plex server.
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        '401':
          description: Unauthorized - authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /api/v1/tailscale/status:
    get:
      tags: [Tailscale]
      summary: Get Tailscale status
      description: Returns the Tailscale daemon status.
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        '401':
          description: Unauthorized - authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /api/v1/tailscale/config:
    post:
      tags: [Tailscale]
      summary: Update Tailscale config
      description: Updates Tailscale integration configuration.
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GenericObject'
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        '401':
          description: Unauthorized - authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /api/v1/tailscale/check-connection:
    get:
      tags: [Tailscale]
      summary: Check Tailscale connection
      description: Checks if the Tailscale daemon is connected.
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        '401':
          description: Unauthorized - authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /api/v1/tailscale/devices:
    get:
      tags: [Tailscale]
      summary: List Tailscale devices
      description: Returns all devices on the Tailnet.
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        '401':
          description: Unauthorized - authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /api/v1/tailscale/protect-service:
    post:
      tags: [Tailscale]
      summary: Protect service via Tailscale
      description: Configures Tailscale access protection for a service.
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GenericObject'
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        '401':
          description: Unauthorized - authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /api/v1/tailscale/oauth-config:
    post:
      tags: [Tailscale]
      summary: Set OAuth config
      description: Stores Tailscale OAuth client credentials.
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GenericObject'
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        '401':
          description: Unauthorized - authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    delete:
      tags: [Tailscale]
      summary: Delete OAuth config
      description: Removes Tailscale OAuth client credentials.
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        '401':
          description: Unauthorized - authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /api/v1/tailscale/api-devices:
    get:
      tags: [Tailscale]
      summary: List API devices
      description: Returns devices accessible via the Tailscale API.
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        '401':
          description: Unauthorized - authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /api/v1/tailscale/sync:
    post:
      tags: [Tailscale]
      summary: Sync Tailscale devices
      description: Triggers a sync of Tailscale devices into DashCaddy.
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GenericObject'
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        '401':
          description: Unauthorized - authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /api/v1/tailscale/acl:
    get:
      tags: [Tailscale]
      summary: Get Tailscale ACL
      description: Returns the current Tailscale ACL configuration.
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        '401':
          description: Unauthorized - authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /api/v1/tailscale/settings:
    get:
      tags: [Tailscale]
      summary: Get Tailscale admin settings
      description: Returns Tailscale coordination/admin settings.
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        '401':
          description: Unauthorized - authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    put:
      tags: [Tailscale]
      summary: Update Tailscale admin settings
      description: Updates Tailscale coordination/admin settings.
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GenericObject'
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        '401':
          description: Unauthorized - authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    delete:
      tags: [Tailscale]
      summary: Delete Tailscale admin settings
      description: Resets Tailscale coordination settings to defaults.
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        '401':
          description: Unauthorized - authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /api/v1/tailscale/settings/test:
    post:
      tags: [Tailscale]
      summary: Test Tailscale admin settings
      description: Tests the Tailscale coordination connection.
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GenericObject'
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        '401':
          description: Unauthorized - authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /api/v1/tailscale/admin/devices:
    get:
      tags: [Tailscale]
      summary: List admin devices
      description: Returns all devices from the Tailscale coordination API.
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        '401':
          description: Unauthorized - authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /api/v1/tailscale/admin/devices/{id}:
    delete:
      tags: [Tailscale]
      summary: Remove admin device
      description: Removes a device from the Tailnet via the coordination API.
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
          description: Device ID
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        '401':
          description: Unauthorized - authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /api/v1/tailscale/admin/users:
    get:
      tags: [Tailscale]
      summary: List admin users
      description: Returns all users from the Tailscale coordination API.
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        '401':
          description: Unauthorized - authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /api/v1/tailscale/admin/keys:
    get:
      tags: [Tailscale]
      summary: List admin keys
      description: Returns all auth keys from the Tailscale coordination API.
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        '401':
          description: Unauthorized - authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    post:
      tags: [Tailscale]
      summary: Create admin key
      description: Creates a new Tailscale auth key.
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GenericObject'
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        '401':
          description: Unauthorized - authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /api/v1/tailscale/admin/keys/{id}:
    delete:
      tags: [Tailscale]
      summary: Delete admin key
      description: Revokes a Tailscale auth key.
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
          description: Key ID
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        '401':
          description: Unauthorized - authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /api/v1/notifications/config:
    get:
      tags: [Notifications]
      summary: Get notification config
      description: Returns the notification system configuration.
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        '401':
          description: Unauthorized - authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    post:
      tags: [Notifications]
      summary: Update notification config
      description: Updates the notification system configuration.
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GenericObject'
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        '401':
          description: Unauthorized - authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /api/v1/notifications/test:
    post:
      tags: [Notifications]
      summary: Test notification
      description: Sends a test notification to configured channels.
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GenericObject'
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        '401':
          description: Unauthorized - authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /api/v1/notifications/history:
    get:
      tags: [Notifications]
      summary: Get notification history
      description: Returns recent notification history.
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        '401':
          description: Unauthorized - authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    delete:
      tags: [Notifications]
      summary: Clear notification history
      description: Clears the notification history log.
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        '401':
          description: Unauthorized - authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /api/v1/notifications/health-check:
    post:
      tags: [Notifications]
      summary: Send health-check notification
      description: Triggers a health-check notification dispatch.
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GenericObject'
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        '401':
          description: Unauthorized - authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /api/v1/notifications/status:
    get:
      tags: [Notifications]
      summary: Get notification status
      description: Returns the notification system status and channel health.
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        '401':
          description: Unauthorized - authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /api/v1/notifications/send:
    post:
      tags: [Notifications]
      summary: Send notification
      description: Sends a custom notification to configured channels.
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GenericObject'
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        '401':
          description: Unauthorized - authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /api/v1/logs/containers:
    get:
      tags: [Container Stats & Logs]
      summary: List log containers
      description: Returns containers available for log viewing.
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        '401':
          description: Unauthorized - authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /api/v1/logs/container/{id}:
    get:
      tags: [Container Stats & Logs]
      summary: Get container logs
      description: Returns log output for a specific container.
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
          description: Container ID
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        '401':
          description: Unauthorized - authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /api/v1/logs/stream/{id}:
    get:
      tags: [Container Stats & Logs]
      summary: Stream container logs
      description: Returns a live log stream (SSE) for a container.
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
          description: Container ID
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SSEResponse'
        '401':
          description: Unauthorized - authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /api/v1/logs/digest/latest:
    get:
      tags: [Container Stats & Logs]
      summary: Get latest log digest
      description: Returns the most recent log digest.
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        '401':
          description: Unauthorized - authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /api/v1/logs/digest/live:
    get:
      tags: [Container Stats & Logs]
      summary: Live log digest
      description: Returns a live-updating log digest (SSE).
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        '401':
          description: Unauthorized - authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /api/v1/logs/digest/history:
    get:
      tags: [Container Stats & Logs]
      summary: Log digest history
      description: Returns historical log digests.
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        '401':
          description: Unauthorized - authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /api/v1/logs/digest/{date}:
    get:
      tags: [Container Stats & Logs]
      summary: Get log digest by date
      description: Returns the log digest for a specific date.
      parameters:
        - name: date
          in: path
          required: true
          schema:
            type: string
          description: Date (YYYY-MM-DD)
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        '401':
          description: Unauthorized - authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /api/v1/logs/digest/generate:
    post:
      tags: [Container Stats & Logs]
      summary: Generate log digest
      description: Triggers generation of a new log digest.
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GenericObject'
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        '401':
          description: Unauthorized - authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /api/v1/logs/docker-disk:
    get:
      tags: [Container Stats & Logs]
      summary: Get Docker disk usage
      description: Returns Docker log disk usage information.
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        '401':
          description: Unauthorized - authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /api/v1/logs/docker-maintenance:
    post:
      tags: [Container Stats & Logs]
      summary: Docker log maintenance
      description: Triggers Docker log cleanup/maintenance.
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GenericObject'
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        '401':
          description: Unauthorized - authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /api/v1/logs/file:
    get:
      tags: [Container Stats & Logs]
      summary: Read log file
      description: Returns content from a specific log file.
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        '401':
          description: Unauthorized - authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /api/v1/backups/schedule:
    get:
      tags: [Automated Backups]
      summary: Get backup schedule
      description: Returns all configured backup schedules.
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        '401':
          description: Unauthorized - authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    post:
      tags: [Automated Backups]
      summary: Create backup schedule
      description: Creates a new backup schedule for an app.
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GenericObject'
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        '401':
          description: Unauthorized - authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /api/v1/backups/schedule/{appId}:
    delete:
      tags: [Automated Backups]
      summary: Delete backup schedule
      description: Removes a backup schedule for an app.
      parameters:
        - name: appId
          in: path
          required: true
          schema:
            type: string
          description: App ID
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        '401':
          description: Unauthorized - authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /api/v1/backups/files:
    get:
      tags: [Automated Backups]
      summary: List backup files
      description: Returns all available backup files.
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        '401':
          description: Unauthorized - authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /api/v1/backups/files/{appId}:
    get:
      tags: [Automated Backups]
      summary: List app backup files
      description: Returns backup files for a specific app.
      parameters:
        - name: appId
          in: path
          required: true
          schema:
            type: string
          description: App ID
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        '401':
          description: Unauthorized - authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /api/v1/backups/backup/{appId}:
    post:
      tags: [Automated Backups]
      summary: Create backup
      description: Creates a backup for a specific app.
      parameters:
        - name: appId
          in: path
          required: true
          schema:
            type: string
          description: App ID
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GenericObject'
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        '401':
          description: Unauthorized - authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /api/v1/backups/restore-file/{filename}:
    post:
      tags: [Automated Backups]
      summary: Restore backup file
      description: Restores a specific backup file by name.
      parameters:
        - name: filename
          in: path
          required: true
          schema:
            type: string
          description: Backup filename
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GenericObject'
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        '401':
          description: Unauthorized - authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /api/v1/backups/compare/{filename}:
    post:
      tags: [Automated Backups]
      summary: Compare backup
      description: Compares a backup file against current state.
      parameters:
        - name: filename
          in: path
          required: true
          schema:
            type: string
          description: Backup filename
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GenericObject'
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        '401':
          description: Unauthorized - authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /api/v1/backups/config:
    get:
      tags: [Automated Backups]
      summary: Get backup config
      description: Returns the backup system configuration.
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        '401':
          description: Unauthorized - authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    post:
      tags: [Automated Backups]
      summary: Update backup config
      description: Updates the backup system configuration.
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GenericObject'
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        '401':
          description: Unauthorized - authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /api/v1/backups/execute:
    post:
      tags: [Automated Backups]
      summary: Execute backup
      description: Triggers an immediate backup of all scheduled apps.
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GenericObject'
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        '401':
          description: Unauthorized - authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /api/v1/backups/history:
    get:
      tags: [Automated Backups]
      summary: Get backup history
      description: Returns the history of executed backups.
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        '401':
          description: Unauthorized - authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /api/v1/backups/storage-info:
    get:
      tags: [Automated Backups]
      summary: Get backup storage info
      description: Returns backup storage usage information.
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        '401':
          description: Unauthorized - authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /api/v1/backups/test-destination:
    post:
      tags: [Automated Backups]
      summary: Test backup destination
      description: Tests connectivity to a backup destination.
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GenericObject'
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        '401':
          description: Unauthorized - authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /api/v1/backups/restore/{backupId}:
    post:
      tags: [Automated Backups]
      summary: Restore backup
      description: Restores a backup by ID.
      parameters:
        - name: backupId
          in: path
          required: true
          schema:
            type: string
          description: Backup ID
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GenericObject'
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        '401':
          description: Unauthorized - authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /api/v1/backups/credentials/{provider}:
    get:
      tags: [Automated Backups]
      summary: Get backup credentials
      description: Returns stored credentials for a backup provider.
      parameters:
        - name: provider
          in: path
          required: true
          schema:
            type: string
          description: Backup provider name
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        '401':
          description: Unauthorized - authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    post:
      tags: [Automated Backups]
      summary: Set backup credentials
      description: Stores credentials for a backup provider.
      parameters:
        - name: provider
          in: path
          required: true
          schema:
            type: string
          description: Backup provider name
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GenericObject'
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        '401':
          description: Unauthorized - authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    delete:
      tags: [Automated Backups]
      summary: Delete backup credentials
      description: Removes credentials for a backup provider.
      parameters:
        - name: provider
          in: path
          required: true
          schema:
            type: string
          description: Backup provider name
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        '401':
          description: Unauthorized - authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /api/v1/ca/info:
    get:
      tags: [Certificate Authority]
      summary: Get CA info
      description: Returns certificate authority metadata (CN, algorithm, expiry).
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        '401':
          description: Unauthorized - authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /api/v1/ca/root.crt:
    get:
      tags: [Certificate Authority]
      summary: Download root certificate
      description: Returns the root CA certificate file.
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        '401':
          description: Unauthorized - authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /api/v1/ca/install-script:
    get:
      tags: [Certificate Authority]
      summary: Get install script
      description: Returns a shell script for installing the CA cert on this OS.
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        '401':
          description: Unauthorized - authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /api/v1/ca/cert/{domain}:
    get:
      tags: [Certificate Authority]
      summary: Get domain certificate
      description: Returns the certificate for a specific domain.
      parameters:
        - name: domain
          in: path
          required: true
          schema:
            type: string
          description: Domain name
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        '401':
          description: Unauthorized - authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /api/v1/ca/certs:
    get:
      tags: [Certificate Authority]
      summary: List certificates
      description: Returns all issued certificates.
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        '401':
          description: Unauthorized - authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /api/v1/browse/roots:
    get:
      tags: [Filesystem Browser]
      summary: List browse roots
      description: Returns allowed root directories for filesystem browsing.
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        '401':
          description: Unauthorized - authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /api/v1/browse/directories:
    get:
      tags: [Filesystem Browser]
      summary: Browse directories
      description: Lists contents of a directory path.
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        '401':
          description: Unauthorized - authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /api/v1/media/detected-mounts:
    get:
      tags: [Filesystem Browser]
      summary: Get detected mounts
      description: Returns detected media mount points.
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        '401':
          description: Unauthorized - authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /api/v1/error-logs:
    get:
      tags: [Error Logs]
      summary: Get error logs
      description: Returns recent system error logs.
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        '401':
          description: Unauthorized - authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    delete:
      tags: [Error Logs]
      summary: Clear error logs
      description: Clears the system error log.
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        '401':
          description: Unauthorized - authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /api/v1/audit-logs:
    get:
      tags: [Audit Log]
      summary: Get audit logs
      description: Returns recent audit log entries.
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        '401':
          description: Unauthorized - authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    delete:
      tags: [Audit Log]
      summary: Clear audit logs
      description: Clears the audit log.
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        '401':
          description: Unauthorized - authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /api/v1/license/activate:
    post:
      tags: [License Management]
      summary: Activate license
      description: Activates a DashCaddy license key.
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GenericObject'
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        '401':
          description: Unauthorized - authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /api/v1/license/status:
    get:
      tags: [License Management]
      summary: Get license status
      description: Returns the current license status and tier.
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        '401':
          description: Unauthorized - authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /api/v1/license/deactivate:
    post:
      tags: [License Management]
      summary: Deactivate license
      description: Deactivates the current license.
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GenericObject'
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        '401':
          description: Unauthorized - authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /api/v1/license/feature/{feature}:
    get:
      tags: [License Management]
      summary: Check feature access
      description: Checks if a feature is available under the current license.
      parameters:
        - name: feature
          in: path
          required: true
          schema:
            type: string
          description: Feature name
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        '401':
          description: Unauthorized - authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /api/v1/openclaw/status:
    get:
      tags: [OpenClaw]
      summary: Get OpenClaw status
      description: Returns the deployment status of OpenClaw.
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        '401':
          description: Unauthorized - authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /api/v1/openclaw/deploy:
    post:
      tags: [OpenClaw]
      summary: Deploy OpenClaw
      description: Deploys the OpenClaw platform.
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GenericObject'
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        '401':
          description: Unauthorized - authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /api/v1/openclaw:
    delete:
      tags: [OpenClaw]
      summary: Remove OpenClaw
      description: Removes the OpenClaw deployment.
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        '401':
          description: Unauthorized - authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /api/v1/recipes/templates:
    get:
      tags: [Recipes]
      summary: List recipe templates
      description: Returns all available recipe templates. Requires premium license.
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        '401':
          description: Unauthorized - authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /api/v1/recipes/templates/{recipeId}:
    get:
      tags: [Recipes]
      summary: Get recipe template
      description: Returns details for a specific recipe template.
      parameters:
        - name: recipeId
          in: path
          required: true
          schema:
            type: string
          description: Recipe ID
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        '401':
          description: Unauthorized - authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /api/v1/recipes/deploy:
    post:
      tags: [Recipes]
      summary: Deploy recipe
      description: Deploys a multi-service recipe stack.
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GenericObject'
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        '401':
          description: Unauthorized - authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /api/v1/recipes/deployed:
    get:
      tags: [Recipes]
      summary: List deployed recipes
      description: Returns all deployed recipe instances.
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        '401':
          description: Unauthorized - authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /api/v1/recipes/{recipeId}/start:
    post:
      tags: [Recipes]
      summary: Start recipe
      description: Starts all services in a deployed recipe.
      parameters:
        - name: recipeId
          in: path
          required: true
          schema:
            type: string
          description: Recipe instance ID
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GenericObject'
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        '401':
          description: Unauthorized - authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /api/v1/recipes/{recipeId}/stop:
    post:
      tags: [Recipes]
      summary: Stop recipe
      description: Stops all services in a deployed recipe.
      parameters:
        - name: recipeId
          in: path
          required: true
          schema:
            type: string
          description: Recipe instance ID
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GenericObject'
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        '401':
          description: Unauthorized - authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /api/v1/recipes/{recipeId}/restart:
    post:
      tags: [Recipes]
      summary: Restart recipe
      description: Restarts all services in a deployed recipe.
      parameters:
        - name: recipeId
          in: path
          required: true
          schema:
            type: string
          description: Recipe instance ID
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GenericObject'
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        '401':
          description: Unauthorized - authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /api/v1/recipes/{recipeId}:
    delete:
      tags: [Recipes]
      summary: Remove recipe
      description: Removes a deployed recipe and all its services.
      parameters:
        - name: recipeId
          in: path
          required: true
          schema:
            type: string
          description: Recipe instance ID
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        '401':
          description: Unauthorized - authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /api/v1/themes:
    get:
      tags: [Themes]
      summary: List themes
      description: Returns all available dashboard themes.
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        '401':
          description: Unauthorized - authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /api/v1/themes/{slug}:
    post:
      tags: [Themes]
      summary: Activate theme
      description: Activates a dashboard theme by slug.
      parameters:
        - name: slug
          in: path
          required: true
          schema:
            type: string
          description: Theme slug
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GenericObject'
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        '401':
          description: Unauthorized - authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    delete:
      tags: [Themes]
      summary: Delete theme
      description: Removes a custom theme by slug.
      parameters:
        - name: slug
          in: path
          required: true
          schema:
            type: string
          description: Theme slug
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        '401':
          description: Unauthorized - authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /api/v1/docker/volumes:
    get:
      tags: [Docker Resources]
      summary: List volumes
      description: Returns all Docker volumes.
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        '401':
          description: Unauthorized - authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    post:
      tags: [Docker Resources]
      summary: Create volume
      description: Creates a new Docker volume.
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GenericObject'
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        '401':
          description: Unauthorized - authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /api/v1/docker/volumes/{name}:
    delete:
      tags: [Docker Resources]
      summary: Delete volume
      description: Removes a Docker volume by name.
      parameters:
        - name: name
          in: path
          required: true
          schema:
            type: string
          description: Volume name
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        '401':
          description: Unauthorized - authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /api/v1/docker/networks:
    get:
      tags: [Docker Resources]
      summary: List networks
      description: Returns all Docker networks.
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        '401':
          description: Unauthorized - authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    post:
      tags: [Docker Resources]
      summary: Create network
      description: Creates a new Docker network.
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GenericObject'
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        '401':
          description: Unauthorized - authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /api/v1/docker/networks/{id}:
    delete:
      tags: [Docker Resources]
      summary: Delete network
      description: Removes a Docker network by ID.
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
          description: Network ID
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        '401':
          description: Unauthorized - authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /api/v1/docker/disk-usage:
    get:
      tags: [Docker Resources]
      summary: Get disk usage
      description: Returns Docker daemon disk usage information.
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        '401':
          description: Unauthorized - authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /api/v1/events/stream:
    get:
      tags: [Events]
      summary: Event stream
      description: Server-sent events stream for real-time updates (resource alerts, health checks, updates, etc.).
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SSEResponse'
        '401':
          description: Unauthorized - authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /api/v1/events/clients:
    get:
      tags: [Events]
      summary: Event client count
      description: Returns the number of connected SSE clients.
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        '401':
          description: Unauthorized - authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /api/v1/workflows/workflows:
    get:
      tags: [Workflows]
      summary: List workflows
      description: Returns all bundled automation workflows.
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        '401':
          description: Unauthorized - authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /api/v1/workflows/workflows/{workflowId}/enable:
    post:
      tags: [Workflows]
      summary: Enable workflow
      description: Enables a specific automation workflow.
      parameters:
        - name: workflowId
          in: path
          required: true
          schema:
            type: string
          description: Workflow ID
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GenericObject'
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        '401':
          description: Unauthorized - authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /api/v1/workflows/workflows/{workflowId}/disable:
    post:
      tags: [Workflows]
      summary: Disable workflow
      description: Disables a specific automation workflow.
      parameters:
        - name: workflowId
          in: path
          required: true
          schema:
            type: string
          description: Workflow ID
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GenericObject'
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        '401':
          description: Unauthorized - authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /api/v1/workflows/workflows/{workflowId}/run:
    post:
      tags: [Workflows]
      summary: Run workflow
      description: Triggers a manual run of a specific workflow.
      parameters:
        - name: workflowId
          in: path
          required: true
          schema:
            type: string
          description: Workflow ID
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GenericObject'
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        '401':
          description: Unauthorized - authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /api/v1/workflows/workflows/{workflowId}/history:
    get:
      tags: [Workflows]
      summary: Get workflow history
      description: Returns execution history for a specific workflow.
      parameters:
        - name: workflowId
          in: path
          required: true
          schema:
            type: string
          description: Workflow ID
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        '401':
          description: Unauthorized - authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /api/v1/workflows/workflows/history:
    get:
      tags: [Workflows]
      summary: Get all workflow history
      description: Returns execution history for all workflows.
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        '401':
          description: Unauthorized - authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /api/v1/security/events:
    get:
      tags: [Security Center]
      summary: List security events
      description: Returns recent security events from all sources.
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        '401':
          description: Unauthorized - authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /api/v1/security/events/{id}:
    get:
      tags: [Security Center]
      summary: Get security event
      description: Returns details for a specific security event.
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
          description: Event ID
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        '401':
          description: Unauthorized - authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /api/v1/security/events/stats:
    get:
      tags: [Security Center]
      summary: Security event stats
      description: Returns aggregate statistics for security events.
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        '401':
          description: Unauthorized - authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /api/v1/security/events/stream:
    get:
      tags: [Security Center]
      summary: Security event stream
      description: SSE stream of live security events.
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SSEResponse'
        '401':
          description: Unauthorized - authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /api/v1/security/events/ingest:
    post:
      tags: [Security Center]
      summary: Ingest security event
      description: Ingests a single security event from an external source.
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GenericObject'
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        '401':
          description: Unauthorized - authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /api/v1/security/events/batch:
    post:
      tags: [Security Center]
      summary: Batch ingest events
      description: Ingests multiple security events in a single request.
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GenericObject'
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        '401':
          description: Unauthorized - authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /api/v1/security/hosts:
    get:
      tags: [Security Center]
      summary: List hosts
      description: Returns all registered security monitoring hosts.
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        '401':
          description: Unauthorized - authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    post:
      tags: [Security Center]
      summary: Register host
      description: Registers a new security monitoring host.
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GenericObject'
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        '401':
          description: Unauthorized - authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /api/v1/security/hosts/{id}:
    get:
      tags: [Security Center]
      summary: Get host
      description: Returns details for a registered host.
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
          description: Host ID
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        '401':
          description: Unauthorized - authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    patch:
      tags: [Security Center]
      summary: Update host
      description: Updates a registered host's properties.
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
          description: Host ID
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GenericObject'
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        '401':
          description: Unauthorized - authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    delete:
      tags: [Security Center]
      summary: Delete host
      description: Removes a registered monitoring host.
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
          description: Host ID
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        '401':
          description: Unauthorized - authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /api/v1/security/hosts/{id}/health:
    get:
      tags: [Security Center]
      summary: Get host health
      description: Returns health status for a registered host.
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
          description: Host ID
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        '401':
          description: Unauthorized - authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /api/v1/security/hosts/{id}/rotate-key:
    post:
      tags: [Security Center]
      summary: Rotate host key
      description: Rotates the Bearer auth key for a registered host.
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
          description: Host ID
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GenericObject'
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        '401':
          description: Unauthorized - authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /api/v1/dependencies/graph:
    get:
      tags: [Dependencies]
      summary: Get dependency graph
      description: Returns the full service dependency graph.
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        '401':
          description: Unauthorized - authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /api/v1/dependencies/validate:
    get:
      tags: [Dependencies]
      summary: Validate dependencies
      description: Validates all dependency configurations.
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        '401':
          description: Unauthorized - authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /api/v1/dependencies/{serviceId}:
    get:
      tags: [Dependencies]
      summary: Get service dependencies
      description: Returns dependencies for a specific service.
      parameters:
        - name: serviceId
          in: path
          required: true
          schema:
            type: string
          description: Service ID
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        '401':
          description: Unauthorized - authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    post:
      tags: [Dependencies]
      summary: Set service dependencies
      description: Configures dependencies for a service.
      parameters:
        - name: serviceId
          in: path
          required: true
          schema:
            type: string
          description: Service ID
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GenericObject'
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        '401':
          description: Unauthorized - authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    delete:
      tags: [Dependencies]
      summary: Delete service dependencies
      description: Removes dependencies for a service.
      parameters:
        - name: serviceId
          in: path
          required: true
          schema:
            type: string
          description: Service ID
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        '401':
          description: Unauthorized - authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /api/v1/dependencies/{serviceId}/chain:
    get:
      tags: [Dependencies]
      summary: Get dependency chain
      description: Returns the full dependency chain for a service.
      parameters:
        - name: serviceId
          in: path
          required: true
          schema:
            type: string
          description: Service ID
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        '401':
          description: Unauthorized - authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /api/v1/dependencies/{serviceId}/status:
    get:
      tags: [Dependencies]
      summary: Get dependency status
      description: Returns the current status of a service's dependencies.
      parameters:
        - name: serviceId
          in: path
          required: true
          schema:
            type: string
          description: Service ID
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        '401':
          description: Unauthorized - authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /api/v1/dependencies/{serviceId}/restart:
    post:
      tags: [Dependencies]
      summary: Restart with dependencies
      description: Restarts a service and all its dependencies in order.
      parameters:
        - name: serviceId
          in: path
          required: true
          schema:
            type: string
          description: Service ID
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GenericObject'
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        '401':
          description: Unauthorized - authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /api/v1/auto-restart/policies:
    get:
      tags: [Auto-Restart]
      summary: List auto-restart policies
      description: Returns all configured auto-restart policies.
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        '401':
          description: Unauthorized - authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /api/v1/auto-restart/policies/{serviceId}:
    get:
      tags: [Auto-Restart]
      summary: Get auto-restart policy
      description: Returns the auto-restart policy for a service.
      parameters:
        - name: serviceId
          in: path
          required: true
          schema:
            type: string
          description: Service ID
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        '401':
          description: Unauthorized - authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    post:
      tags: [Auto-Restart]
      summary: Set auto-restart policy
      description: Creates or updates an auto-restart policy for a service.
      parameters:
        - name: serviceId
          in: path
          required: true
          schema:
            type: string
          description: Service ID
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GenericObject'
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        '401':
          description: Unauthorized - authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    delete:
      tags: [Auto-Restart]
      summary: Delete auto-restart policy
      description: Removes an auto-restart policy for a service.
      parameters:
        - name: serviceId
          in: path
          required: true
          schema:
            type: string
          description: Service ID
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        '401':
          description: Unauthorized - authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /api/v1/auto-restart/policies/{serviceId}/test:
    post:
      tags: [Auto-Restart]
      summary: Test auto-restart policy
      description: Triggers a test of an auto-restart policy.
      parameters:
        - name: serviceId
          in: path
          required: true
          schema:
            type: string
          description: Service ID
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GenericObject'
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        '401':
          description: Unauthorized - authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /api/v1/config-drift/report:
    get:
      tags: [Config Drift]
      summary: Get drift report
      description: Runs a fresh drift detection and returns the full report.
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        '401':
          description: Unauthorized - authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /api/v1/config-drift/last:
    get:
      tags: [Config Drift]
      summary: Get last drift report
      description: Returns the last cached drift report without re-detection.
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        '401':
          description: Unauthorized - authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /api/v1/config-drift/fix:
    post:
      tags: [Config Drift]
      summary: Fix drift
      description: Applies fixes for detected configuration drift.
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GenericObject'
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        '401':
          description: Unauthorized - authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /api/v1/config-drift/polling:
    post:
      tags: [Config Drift]
      summary: Update polling config
      description: Updates the drift detector polling configuration.
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GenericObject'
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        '401':
          description: Unauthorized - authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /api/v1/ssl/certificates:
    get:
      tags: [SSL Monitor]
      summary: List SSL certificates
      description: Returns status for all monitored SSL certificates.
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        '401':
          description: Unauthorized - authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /api/v1/ssl/certificates/{serviceId}:
    get:
      tags: [SSL Monitor]
      summary: Get SSL certificate status
      description: Returns SSL certificate status for a specific service.
      parameters:
        - name: serviceId
          in: path
          required: true
          schema:
            type: string
          description: Service ID
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        '401':
          description: Unauthorized - authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /api/v1/ssl/check:
    post:
      tags: [SSL Monitor]
      summary: Check all certificates
      description: Triggers an SSL certificate check for all services.
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GenericObject'
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        '401':
          description: Unauthorized - authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /api/v1/ssl/check/{serviceId}:
    post:
      tags: [SSL Monitor]
      summary: Check service certificate
      description: Triggers an SSL certificate check for a specific service.
      parameters:
        - name: serviceId
          in: path
          required: true
          schema:
            type: string
          description: Service ID
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GenericObject'
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        '401':
          description: Unauthorized - authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /api/v1/ssl/config:
    get:
      tags: [SSL Monitor]
      summary: Get SSL monitor config
      description: Returns the SSL monitor configuration.
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        '401':
          description: Unauthorized - authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    post:
      tags: [SSL Monitor]
      summary: Update SSL monitor config
      description: Updates the SSL monitor configuration.
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GenericObject'
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        '401':
          description: Unauthorized - authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /api/v1/disk:
    get:
      tags: [Disk Space]
      summary: Get disk usage
      description: Returns the current disk space usage snapshot.
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        '401':
          description: Unauthorized - authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /api/v1/disk/breakdown:
    get:
      tags: [Disk Space]
      summary: Get disk breakdown
      description: Returns a breakdown of disk usage by category.
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        '401':
          description: Unauthorized - authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /api/v1/disk/config:
    get:
      tags: [Disk Space]
      summary: Get disk config
      description: Returns the disk space monitor configuration.
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        '401':
          description: Unauthorized - authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    post:
      tags: [Disk Space]
      summary: Update disk config
      description: Updates the disk space monitor configuration.
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GenericObject'
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        '401':
          description: Unauthorized - authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /api/v1/disk/cleanup:
    post:
      tags: [Disk Space]
      summary: Trigger disk cleanup
      description: Triggers an automated disk cleanup operation.
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GenericObject'
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        '401':
          description: Unauthorized - authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /api/v1/share:
    get:
      tags: [Sharing]
      summary: List shares
      description: Returns all active share links.
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        '401':
          description: Unauthorized - authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    post:
      tags: [Sharing]
      summary: Create share
      description: Creates a new share link for dashboard access.
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GenericObject'
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        '401':
          description: Unauthorized - authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /api/v1/share/{id}:
    delete:
      tags: [Sharing]
      summary: Delete share
      description: Removes a share link by ID.
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
          description: Share ID
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'

  /api/v1/share/{token}/preview:
    get:
      tags: [Sharing]
      summary: Preview share
      description: Public preview of a share link by token.
      parameters:
        - name: token
          in: path
          required: true
          schema:
            type: string
          description: Share token
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'

  /api/v1/share/{token}/subscribe:
    post:
      tags: [Sharing]
      summary: Subscribe to share
      description: Subscribes a client to share updates via token.
      parameters:
        - name: token
          in: path
          required: true
          schema:
            type: string
          description: Share token
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GenericObject'
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'

  /api/v1/share/tailscale:
    post:
      tags: [Sharing]
      summary: Create Tailscale share
      description: Creates a share that uses Tailscale for access.
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GenericObject'
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'

  /api/v1/share/{token}/redeem-tailscale:
    post:
      tags: [Sharing]
      summary: Redeem Tailscale share
      description: Redeems a Tailscale-mediated share token.
      parameters:
        - name: token
          in: path
          required: true
          schema:
            type: string
          description: Share token
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GenericObject'
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'

  /api/v1/billing/checkout:
    post:
      tags: [Billing]
      summary: Create checkout session
      description: Creates a Stripe checkout session for license purchase. Public endpoint — no auth required.
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GenericObject'
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'

  /api/v1/billing/lookup/{sessionId}:
    get:
      tags: [Billing]
      summary: Lookup checkout session
      description: Returns the status of a Stripe checkout session by ID.
      parameters:
        - name: sessionId
          in: path
          required: true
          schema:
            type: string
          description: Stripe session ID
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'

components:
  schemas:
    SuccessResponse:
      type: object
      properties:
        success:
          type: boolean
          example: true
        data:
          type: object
          description: Response payload (varies by endpoint)
      required:
        - success

    ErrorResponse:
      type: object
      properties:
        success:
          type: boolean
          example: false
        error:
          type: string
          description: Error message
      required:
        - success
        - error

    GenericObject:
      type: object
      description: Generic request body (schema varies by endpoint)
      additionalProperties: true

    SSEResponse:
      type: string
      description: Server-Sent Events stream (text/event-stream)

    Service:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        url:
          type: string
        icon:
          type: string
        category:
          type: string
        healthCheck:
          type: boolean
      required:
        - id
        - name
        - url

    Config:
      type: object
      properties:
        title:
          type: string
        theme:
          type: string
          enum: [light, dark, auto]
        logo:
          type: string
        favicon:
          type: string
        customCss:
          type: string

    AppTemplate:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        description:
          type: string
        logo:
          type: string
        image:
          type: string
        defaultPort:
          type: integer
        category:
          type: string
        environment:
          type: array
          items:
            type: object
            properties:
              name:
                type: string
              label:
                type: string
              default:
                type: string
        volumes:
          type: array
          items:
            type: object
            properties:
              container:
                type: string
              host:
                type: string
      required:
        - id
        - name
        - image

    ContainerStats:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        cpuPercent:
          type: number
        memoryUsage:
          type: integer
        memoryLimit:
          type: integer
        memoryPercent:
          type: number
        networkRx:
          type: integer
        networkTx:
          type: integer
        blockRead:
          type: integer
        blockWrite:
          type: integer