openapi: 3.0.1
info:
  title: OpenWiFi Analytics Service
  description: Definitions and APIs to analyze OpenWiFi network.
  version: 2.7.0
  license:
    name: BSD3
    url: https://github.com/routerarchitects/ra-wlan-cloud-analytics/blob/main/LICENSE

servers:
  - url: 'https://openwifi.wlan.local:16009/api/v1'

security:
  - bearerAuth: []
  - ApiKeyAuth: []

components:
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-KEY
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT

  responses:
    NotFound:
      $ref: 'https://raw.githubusercontent.com/routerarchitects/ra-wlan-cloud-ucentralsec/main/openapi/owsec.yaml#/components/responses/NotFound'
    Unauthorized:
      $ref: 'https://raw.githubusercontent.com/routerarchitects/ra-wlan-cloud-ucentralsec/main/openapi/owsec.yaml#/components/responses/Unauthorized'
    Success:
      $ref: 'https://raw.githubusercontent.com/routerarchitects/ra-wlan-cloud-ucentralsec/main/openapi/owsec.yaml#/components/responses/Success'
    BadRequest:
      $ref: 'https://raw.githubusercontent.com/routerarchitects/ra-wlan-cloud-ucentralsec/main/openapi/owsec.yaml#/components/responses/BadRequest'
    CommonAnalyticsBadRequest:
      description: Invalid analytics request parameters.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/CommonAnalyticsBadRequestError'
          examples:
            invalidRouterId:
              value:
                error: invalid_router_id
                message: routerId must be a valid path-safe OWPROV gateway serial number (1 to 64 alphanumeric characters, hyphens, or underscores)
            invalidTimestamp:
              value:
                error: invalid_timestamp
                message: timestampTill must be a valid UTC timestamp in YYYY-MM-DDTHH:mm:ssZ format
            invalidLookbackHours:
              value:
                error: invalid_lookback_hours
                message: lookbackHours must be greater than 0 and less than or equal to the configured maximum lookback
            invalidQueryParameter:
              value:
                error: invalid_query_parameter
                message: "Unsupported query parameter: unexpectedParam"
            lookbackOutsideRetention:
              value:
                error: lookback_outside_retention
                message: Requested range is outside the configured monitoring retention window
    TemperatureAnalyticsBadRequest:
      description: Invalid request for radio temperature analytics.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/TemperatureBadRequestError'
          examples:
            invalidRouterId:
              value:
                error: invalid_router_id
                message: routerId must be a valid path-safe OWPROV gateway serial number (1 to 64 alphanumeric characters, hyphens, or underscores)
            invalidTimestamp:
              value:
                error: invalid_timestamp
                message: timestampTill must be a valid UTC timestamp in YYYY-MM-DDTHH:mm:ssZ format
            invalidLookbackHours:
              value:
                error: invalid_lookback_hours
                message: lookbackHours must be greater than 0 and less than or equal to the configured maximum lookback
            invalidQueryParameter:
              value:
                error: invalid_query_parameter
                message: "Unsupported query parameter: unexpectedParam"
            lookbackOutsideRetention:
              value:
                error: lookback_outside_retention
                message: Requested range is outside the configured monitoring retention window
    AvailabilityAnalyticsBadRequest:
      description: Invalid availability summary request.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/AvailabilityBadRequestError'
          examples:
            invalidRouterId:
              value:
                error: invalid_router_id
                message: routerId must be a valid path-safe OWPROV gateway serial number (1 to 64 alphanumeric characters, hyphens, or underscores)
            invalidTimestamp:
              value:
                error: invalid_timestamp
                message: timestampTill must be a valid UTC timestamp in YYYY-MM-DDTHH:mm:ssZ format
            invalidLookbackHours:
              value:
                error: invalid_lookback_hours
                message: lookbackHours must be greater than 0 and less than or equal to the configured maximum lookback
            invalidQueryParameter:
              value:
                error: invalid_query_parameter
                message: "Unsupported query parameter: unexpectedParam"
            lookbackOutsideRetention:
              value:
                error: lookback_outside_retention
                message: Requested range is outside the configured monitoring retention window
    AnalyticsUnauthorized:
      description: Bearer token is missing, invalid, or expired.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/AnalyticsUnauthorizedError'
          examples:
            unauthorized:
              value:
                error: unauthorized
                message: Missing, invalid, or expired bearer token
    AnalyticsNotFound:
      description: Router was not found, caller cannot access it, or monitoring is not configured for the resolved router scope. Public 404 responses for inventory missing, empty venue, board not configured, and access denied are intentionally collapsed to not_found unless monitoring is not configured.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/AnalyticsNotFoundError'
          examples:
            notFound:
              value:
                error: not_found
                message: Router was not found
            monitoringNotConfigured:
              value:
                error: monitoring_not_configured
                message: Monitoring is not configured for this router scope
    AnalyticsConflict:
      description: Monitoring is disabled or router ownership resolution found conflicting current board mappings.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/AnalyticsConflictError'
          examples:
            monitoringDisabled:
              value:
                error: monitoring_disabled
                message: Monitoring is disabled for this router scope
            multipleBoards:
              value:
                error: multiple_boards
                message: Router is mapped to multiple current boards
    MemorySummaryInternalError:
      description: Memory summary retrieval failed.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/MemorySummaryInternalError'
          examples:
            memorySummaryFailed:
              value:
                error: memory_summary_query_failed
                message: Unable to retrieve gateway memory history
            internalError:
              value:
                error: internal_error
                message: Internal error
    RadioTemperatureSummaryInternalError:
      description: Radio temperature summary retrieval failed.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/RadioTemperatureSummaryInternalError'
          examples:
            radioTemperatureSummaryFailed:
              value:
                error: radio_temperature_summary_query_failed
                message: Unable to retrieve gateway radio temperature history
            internalError:
              value:
                error: internal_error
                message: Internal error
    WifiClientUsageInternalError:
      description: Wi-Fi client usage summary retrieval failed.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/WifiClientUsageInternalError'
          examples:
            wifiClientUsageFailed:
              value:
                error: wifi_client_usage_query_failed
                message: Unable to retrieve Wi-Fi client usage history
            internalError:
              value:
                error: internal_error
                message: Internal error
    WifiClientRssiInternalError:
      description: Wi-Fi client RSSI summary retrieval failed.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/WifiClientRssiInternalError'
          examples:
            wifiClientRssiFailed:
              value:
                error: wifi_client_rssi_query_failed
                message: Unable to retrieve Wi-Fi client RSSI history
            internalError:
              value:
                error: internal_error
                message: Internal error
    AvailabilityInternalError:
      description: Availability summary retrieval failed.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/AvailabilityInternalError'
          examples:
            availabilityQueryFailed:
              value:
                error: availability_query_failed
                message: Unable to retrieve gateway availability history
            internalError:
              value:
                error: internal_error
                message: Internal error
    AnalyticsBadGateway:
      description: Upstream provisioning service is unavailable or returned an invalid response after cache fallback was exhausted.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/AnalyticsBadGatewayError'
          examples:
            owprovUnavailable:
              value:
                error: owprov_unavailable
                message: Upstream provisioning service is unavailable
            owprovInvalidResponse:
              value:
                error: owprov_invalid_response
                message: Upstream provisioning service returned an invalid response

  parameters:
    RouterIdPath:
      in: path
      name: routerId
      required: true
      description: Gateway serial number accepted by OWPROV inventory. Path-safe serial identifiers (1 to 64 alphanumeric characters, hyphens, and underscores; free of path separators and dot-segments) are accepted by syntax validation and resolved via OWPROV. Values containing path dot-segments, path separators, spaces, control characters, or invalid encoded path separators are rejected before OWPROV ownership resolution.
      schema:
        $ref: '#/components/schemas/RouterId'
    TimestampTill:
      in: query
      name: timestampTill
      description: Exclusive UTC upper bound for the summary window. The raw query collection must contain timestampTill exactly once. The value must match YYYY-MM-DDTHH:mm:ssZ, must be semantically parsed as a real UTC date-time, and must reject invalid dates or times such as 2026-99-99T88:77:66Z. Missing timezones, fractional seconds, timezone offsets such as +05:30, repeated values, and timestamps beyond the configured server clock-skew tolerance are invalid.
      schema:
        $ref: '#/components/schemas/TimestampTill'
      required: true
    LookbackHours:
      in: query
      name: lookbackHours
      description: >
        Number of hours to look back from timestampTill. Must be greater than 0 and less than or equal to
        maxLookbackHours, where maxLookbackHours is bounded by the configured board retention (monitoringDuration / 3600)
        up to an absolute maximum API safety limit of 87600 hours (10 years); the resulting half-open range must fit inside
        the configured retention window. Handlers must parse the raw HTTP query parameter collection to ensure lookbackHours
        appears exactly once and reject repeated, empty, fractional, partially numeric, overflowing, zero, and negative values.
      schema:
        type: integer
        format: int32
        minimum: 1
        maximum: 87600
        example: 24
      required: true
  schemas:
    RouterId:
      type: string
      minLength: 1
      maxLength: 64
      pattern: '^[a-zA-Z0-9_-]+$'
      description: Path-safe gateway serial number. Path separators, dot-segments, spaces, control characters, and invalid encoded path separators are rejected.
      example: "dc6279652334"

    TimestampTill:
      type: string
      format: date-time
      pattern: '^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}Z$'
      description: Strict RFC3339 UTC timestamp in YYYY-MM-DDTHH:mm:ssZ format. Timezone offsets, missing timezone, fractional seconds, invalid calendar dates or times, and timestamps beyond configured server clock-skew tolerance are rejected.
      example: "2026-07-27T12:00:00Z"

    RequestedWindow:
      type: object
      description: Exact requested half-open interval [startTime, endTime).
      required:
        - startTime
        - endTime
      properties:
        startTime:
          type: string
          format: date-time
        endTime:
          type: string
          format: date-time

    ObservedWindow:
      type: object
      description: >
        Actual earliest/latest persisted sample or event timestamps that contributed to the result.
        startTime and endTime are both null when no valid persisted data contributes to the result;
        otherwise both timestamps are populated.
      required:
        - startTime
        - endTime
      oneOf:
        - properties:
            startTime:
              type: string
              format: date-time
            endTime:
              type: string
              format: date-time
        - properties:
            startTime:
              type: string
              nullable: true
              enum:
                - null
            endTime:
              type: string
              nullable: true
              enum:
                - null

    MacAddress:
      type: string
      pattern: '^[0-9a-f]{2}(:[0-9a-f]{2}){5}$'
      description: Canonical lowercase colon-separated MAC address.
      example: "e2:51:95:ed:0f:28"

    ObjectInfo:
      type: object
      properties:
        id:
          type: string
          format: uuid
        name:
          type: string
        description:
          type: string
        notes:
          type: array
          items:
            $ref: '#/components/schemas/NoteInfo'
        created:
          type: integer
          format: int64
        modified:
          type: integer
          format: int64
        tags:
          type: array
          items:
            type: integer
            format: int64

    VenueInfo:
      type: object
      properties:
        id:
          type: string
          format: uuid
        name:
          type: string
        description:
          type: string
        retention:
          type: integer
        interval:
          type: integer
        monitorSubVenues:
          type: boolean

    BoardInfo:
      allOf:
        - $ref: '#/components/schemas/ObjectInfo'
        - type: object
          properties:
            venueList:
              type: array
              items:
                $ref: '#/components/schemas/VenueInfo'

    BoardInfoList:
      type: object
      properties:
        boards:
          type: array
          items:
            $ref: '#/components/schemas/BoardInfo'
 
    DeviceInfo:
      type: object
      properties:
        boardId:
          type: string
          format: uuid
        type:
          type: string
          enum:
            - ap
            - switch
            - iot
            - unknown
        serialNumber:
          type: string
        deviceType:
          type: string
        platform:
          type: string
        lastHealth:
          type: integer
          format: int64
        health:
          type: integer
          format: int64
        lastContact:
          type: integer
          format: int64
        lastPing:
          type: integer
          format: int64
        lastState:
          type: integer
          format: int64
        lastFirmwareUpdate:
          type: integer
          format: int64
        lastFirmware:
          type: string
        lastConnection:
          type: integer
          format: int64
        lastDisconnection:
          type: integer
          format: int64
        pings:
          type: integer
          format: int64
        states:
          type: integer
          format: int64
        connected:
          type: boolean
        connectionIp:
          type: string
        associations_2g:
          type: integer
          format: int64
        associations_5g:
          type: integer
          format: int64
        associations_6g:
          type: integer
          format: int64
        locale:
          type: string
        memory:
          type: number
        uptime:
          type: integer
          format: int64

    DeviceInfoList:
      type: object
      properties:
        devices:
          type: array
          items:
            $ref: '#/components/schemas/DeviceInfo'

    TIDstat_entry:
      type: object
      properties:
        rx_msdu:
          type: integer
          format: int64
        tx_msdu:
          type: integer
          format: int64
        tx_msdu_failed:
          type: integer
          format: int64
        tx_msdu_retries:
          type: integer
          format: int64

    UE_rate:
      type: object
      properties:
        bitrate:
          type: integer
          format: int64
        mcs:
          type: integer
          format: int64
        nss:
          type: integer
          format: int64
        chwidth:
          type: integer
          format: int64
        ht:
          type: boolean
        sgi:
          type: boolean

    Fingerprint:
      type: object
      additionalProperties: true

    UETimePoint:
      type: object
      properties:
        association_bssid:
          type: string
        station:
          type: string
        fingerprint:
          $ref: '#/components/schemas/Fingerprint'
        rssi:
          type: integer
          format: int64
        tx_bytes:
          type: integer
          format: int64
        rx_bytes:
          type: integer
          format: int64
        tx_duration:
          type: integer
          format: int64
        rx_packets:
          type: integer
          format: int64
        tx_packets:
          type: integer
          format: int64
        tx_retries:
          type: integer
          format: int64
        tx_failed:
          type: integer
          format: int64
        connected:
          type: integer
          format: int64
        inactive:
          type: integer
          format: int64
        tx_rate:
          $ref: '#/components/schemas/UE_rate'
        rx_rate:
          $ref: '#/components/schemas/UE_rate'
        tidstats:
          type: array
          items:
            $ref: '#/components/schemas/TIDstat_entry'
        tx_bytes_bw:
          type: number
        rx_bytes_bw:
          type: number
        tx_packets_bw:
          type: number
        rx_packets_bw:
          type: number
        tx_failed_pct:
          type: number
        tx_retries_pct:
          type: number
        tx_duration_pct:
          type: number
        tx_bytes_delta:
          type: integer
          format: int64
        rx_bytes_delta:
          type: integer
          format: int64
        tx_packets_delta:
          type: integer
          format: int64
        rx_packets_delta:
          type: integer
          format: int64
        tx_failed_delta:
          type: integer
          format: int64
        tx_retries_delta:
          type: integer
          format: int64
        tx_duration_delta:
          type: integer
          format: int64

    AveragePoint:
      type: object
      properties:
        min:
          type: number
        max:
          type: number
        avg:
          type: number

    SSIDTimePoint:
      type: object
      properties:
        bssid:
          type: string
        mode:
          type: string
        ssid:
          type: string
        band:
          type: integer
        associations:
          type: array
          items:
            $ref: '#/components/schemas/UETimePoint'
        tx_bytes_bw:
          $ref: '#/components/schemas/AveragePoint'
        rx_bytes_bw:
          $ref: '#/components/schemas/AveragePoint'
        tx_packets_bw:
          $ref: '#/components/schemas/AveragePoint'
        rx_packets_bw:
          $ref: '#/components/schemas/AveragePoint'
        tx_failed_pct:
          $ref: '#/components/schemas/AveragePoint'
        tx_retries_pct:
          $ref: '#/components/schemas/AveragePoint'
        tx_duration_pct:
          $ref: '#/components/schemas/AveragePoint'

    APTimePoint:
      type: object
      properties:
        collisions:
          type: integer
          format: int64
        multicast:
          type: integer
          format: int64
        rx_bytes:
          type: integer
          format: int64
        rx_dropped:
          type: integer
          format: int64
        rx_errors:
          type: integer
          format: int64
        rx_packets:
          type: integer
          format: int64
        tx_bytes:
          type: integer
          format: int64
        tx_dropped:
          type: integer
          format: int64
        tx_errors:
          type: integer
          format: int64
        tx_packets:
          type: integer
          format: int64
        tx_bytes_delta:
          type: integer
          format: int64
        rx_bytes_delta:
          type: integer
          format: int64
        rx_dropped_delta:
          type: integer
          format: int64
        tx_dropped_delta:
          type: integer
          format: int64
        rx_packets_delta:
          type: integer
          format: int64
        tx_packets_delta:
          type: integer
          format: int64
        rx_errors_delta:
          type: integer
          format: int64
        tx_errors_delta:
          type: integer
          format: int64

    DeviceResourceTimePoint:
      type: object
      description: Stored device resource telemetry including unsigned memory metrics.
      properties:
        memory_free:
          type: integer
          minimum: 0
          maximum: 18446744073709551615
          nullable: true
          description: Available free memory in bytes.
        memory_total:
          type: integer
          minimum: 0
          maximum: 18446744073709551615
          nullable: true
          description: Total system memory in bytes.
        memory_cached:
          type: integer
          minimum: 0
          maximum: 18446744073709551615
          nullable: true
          description: Cached memory in bytes.
        memory_buffered:
          type: integer
          minimum: 0
          maximum: 18446744073709551615
          nullable: true
          description: Buffered memory in bytes.

    RadioTimePoint:
      type: object
      properties:
        band:
          type: integer
          format: int64
        radio_channel:
          type: integer
          format: int64
        active_ms:
          type: integer
          format: int64
        busy_ms:
          type: integer
          format: int64
        receive_ms:
          type: integer
          format: int64
        transmit_ms:
          type: integer
          format: int64
        tx_power:
          type: integer
          format: int64
        channel:
          type: integer
          format: int64
        temperature:
          type: number
          format: double
          nullable: true
          description: Wi-Fi radio temperature in degrees Celsius. Null or missing values are ignored by radio-temperature-summary aggregation. A reported 0°C value is a valid numeric temperature reading and must not be interpreted as unavailable or missing.
        noise:
          type: integer
          format: int64
        active_pct:
          type: number
        busy_pct:
          type: number
        receive_pct:
          type: number
        transmit_pct:
          type: number

    DeviceTimePoint:
      type: object
      properties:
        id:
          type: string
          format: uuid
        boardId:
          type: string
          format: uuid
        serialNumber:
          type: string
        timestamp:
          type: integer
          format: int64
        ap_data:
          $ref: '#/components/schemas/APTimePoint'
        ssid_data:
          type: array
          items:
            $ref: '#/components/schemas/SSIDTimePoint'
        radio_data:
          type: array
          items:
            $ref: '#/components/schemas/RadioTimePoint'
        device_info:
          $ref: '#/components/schemas/DeviceInfo'
        resource_data:
          $ref: '#/components/schemas/DeviceResourceTimePoint'

    DeviceTimePointAnalysis:
      type: object
      properties:
        timestamp:
          type: integer
          format: int64
          description: Start (or representative time) of the aggregation window
        noise:
          $ref: '#/components/schemas/AveragePoint'
        active_pct:
          $ref: '#/components/schemas/AveragePoint'
        busy_pct:
          $ref: '#/components/schemas/AveragePoint'
        receive_pct:
          $ref: '#/components/schemas/AveragePoint'
        transmit_pct:
          $ref: '#/components/schemas/AveragePoint'
        tx_power:
          $ref: '#/components/schemas/AveragePoint'
        tx_bytes_bw:
          $ref: '#/components/schemas/AveragePoint'
        rx_bytes_bw:
          $ref: '#/components/schemas/AveragePoint'
        rx_dropped_pct:
          $ref: '#/components/schemas/AveragePoint'
        tx_dropped_pct:
          $ref: '#/components/schemas/AveragePoint'
        rx_packets_bw:
          $ref: '#/components/schemas/AveragePoint'
        tx_packets_bw:
          $ref: '#/components/schemas/AveragePoint'
        rx_errors_pct:
          $ref: '#/components/schemas/AveragePoint'
        tx_errors_pct:
          $ref: '#/components/schemas/AveragePoint'

    DeviceTimePointList:
      type: object
      properties:
        points:
          type: array
          items:
            type: array
            items:
              $ref: '#/components/schemas/DeviceTimePoint'
        stats:
          type: array
          items:
            $ref: '#/components/schemas/DeviceTimePointAnalysis'

    DeviceTimePointStats:
      type: object
      properties:
        firstPoint:
          type: integer
          format: int64
        lastPoint:
          type: integer
          format: int64
        count:
          type: integer
          format: int64

    WifiClientHistory:
      type: object
      properties:
        timestamp:
          type: integer
        station_id:
          type: string
        bssid:
          type: string
        ssid:
          type: string
        rssi:
          type: integer
        rx_bitrate:
          type: integer
        rx_chwidth:
          type: integer
        rx_mcs:
          type: integer
        rx_nss:
          type: integer
        rx_vht:
          type: boolean
        tx_bitrate:
          type: integer
        tx_chwidth:
          type: integer
        tx_mcs:
          type: integer
        tx_nss:
          type: integer
        tx_vht:
          type: boolean
        rx_bytes:
          type: integer
        tx_bytes:
          type: integer
        rx_duration:
          type: integer
        tx_duration:
          type: integer
        rx_packets:
          type: integer
        tx_packets:
          type: integer
        ipv4:
          type: string
        ipv6:
          type: string
        channel_width:
          type: integer
        noise:
          type: integer
        tx_power:
          type: integer
        channel:
          type: integer
        active_ms:
          type: integer
        busy_ms:
          type: integer
        receive_ms:
          type: integer
        mode:
          type: string
        ack_signal:
          type: integer
        ack_signal_avg:
          type: integer
        connected:
          type: integer
        inactive:
          type: integer
        tx_retries:
          type: integer
        venue_id:
          type: string

    WifiClientHistoryList:
      type: object
      properties:
        entries:
          type: array
          items:
            $ref: '#/components/schemas/WifiClientHistory'

    MacList:
      type: object
      properties:
        entries:
          type: array
          items:
            type: string

    ExtraSystemConfiguration:
      type: object
      properties:
        parameterName:
          type: string
        parameterValue:
          type: string

    #########################################################################################
    ##
    ## These are endpoints that all services in the OPenWiFI stack must provide
    ##
    #########################################################################################
    AnyPayload:
      type: object
      properties:
        Document:
          type: string

    StringList:
      type: object
      properties:
        list:
          type: array
          items:
            type: string

    ExtraConfigurationStatus:
      type: object
      properties:
        additionalConfiguration:
          type: boolean
          description: Indicates whether additional configuration is enabled

    TagValuePair:
      type: object
      properties:
        tag:
          type: string
        value:
          type: string

    TagValuePairList:
      type: object
      properties:
        tagList:
          type: array
          items:
            $ref: '#/components/schemas/TagValuePair'

    TagIntPair:
      type: object
      properties:
        tag:
          type: string
        value:
          type: integer
          format: int64

    TagIntPairList:
      type: object
      properties:
        tagList:
          type: array
          items:
            $ref: '#/components/schemas/TagIntPair'

    CommonAnalyticsBadRequestError:
      type: object
      required:
        - error
        - message
      properties:
        error:
          type: string
          enum:
            - invalid_router_id
            - invalid_timestamp
            - invalid_lookback_hours
            - invalid_query_parameter
            - lookback_outside_retention
        message:
          type: string

    TemperatureBadRequestError:
      type: object
      required:
        - error
        - message
      properties:
        error:
          type: string
          enum:
            - invalid_router_id
            - invalid_timestamp
            - invalid_lookback_hours
            - invalid_query_parameter
            - lookback_outside_retention
        message:
          type: string

    AvailabilityBadRequestError:
      type: object
      required:
        - error
        - message
      properties:
        error:
          type: string
          enum:
            - invalid_router_id
            - invalid_timestamp
            - invalid_lookback_hours
            - invalid_query_parameter
            - lookback_outside_retention
        message:
          type: string

    AnalyticsUnauthorizedError:
      type: object
      required:
        - error
        - message
      properties:
        error:
          type: string
          enum:
            - unauthorized
        message:
          type: string

    AnalyticsNotFoundError:
      type: object
      required:
        - error
        - message
      properties:
        error:
          type: string
          enum:
            - not_found
            - monitoring_not_configured
        message:
          type: string

    AnalyticsConflictError:
      type: object
      required:
        - error
        - message
      properties:
        error:
          type: string
          enum:
            - monitoring_disabled
            - multiple_boards
        message:
          type: string

    AnalyticsBadGatewayError:
      type: object
      required:
        - error
        - message
      properties:
        error:
          type: string
          enum:
            - owprov_unavailable
            - owprov_invalid_response
        message:
          type: string

    MemorySummaryInternalError:
      type: object
      required:
        - error
        - message
      properties:
        error:
          type: string
          enum:
            - memory_summary_query_failed
            - internal_error
        message:
          type: string

    RadioTemperatureSummaryInternalError:
      type: object
      required:
        - error
        - message
      properties:
        error:
          type: string
          enum:
            - radio_temperature_summary_query_failed
            - internal_error
        message:
          type: string

    WifiClientUsageInternalError:
      type: object
      required:
        - error
        - message
      properties:
        error:
          type: string
          enum:
            - wifi_client_usage_query_failed
            - internal_error
        message:
          type: string

    WifiClientRssiInternalError:
      type: object
      required:
        - error
        - message
      properties:
        error:
          type: string
          enum:
            - wifi_client_rssi_query_failed
            - internal_error
        message:
          type: string

    AvailabilityInternalError:
      type: object
      required:
        - error
        - message
      properties:
        error:
          type: string
          enum:
            - availability_query_failed
            - internal_error
        message:
          type: string

    GatewayMemorySummary:
      type: object
      description: >
        Gateway free memory summary in bytes. Memory statistics are arithmetic aggregations of
        stored memory_free samples whose timestamps fall within the requested half-open window.
        They are not time-weighted. When samples exist, all values are nonnegative and satisfy
        min_memfree <= avg_memfree <= max_memfree. When no valid memory samples exist, all three
        fields are null.
      required:
        - requestedWindow
        - observedWindow
        - min_memfree
        - max_memfree
        - avg_memfree
      properties:
        requestedWindow:
          $ref: '#/components/schemas/RequestedWindow'
        observedWindow:
          $ref: '#/components/schemas/ObservedWindow'
        min_memfree:
          type: integer
          minimum: 0
          maximum: 18446744073709551615
          nullable: true
          description: Minimum reported free memory in bytes for the requested aggregation window.
        max_memfree:
          type: integer
          minimum: 0
          maximum: 18446744073709551615
          nullable: true
          description: Maximum reported free memory in bytes for the requested aggregation window.
        avg_memfree:
          type: number
          format: double
          minimum: 0
          maximum: 18446744073709551615
          nullable: true
          description: Arithmetic average of reported free-memory samples in bytes for the requested aggregation window.

    GatewayWifiTemperatureSummary:
      type: object
      description: >
        Wi-Fi radio temperature summary envelope. requestedWindow and observedWindow are returned
        in meta. Temperature statistics are returned in data.
      required:
        - data
        - meta
      properties:
        meta:
          type: object
          required:
            - requestedWindow
            - observedWindow
          properties:
            requestedWindow:
              $ref: '#/components/schemas/RequestedWindow'
            observedWindow:
              $ref: '#/components/schemas/ObservedWindow'
        data:
          $ref: '#/components/schemas/GatewayWifiTemperatureSummaryData'

    GatewayWifiTemperatureSummaryData:
      type: object
      description: >
        Wi-Fi radio temperature summary metrics. The 2.4 GHz JSON property names intentionally
        use the dotted `2.4G` suffix to match the MCP API wire contract; clients should treat
        these as literal JSON keys, not property paths. Temperature statistics are arithmetic
        aggregations of valid radio temperature samples whose timestamps fall within the
        requested half-open window. They are not time-weighted. For gateways with multiple
        radios in the same band, all valid samples for that band are combined directly rather
        than averaging each radio first. Null applies independently per band: a band returns
        null min, max, average, and latest values when that band has no valid temperature samples,
        even if another band has samples. A valid radio temperature sample is a present,
        finite Celsius value where -40 <= temperature <= 125. A reported 0°C value is valid
        and participates in aggregation. Missing, null, non-numeric, NaN, infinite, 255, and
        out-of-range values are excluded from aggregation.
      required:
        - min_wifi_temp_2.4G
        - max_wifi_temp_2.4G
        - avg_wifi_temp_2.4G
        - latest_wifi_temp_2.4G
        - min_wifi_temp_5G
        - max_wifi_temp_5G
        - avg_wifi_temp_5G
        - latest_wifi_temp_5G
      properties:
        min_wifi_temp_2.4G:
          type: number
          format: double
          minimum: -40
          maximum: 125
          nullable: true
          description: Minimum reported 2.4 GHz Wi-Fi radio temperature in degrees Celsius for the effective aggregation window. Literal MCP JSON key; dotted suffix is required for compatibility.
        max_wifi_temp_2.4G:
          type: number
          format: double
          minimum: -40
          maximum: 125
          nullable: true
          description: Maximum reported 2.4 GHz Wi-Fi radio temperature in degrees Celsius for the effective aggregation window. Literal MCP JSON key; dotted suffix is required for compatibility.
        avg_wifi_temp_2.4G:
          type: number
          format: double
          minimum: -40
          maximum: 125
          nullable: true
          description: Arithmetic average of reported 2.4 GHz Wi-Fi radio temperature samples in degrees Celsius for the effective aggregation window. Literal MCP JSON key; dotted suffix is required for compatibility.
        latest_wifi_temp_2.4G:
          type: number
          format: double
          minimum: -40
          maximum: 125
          nullable: true
          description: Latest valid 2.4 GHz Wi-Fi radio temperature sample in degrees Celsius for the effective aggregation window. Literal MCP JSON key; dotted suffix is required for compatibility.
        min_wifi_temp_5G:
          type: number
          format: double
          minimum: -40
          maximum: 125
          nullable: true
          description: Minimum reported 5 GHz Wi-Fi radio temperature in degrees Celsius for the effective aggregation window.
        max_wifi_temp_5G:
          type: number
          format: double
          minimum: -40
          maximum: 125
          nullable: true
          description: Maximum reported 5 GHz Wi-Fi radio temperature in degrees Celsius for the effective aggregation window.
        avg_wifi_temp_5G:
          type: number
          format: double
          minimum: -40
          maximum: 125
          nullable: true
          description: Arithmetic average of reported 5 GHz Wi-Fi radio temperature samples in degrees Celsius for the effective aggregation window.
        latest_wifi_temp_5G:
          type: number
          format: double
          minimum: -40
          maximum: 125
          nullable: true
          description: Latest valid 5 GHz Wi-Fi radio temperature sample in degrees Celsius for the effective aggregation window.

    ClientBandwidthConsumption:
      type: object
      description: >
        Per-client usage totals. Raw byte counters are authoritative; total_bytes is always
        rx_bytes + tx_bytes. Formatted string fields are display-only decimal megabytes using
        bytes / 1,000,000, formatted with standard floating point two decimal places
        and the literal " MB" suffix. Wi-Fi usage is a cumulative-counter
        differential summary calculated from valid persisted samples available to Analytics. The
        implementation may use internal streams, sessions, boundary samples, reset detection, and
        segments to calculate safe deltas, but those mechanics are not part of the public response.
      required:
        - mac
        - rx_bytes
        - tx_bytes
        - total_bytes
        - data_consume_rx
        - data_consume_tx
        - total_data_usage
      properties:
        mac:
          $ref: '#/components/schemas/MacAddress'
        rx_bytes:
          type: integer
          minimum: 0
          maximum: 18446744073709551615
        tx_bytes:
          type: integer
          minimum: 0
          maximum: 18446744073709551615
        total_bytes:
          type: integer
          minimum: 0
          maximum: 18446744073709551615
        data_consume_rx:
          type: string
          description: Display-only decimal megabytes derived from rx_bytes / 1,000,000. Format using standard floating point two decimal places and the literal " MB" suffix. Use raw byte fields for calculations.
          example: 106.49 MB
        data_consume_tx:
          type: string
          description: Display-only decimal megabytes derived from tx_bytes / 1,000,000. Format using standard floating point two decimal places and the literal " MB" suffix. Use raw byte fields for calculations.
          example: 3.85 MB
        total_data_usage:
          type: string
          description: Display-only decimal megabytes derived from total_bytes / 1,000,000. Format using standard floating point two decimal places and the literal " MB" suffix. Use raw byte fields for calculations.
          example: 110.34 MB
    ClientBandwidthConsumptionData:
      type: object
      description: >
        Wi-Fi usage differential summary data calculated from persisted samples currently
        available to Analytics.
      required:
        - items
        - totalClients
        - truncated
      properties:
        items:
          type: array
          maxItems: 500
          description: >
            Clients ordered by total_bytes descending. Clients with equal
            total_bytes are ordered by normalized MAC address ascending.
            Only the first 500 clients are returned.
          items:
            $ref: '#/components/schemas/ClientBandwidthConsumption'
        totalClients:
          type: integer
          minimum: 0
          description: Total number of distinct client MAC addresses having at least one in-window observation or proven session overlap during the requested interval [startTime, endTime), calculated before applying the 500-client limit. Outside-window samples may be used internally as boundary calculation aids for eligible clients.
        truncated:
          type: boolean
          description: True when totalClients is greater than the number of returned items.

    ClientBandwidthConsumptionResponse:
      type: object
      description: >
        Wrapped Wi-Fi usage differential summary. requestedWindow is the requested interval
        returned in meta. observedWindow is the earliest/latest persisted sample timestamp used
        by any returned client calculation, or null/null when no valid sample contributes.
        Usage items and counts are returned in data.
      required:
        - data
        - meta
      properties:
        meta:
          type: object
          required:
            - requestedWindow
            - observedWindow
          properties:
            requestedWindow:
              $ref: '#/components/schemas/RequestedWindow'
            observedWindow:
              $ref: '#/components/schemas/ObservedWindow'
        data:
          $ref: '#/components/schemas/ClientBandwidthConsumptionData'

    ClientRssiQuality:
      type: object
      description: >
        Per-client RSSI quality percentages calculated from valid RSSI samples only. RSSI
        categories use dBm thresholds: excellent is RSSI >= -55, good is -67 <= RSSI < -55,
        fair is -75 <= RSSI < -67, and poor is RSSI < -75. RSSI values of 0, positive RSSI
        values, values below -127, missing RSSI values, and malformed station MAC addresses
        are excluded. Supported station MAC inputs are colon-separated, hyphen-separated,
        Cisco-style dotted, or unseparated 12-digit hexadecimal strings; malformed or mixed
        separator representations are ignored. Clients with no valid RSSI samples are
        omitted. Percentages use valid samples as the denominator and are independently
        rounded to two decimal places, so they may sum to slightly above or below 100 because
        of rounding.
      required:
        - mac
        - rssi_excellent_pct
        - rssi_good_pct
        - rssi_fair_pct
        - rssi_poor_pct
        - rssi_total_samples
      properties:
        mac:
          $ref: '#/components/schemas/MacAddress'
        rssi_excellent_pct:
          type: number
          format: double
          minimum: 0
          maximum: 100
          description: Percentage of valid RSSI samples where RSSI >= -55 dBm.
        rssi_good_pct:
          type: number
          format: double
          minimum: 0
          maximum: 100
          description: Percentage of valid RSSI samples where -67 dBm <= RSSI < -55 dBm.
        rssi_fair_pct:
          type: number
          format: double
          minimum: 0
          maximum: 100
          description: Percentage of valid RSSI samples where -75 dBm <= RSSI < -67 dBm.
        rssi_poor_pct:
          type: number
          format: double
          minimum: 0
          maximum: 100
          description: Percentage of valid RSSI samples where -127 dBm <= RSSI < -75 dBm.
        rssi_total_samples:
          type: integer
          format: int64
          minimum: 1
          description: Number of valid RSSI samples used as the denominator for the percentage fields.

    ClientRssiQualityData:
      type: object
      description: >
        Wi-Fi RSSI quality summary data calculated from persisted samples currently
        available to Analytics.
      required:
        - items
        - totalClients
        - truncated
      properties:
        items:
          type: array
          maxItems: 500
          description: >
            Clients ordered by normalized MAC address ascending.
            Only the first 500 clients are returned.
          items:
            $ref: '#/components/schemas/ClientRssiQuality'
        totalClients:
          type: integer
          minimum: 0
          description: Total number of distinct client MAC addresses having at least one valid RSSI sample in the requested interval, calculated before applying the 500-client limit.
        truncated:
          type: boolean
          description: True when totalClients is greater than the number of returned items.

    ClientRssiQualityResponse:
      type: object
      description: >
        Wrapped RSSI quality summary. requestedWindow is the requested interval
        returned in meta. observedWindow is derived from the earliest/latest valid
        persisted RSSI samples contributing to returned items after applying the
        500-client response limit. When no clients are returned, data.items is
        empty, data.totalClients is 0, data.truncated is false, and
        meta.observedWindow is null/null.
      required:
        - meta
        - data
      properties:
        meta:
          type: object
          required:
            - requestedWindow
            - observedWindow
          properties:
            requestedWindow:
              $ref: '#/components/schemas/RequestedWindow'
            observedWindow:
              $ref: '#/components/schemas/ObservedWindow'
        data:
          $ref: '#/components/schemas/ClientRssiQualityData'

    GatewayAvailabilityMeta:
      type: object
      description: Metadata for observed persisted availability events used by the response.
      required:
        - requestedWindow
        - observedWindow
      properties:
        requestedWindow:
          $ref: '#/components/schemas/RequestedWindow'
        observedWindow:
          $ref: '#/components/schemas/ObservedWindow'

    GatewayAvailabilityData:
      type: object
      description: Gateway offline transition count calculated from persisted availability events.
      required:
        - gw_uuid
        - fetch_status
        - offlineEventCount
      properties:
        gw_uuid:
          $ref: '#/components/schemas/RouterId'
        fetch_status:
          type: string
          enum:
            - success
          description: Status string for availability data retrieval; always "success" in HTTP 200 responses.
          example: success
        offlineEventCount:
          type: integer
          format: int64
          minimum: 0
          description: Number of persisted offline transition rows matching the requested gateway and half-open interval in Analytics storage.

    GatewayAvailabilitySummaryResponse:
      type: object
      description: >
        Wrapped gateway availability summary response. The endpoint counts persisted offline
        transition rows in device_availability_events for the requested half-open interval and reports the
        observed event-time window for matching rows.
      required:
        - meta
        - data
      properties:
        meta:
          $ref: '#/components/schemas/GatewayAvailabilityMeta'
        data:
          $ref: '#/components/schemas/GatewayAvailabilityData'

    SystemCommandDetails:
      type: object
      properties:
        command:
          type: string
          enum:
            - setloglevels
            - getloglevels
            - getSubSystemNames
            - getLogLevelNames
            - stats
        parameters:
          oneOf:
            - $ref: '#/components/schemas/StringList'
            - $ref: '#/components/schemas/TagValuePairList'

    NoteInfo:
      type: object
      properties:
        created:
          type: integer
          format: int64
        createdBy:
          type: string
        note:
          type: string

    SystemInfoResults:
      type: object
      properties:
        version:
          type: string
        uptime:
          type: integer
          format: int64
        start:
          type: integer
          format: int64
        os:
          type: string
        processors:
          type: integer
        hostname:
          type: string
        certificates:
          type: array
          items:
            type: object
            properties:
              filename:
                type: string
              expires:
                type: integer
                format: int64

    SystemResources:
      type: object
      properties:
        numberOfFileDescriptors:
          type: integer
          format: int64
        currRealMem:
          type: integer
          format: int64
        peakRealMem:
          type: integer
          format: int64
        currVirtMem:
          type: integer
          format: int64
        peakVirtMem:
          type: integer
          format: int64

    SystemCommandResults:
      type: object
      oneOf:
        - $ref: '#/components/schemas/SystemResources'
        - $ref: '#/components/schemas/SystemInfoResults'
        - $ref: '#/components/schemas/StringList'
        - $ref: '#/components/schemas/TagValuePairList'
        - $ref: '#/components/schemas/ExtraConfigurationStatus' 

    Dashboard:
      type: object
      properties:
        snapshot:
          type: integer
          format: int64
        tenants:
          $ref: '#/components/schemas/TagIntPairList'

    SystemCommandSetLogLevel:
      type: object
      properties:
        command:
          type: string
          enum:
            - setloglevel
        subsystems:
          type: array
          items:
            $ref: '#/components/schemas/TagValuePair'

    SystemCommandReload:
      type: object
      properties:
        command:
          type: string
          enum:
            - reload
        subsystems:
          type: array
          items:
            type: string
            example: these are the SubSystems names retrieve with the GetSubSystemsNamesResult.

    SystemCommandGetLogLevels:
      type: object
      properties:
        command:
          type: string
          enum:
            - getloglevels

    SystemGetLogLevelsResult:
      type: object
      properties:
        taglist:
          type: array
          items:
            $ref: '#/components/schemas/TagValuePair'

    SystemCommandGetLogLevelNames:
      type: object
      properties:
        command:
          type: string
          enum:
            - getloglevelnames

    SystemCommandGetSubsystemNames:
      type: object
      properties:
        command:
          type: string
          enum:
            - getsubsystemnames

    SystemCommandGetLogLevelNamesResult:
      type: object
      properties:
        list:
          type: array
          items:
            type: string

    SystemGetSubSystemNamesResult:
      type: object
      properties:
        list:
          type: array
          items:
            type: string

