openapi3_spec.json

{"openapi":"3.1.0","info":{"title":"nut_webgui JSON API","version":"0.4.0","summary":"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}","description":"nut_webgui server","variables":{"host":{"default":"localhost"},"port":{"default":"9000"},"protocol":{"default":"http","enum":["http","https"]}}}],"paths":{"/api/ups":{"description":"Returns collection of all available UPS devices.","get":{"tags":["ups"],"operationId":"api_ups_collection_get","responses":{"200":{"description":"Collection of UPS devices.","content":{"application/json":{"examples":{"ups_list":{"$ref":"#/components/examples/ups_list_response"},"empty_list":{"$ref":"#/components/examples/empty_ups_list_response"}},"schema":{"$ref":"#/components/schemas/UpsList"}}}},"500":{"description":"Server or daemon errors.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"503":{"description":"Server is not ready to serve.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}}}}},"/api/ups/{ups_name}":{"description":"Returns a UPS devices.","get":{"parameters":[{"name":"ups_name","in":"path","description":"UPS name","required":true,"allowEmptyValue":false,"schema":{"type":"string"}}],"tags":["ups"],"operationId":"api_ups_get","responses":{"200":{"description":"UPS device response.","content":{"application/json":{"examples":{"ups":{"$ref":"#/components/examples/ups_response"}},"schema":{"$ref":"#/components/schemas/Ups"}}}},"404":{"description":"Ups does not exists.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"500":{"description":"Server or daemon errors.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"503":{"description":"Server is not ready to serve.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}}}}},"/api/ups/{ups_name}/command":{"description":"Instantiate a UPS command.","post":{"requestBody":{"description":"Command request body.","required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CommandRequest"}}}},"parameters":[{"name":"ups_name","in":"path","description":"UPS name","required":true,"allowEmptyValue":false,"schema":{"type":"string"}}],"tags":["ups"],"operationId":"api_ups_instcmd","responses":{"202":{"description":"Command is accepted."},"401":{"description":"Upsd user and password configs are not set.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"404":{"description":"Ups does not exists.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"500":{"description":"Server or daemon errors.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"503":{"description":"Server is not ready to serve.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}}}}},"/probes/health":{"description":"Server health check","get":{"tags":["probes"],"operationId":"probes_health","responses":{"200":{"description":"Command is accepted","content":{"application/json":{"examples":{"default":{"$ref":"#/components/examples/health_200"}},"schema":{"$ref":"#/components/schemas/HealthResponse"}}}},"500":{"description":"Upsd daemon failure","content":{"application/json":{"examples":{"default":{"$ref":"#/components/examples/health_500"}},"schema":{"$ref":"#/components/schemas/HealthResponse"}}}},"503":{"description":"Server is not ready to serve","content":{"application/json":{"examples":{"default":{"$ref":"#/components/examples/health_503"}},"schema":{"$ref":"#/components/schemas/HealthResponse"}}}}}}},"/probes/readiness":{"description":"Server readiness probe mainly intented for Kubernetes.","get":{"tags":["probes"],"operationId":"probes_readiness","responses":{"200":{"description":"Server is ready to response.","content":{"text/plain":{"schema":{"enum":["READY"]}}}},"503":{"description":"Server is not ready to response.","content":{"text/plain":{"schema":{"enum":["NOT READY"]}}}}}}}},"components":{"schemas":{"Ups":{"type":"object","required":["name","desc","vars","cmds"],"properties":{"name":{"type":"string"},"desc":{"type":"string"},"vars":{"type":"object","additionalProperties":{"oneOf":[{"type":"number"},{"type":"string"}]}},"cmds":{"type":"array","items":{"type":"string"}}}},"UpsList":{"type":"array","items":{"$ref":"#/components/schemas/Ups"}},"ProblemDetails":{"type":"object","required":["title","status"],"properties":{"title":{"type":"string"},"details":{"type":"string"},"status":{"type":"number","minimum":100,"exclusiveMaximum":1000},"instance":{"type":"string","format":"uri"}}},"CommandRequest":{"type":"object","required":["cmd"],"properties":{"cmd":{"type":"string"}}},"HealthResponse":{"type":"object","required":["upsd_status","upsd_server"],"properties":{"last_updated":{"type":"string","format":"date-time"},"upsd_server":{"type":"string","format":"hostname"},"upsd_status":{"type":"string","enum":["Online","Dead","NotReady"]}}}},"examples":{"health_200":{"summary":"Server Online","value":"{\n  \"upsd_status\": \"Online\",\n  \"last_modified\": \"2024-10-12T00:11:21.746872446Z\",\n  \"upsd_server\": \"localhost:3493\"\n}\n"},"health_500":{"summary":"Server Dead","value":"{\n  \"upsd_status\": \"Dead\",\n  \"last_modified\": null,\n  \"upsd_server\": \"localhost:3493\"\n}\n"},"health_503":{"summary":"Server NotReady","value":"{\n  \"upsd_status\": \"NotReady\",\n  \"last_modified\": null,\n  \"upsd_server\": \"localhost:3493\"\n}\n"},"ups_response":{"summary":"UPS device","value":"{\n  \"name\": \"apc_back-ups_cs_650\",\n  \"desc\": \"dummy-ups apc_back-ups_cs_650\",\n  \"vars\": {\n    \"battery.charge\": 100,\n    \"battery.charge.low\": 10,\n    \"battery.charge.warning\": \"50\",\n    \"battery.date\": \"2005/09/28\",\n    \"battery.mfr.date\": \"2005/09/28\",\n    \"battery.runtime\": 1312,\n    \"battery.runtime.low\": \"120\",\n    \"battery.temperature\": 29.2,\n    \"battery.type\": \"PbAc\",\n    \"battery.voltage\": 13.6,\n    \"battery.voltage.nominal\": 12,\n    \"device.mfr\": \"American Power Conversion\",\n    \"device.model\": \"Back-UPS CS 650\",\n    \"device.serial\": \"000000000000\",\n    \"device.type\": \"ups\",\n    \"driver.debug\": \"0\",\n    \"driver.flag.allow_killpower\": \"0\",\n    \"driver.name\": \"dummy-ups\",\n    \"driver.parameter.mode\": \"dummy-once\",\n    \"driver.parameter.pollinterval\": 2,\n    \"driver.parameter.port\": \"APC_Back-UPS_CS_650.dev\",\n    \"driver.parameter.synchronous\": \"auto\",\n    \"driver.state\": \"updateinfo\",\n    \"driver.version\": \"2.8.1\",\n    \"driver.version.internal\": \"0.18\",\n    \"input.sensitivity\": \"high\",\n    \"input.transfer.high\": 256,\n    \"input.transfer.low\": 196,\n    \"input.voltage\": 228,\n    \"input.voltage.nominal\": 230,\n    \"output.frequency\": \"50.0\",\n    \"output.voltage\": \"230.0\",\n    \"output.voltage.nominal\": \"230.0\",\n    \"ups.beeper.status\": \"disabled\",\n    \"ups.delay.shutdown\": 20,\n    \"ups.delay.start\": 30,\n    \"ups.firmware\": \"817.v2.I\",\n    \"ups.firmware.aux\": \"v2\",\n    \"ups.load\": 27,\n    \"ups.mfr\": \"American Power Conversion\",\n    \"ups.mfr.date\": \"2005/09/28\",\n    \"ups.model\": \"Back-UPS CS 650\",\n    \"ups.productid\": \"0002\",\n    \"ups.realpower.nominal\": 400,\n    \"ups.serial\": \"000000000000\",\n    \"ups.status\": \"OL\",\n    \"ups.test.result\": \"No test initiated\",\n    \"ups.timer.reboot\": \"0\",\n    \"ups.timer.shutdown\": -1,\n    \"ups.timer.start\": 0,\n    \"ups.vendorid\": \"051d\"\n  },\n  \"cmds\": [\n    \"driver.killpower\",\n    \"driver.reload\",\n    \"driver.reload-or-error\",\n    \"driver.reload-or-exit\",\n    \"load.off\"\n  ]\n}\n"},"empty_ups_list_response":{"summary":"Empty UPS list","value":"[]"},"ups_list_response":{"summary":"Populated UPS list","value":"[{\n  \"name\": \"apc_back-ups_cs_650\",\n  \"desc\": \"dummy-ups apc_back-ups_cs_650\",\n  \"vars\": {\n    \"battery.charge\": 100,\n    \"battery.charge.low\": 10,\n    \"battery.charge.warning\": \"50\",\n    \"battery.date\": \"2005/09/28\",\n    \"battery.mfr.date\": \"2005/09/28\",\n    \"battery.runtime\": 1312,\n    \"battery.runtime.low\": \"120\",\n    \"battery.temperature\": 29.2,\n    \"battery.type\": \"PbAc\",\n    \"battery.voltage\": 13.6,\n    \"battery.voltage.nominal\": 12,\n    \"device.mfr\": \"American Power Conversion\",\n    \"device.model\": \"Back-UPS CS 650\",\n    \"device.serial\": \"000000000000\",\n    \"device.type\": \"ups\",\n    \"driver.debug\": \"0\",\n    \"driver.flag.allow_killpower\": \"0\",\n    \"driver.name\": \"dummy-ups\",\n    \"driver.parameter.mode\": \"dummy-once\",\n    \"driver.parameter.pollinterval\": 2,\n    \"driver.parameter.port\": \"APC_Back-UPS_CS_650.dev\",\n    \"driver.parameter.synchronous\": \"auto\",\n    \"driver.state\": \"updateinfo\",\n    \"driver.version\": \"2.8.1\",\n    \"driver.version.internal\": \"0.18\",\n    \"input.sensitivity\": \"high\",\n    \"input.transfer.high\": 256,\n    \"input.transfer.low\": 196,\n    \"input.voltage\": 228,\n    \"input.voltage.nominal\": 230,\n    \"output.frequency\": \"50.0\",\n    \"output.voltage\": \"230.0\",\n    \"output.voltage.nominal\": \"230.0\",\n    \"ups.beeper.status\": \"disabled\",\n    \"ups.delay.shutdown\": 20,\n    \"ups.delay.start\": 30,\n    \"ups.firmware\": \"817.v2.I\",\n    \"ups.firmware.aux\": \"v2\",\n    \"ups.load\": 27,\n    \"ups.mfr\": \"American Power Conversion\",\n    \"ups.mfr.date\": \"2005/09/28\",\n    \"ups.model\": \"Back-UPS CS 650\",\n    \"ups.productid\": \"0002\",\n    \"ups.realpower.nominal\": 400,\n    \"ups.serial\": \"000000000000\",\n    \"ups.status\": \"OL\",\n    \"ups.test.result\": \"No test initiated\",\n    \"ups.timer.reboot\": \"0\",\n    \"ups.timer.shutdown\": -1,\n    \"ups.timer.start\": 0,\n    \"ups.vendorid\": \"051d\"\n  },\n  \"cmds\": [\n    \"driver.killpower\",\n    \"driver.reload\",\n    \"driver.reload-or-error\",\n    \"driver.reload-or-exit\",\n    \"load.off\"\n  ]\n},\n{\n  \"name\": \"apc_smart-ups_c1500\",\n  \"desc\": \"dummy-ups apc_smart-ups_c1500\",\n  \"vars\": {\n    \"battery.charge\": 100,\n    \"battery.charge.low\": 10,\n    \"battery.charge.warning\": \"50\",\n    \"battery.runtime\": 17820,\n    \"battery.runtime.low\": \"120\",\n    \"battery.type\": \"PbAc\",\n    \"battery.voltage\": 27.3,\n    \"battery.voltage.nominal\": 24,\n    \"device.mfr\": \"American Power Conversion\",\n    \"device.model\": \"Smart-UPS C 1500\",\n    \"device.serial\": \"000000000000\",\n    \"device.type\": \"ups\",\n    \"driver.debug\": \"0\",\n    \"driver.flag.allow_killpower\": \"0\",\n    \"driver.name\": \"dummy-ups\",\n    \"driver.parameter.mode\": \"dummy-once\",\n    \"driver.parameter.pollinterval\": 2,\n    \"driver.parameter.port\": \"APC_Smart-UPS_C1500.dev\",\n    \"driver.parameter.synchronous\": \"auto\",\n    \"driver.state\": \"quiet\",\n    \"driver.version\": \"2.8.1\",\n    \"driver.version.internal\": \"0.18\",\n    \"ups.beeper.status\": \"disabled\",\n    \"ups.delay.shutdown\": 20,\n    \"ups.firmware\": \"UPS 10.0 / ID = 1005\",\n    \"ups.mfr\": \"American Power Conversion\",\n    \"ups.mfr.date\": \"2016/08/17\",\n    \"ups.model\": \"Smart-UPS C 1500\",\n    \"ups.productid\": \"0003\",\n    \"ups.serial\": \"000000000000\",\n    \"ups.status\": \"OL\",\n    \"ups.timer.reboot\": \"-1\",\n    \"ups.timer.shutdown\": -1,\n    \"ups.vendorid\": \"051d\"\n  },\n  \"cmds\": [\n    \"driver.killpower\",\n    \"driver.reload\",\n    \"driver.reload-or-error\",\n    \"driver.reload-or-exit\",\n    \"load.off\"\n  ]}\n]\n"}}},"tags":[{"name":"ups","description":"UPS endpoints"},{"name":"probes","description":"Server health check endpoints"}]}