The /system/* endpoints expose system-level operations on the gateway: firmware upgrades, supervision package upgrades, system backups, snapshot downloads, and reboot. They are typically called by the cloud during remote maintenance windows.
All endpoints require an authenticated session — see authentication.
POST /system/upgradeUpload a new supervision package (the gateway application itself) and apply it. The gateway saves the file under its base directory and triggers the upgrade pipeline — every running driver is stopped cleanly, the new code is installed, and the gateway reboots into the new revision.
Request:
multipart/form-data with one file field. The field name is not enforced — file is conventional.
Response:
200 OK on successful upload (the upgrade itself runs asynchronously). 500 on upload failure with a plain-text error body.
Example:
curl -b cookies.txt -X POST \
-F 'file=@supervision-2026.04.zip' \
'https://gateway.example.com/system/upgrade'
See also: the peers equivalent
system.upgradeSupervisionRevision, which fetches the new revision from the upgrade server instead of accepting an upload.
POST /system/firmware/upgradeSame as /system/upgrade but targets the firmware layer (kernel, OS, base services). The upload lands under /install and is picked up by the firmware upgrade pipeline at the next boot.
Example:
curl -b cookies.txt -X POST \
-F 'file=@firmware-2026.04.bin' \
'https://gateway.example.com/system/firmware/upgrade'
GET /system/actions/rebootTrigger an immediate reboot of the gateway machine.
Example:
curl -b cookies.txt 'https://gateway.example.com/system/actions/reboot'
The HTTP response may not arrive — the system starts rebooting before the response is flushed. Treat this as fire-and-forget.
See also: the peers equivalent
system.reboot.
GET /system/backupDownload a complete system backup as a ZIP archive — all configuration, addresses, gateways, routes, logics, and account data. This is the snapshot the cloud uses for off-site backups and remote restore.
Response headers:
Content-Type: application/zip
Content-Disposition: attachment; filename="<SUPERVISION_NAME>-<YYYY-MM-DD-HH-mm-ss>.zip"
Body: the ZIP archive (streamed).
Example:
curl -b cookies.txt -OJ \
'https://gateway.example.com/system/backup'
# saves <name>-<date>.zip
If a restore is currently in progress, the endpoint returns 500 with the body System is restoring....
GET /system/snapshot/:nameDownload a previously-saved snapshot by filename. Snapshots are taken automatically by the gateway on a schedule (or manually via the UI) and stored in the snapshot directory. Use :name exactly as listed by the snapshot manager.
Response headers:
Content-Disposition: attachment; filename="<SUPERVISION_NAME>-Snapshot-<formatted-date>.zip"
Example:
curl -b cookies.txt -OJ \
'https://gateway.example.com/system/snapshot/2026-04-08T03-00-00.zip'
Returns 404 if the snapshot file does not exist.
POST /system/restoreUpload a backup or snapshot ZIP and restore the gateway from it. Once the upload is complete, the restore pipeline runs and the gateway reboots its PM2 supervisor to pick up the restored state.
Request:
multipart/form-data with one file field. Up to 12 files can be uploaded in the same call (only the first one is restored).
Response:
{ "err" : null }
on success, or:
{ "err" : "<error message>" }
on failure.
Example:
curl -b cookies.txt -X POST \
-F 'file=@boiler-room-2026-04-01.zip' \
'https://gateway.example.com/system/restore'
Important: the gateway reboots its supervisor at the end of a successful restore — the connection is dropped while it comes back up. Wait at least ~30 seconds before re-authenticating.
GET /sessionReturn the current authenticated session, or 401 if there is no session. Useful as a cheap "is my cookie still valid" check.
curl -b cookies.txt -w '%{http_code}\n' 'https://gateway.example.com/session'
#!/bin/bash
# 1. authenticate
curl -c /tmp/cookies.txt -X POST 'https://gateway.example.com/auth/rest' \
-H 'Content-Type: application/json' \
-d "{\"username\":\"admin\",\"password\":\"$(echo -n $PASS | md5sum | awk '{print $1}')\"}"
# 2. download backup
curl -b /tmp/cookies.txt -OJ 'https://gateway.example.com/system/backup'
# 3. logout
curl -b /tmp/cookies.txt -X POST 'https://gateway.example.com/logout'
HTTP_CODE=$(curl -b cookies.txt -s -o /dev/null -w '%{http_code}' 'https://gateway.example.com/session')
if [ "$HTTP_CODE" != "200" ]; then
echo "session expired, re-authenticating..."
# ... call /auth/rest again
fi