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.
Backup, snapshot, restore, upgrade and reboot each need the matching right in the role of the account. Without it the answer is 403.
POST /system/upgradeUpload a new supervision package (the gateway application itself). The file is stored on the gateway; the upgrade starts when you then call system.upgradeSupervisionRevision('file', callback), which is what the web interface does.
Request:
multipart/form-data with one field named file.
Response:
200 on successful upload. 208 with SYSTEM_ALREADY_UPGRADING if an upgrade is running. 405 with ALREADY_UPLOADING if another upload is in progress. 500 on 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 upgrade starts when you then call system.upgradeFirmwareRevision('file', callback).
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).
By default the network configuration of the device is kept. Add the form field applyNetwork=1 to restore the network configuration of the backup as well.
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\":\"$PASS\"}"
# 2. download backup
curl -b /tmp/cookies.txt -OJ 'https://gateway.example.com/system/backup'
# 3. logout
curl -b /tmp/cookies.txt '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