API Documentation – powersentrix.com

0 Communication Architecture

The UPS device initiates all communication with the server — the server never polls the UPS, the UPS registers itself. The server can then directly control the device via HTTP calls to the UPS IP address stored during registration.

Key principle: The UPS actively pushes data to the server. When the server needs to control the UPS (e.g. toggle a port), it calls directly over HTTP to the address the UPS registered from — not through any cloud tunnel. If the UPS is behind NAT, the customer's router translates and forwards the request into the internal network.

Multiple UPS systems — only one public IP address needed. You do not need a separate public IP for each UPS. Simply configure NAT port forwarding on your router — each UPS gets a different port of the same public IP:

// Router NAT port forwarding (example)
XXX.XXX.XXX.XXX:5000  →  10.10.18.10:443   // UPS 1  (e.g. server room A)
XXX.XXX.XXX.XXX:5001  →  10.10.19.10:443   // UPS 2  (e.g. server room B)
XXX.XXX.XXX.XXX:5002  →  10.10.20.10:443   // UPS 3  (e.g. branch office)
// ...

In each UPS web management (Server URL field) enter its assigned address: https://XXX.XXX.XXX.XXX:5000. After registration the NMS server stores exactly that address and uses it for all direct calls to that UPS. A single public IP address is therefore sufficient to manage any number of UPS systems.

1 Authentication

Management API endpoints (sections 3 & 4) require a JWT bearer token obtained from /user/authenticate. Device API (section 2) does not require a token.

POST /user/authenticate No token

Authenticate with email and password. Returns a JWT token.

Request body

{
  "email": "your@email.com",
  "password": "yourPassword"
}

Response 200 OK

{
  "token": "eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiJ1c2VyQGV4YW1...",
  "user": {
    "id": 42,
    "login": "your@email.com",
    "name": "Novak Jan",
    "role": "ROLE_USER",
    "avatar": "base64encodedImage..."
  }
}

Using the token — add this header to every subsequent request:
Authorization: Bearer <token>

Response 400 — Error

{ "message": "invalidEmailOrPassword" }
// alebo / or: "disabledLoginFromWeb"

2 Device API (UPS firmware → server)

These endpoints are called directly by the UPS firmware. You only need them when running your own monitoring server instead of the PowerSentrix cloud portal.

Auth: These endpoints do not require JWT. Identification is via companyId — keep it confidential.

POST /api/setNewUps companyId + cmm

Registers a new UPS on the server. Called by firmware on first boot or after factory reset. The server automatically captures the device IP.

Query parameters

Parameter	Type	Description
`companyId` *	string	Your company ID (from the portal)
`cmm` *	string	Unique UPS identifier (upsId field in UPS config)
`upsDescription`	string	Optional device description

Request body — Ident

{
  "sn":           "PSX-2024-001234",  // sériové číslo / serial number
  "type":         "PWX-12-4422",     // model (musí existovať na serveri)
  "comFirmware":  "v3.2.1",          // firmware ESP32 (komunikačný modul)
  "mainFirmware": "v2.1.0",          // firmware STM32 (hlavný kontrolér)
  "comUptime":    "2d 14h 33m",      // uptime ESP32
  "mainUptime":   "5d 02h 11m",      // uptime STM32
  "cpuLoad":      12,                // zaťaženie CPU v %
  "totalRamSize": 327680,           // celková heap pamäť (bytes)
  "freeRamSize":  218340,           // voľná heap pamäť (bytes)
  "info":         ""                 // voliteľný doplňujúci text
}

POST /api/setUpsData companyId + cmm

Pushes the full device status to the server. Called periodically by firmware (default every 5 minutes).

Query parameters

Parameter	Type	Description
`companyId` *	string	Company ID
`cmm` *	string	UPS identifier

Request body — UpsComplexObject