paths:
  /boards:
    get:
      tags:
        - Boards
      operationId: getBoards
      summary: Retrieve a list of boards.
      parameters:
        - in: query
          description: Pagination start (starts at 1. If not specified, 1 is assumed)
          name: offset
          schema:
            type: integer
          required: false
        - in: query
          description: Maximum number of entries to return (if absent, no limit is assumed)
          name: limit
          schema:
            type: integer
          required: false
        - in: query
          description: Filter the results
          name: filter
          schema:
            type: string
          required: false
        - in: query
          description: return the number of boards
          name: countOnly
          schema:
            type: boolean
          required: false
        - in: query
          description: list of boards for a given venue
          name: forVenue
          schema:
            type: string
            format: uuid
          required: false
      responses:
        200:
          description: Return a list of boards
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BoardInfoList'
        400:
          $ref: '#/components/responses/BadRequest'
        403:
          $ref: '#/components/responses/Unauthorized'
        404:
          $ref: '#/components/responses/NotFound'

  /board/{id}:
    get:
      tags:
        - Boards
      operationId: getBoard
      summary: Retrieve a board
      parameters:
        - in: path
          name: id
          schema:
            type: string
            format: uuid
          required: true
      responses:
        200:
          description: Return a list of boards
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BoardInfo'
        400:
          $ref: '#/components/responses/BadRequest'
        403:
          $ref: '#/components/responses/Unauthorized'
        404:
          $ref: '#/components/responses/NotFound'
    delete:
      tags:
        - Boards
      operationId: deleteBoard
      summary: Remove a board
      parameters:
        - in: path
          name: id
          schema:
            type: string
            format: uuid
          required: true
      responses:
        200:
          $ref: '#/components/responses/Success'
        400:
          $ref: '#/components/responses/BadRequest'
        403:
          $ref: '#/components/responses/Unauthorized'
        404:
          $ref: '#/components/responses/NotFound'
    post:
      tags:
        - Boards
      operationId: createBoard
      summary: Create a board
      parameters:
        - in: path
          name: id
          schema:
            type: string
            format: uuid
          required: true
          example: value should be 0 for a post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BoardInfo'
      responses:
        200:
          description: Return the created board
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BoardInfo'
        400:
          $ref: '#/components/responses/BadRequest'
        403:
          $ref: '#/components/responses/Unauthorized'
        404:
          $ref: '#/components/responses/NotFound'
    put:
      tags:
        - Boards
      operationId: modifyBoard
      summary: Modify a board
      parameters:
        - in: path
          name: id
          schema:
            type: string
            format: uuid
          required: true
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BoardInfo'
      responses:
        200:
          description: Return the updated board
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BoardInfo'
        400:
          $ref: '#/components/responses/BadRequest'
        403:
          $ref: '#/components/responses/Unauthorized'
        404:
          $ref: '#/components/responses/NotFound'

  /board/{id}/devices:
    get:
      tags:
        - Board Devices
      summary: Get basic information about all the devices for a venue.
      operationId: getBoardDevices
      parameters:
        - in: path
          name: id
          schema:
            type: string
            format: uuid
          required: true

      responses:
        200:
          description: Return device information for the board
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeviceInfoList'
        400:
          $ref: '#/components/responses/BadRequest'
        403:
          $ref: '#/components/responses/Unauthorized'
        404:
          $ref: '#/components/responses/NotFound'

  /devices/{routerId}/memory-summary:
    get:
      tags:
        - Device Metrics
      operationId: getGatewayMemorySummary
      summary: Retrieve gateway free memory summary for a lookback window.
      security:
        - bearerAuth: []
      parameters:
        - $ref: '#/components/parameters/RouterIdPath'
        - $ref: '#/components/parameters/TimestampTill'
        - $ref: '#/components/parameters/LookbackHours'
      responses:
        200:
          description: Return gateway free memory summary for the requested aggregation window.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GatewayMemorySummary'
              examples:
                withSamples:
                  value:
                    requestedWindow:
                      startTime: "2026-07-26T12:00:00Z"
                      endTime: "2026-07-27T12:00:00Z"
                    observedWindow:
                      startTime: "2026-07-26T12:03:00Z"
                      endTime: "2026-07-27T11:57:00Z"
                    min_memfree: 211374
                    max_memfree: 215050
                    avg_memfree: 212074.36
                noSamples:
                  value:
                    requestedWindow:
                      startTime: "2026-07-26T12:00:00Z"
                      endTime: "2026-07-27T12:00:00Z"
                    observedWindow:
                      startTime: null
                      endTime: null
                    min_memfree: null
                    max_memfree: null
                    avg_memfree: null
        400:
          $ref: '#/components/responses/CommonAnalyticsBadRequest'
        401:
          $ref: '#/components/responses/AnalyticsUnauthorized'
        404:
          $ref: '#/components/responses/AnalyticsNotFound'
        409:
          $ref: '#/components/responses/AnalyticsConflict'
        500:
          $ref: '#/components/responses/MemorySummaryInternalError'
        502:
          $ref: '#/components/responses/AnalyticsBadGateway'

  /devices/{routerId}/radio-temperature-summary:
    get:
      tags:
        - Device Metrics
      operationId: getGatewayRadioTemperatureSummary
      summary: Retrieve gateway Wi-Fi radio temperature summary for a lookback window.
      security:
        - bearerAuth: []
      parameters:
        - $ref: '#/components/parameters/RouterIdPath'
        - $ref: '#/components/parameters/TimestampTill'
        - $ref: '#/components/parameters/LookbackHours'
      responses:
        200:
          description: Return Wi-Fi radio temperature summary for the requested aggregation window.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GatewayWifiTemperatureSummary'
              examples:
                withSamples:
                  value:
                    meta:
                      requestedWindow:
                        startTime: "2026-07-26T12:00:00Z"
                        endTime: "2026-07-27T12:00:00Z"
                      observedWindow:
                        startTime: "2026-07-26T12:04:00Z"
                        endTime: "2026-07-27T11:55:00Z"
                    data:
                      min_wifi_temp_2.4G: 62
                      max_wifi_temp_2.4G: 70
                      avg_wifi_temp_2.4G: 66.64
                      latest_wifi_temp_2.4G: 68
                      min_wifi_temp_5G: 56
                      max_wifi_temp_5G: 65
                      avg_wifi_temp_5G: 60.38
                      latest_wifi_temp_5G: 60
        400:
          $ref: '#/components/responses/TemperatureAnalyticsBadRequest'
        401:
          $ref: '#/components/responses/AnalyticsUnauthorized'
        404:
          $ref: '#/components/responses/AnalyticsNotFound'
        409:
          $ref: '#/components/responses/AnalyticsConflict'
        500:
          $ref: '#/components/responses/RadioTemperatureSummaryInternalError'
        502:
          $ref: '#/components/responses/AnalyticsBadGateway'

  /devices/{routerId}/wifi-clients/usage-summary:
    get:
      tags:
        - Device Metrics
      operationId: getWifiClientUsageSummary
      summary: Retrieve per-client Wi-Fi usage summary for a gateway lookback window.
      security:
        - bearerAuth: []
      parameters:
        - $ref: '#/components/parameters/RouterIdPath'
        - $ref: '#/components/parameters/TimestampTill'
        - $ref: '#/components/parameters/LookbackHours'
      responses:
        200:
          description: >
            Return reset-safe per-client Wi-Fi usage summaries calculated from available
            persisted samples.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClientBandwidthConsumptionResponse'
              examples:
                withClients:
                  value:
                    meta:
                      requestedWindow:
                        startTime: "2026-07-26T12:00:00Z"
                        endTime: "2026-07-27T12:00:00Z"
                      observedWindow:
                        startTime: "2026-07-26T11:55:00Z"
                        endTime: "2026-07-27T12:05:00Z"
                    data:
                      items:
                        - mac: "e2:51:95:ed:0f:28"
                          rx_bytes: 106487500
                          tx_bytes: 3851250
                          total_bytes: 110338750
                          data_consume_rx: "106.49 MB"
                          data_consume_tx: "3.85 MB"
                          total_data_usage: "110.34 MB"
                      totalClients: 1
                      truncated: false
        400:
          $ref: '#/components/responses/CommonAnalyticsBadRequest'
        401:
          $ref: '#/components/responses/AnalyticsUnauthorized'
        404:
          $ref: '#/components/responses/AnalyticsNotFound'
        409:
          $ref: '#/components/responses/AnalyticsConflict'
        500:
          $ref: '#/components/responses/WifiClientUsageInternalError'
        502:
          $ref: '#/components/responses/AnalyticsBadGateway'

  /devices/{routerId}/wifi-clients/rssi-summary:
    get:
      tags:
        - Device Metrics
      operationId: getWifiClientRssiSummary
      summary: Retrieve per-client RSSI quality summary for a gateway lookback window.
      security:
        - bearerAuth: []
      parameters:
        - $ref: '#/components/parameters/RouterIdPath'
        - $ref: '#/components/parameters/TimestampTill'
        - $ref: '#/components/parameters/LookbackHours'
      responses:
        200:
          description: Return per-client RSSI quality percentages.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClientRssiQualityResponse'
              examples:
                withClients:
                  value:
                    meta:
                      requestedWindow:
                        startTime: "2026-07-26T12:00:00Z"
                        endTime: "2026-07-27T12:00:00Z"
                      observedWindow:
                        startTime: "2026-07-26T12:01:00Z"
                        endTime: "2026-07-27T11:58:00Z"
                    data:
                      items:
                        - mac: "e2:51:95:ed:0f:28"
                          rssi_excellent_pct: 41.67
                          rssi_good_pct: 50.0
                          rssi_fair_pct: 1.67
                          rssi_poor_pct: 6.67
                          rssi_total_samples: 60
                      totalClients: 1
                      truncated: false
                noResults:
                  value:
                    meta:
                      requestedWindow:
                        startTime: "2026-07-26T12:00:00Z"
                        endTime: "2026-07-27T12:00:00Z"
                      observedWindow:
                        startTime: null
                        endTime: null
                    data:
                      items: []
                      totalClients: 0
                      truncated: false
        400:
          $ref: '#/components/responses/CommonAnalyticsBadRequest'
        401:
          $ref: '#/components/responses/AnalyticsUnauthorized'
        404:
          $ref: '#/components/responses/AnalyticsNotFound'
        409:
          $ref: '#/components/responses/AnalyticsConflict'
        500:
          $ref: '#/components/responses/WifiClientRssiInternalError'
        502:
          $ref: '#/components/responses/AnalyticsBadGateway'

  /devices/{routerId}/availability-summary:
    get:
      tags:
        - Device Metrics
      operationId: getGatewayAvailabilitySummary
      summary: Retrieve gateway offline transition count for a lookback window.
      security:
        - bearerAuth: []
      parameters:
        - $ref: '#/components/parameters/RouterIdPath'
        - $ref: '#/components/parameters/TimestampTill'
        - $ref: '#/components/parameters/LookbackHours'
      responses:
        200:
          description: Return the gateway offline-transition count calculated from matching availability events currently persisted in Analytics storage for the requested range.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GatewayAvailabilitySummaryResponse'
              examples:
                withEvents:
                  value:
                    meta:
                      requestedWindow:
                        startTime: "2026-07-26T12:00:00Z"
                        endTime: "2026-07-27T12:00:00Z"
                      observedWindow:
                        startTime: "2026-07-26T13:15:00Z"
                        endTime: "2026-07-27T09:45:00Z"
                    data:
                      gw_uuid: "60cf84f22290"
                      fetch_status: success
                      offlineEventCount: 6
                zeroEvents:
                  value:
                    meta:
                      requestedWindow:
                        startTime: "2026-07-26T12:00:00Z"
                        endTime: "2026-07-27T12:00:00Z"
                      observedWindow:
                        startTime: null
                        endTime: null
                    data:
                      gw_uuid: "60cf84f22290"
                      fetch_status: success
                      offlineEventCount: 0
        400:
          $ref: '#/components/responses/AvailabilityAnalyticsBadRequest'
        401:
          $ref: '#/components/responses/AnalyticsUnauthorized'
        404:
          $ref: '#/components/responses/AnalyticsNotFound'
        409:
          $ref: '#/components/responses/AnalyticsConflict'
        500:
          $ref: '#/components/responses/AvailabilityInternalError'
        502:
          $ref: '#/components/responses/AnalyticsBadGateway'

  /board/{id}/timepoints:
    get:
      tags:
        - Board data
      summary: retrieve board data for a given time period.
      operationId: getBoardTimepoint
      parameters:
        - in: path
          name: id
          schema:
            type: string
            format: uuid
          required: true
        - in: query
          name: fromDate
          schema:
            type: integer
          required: false
        - in: query
          name: endDate
          schema:
            type: integer
          required: false
        - in: query
          name: maxRecords
          schema:
            type: integer
            default: 100
          required: false
        - in: query
          name: statsOnly
          schema:
            type: boolean
            default: false
          required: false
        - in: query
          name: pointsOnly
          schema:
            type: boolean
            default: false
          required: false
        - in: query
          name: pointsStatsOnly
          schema:
            type: boolean
            default: false
          required: false

      responses:
        200:
          description: Return board timepoints or summary statistics
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeviceTimePointList'
        400:
          $ref: '#/components/responses/BadRequest'
        403:
          $ref: '#/components/responses/Unauthorized'
        404:
          $ref: '#/components/responses/NotFound'

    delete:
      tags:
        - Board data
      summary: delete board data for a given time period.
      operationId: deleteBoardTimepoints
      parameters:
        - in: path
          name: id
          schema:
            type: string
            format: uuid
          required: true
        - in: query
          name: fromDate
          schema:
            type: integer
          required: false
        - in: query
          name: endDate
          schema:
            type: integer
          required: false
      responses:
        200:
          $ref: '#/components/responses/Success'
        400:
          $ref: '#/components/responses/BadRequest'
        403:
          $ref: '#/components/responses/Unauthorized'
        404:
          $ref: '#/components/responses/NotFound'

  /wifiClientHistory:
    get:
      tags:
        - WiFiClientHistory
      operationId: getWifiClientHistory
      summary: Retrieve WiFi client addresses 
      parameters:
        - in: query
          name: fromDate
          schema:
            type: integer
          required: false
        - in: query
          name: endDate
          schema:
            type: integer
          required: false
        - in: query
          description: Pagination start (starts at 1. If not specified, 1 is assumed)
          name: offset
          schema:
            type: integer
          required: false
        - in: query
          description: Maximum number of entries to return (if absent, no limit is assumed)
          name: limit
          schema:
            type: integer
          required: false
        - in: query
          description: Maximum number of entries to return (if absent, no limit is assumed)
          name: macsOnly
          schema:
            type: boolean
            default: false
          required: false
        - in: query
          description: Maximum number of entries to return (if absent, no limit is assumed)
          name: macFilter
          schema:
            type: string
            example:
              112233445566, 11223344*, *5566
          required: false
        - in: query
          description: Venue for the search. If omitted, boardId may be used to derive it.
          name: venue
          schema:
            type: string
            format: uuid
          required: false
        - in: query
          description: Board used to derive venue when venue is not provided.
          name: boardId
          schema:
            type: string
            format: uuid
          required: false
      responses:
        200:
          description: Return matching client MAC addresses
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MacList'
        403:
          $ref: '#/components/responses/Unauthorized'
        404:
          $ref: '#/components/responses/NotFound'

  /wifiClientHistory/{client}:
    get:
      tags:
        - WiFiClientHistory
      operationId: getWifiClientHistoryEntries
      summary: Retrieve WiFi client history per device
      parameters:
        - in: path
          name: client
          schema:
            type: string
            example:
              "112233aabbcc"
          required: true
        - in: query
          name: fromDate
          schema:
            type: integer
          required: false
        - in: query
          name: endDate
          schema:
            type: integer
          required: false
        - in: query
          description: Pagination start (starts at 1. If not specified, 1 is assumed)
          name: offset
          schema:
            type: integer
          required: false
        - in: query
          description: Maximum number of entries to return (if absent, no limit is assumed)
          name: limit
          schema:
            type: integer
          required: false
        - in: query
          description: Venue for the search. If omitted, boardId may be used to derive it.
          name: venue
          schema:
            type: string
            format: uuid
          required: false
        - in: query
          description: Board used to derive venue when venue is not provided.
          name: boardId
          schema:
            type: string
            format: uuid
          required: false
        - in: query
          description: return extended information
          name: orderBy
          schema:
            type: string
            example: serialNumber:a,created:d
          required: false
        - in: query
          description: return extended information
          name: orderSpec
          schema:
            type: boolean
            default: false
          required: false
        - in: query
          description: Return count only
          name: countOnly
          schema:
            type: boolean
          required: false
      responses:
        200:
          description: Return WiFi client history entries per device
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WifiClientHistoryList'
        403:
          $ref: '#/components/responses/Unauthorized'
        404:
          $ref: '#/components/responses/NotFound'

    delete:
      tags:
        - WiFiClientHistory
      operationId: deleteWifiClientHistory
      summary: Delete WiFi client history per device
      parameters:
        - in: query
          description: The venue to for the search.
          name: venue
          schema:
            type: string
            format: uuid
          required: true
        - in: path
          name: client
          schema:
            type: string
            example:
              "112233aabbcc"
          required: true
        - in: query
          name: fromDate
          schema:
            type: integer
          required: false
        - in: query
          name: endDate
          schema:
            type: integer
          required: false
      responses:
        200:
          $ref: '#/components/responses/Success'
        403:
          $ref: '#/components/responses/Unauthorized'
        404:
          $ref: '#/components/responses/NotFound'

  #########################################################################################
  ##
  ## These are endpoints that all services in the OpenWiFi stack must provide
  ##
  #########################################################################################
  /system:
    post:
      tags:
        - System Commands
      summary: Perform some system wide commands.
      operationId: systemCommand
      requestBody:
        description: Command details
        content:
          application/json:
            schema:
              oneOf:
                - $ref: '#/components/schemas/SystemCommandSetLogLevel'
                - $ref: '#/components/schemas/SystemCommandReload'
                - $ref: '#/components/schemas/SystemCommandGetLogLevels'
                - $ref: '#/components/schemas/SystemCommandGetLogLevelNames'
                - $ref: '#/components/schemas/SystemCommandGetSubsystemNames'
      responses:
        200:
          description: Successful command execution
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: '#/components/schemas/SystemGetLogLevelsResult'
                  - $ref: '#/components/schemas/SystemCommandGetLogLevelNamesResult'
                  - $ref: '#/components/schemas/SystemGetSubSystemNamesResult'
        400:
          $ref: '#/components/responses/BadRequest'
        403:
          $ref: '#/components/responses/Unauthorized'
        404:
          $ref: '#/components/responses/NotFound'
    get:
      tags:
        - System Commands
      summary: Retrieve different values from the running service.
      operationId: getSystemCommand
      parameters:
        - in: query
          description: Get a value
          name: command
          schema:
            type: string
            enum:
              - info
              - extraConfiguration
              - resources
          required: true
      responses:
        200:
          description: Return the requested system information
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SystemCommandResults'
        403:
          $ref: '#/components/responses/Unauthorized'
        404:
          $ref: '#/components/responses/NotFound'

  /systemConfiguration:
    get:
      tags:
        - SystemConfiguration
      summary: Retrieve system configuration items
      operationId: getSystemConfiguration
      parameters:
        - in: query
          description: Which parameters you want to retrieve
          name: entries
          schema:
            type: string
            example:
              - element1
              - element1,element2,element3
          required: true
      responses:
        200:
          description: List of configuration elements
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ExtraSystemConfiguration'
        403:
          $ref: '#/components/responses/Unauthorized'
        404:
          $ref: '#/components/responses/NotFound'