openapi3_spec.yaml

# yaml-language-server: $schema=https://spec.openapis.org/oas/3.0/schema/2024-10-18

openapi: "3.0.4"

info:
  title: "nut_webgui JSON API"
  version: "0.10.0"
  description: "Simple JSON API for interfacing with nut_webgui."
  license:
    name: "Apache 2.0"
    url: "https://raw.githubusercontent.com/SuperioOne/nut_webgui/refs/heads/master/LICENSE"
  contact:
    url: "https://github.com/SuperioOne/nut_webgui/issues"
    email: "pm@smdd.dev"

servers:
  - url: "{protocol}://{host}:{port}/{base_path}"
    description: "nut_webgui server"
    variables:
      host:
        default: localhost
      base_path:
        default: ""
      port:
        default: "9000"
      protocol:
        default: "http"
        enum:
          - http
          - https

paths:
  /api:
    get:
      operationId: "get_namespace_collection"
      description: "Returns all available namespaces and connection information."
      security:
        - ApiToken: []
      tags:
        - namespace
      responses:
        "200":
          description: "Collection of all existing namespace details."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ArrayOfNamespaces"
        "401":
          description: "Unauthorized if authentication is enabled and an invalid bearer token or no token is provided."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ProblemDetails"
        "500":
          description: "Unexpected server error occured."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ProblemDetails"
        "503":
          description: "HTTP server is started but unable to serve requsted resource."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ProblemDetails"

  /api/{namespace}:
    get:
      operationId: "get_namespace"
      description: "Returns information about a specific namespace."
      security:
        - ApiToken: []
      tags:
        - namespace
      parameters:
        - name: namespace
          in: path
          description: "Target namespace"
          required: true
          allowEmptyValue: false
          example: "default"
          schema:
            type: string
      responses:
        "200":
          description: "Namespace details object."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Namespace"
        "401":
          description: "Unauthorized if authentication is enabled and an invalid bearer token or no token is provided."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ProblemDetails"
        "404":
          description: "Namespace does not exist."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ProblemDetails"
        "500":
          description: "Unexpected server error occured."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ProblemDetails"
        "503":
          description: "HTTP server is started but unable to serve requsted resource."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ProblemDetails"

  /api/{namespace}/devices:
    get:
      description: "List all UPS devices in a specific namespace."
      tags:
        - ups
      security:
        - ApiToken: []
      operationId: "get_namespace_device_collection"
      parameters:
        - name: namespace
          in: path
          description: "Target namespace"
          required: true
          allowEmptyValue: false
          schema:
            type: string
      responses:
        "200":
          description: "Collection of UPS devices in the target namespace."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ArrayOfDevices"
        "401":
          description: "Unauthorized if authentication is enabled and an invalid bearer token or no token is provided."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ProblemDetails"
        "404":
          description: "Namespace does not exist."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ProblemDetails"
        "500":
          description: "Unexpected server error."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ProblemDetails"
        "503":
          description: "HTTP server is started but unable to serve requsted resource."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ProblemDetails"

  /api/{namespace}/devices/{ups_name}:
    patch:
      operationId: "patch_namespace_device"
      description: "Updates a specific device in the specified namespace."
      requestBody:
        description: "JSON object containing variable name to update and its new value."
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/SetVarRequest"
      parameters:
        - name: namespace
          in: path
          description: "Target namespace"
          required: true
          allowEmptyValue: false
          schema:
            type: string
        - name: ups_name
          in: path
          description: "UPS name"
          required: true
          allowEmptyValue: false
          schema:
            type: string
      security:
        - ApiToken: []
      tags:
        - ups
      responses:
        "202":
          description: "SETVAR request accepted by the UPS driver."
        "400":
          description: "Invalid SETVAR request."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ProblemDetails"
        "401":
          description: "Unauthorized if authentication is enabled and an invalid bearer token or no token is provided."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ProblemDetails"
        "403":
          description: "It's either server cannot authenticate to NUT server due missing/invalid configuration or provided API token does not have the 'setvar' permission."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ProblemDetails"
        "404":
          description: "UPS or namespace does not exists."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ProblemDetails"
        "500":
          description: "Unexpected server error."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ProblemDetails"
        "503":
          description: "HTTP server is started but unable to serve requsted resource."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ProblemDetails"

    get:
      operationId: "get_namespace_device"
      description: "Returns information about a specific UPS device."
      parameters:
        - name: namespace
          in: path
          description: "Target namespace"
          required: true
          allowEmptyValue: false
          schema:
            type: string
        - name: ups_name
          in: path
          description: "UPS name"
          required: true
          allowEmptyValue: false
          schema:
            type: string
      security:
        - ApiToken: []
      tags:
        - ups
      responses:
        "200":
          description: "UPS device response."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/UpsDevice"
        "401":
          description: "Unauthorized if authentication is enabled and an invalid bearer token or no token is provided."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ProblemDetails"
        "404":
          description: "UPS or namespace does not exists."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ProblemDetails"
        "500":
          description: "Unexpected server error."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ProblemDetails"
        "503":
          description: "HTTP server is started but unable to serve requsted resource."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ProblemDetails"

  /api/{namespace}/devices/{ups_name}/instcmd:
    post:
      description: "Calls UPS INSTCMD command."
      requestBody:
        description: "JSON object containing INSTCMD name."
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CommandRequest"
      parameters:
        - name: namespace
          in: path
          description: "Target namespace"
          required: true
          allowEmptyValue: false
          example: "default"
          schema:
            type: string
        - name: ups_name
          in: path
          description: "UPS name"
          required: true
          allowEmptyValue: false
          schema:
            type: string
      security:
        - ApiToken: []
      tags:
        - ups
      operationId: "post_namespace_device_instcmd"
      responses:
        "202":
          description: "INSTCMD is accepted by UPS driver."
        "400":
          description: "Invalid INSTCMD"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ProblemDetails"
        "401":
          description: "Unauthorized if authentication is enabled and an invalid bearer token or no token is provided."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ProblemDetails"
        "403":
          description: "It's either server cannot authenticate to NUT server due missing/invalid configuration or provided API token does not have the 'instcmd' permission."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ProblemDetails"
        "404":
          description: "UPS or namespace does not exist."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ProblemDetails"
        "500":
          description: "Unexpected server error."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ProblemDetails"
        "503":
          description: "HTTP server is started but unable to serve requsted resource."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ProblemDetails"

  /api/{namespace}/devices/{ups_name}/fsd:
    post:
      description: "Sets forced shutdown (FSD) on UPS."
      parameters:
        - name: namespace
          in: path
          description: "Target namespace"
          required: true
          allowEmptyValue: false
          example: "default"
          schema:
            type: string
        - name: ups_name
          in: path
          description: "UPS name"
          required: true
          allowEmptyValue: false
          schema:
            type: string
      security:
        - ApiToken: []
      tags:
        - ups
      operationId: "post_namespace_device_fsd"
      responses:
        "202":
          description: "FSD is accepted by the UPS driver."
        "401":
          description: "Unauthorized if authentication is enabled and an invalid bearer token or no token is provided."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ProblemDetails"
        "403":
          description: "It's either server cannot authenticate to NUT server due missing/invalid configuration or provided API token does not have the 'fsd' permission."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ProblemDetails"
        "404":
          description: "UPS or namespace does not exist."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ProblemDetails"
        "500":
          description: "Unexpected server error."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ProblemDetails"
        "503":
          description: "HTTP server is started but unable to serve requsted resource."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ProblemDetails"

  /probes/health:
    get:
      description: "Checks the overall health of the HTTP server and its UPSD connections."
      tags:
        - probes
      operationId: "get_probe_health"
      responses:
        "200":
          description: "HTTP server is ready and has at least one healthy UPSD connection."
          content:
            text/plain:
              example: "READY"
              schema:
                enum:
                  - "READY"
                  - "DEGRADED"
        "500":
          description: "The HTTP server is not functioning properly or all UPSD connections are dead."
          content:
            text/plain:
              schema:
                type: string
                example: "DEAD"

  /probes/readiness:
    get:
      description: "Checks if the server is ready to respond."
      tags:
        - probes
      operationId: "get_probe_readiness"
      responses:
        "200":
          description: "Server is ready to response."
          content:
            text/plain:
              schema:
                type: string
                example: "READY"
        "503":
          description: "Server is not ready to response."
          content:
            text/plain:
              schema:
                type: string
                example: "NOT-READY"

  /probes/health/{namespace}:
    get:
      operationId: "get_probe_health_namespace"
      description: "Checks the health of a specific UPSD connection in the specified namespace."
      tags:
        - probes
      parameters:
        - name: namespace
          in: path
          description: "Target namespace"
          required: true
          allowEmptyValue: false
          example: "default"
          schema:
            type: string
      responses:
        "200":
          description: "UPSD connection is healthy."
          content:
            text/plain:
              example: "READY"
              schema:
                type: string
        "404":
          description: "Namespace does not exist."
          content:
            text/plain:
              example: "UPSD NAMESPACE DOES NOT EXIST"
              schema:
                type: string
        "500":
          description: "UPSD connection is dead."
          content:
            text/plain:
              schema:
                type: string
                example: "DEAD"

  /probes/readiness/{namespace}:
    get:
      operationId: "get_probe_readiness_namespace"
      description: "Checks if a specific UPSD connection in the specified namespace is ready to serve data."
      tags:
        - probes
      parameters:
        - name: namespace
          in: path
          description: "Target namespace"
          required: true
          allowEmptyValue: false
          example: "default"
          schema:
            type: string
      responses:
        "200":
          description: "UPSD connection is online and data is ready to be served."
          content:
            text/plain:
              schema:
                type: string
                example: "READY"
        "404":
          description: "Namespace does not exist."
          content:
            text/plain:
              example: "UPSD NAMESPACE DOES NOT EXIST"
              schema:
                type: string
        "503":
          description: "Data syncing from UPSD connection is not completed yet."
          content:
            text/plain:
              schema:
                type: string
                example: "NOT-READY"