{
  "config": {
    "settings": {
      "dhcp": 1, "ip": "192.168.1.100", "netmask": "255.255.255.0",
      "gateway": "192.168.1.1", "dns": "8.8.8.8",
      "ntpServer": "pool.ntp.org", "timezone": "CET-1CEST,M3.5.0,M10.5.0/3",
      "forcePowerFromBatteries": 0,
      "remoteServer": { "serverUrl": "https://view.powersentrix.com", "companyId": "abc123", "upsId": "ups-01" }
    },
    "outputs": [
      { "id": 0, "description": "Router", "status": "ON", "voltage": 4810 },
      // ... celkom 12 výstupov (id 0–11) / 12 outputs total (id 0–11)
    ],
    "extraActions": [
      { "id": "0", "event": 1, "baseStatus": 0, "action": 1 }
    ],
    "ident": { /* Ident objekt — rovnaký ako pri setNewUps */ }
  },
  "upsData": {
    "voltages": [4810, 4805, 2410, 2408, 1205, 1202, 502, 501, 0, 0, 0, 0],
    // napätia v mV×10 (napr. 4810 = 48.10 V) / voltages in mV×10 (e.g. 4810 = 48.10 V)
    "currents": [150, 320, 200, 0, 0, 0, 0, 0, 0, 0, 0, 0],
    // prúdy v mA (napr. 150 = 1.50 A) / currents in mA (e.g. 150 = 1.50 A)
    "outputs": [1, 1, 1, 0, 1, 1, 0, 0, 0, 0, 0, 0],
    // 1 = ZAP/ON, 0 = VYP/OFF
    "ventilation": 0,
    "uptime": "5d 02h 11m",
    "temps": { "board": 42, "mcu": 51 },
    // teploty v °C (integer) / temperatures in °C
    "ps": [
      {
        "main": 5410, "load": 4810, "batt": 5220, "buv": 4800,
        "cell": [1305, 1308, 1302, 1305],
        "status": { "h": { "hb": [1], "lb": [0] }, "l": { "hb": [0], "lb": [1] } }
      }
      // druhý PSU má rovnakú štruktúru / second PSU has the same structure
    ]
  }
}

POST /api/setUpsLog companyId + cmm

Sends a single event log record (output state change, alarm, power failure…).

Request body — UpsLogRecord

{
  "ord":         1234,                        // sekvenčné číslo záznamu
  "code":        "I/E01",                     // kód udalosti
  "cmm":         "ups-01",                    // identifikátor UPS
  "description": "Output 1 turned ON",       // popis udalosti
  "params":      "",                          // voliteľné parametre
  "timestamp":   "2026-05-08 14:32:01"        // formát: yyyy-MM-dd HH:mm:ss
}

3 Monitoring API

Endpoints for reading UPS data from the monitoring server — for custom dashboards and integrations.

All endpoints in this section require: Authorization: Bearer <token>

GET /ups/getUpsComplexObject JWT

Returns the full UPS status object — live data, config, outputs, temperatures, power supplies. Same structure as the setUpsData body.

Parameter	Type	Description
`id` *	string	Internal UPS database ID (from getUpsList or portal)

Response

{ "responseMessage": "OK", "responseObject": { /* UpsComplexObject */ } }

GET /ups/getUpsLogs JWT

Returns event log records for a UPS. Supports pagination.

Parameter	Type	Description
`id` *	string	UPS ID
`page`	integer	Page number (0-based, default 0)
`limit`	integer	Max records per page (default 50)

Response

[
  {
    "id": 9901,
    "upsId": "42",
    "cmm": "ups-01",
    "code": "I/E01",
    "description": "Output 1 turned ON",
    "params": "",
    "timestamp": "2026-05-08T14:32:01"
  }, // ...
]

GET /ups/getBasicInfo JWT

Basic device summary — name, model, firmware versions, uptime, temperature, location.

Parameter	Type	Description
`id` *	string	UPS ID

Response

{
  "name": "Server Room UPS",   "ip": "192.168.1.100",
  "model": "PWX-12-4422",       "serialNumber": "PSX-2024-001234",
  "comFirmware": "v3.2.1",    "mainFirmware": "v2.1.0",
  "comUptime": "2d 14h 33m",  "mainUptime": "5d 02h 11m",
  "onOffLine": "online",       "temperature": 42,
  "description": "...",        "location": "Rack A",
  "company": "Acme Corp",     "cmm": "ups-01",
  "timestamp": "2026-05-08T14:30:00.000+0000"
}

GET /ups/getUpsList JWT

List of UPS devices accessible to the authenticated user.

Parameter	Type	Description
`searchText`	string	Filter by name or description
`searchType`	string	Filter by model type name

Response

{ "responseMessage": "OK", "responseObject": [ /* pole Ups objektov */ ] }

4 UPS Control

Remote control of UPS output ports. The server does not queue commands for the UPS to fetch — when a command arrives, the server calls the UPS HTTP endpoint directly at the IP stored during registration.

