- API Reference
- Box API
- System settings
Change one section of the system settings (selected by type)
Use this to save one settings section. type picks the section and data carries the same shape GET /get_system_settings returns for it. Side effects by type: current_timezone restarts the panel (msg success_app_restart); static_ip reboots the box (success_app_reboot) and can make it unreachable on a wrong address; dashboard_port restarts the panel on the new port; dashboard_auth replaces the dashboard login and whitelist at once (and on the VPS when forwarding is on); duckdns tests the token before saving; telemetry restarts log shipping; system_recovery updates the dongle and USB recovery service. Other types: force_dhcp, controller_log_retention, watch_dog, bridging_service, ttl, gui_theme. An unknown type, or a timezone change whose link command fails, still answers status true. The request may carry secrets (dashboard password, DDNS token, ingestion key).
/update_system_settingsRequest body application/json · required
current_timezone, static_ip, dashboard_auth, duckdns, dashboard_port, force_dhcp, controller_log_retention, watch_dog, bridging_service, ttl, telemetry, system_recovery, gui_themeSection payload keyed like the GET response.
Responses
Result of the section save.
True when the box accepted the request.
Outcome code or message (see the operation's error table).
The caller is not trusted (not loopback, LAN, whitelisted or allowed Tailscale) and sent no valid Basic credentials. The body depends on whether "Basic auth for all API" is on. Routes that also use the panel login can answer a plain-text 401 "Unauthorized Access" instead.
Errors returned in msg
| msg | Meaning | What to do |
|---|---|---|
success_app_restart | Saved; the panel restarts now. | Wait about a minute then reconnect. |
success_app_reboot | Static IP saved; the box reboots now. | Reconnect on the new address after the reboot. |
Invalid timezone! | The timezone is not a known name. | Use a value from timezones. |
Static IP invalid. Please correct and try again! | Bad static IP. | Send a valid IPv4. |
Gateway IP invalid. Please correct and try again! | Bad gateway. | Send a valid IPv4. |
Netmask invalid. Please correct and try again! | Bad netmask. | Send a dotted mask or a prefix up to 32. |
Static IP is same with Gateway IP. Please change to another! | IP equals gateway. | Use a different address. |
does not same subnet | The static IP is not in the /24 of the gateway (message starts with the two addresses). | Use an address in the gateway subnet. |
Need enable Dashboard Authentication when filled Username/Password! | User or password sent with login disabled. | Enable login or clear the fields. |
Need fill Username/Password when enabled Dashboard Authentication! | Login enabled without credentials. | Send both. |
Need enable Password Authentication when Whitelist IP Authentication enabled! | Whitelist needs password login. | Enable password login. |
Need enable Password Authentication when Authentication in LAN enabled! | LAN auth needs password login. | Enable password login. |
Need enable Password Authentication when Tailscale devices may skip the login! | Tailscale bypass needs password login. | Enable password login. |
Test and setting successfully! | DuckDNS token works and is saved. | None. |
Domain or Token invalid! | DuckDNS rejected the hostname or token. | Check both in DuckDNS. |
Please choice the port in the range (80-65535) | Dashboard port out of range. | Use 80-65535. |
Please set watchdog time | Watchdog enabled without time. | Send a time. |
TTL must be a number between 1 and 255! | Bad TTL. | Send 1-255. |
Service name is required | Telemetry enabled without service name. | Send service_name. |
Log path is required | Telemetry enabled without log path. | Send log_path. |
SigNoz endpoint and ingestion key are required | SigNoz chosen without endpoint or key. | Send both. |
Graylog endpoint is required | Graylog chosen without endpoint. | Send the endpoint. |
Failed to initialize | Telemetry saved but the provider did not start (message ends with the provider). | Check endpoint and key. |
Invalid value for | A recovery field has the wrong type (message ends with the field). | Send the right type. |
Backoff base interval must be at least 5 seconds | Recovery value out of range. | Raise the value. |
Backoff max interval must be >= base interval | Recovery value out of range. | Fix the interval. |
Backoff factor must be at least 1 | Recovery value out of range. | Raise the value. |
No response must be 30-86400 seconds | Recovery value out of range. | Use 30-86400. |
Web page down must be 0 (never) or 2-1440 minutes | Recovery value out of range. | Use 0 or 2-1440. |
No IP must be 1-1440 minutes | Recovery value out of range. | Use 1-1440. |
Failed to enable USB recovery service | The recovery service did not start. | Retry; check the box logs. |
Failed to apply system recovery setting | Unexpected error while saving recovery. | Retry; check the box logs. |
Theme saved! | GUI theme saved. | None. |
Configuration failed! | type or data is missing or malformed. | Send type and the section payload. |