Accessing and Using NUTCase

Introduction

NUTCase is accessed through a single HTTP connection. The path (end-point) after the address and port along with the parameters on the URL determine what NUTCase returns as data.

End-Points

Valid end points are:

Path	Function	Notes
/	Displays the GUI with information from a selected device	Available since version V0.3.0
/help	Returns a page of usage information
/log	View the the last default (20) number of lines from the log	Optionally takes lines as a parameter
/health	Returns a JSON response { "OK": "true" }	Use with monitoring applications such as Uptime Kuma etc.
/metrics	Returns the UPS information as text suitable for scraping by Prometheus	Requires an address using target or addr see below
/json	For JSON output compatible with HomePage and Webhooks.	Requires an address using target or addr see below
/raw	JSON containing all, unprocessed, data received from the server.	Requires an address using target or addr see below. This is intended for diagnostics only.
/apclog	Displays the event data from an APC apcupsd server.	Must be used with mode=apc

Examples are:

The GUI

The GUI is accessed at the root / end point. Only addr and optionally port parameters should be used, target is not supported.

Warning

The device name of your UPS must be specified along with the server address.

If no parameters are given then the server marked as default in the servers list is taken from the configuration file.

http://<nutcase-ip>:<port>?addr=A.B.C.D&dev=(your-ups-device-name)

or

http://<nutcase-ip>:<port>?addr=A.B.C.D&port=P&dev=(your-ups-device-name)

Metrics & Text

The metrics end point returns data suitable for Prometheus. If called from a browser then plain text is returned. Calling this end-point usually uses the target parameter as this is the usual method used by Prometheus. However it can also be called with addr and port.

Specifying the address of the server, assuming the default port, 3493.

http://<nutcase-ip>:<port>/metrics?target=A.B.C.D

Specifying the address of the server and the port:

http://<nutcase-ip>:<port>/metrics?target=A.B.C.D:P

Specifying the address of the server and the port (P):

http://<nutcase-ip>:<port>/metrics?addr=A.B.C.D&port=P

The JSON End-point

The JSON end point returns JSON data suitable for HomePage or any app that can use the formatted JSON data. Calling this end-point can use the target parameter or the addr and port parameters. Examples are:

Specifying the address of the server, assuming the default port, 3493.

http://<nutcase-ip>:<port>/json?target=A.B.C.D

Specifying the address of the server and the port.

http://<nutcase-ip>:<port>/json?target=A.B.C.D:P

Specifying the address of the server and the port (P).

http://<nutcase-ip>:<port>/json?addr=A.B.C.D&port=P

Diagnostics

The log End-point

The log end point returns a list of the last 20, or other requested number, of lines from the log file to speed diagnostics.

View the last 20 lines of the log file.

http://<nutcase-ip>:<port>/log

Optionally view a given number of last lines of the log file.

http://<nutcase-ip>:<port>/log?lines=30

The help End-point

The help end point returns basic usage information and advice.

http://<nutcase-ip>:<port>/help

The raw end-point

The raw end point returns JSON data with extra diagnostic information and is intended for support and debugging.

Specifying the address of the server, assuming the default port, 3493.

http://<nutcase-ip>:<port>/raw?target=A.B.C.D

Specifying the address of the server and the port.

http://<nutcase-ip>:<port>/raw?target=A.B.C.D:P

Specifying the address of the server and the port (P).

http://<nutcase-ip>:<port>/raw?addr=A.B.C.D&port=P

Parameters

Valid URL parameters are:

Path	Function	Notes
lines	Only valid when calling /log	http://(nutcase-ip):(nutcase-port)/log?lines=40
mode	Only valid when calling /json or /raw	Options: nut apc Default nut (no need to specify)
target	Specifies the address and, optionally, port of the target server	Used only with these end points: /json /metrics /raw /apclog
	Format:
	http://(nutcase-ip):(nutcase-port)/json?target=10.20.30.40	Sets the server address. The default port is inferred by the mode (apc or nut)
	http://(nutcase-ip):(nutcase-port)/json?target=10.20.30.40:4567	Sets the server address and explicitly sets the port
addr	Specifies the address of the target server	Sets the server address. The default port is inferred by the mode (apc or nut) but can be set explicitly by adding a port parameter Used with these end points: / /json /metrics /raw /apclog
	Format:
	http://(nutcase-ip):(nutcase-port)/json?addr=10.20.30.40	Sets the server address. The default port is inferred by the mode (apc or nut)
	http://(nutcase-ip):(nutcase-port)/json?addr=10.20.30.40&port=4567	Sets the server address and explicitly sets the port, if a non-statndard one is in use.
port	Specifies the port of the target server	Explicitly defines the port when using addr
elem	Causes the JSON to be filtered to return only the listed elements.	Multiple elem attributes can be specified, See Filtering the JSON

elem=ups/ups.status