- API Reference
- Box API
- Proxy settings
Change one section of the global proxy settings
Saves one section of the Proxy settings page, chosen by type; data carries that section's fields with the same names /get_proxies_settings returns. Sections: ipv6Config (ipv6Config, multipleIpv6Config; needs the IPv6 license feature to turn on), proxyStartPort (proxyStartPort, autoPort, ipv6Mode, proxyWatchdogInterval, optional vlessEnabled, vlessSni, ssEnabled, ssMethod), proxyGroupConfig (group_* health-check fields), rotationConfig (needs the rotation feature), enableProxyAuth (enableProxyAuth, disableProxyCache, proxyUser, proxyPass), enableIPAuth (enableIPAuth, forceLocalAuthen, ipList, optional allowTailscaleNoAuth), enablePerPortAuth (needs the selling feature to turn on), enableWhiteList / enableBlackList / bandwidthEnable (need the website-access feature to turn on; bandwidth rules go in data.data), globalWebsiteAuthorizationMode, stickyIPEnable, enableLogging, forceServerResolveDNS, webrtc, auto_reboot, exportConfig, wanProxy. Side effects: msg: success_app_restart means the controller restarts (all proxies drop for some seconds) — this happens for an IPv6 change, a port-layout change (start port, auto port, IPv6 mode, VLESS or Shadowsocks on/off), group health-check settings and WebRTC changes. Most other sections reload every proxy config. An unknown type changes nothing but still reloads all proxies and answers success. Turning on Shadowsocks or VLESS without the license answers HTTP 403.
/update_proxies_settingsRequest body application/json · required
Section to save.
ipv6Config, proxyStartPort, proxyGroupConfig, rotationConfig, enableProxyAuth, enableIPAuth, enablePerPortAuth, enableWhiteList, enableBlackList, globalWebsiteAuthorizationMode, bandwidthEnable, stickyIPEnable, enableLogging, forceServerResolveDNS, webrtc, auto_reboot, exportConfig, wanProxyFields of that section (see the description). For webrtc send enable_webrtc_leak and wan_interfaces (array); eth0 and tailscale0 are always kept.
Authentication
Needs a trusted caller (loopback, LAN unless "force auth for local" is on, whitelisted IP, allowed Tailscale) or valid dashboard Basic credentials, which are checked only when dashboard authentication is enabled.
Responses
Result. applied is live (saved, nothing restarted) or reloaded (VLESS/Shadowsocks listeners re-rendered) for the proxyStartPort and ipv6Config sections.
True when the box accepted the request.
Outcome code or message (see the operation's error table).
live, reloadedThe 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.
Turning on Shadowsocks or VLESS (including WAN VLESS/Shadowsocks) without a Premium or Business license.
True when the box accepted the request.
Outcome code or message (see the operation's error table).
Errors returned in msg
| msg | Meaning | What to do |
|---|---|---|
success_app_restart | Saved; the controller restarts to apply it (status true). | Wait until the panel answers again, then verify. |
need_upgrade | The license lacks the feature needed to turn this section on (IPv6, rotation, website access, WAN proxy). | Upgrade the license or leave the feature off. |
need_upgrade_selling | Per-port authentication needs the selling feature. | Upgrade the license. |
Start port too high for Shadowsocks: ... | The start port leaves no room for the Shadowsocks IPv6 band. | Use a start port at or below proxyStartPortMax. |
Start port range collides with WAN proxy port N — disable "Proxy through WAN" or move it first! | The new port range overlaps the WAN proxy listener. | Move or disable the WAN proxy first. |
Shadowsocks requires a Premium or Business license | HTTP 403; Shadowsocks cannot be turned on with this license. | Upgrade the license. |
VLESS requires a Premium or Business license | HTTP 403; VLESS cannot be turned on with this license. | Upgrade the license. |
Shadowsocks ports are already in use (...), free them or change the Starting Port first! | Other services already use ports of the Shadowsocks band. | Free the listed ports or pick another start port. |
Unsupported Shadowsocks cipher | ssMethod is not aes-128-gcm, aes-256-gcm or chacha20-ietf-poly1305. | Send one of those ciphers. |
The IPv6 mode is invalid! | ipv6Mode is not '0', '46' or '64'. | Send one of those values as a string. |
The Proxy Watchdog Interval is invalid, range [5-300s]! | proxyWatchdogInterval is outside 5–300. | Send a value from 5 to 300. |
WAN proxy port must be in range [1024-N] | wanProxyPort is too low or leaves no room for the VLESS/Shadowsocks offsets. | Pick a port in the given range. |
Proxy engine is not ready yet! | The proxy engine is still starting. | Retry in a few seconds. |
Port N collides with ... — pick another port! | A WAN proxy port is already used. | Pick another wanProxyPort. |
Configuration failed! | A required field of the section is missing or saving failed. | Send every field of the section and retry. |