How UPS control works:

1. The UPS registers via POST /api/setNewUps — server stores the UPS IP address and API Key.
2. When you call GET /ups/changePortState, the server immediately makes:

GET http://{ups.ip}/api_actions?apiKey={key}&fn=3&param1={port}
// direct HTTP call to the UPS IP address

3. The UPS processes the command and responds. The server returns the result to you.

Network reachability: The monitoring server calls the address it stored when the UPS registered (the address from which setNewUps was called). If the UPS is behind NAT, the customer's router translates the request and forwards it into the internal network — the server does not need to know the internal IP, the external address and port just need to be reachable from the internet.

API Key — where to get it: The API Key is generated automatically when a user account is created on the UPS (Web Management → Users). Each user has their own unique API Key. To allow the API to also control the UPS (not just read data), the checkbox Enable API Write Actions must be ticked in that user's profile card. Without this permission the server rejects port state change requests.

UPS /api_actions — fn parameter reference

fn	Action	Extra param	Used by server
`1`	Device identification	—	`testConnection`, `getBasicInfo`
`2`	Full UPS data object	—	`getUpsComplexObject`
`3`	Toggle port state (ON↔OFF)	`param1=N` (port 0–11)	`changePortState`
`4`	Port restart — OFF for 5 s then ON	`param1=N` (port 0–11)	`restartPort`
`5`	Change output port description	`param1=N` `param2=`text (URL-encoded)	—

fn=4 (Port restart) — The port is immediately turned off and automatically switched back on after 5 seconds. Only works if the port is currently ON (status=ON). Restart runs asynchronously (FreeRTOS task) — response {info:1} means the restart was initiated, not that it has completed.

fn=5 (Change description) — URL-decodes param2 (%20→space, +→space). Max 128 characters. Change is immediately saved to SPIFFS configuration.

GET /ups/changePortState JWT

Toggles an output port state (ON→OFF or OFF→ON). The server calls the UPS via GET /api_actions?fn=3&param1={port} at the stored IP.

This endpoint toggles the current state — it does not set a specific value. Check the current port state via getUpsComplexObject before calling.

Parameter	Type	Description
`id` *	string	Internal UPS DB ID (from getUpsList)
`port` *	integer	Output port index (0–11)

Example call

GET /ups/changePortState?id=42&port=0
Authorization: Bearer eyJhbGci...

// server then calls:
GET http://192.168.1.100/api_actions?apiKey=mykey&fn=3&param1=0

5 Data Models

Output

{
  "id": 0,                   // 0–11
  "description": "Router",   // používateľský názov / user label
  "status": "ON",            // "ON" alebo "OFF"
  "voltage": 4810           // mV×10  →  48.10 V
}

ExtraAction

{
  "id": "0",          // slot "0"–"3"
  "event": 1,        // 0=žiadna, 1=IN1↑, 2=IN1↓, 3=IN2↑, 4=IN2↓
  "baseStatus": 0,  // index výstupu (0–11)
  "action": 1        // 0=vypnúť výstup, 1=zapnúť výstup
}

PowerSupply

{
  "main": 5410,                           // vstupné napätie zo siete (mV×10)
  "load": 4810,                           // napätie 48V zbernice (mV×10)
  "batt": 5220,                           // napätie batériového bloku (mV×10)
  "buv": 4800,                            // podpäťová ochrana batérie (mV×10)
  "cell": [1305, 1308, 1302, 1305],      // napätia jednotlivých článkov (mV×10)
  "status": { "h": { "hb": [1], "lb": [0] }, "l": { "hb": [0], "lb": [1] } }
}

Voltage & Current units:
Voltages: integer × 10 = mV (e.g. 4810 = 48.10 V) · Currents: integer = mA (e.g. 150 = 1.50 A) · Temperatures: integer = °C

6 Error Codes

HTTP	When
200 OK	Request successful. Check responseMessage field.
400 Bad Request	Invalid credentials or malformed request body.
401 Unauthorized	Missing or invalid JWT token, or companyId not found.
404 Not Found	Requested resource (UPS, company) not found.

Message field codes

Code	Description
`invalidEmailOrPassword`	Wrong email or password.
`disabledLoginFromWeb`	Web login is disabled for this user account.
`Invalid authorization token`	JWT token is missing, expired, or invalid.