API Reference

The device HTTP server exposes a REST API covering auth, system, network, OTA, peripherals, protocols, and rule scripts. This page lists core endpoints and conventions.

1. Conventions

• Base URL: http://<device-ip> (STA: DHCP address; AP: 192.168.4.1).
• Auth: unless marked public, endpoints require the sessionId cookie from login. Sessions are memory-only — a reboot invalidates them.
• Responses: JSON; errors look like { "error": "<message>" }.
• Memory gating: heavy endpoints return 503 + Retry-After under SEVERE memory pressure; clients should retry.
• Login form: /api/auth/login reads form/query params only — no JSON body. Use application/x-www-form-urlencoded.

2. Auth

Method	Path	Description
POST	/api/auth/login	Login (username, password), returns sessionId
POST	/api/auth/logout	Logout
GET	/api/auth/session	Session status
POST	/api/auth/change-password	Change password

Default account admin / admin123:

curl.exe --noproxy "*" -s -c cookie.txt -X POST "http://192.168.5.36/api/auth/login" `
  -d "username=admin&password=admin123"

3. System

Method	Path	Description
GET	/api/health	Health check (public, used for reboot-recovery polling)
GET	/api/system/status	Heap, uptime, network state
GET	/api/system/info	Firmware version, chip, build info
GET	/api/system/metrics	Live metrics
GET	/api/system/diag-bundle	Diagnostics incl. restart.lastRestartReason
GET	/api/system/capabilities	Feature switches & capability list
POST	/api/system/restart	Reboot
POST	/api/system/factory-reset	Factory reset

4. Network & WiFi

Method	Path	Description
GET	/api/network/status	Current mode/IP/connection state
POST	/api/network/config	Update config (JSON, mode numeric string; schedules reboot)
GET	/api/wifi/scan	Scan networks
POST	/api/wifi/config	Provisioning
POST	/api/wifi/connect	Connect to an SSID

mode: "0" = STA, "1" = AP. Clear staSSID when switching to AP for testing, or boot-time smart correction switches back to STA. See Network Mode Switching.

5. OTA Upgrade

All /api/ota/* require auth.

Method	Path	Description
POST	/api/ota/begin	Begin OTA (optional form param size); memory gate + ota_1 pre-check
POST	/api/ota/upload	multipart upload; auto-reboot 3s after final chunk
GET	/api/ota/status	Progress (progress, in_progress)
POST	/api/ota/cancel	Cancel session
POST	/api/ota/url	Online URL upgrade
POST	/api/ota/update	Trigger local update

Status codes: 200 success · 400 bad params/session conflict/upload without begin (no retry) · 501 no OTA partition (permanent, never retry) · 503 memory gate (retry per Retry-After).

See OTA Firmware Upgrade for the full flow and false-failure handling.

6. Device & Config

/api/device/info, /api/device/config, /api/config, /api/config/transfer/export|import|import-chunk, /api/device/time, /api/device/time/sync.

7. Peripherals & Execution

/api/peripherals (list/update/enable/disable/read/write), /api/peripherals/types, /api/peripherals/validate-pins, /api/periph-exec (list/run/results/controls/events).

8. Protocols & Rules

/api/protocol/config, /api/protocol/mqtt/config, /api/mqtt/status|reconnect|disconnect|test, /api/protocol/modbus-rtu/config, /api/rule-script.

9. Logs and Optional File APIs

/api/logs provides list/info/clear operations. /api/files provides list/content/save only in custom firmware built with FASTBEE_ENABLE_FILE_MANAGER=1; current release builds have no matching Web page.

Runtime Capability

Logs, user management, and RuleScript endpoints depend on compile support, user switches, and the memory budget. Optional file APIs depend on their compile macro. Query /api/system/capabilities and /api/features/status; unavailable APIs return the documented status.

10. Automation Entry Points

• E2E OTA: node scripts/e2e-ota-test.js --url http://<IP> --user admin --pass admin123
• Browser quick suite: DEVICE_IP=<IP> FAST_MODE=1 TEST_DELAY_MS=500 npx playwright test -c test/browser/playwright.quick.config.ts
• Full device suite: scripts/test-all.ps1 -Checks all -BaseUrl http://<IP> -DeviceProfile unified (includes device soak and memory monitoring)