# AUTO-GENERATED FILE - DO NOT EDIT MANUALLY
# Generated from @openapi blocks in include/, src/, and lib/ by scripts/openapi_generator.py
openapi: 3.0.3
info:
  title: ESP32 Service Uptime Monitor API
  version: 0.0.1-SNAPSHOT
  description: 'REST API exposed by the ESP32 Service Uptime Monitor firmware.


    ### Device Address

    Set your device IP address or mDNS hostname (for example `192.168.0.118` or `esp32-service-uptime-monitor.local`)

    in the **Servers -> `host`** field below before executing requests.

    If calling a local HTTP device from HTTPS GitHub Pages is blocked by your browser, allow *Local Network Access / Insecure
    content* in site settings or copy the generated `curl` command.


    ### Configuration Protection (BOOT Button)

    Configuration and management endpoints return `403 Forbidden` when configuration mode is locked.

    Press the hardware **BOOT** button on the device (or switch into AP setup mode) to unlock them.


    ### Real-Time WebSocket & OTA

    - Live status updates and log streams are available over WebSocket at `ws://{host}/ws`.

    - Firmware OTA updates are served natively at `/ota/start` and `/ota/upload`.

    '
servers:
- url: http://{host}
  description: ESP32 device on local network (HTTP)
  variables:
    host:
      default: esp32-service-uptime-monitor.local
      description: Device IP address or mDNS hostname (e.g. 192.168.0.118 or esp32-service-uptime-monitor.local)
tags:
- name: System
  description: Health checks and hardware/network diagnostics
- name: Monitoring
  description: Monitored services management and uptime summary
- name: Configuration
  description: Device settings, backup/restore, Wi-Fi scan, and hardware tests (requires configuration mode)
- name: Updates
  description: Firmware OTA and Web UI archive updates