components:
  securitySchemes:
    ApiToken:
      type: http
      scheme: bearer
  schemas:
    Namespace:
      type: object
      required:
        - address
        - device_count
        - last_sync_time
        - namespace
        - poll_freq
        - poll_interval
        - port
        - protocol_version
        - status
        - tls_mode
        - version
      properties:
        address:
          type: string
          description: "The hostname or IP address of the UPSD connection."
          example: "localhost"
        device_count:
          type: integer
          description: "Total number of UPS devices connected to the UPSD server."
          example: 12
        last_sync_time:
          type: string
          format: date-time
          description: "UTC timestamp indicating when the last synchronization occurred."
          example: "2025-11-04T19:13:01.205137806Z"
        namespace:
          type: string
          description: "Name used to group related UPS devices for management purposes."
          example: "kongou"
        poll_freq:
          type: integer
          description: "Frequency at which the UPSD server is polled in seconds."
          example: 30
        poll_interval:
          type: integer
          description: "Interval at critical variables is polled in seconds."
          example: 2
        port:
          type: integer
          description: "Port number on which the UPSD service is running."
          example: 3493
        protocol_version:
          type: string
          description: "Version of the NUT (Network UPS Tools) protocol reported by the UPSD server."
          example: "1.3"
        status:
          type: string
          enum:
            - "Online"
            - "Dead"
            - "Not Ready"
          description: "Current operational status of the connection to the UPSD server."
          example: "Online"
        tls_mode:
          type: string
          enum:
            - "disable"
            - "skip"
            - "strict"
          description: "Mode for TLS encryption during connections to the UPSD server."
          example: "disable"
        version:
          type: string
          description: "Version information of the Network UPS Tools software."
          example: "Network UPS Tools upsd 2.8.1 - https://www.networkupstools.org/"

    ArrayOfNamespaces:
      type: array
      items:
        "$ref": "#/components/schemas/Namespace"

    UpsDevice:
      type: object
      description: "UPS device details including status, variables, and supported commands."
      required:
        - attached
        - commands
        - desc
        - last_modified
        - name
        - rw_variables
        - status
        - variables
      properties:
        name:
          type: string
          description: "Unique identifier of the UPS device."
          example: "lab-ups"
        desc:
          type: string
          description: "Description of the UPS device."
          example: "Secondary rack mounted ups"
        status:
          type: string
          description: "Current operational status flags reported by the UPS device."
          example: "OL TEST"
        last_modified:
          type: string
          description: "UTC timestamp indicating when the device details were last updated."
          format: date-time
          example: "2025-11-04T22:46:12.354759505Z"
        rw_variables:
          type: object
          description: "UPS variables that support read-write operations with their data types and constraints."
          additionalProperties:
            oneOf:
              - type: object
                required:
                  - type
                properties:
                  type:
                    type: string
                    default: string
                    example: string
                    enum:
                      - string
                  max_len:
                    type: integer
                    example: 12
              - type: object
                required:
                  - type
                properties:
                  type:
                    type: string
                    default: number
                    example: number
                    enum:
                      - number
              - type: object
                required:
                  - type
                  - options
                properties:
                  type:
                    type: string
                    default: enum
                    example: enum
                    enum:
                      - enum
                  options:
                    type: array
                    example: ["high", "low"]
                    items:
                      type: string
              - type: object
                required:
                  - type
                  - min
                  - max
                properties:
                  type:
                    type: string
                    default: range
                    example: range
                    enum:
                      - range
                  min:
                    type: number
                    example: 140
                  max:
                    type: number
                    example: 240
          example:
            "battery.mfr.date":
              type: string,
              max_len: 10
            "battery.charge.low":
              type: "number"
            "input.sensitivity":
              type: "enum"
              options:
                - high
                - low
            "battery.runtime.low":
              type: range
              min: 5
              max: 75
        variables:
          type: object
          description: "Variables collected from the UPS device via the NUT protocol."
          example:
            "battery.mfr.date": "2023/02/25"
            "battery.type": "PbAc"
            "battery.voltage": 27.3
            "device.mfr": "American Power Conversion"
            "device.model": "Back-UPS BX1600MI"
            "device.serial": "999999999999"
            "driver.flag.allow_killpower": 0
            "driver.parameter.pollinterval": 2
            "driver.parameter.vendorid": "051D"
            "driver.version.data": "APC HID 0.100"
            "driver.version.internal": 0.52
            "driver.version.usb": "libusb-1.0.27 (API: 0x100010a)"
            "input.sensitivity": "medium"
            "input.transfer.high": 295
            "input.transfer.low": 145
            "input.voltage": 230.0
            "ups.load": 26
            "ups.mfr.date": "2023/02/25"
            "ups.model": "Back-UPS BX1600MI"
            "ups.status": "OL"
            "ups.timer.shutdown": -1
          additionalProperties:
            oneOf:
              - type: "number"
              - type: "string"
        commands:
          type: "array"
          description: "List of supported INSTCMD operations for the UPS device."
          example: ["beeper.on", "beeper.off"]
          items:
            type: "string"
        attached:
          type: "array"
          description: "List of IP addresses of devices attached to the UPS for power."
          items:
            type: "object"
            required:
              - "addr"
            properties:
              addr:
                type: string
                description: "Ipv4 or Ipv6 address of the attached client."
                example: "192.168.1.10"
              name:
                type: string
                description: "Optional client hostname."
                example: "example.smdd.dev"

    ArrayOfDevices:
      type: array
      items:
        "$ref": "#/components/schemas/UpsDevice"

    ProblemDetails:
      type: object
      required:
        - title
        - status
      properties:
        title:
          type: string
          description: "Human-readable title of the encountered error."
          example: "Error title"
        details:
          type: string
          description: "Optional additional information providing context about the error."
          example: "It's just a flesh wound."
        status:
          type: number
          description: "HTTP error code corresponding to the problem."
          minimum: 100
          maximum: 599
          example: 400

    CommandRequest:
      type: object
      required:
        - instcmd
      properties:
        instcmd:
          type: string
          description: "INSTCMD to be executed on the UPS device."
          example: "beeper.disable"

    SetVarRequest:
      type: object
      required:
        - variable
        - value
      properties:
        variable:
          type: string
          description: "Name of the UPS variable to modify."
          example: "battery.charge.low"
        value:
          example: 25
          description: "Value to set for the specified variable. Value type depends on the variable's data type."
          oneOf:
            - type: "number"
            - type: "string"

tags:
  - name: namespace
    description: "Endpoints for namespaces and their configurations."
  - name: ups
    description: "Endpoints for UPS devices monitoring and control."
  - name: probes
    description: "Server health check and readiness endpoints."