API Reference
Dashboard
  1. API Reference
  2. Box API
  3. 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).

  • Destructive · confirm first
  • Basic auth
  • Panel API · since v20.8.0
  • Hub: needs owner approval
  • updateSystemSettings
POST/update_system_settings

Request body application/json · required

typestringrequired
One of current_timezone, static_ip, dashboard_auth, duckdns, dashboard_port, force_dhcp, controller_log_retention, watch_dog, bridging_service, ttl, telemetry, system_recovery, gui_theme
dataobjectrequired

Section payload keyed like the GET response.

Responses

Result of the section save.

statusbooleanrequired

True when the box accepted the request.

msgstringrequired

Outcome code or message (see the operation's error table).

Errors returned in msg

msgMeaningWhat to do
success_app_restartSaved; the panel restarts now.Wait about a minute then reconnect.
success_app_rebootStatic 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 subnetThe 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 timeWatchdog enabled without time.Send a time.
TTL must be a number between 1 and 255!Bad TTL.Send 1-255.
Service name is requiredTelemetry enabled without service name.Send service_name.
Log path is requiredTelemetry enabled without log path.Send log_path.
SigNoz endpoint and ingestion key are requiredSigNoz chosen without endpoint or key.Send both.
Graylog endpoint is requiredGraylog chosen without endpoint.Send the endpoint.
Failed to initializeTelemetry saved but the provider did not start (message ends with the provider).Check endpoint and key.
Invalid value forA recovery field has the wrong type (message ends with the field).Send the right type.
Backoff base interval must be at least 5 secondsRecovery value out of range.Raise the value.
Backoff max interval must be >= base intervalRecovery value out of range.Fix the interval.
Backoff factor must be at least 1Recovery value out of range.Raise the value.
No response must be 30-86400 secondsRecovery value out of range.Use 30-86400.
Web page down must be 0 (never) or 2-1440 minutesRecovery value out of range.Use 0 or 2-1440.
No IP must be 1-1440 minutesRecovery value out of range.Use 1-1440.
Failed to enable USB recovery serviceThe recovery service did not start.Retry; check the box logs.
Failed to apply system recovery settingUnexpected 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.
Verified against XProxy v21.3.2 on Nov 17, 2026