components:
  schemas:
    StatusResponse:
      type: object
      properties:
        status:
          type: string
          example: success
        message:
          type: string
    ErrorResponse:
      type: object
      properties:
        error:
          type: string
          example: Not found
    HealthResponse:
      type: object
      properties:
        status:
          type: string
          example: UP
    SummaryResponse:
      type: object
      properties:
        total:
          type: integer
          example: 5
        online:
          type: integer
          example: 4
        offline:
          type: integer
          example: 1
    LedTestResponse:
      type: object
      properties:
        status:
          type: string
          example: success
        message:
          type: string
          example: LED test started
        brightness:
          type: integer
          minimum: 0
          maximum: 100
          example: 50
        duration:
          type: integer
          example: 3000
    Config:
      type: object
      properties:
        wifiSSID:
          type: string
          example: MyWiFi
        wifiPassword:
          type: string
          description: Wi-Fi password (masked as ****** on read)
          example: secret123
        sntpServer:
          type: string
          maxLength: 64
          example: pool.ntp.org
        offsetHours:
          type: integer
          minimum: -12
          maximum: 14
          example: 1
        checkInterval:
          type: integer
          minimum: 5
          maximum: 255
          description: Check interval in seconds
          example: 60
        discordWebhookURL:
          type: string
          description: Discord webhook URL (token suffix masked as ****** on read)
          example: https://discord.com/api/webhooks/...
        hostname:
          type: string
          description: RFC 1123 mDNS hostname without .local suffix
          example: esp32-service-uptime-monitor
        otaToken:
          type: string
          description: PlatformIO OTA update authentication token (minimum 8 characters; masked on read)
          example: '******'
        logLevel:
          type: integer
          minimum: 0
          maximum: 11
          example: 8
        logLevelName:
          type: string
          example: DEBUG
        ledBrightness:
          type: integer
          minimum: 0
          maximum: 100
          example: 50
        configEnabled:
          type: boolean
          description: Whether configuration mode is currently active
          example: true
        configTimeoutRemaining:
          type: integer
          description: Remaining configuration mode timeout in seconds
          example: 600
    MonitoredEntity:
      type: object
      properties:
        name:
          type: string
          maxLength: 63
          example: Router
        address:
          type: string
          maxLength: 127
          example: http://192.168.0.1/
        icon:
          type: string
          maxLength: 127
          description: Material Design Icons class (mdi-*), Dashboard Icons slug (di:*), or icon URL
          example: mdi-router-wireless
        isOnline:
          type: boolean
          example: true
        notification:
          type: boolean
          example: true
        disabled:
          type: boolean
          example: false
        lastChanged:
          type: integer
          format: int64
          description: Unix timestamp of the last status transition
          example: 1700000000
    MonitoredEntityInput:
      type: object
      required:
      - name
      - address
      properties:
        name:
          type: string
          maxLength: 63
          example: Router
        address:
          type: string
          maxLength: 127
          example: http://192.168.0.1/
        icon:
          type: string
          maxLength: 127
          description: Material Design Icons class (mdi-*), Dashboard Icons slug (di:*), or icon URL
          example: mdi-router-wireless
        notification:
          type: boolean
          default: true
        disabled:
          type: boolean
          default: false
        isOnline:
          type: boolean
          default: false
        lastChanged:
          type: integer
          format: int64
    BackupPayload:
      type: object
      required:
      - config
      - entities
      properties:
        config:
          $ref: '#/components/schemas/Config'
        entities:
          type: array
          items:
            $ref: '#/components/schemas/MonitoredEntity'
    WifiNetwork:
      type: object
      properties:
        ssid:
          type: string
        rssi:
          type: integer
        bssid:
          type: string
        channel:
          type: integer
        encryptionType:
          type: integer
    WifiScanResponse:
      type: object
      properties:
        status:
          type: string
          enum:
          - scanning
          - in progress
          - done
        networks:
          type: array
          items:
            $ref: '#/components/schemas/WifiNetwork'
    BasicSysinfo:
      type: object
      properties:
        temperature:
          type: number
          format: float
        heapSize:
          type: integer
        freeHeap:
          type: integer
        minFreeHeap:
          type: integer
        maxAllocHeap:
          type: integer
        maxFreeBlock:
          type: integer
        psramSize:
          type: integer
        freePsram:
          type: integer
        minFreePsram:
          type: integer
        maxAllocPsram:
          type: integer
        rssi:
          type: integer
        wsClients:
          type: integer
        uptime:
          type: integer
        localTime:
          type: string
        timeSynced:
          type: boolean
        lastCheckDurationMs:
          type: integer
        lastCheckTime:
          type: string
        stackHighWaterBytes:
          type: integer
        version:
          type: string
        buildDate:
          type: string
        commit:
          type: string
        configEnabled:
          type: boolean
        configTimeoutRemaining:
          type: integer
          description: Remaining configuration mode timeout in seconds
          example: 600
    DetailedSysinfo:
      allOf:
      - $ref: '#/components/schemas/BasicSysinfo'
      - type: object
        properties:
          device:
            type: object
            properties:
              board:
                type: string
                example: ESP32-S3-CAM
              chipModel:
                type: string
                example: ESP32-S3
              chipRevision:
                type: integer
              chipCores:
                type: integer
              cpuFreqMHz:
                type: integer
              resetReason:
                type: string
                example: POWERON
              efuseMac:
                type: string
                example: AA:BB:CC:DD:EE:FF
              hasTempSensor:
                type: boolean
          memory:
            type: object
            properties:
              heapSize:
                type: integer
              freeHeap:
                type: integer
              minFreeHeap:
                type: integer
              maxAllocHeap:
                type: integer
              maxFreeBlock:
                type: integer
              psramSize:
                type: integer
              freePsram:
                type: integer
              minFreePsram:
                type: integer
              maxAllocPsram:
                type: integer
              flashSize:
                type: integer
              flashSpeed:
                type: integer
              sketchSize:
                type: integer
              freeSketchSpace:
                type: integer
          storage:
            type: object
            properties:
              backend:
                type: string
                example: SD_MMC
              available:
                type: boolean
              cardType:
                type: string
              cardSizeBytes:
                type: integer
                format: int64
              totalBytes:
                type: integer
                format: int64
              usedBytes:
                type: integer
                format: int64
              freeBytes:
                type: integer
                format: int64
          network:
            type: object
            properties:
              mode:
                type: string
                enum:
                - STA
                - AP
              connected:
                type: boolean
              ssid:
                type: string
              bssid:
                type: string
              channel:
                type: integer
              rssi:
                type: integer
              ip:
                type: string
              subnetMask:
                type: string
              gateway:
                type: string
              dns:
                type: string
              mac:
                type: string
              hostname:
                type: string
              wsClients:
                type: integer
          time:
            type: object
            properties:
              localTime:
                type: string
              timeSynced:
                type: boolean
              sntpServer:
                type: string
              timezoneOffset:
                type: integer
              uptime:
                type: integer
          monitoring:
            type: object
            properties:
              checkInterval:
                type: integer
              lastCheckDurationMs:
                type: integer
              lastCheckTime:
                type: string
              stackHighWaterBytes:
                type: integer
          firmware:
            type: object
            properties:
              version:
                type: string
              commit:
                type: string
              buildDate:
                type: string
              uiVersion:
                type: string
              expectedUiVersion:
                type: string
              otaPartition:
                type: string
              sdkVersion:
                type: string
              coreVersion:
                type: string
              configEnabled:
                type: boolean
paths:
  /api/config/backup:
    get:
      tags:
      - Configuration
      summary: Export configuration and monitored entities backup
      responses:
        '200':
          description: Backup JSON payload
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BackupPayload'
        '403':
          description: Configuration mode disabled
        '500':
          description: Failed to read or parse config files
  /api/config/restore:
    post:
      tags:
      - Configuration
      summary: Restore configuration and monitored entities from backup file
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              required:
              - file
              properties:
                file:
                  type: string
                  format: binary
                  description: Backup JSON file containing config and entities (max 32 KB)
      responses:
        '200':
          description: Restore completed and device restarting
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StatusResponse'
        '400':
          description: Invalid JSON or missing config/entities keys
        '403':
          description: Configuration mode disabled
        '413':
          description: Backup payload exceeds maximum allowed size (32 KB)
        '500':
          description: Storage unavailable or failed to write config files
  /api/config/factoryReset:
    post:
      tags:
      - Configuration
      summary: Delete configuration and entity files and reboot into AP mode
      responses:
        '200':
          description: Factory reset result
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StatusResponse'
        '403':
          description: Configuration mode disabled
  /api/wifiscan:
    get:
      tags:
      - Configuration
      summary: Trigger or poll non-blocking Wi-Fi network scan
      responses:
        '200':
          description: Current scan state and discovered networks
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WifiScanResponse'
        '403':
          description: Configuration mode disabled
  /api/testDiscord:
    post:
      tags:
      - Configuration
      summary: Send a test message to a Discord webhook URL
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              required:
              - url
              properties:
                url:
                  type: string
                  description: Discord webhook URL (if empty or masked with ******, uses currently saved webhook URL)
                  example: https://discord.com/api/webhooks/...
      responses:
        '200':
          description: Notification sent successfully (OK)
        '400':
          description: Missing or invalid Discord webhook URL
        '403':
          description: Configuration mode disabled
        '500':
          description: Webhook request failed
  /api/config/test-led:
    post:
      tags:
      - Configuration
      summary: Trigger a temporary cyan pulse test on the onboard RGB LED
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              properties:
                brightness:
                  type: integer
                  minimum: 0
                  maximum: 100
                  example: 50
                duration:
                  type: integer
                  minimum: 1
                  maximum: 10000
                  description: Test duration in milliseconds
                  example: 3000
      responses:
        '200':
          description: LED test started
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LedTestResponse'
        '400':
          description: RGB LED not supported on this board
        '403':
          description: Configuration mode disabled
        '415':
          description: Unsupported Media Type (application/json required when body is present)
  /api/config:
    get:
      tags:
      - Configuration
      summary: Get current device configuration
      responses:
        '200':
          description: Current configuration
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Config'
        '403':
          description: Configuration mode disabled
    post:
      tags:
      - Configuration
      summary: Save updated device configuration
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Config'
      responses:
        '200':
          description: Configuration saved
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    example: success
                  message:
                    type: string
                  restarting:
                    type: boolean
        '400':
          description: Invalid JSON, missing body, or Wi-Fi connection failed
        '403':
          description: Configuration mode disabled
        '413':
          description: Payload Too Large (exceeds 4 KB)
        '415':
          description: Unsupported Media Type (application/json required)
        '500':
          description: Failed to save configuration
  /api/web/upload-archive:
    post:
      tags:
      - Updates
      summary: Upload and extract a web.zip UI archive into storage
      parameters:
      - in: header
        name: X-PlatformIO-Upload
        required: false
        schema:
          type: string
        description: Optional header used by PlatformIO uploadweb script to bypass lock
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              required:
              - file
              properties:
                file:
                  type: string
                  format: binary
                  description: Minified web.zip archive
      responses:
        '200':
          description: Web UI updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StatusResponse'
        '403':
          description: Configuration mode disabled
        '500':
          description: Storage unavailable or extraction failed
  /ota/start:
    get:
      tags:
      - Updates
      summary: Initialize a firmware OTA upload session
      parameters:
      - in: query
        name: mode
        required: false
        schema:
          type: string
          enum:
          - fr
          default: fr
        description: OTA target mode ('fr' for firmware flash)
      - in: query
        name: hash
        required: false
        schema:
          type: string
        description: Optional 32-character hexadecimal MD5 checksum of the firmware binary
      - in: header
        name: X-PlatformIO-Upload
        required: false
        schema:
          type: string
        description: Optional header used by PlatformIO OTA upload script to bypass lock
      responses:
        '200':
          description: OTA session ready
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StatusResponse'
        '400':
          description: Invalid OTA mode or MD5 checksum format
        '403':
          description: Configuration mode disabled
        '409':
          description: Another OTA update is already in progress
  /ota/upload:
    post:
      tags:
      - Updates
      summary: Upload and flash a firmware binary via native ESP32 OTA
      parameters:
      - in: header
        name: X-PlatformIO-Upload
        required: false
        schema:
          type: string
        description: Optional header used by PlatformIO OTA upload script to bypass lock
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              required:
              - file
              properties:
                MD5:
                  type: string
                  description: Optional 32-character hexadecimal MD5 checksum
                file:
                  type: string
                  format: binary
                  description: Compiled firmware .bin image
      responses:
        '200':
          description: Firmware flashed successfully, device rebooting
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StatusResponse'
        '400':
          description: Empty firmware image or invalid request
        '403':
          description: Configuration mode disabled
        '500':
          description: OTA flash initialization, write, or verification failed
  /api/summary:
    get:
      tags:
      - Monitoring
      summary: Get monitored entities count summary
      responses:
        '200':
          description: Total, online, and offline counts
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SummaryResponse'
  /api/monitoredentities:
    get:
      tags:
      - Monitoring
      summary: List all monitored entities
      responses:
        '200':
          description: Array of monitored entities
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/MonitoredEntity'
  /api/monitoredentity/{name}:
    get:
      tags:
      - Monitoring
      summary: Get a monitored entity by name
      parameters:
      - in: path
        name: name
        required: true
        schema:
          type: string
        example: Router
      responses:
        '200':
          description: Monitored entity details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MonitoredEntity'
        '404':
          description: Entity not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    delete:
      tags:
      - Monitoring
      summary: Delete a monitored entity by name
      parameters:
      - in: path
        name: name
        required: true
        schema:
          type: string
        example: Router
      responses:
        '200':
          description: Entity deleted
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    example: deleted
        '403':
          description: Configuration mode disabled
        '404':
          description: Entity not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    put:
      tags:
      - Monitoring
      summary: Update an existing monitored entity
      parameters:
      - in: path
        name: name
        required: true
        schema:
          type: string
        example: Router
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MonitoredEntityInput'
      responses:
        '200':
          description: Entity updated
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    example: updated
        '400':
          description: Invalid JSON, name, or address
        '403':
          description: Configuration mode disabled
        '404':
          description: Entity not found
        '413':
          description: Payload Too Large (exceeds 4 KB)
        '415':
          description: Unsupported Media Type (application/json required)
  /api/monitoredentity:
    post:
      tags:
      - Monitoring
      summary: Add a new monitored entity
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MonitoredEntityInput'
      responses:
        '201':
          description: Entity created
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    example: created
        '400':
          description: Invalid JSON, name, or address
        '403':
          description: Configuration mode disabled
        '409':
          description: Entity with this name already exists
        '413':
          description: Payload Too Large (exceeds 4 KB)
        '415':
          description: Unsupported Media Type (application/json required)
  /api/health:
    get:
      tags:
      - System
      summary: Health check endpoint
      responses:
        '200':
          description: Device is up and responding
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HealthResponse'
  /api/sysinfo/details:
    get:
      tags:
      - System
      summary: Get detailed device, memory, storage, network, and firmware diagnostics
      responses:
        '200':
          description: Detailed system information
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DetailedSysinfo'
  /api/sysinfo:
    get:
      tags:
      - System
      summary: Get basic system metrics (heap, RSSI, uptime, temperature, version)
      responses:
        '200':
          description: Basic system information
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BasicSysinfo'
