API Reference
Dashboard
  1. API Reference
  2. Box API
  3. Proxy settings

Add a proxy group

Appends the posted group to the group list and reloads all proxies. Needs the proxy-group license feature. The handler does not reject a primary_port that already exists, so posting the same group twice creates a duplicate; check /proxy_group_config first and use /edit_proxy_group_config to change a group.

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

Request body application/json · required

primary_portintegerrequired

Port of the group proxy. Identifies the group.

position_listinteger[]required

Slots (positions) that serve the group.

proxy_typestringoptional

0 HTTP over IPv4, 1 SOCKS5 over IPv4, 2 HTTP over IPv6, 3 SOCKS5 over IPv6.

One of 0, 1, 2, 3
user_groupstringoptional

Proxy username of the group (empty for none).

pass_groupstringoptional

Proxy password of the group (empty for none).

ip_groupstringoptional

Client IPs allowed without a password, comma separated.

randomize_ip_groupbooleanoptional

When true, each new connection picks a random slot instead of the next one.

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

The stored group echoed back, or a license refusal.

statusbooleanoptional
msgstringoptional
dataobjectoptional

One proxy group: a single shared port (primary_port) that spreads clients over the listed slots.

data.primary_portintegerrequired

Port of the group proxy. Identifies the group.

data.position_listinteger[]required

Slots (positions) that serve the group.

data.proxy_typestringoptional

0 HTTP over IPv4, 1 SOCKS5 over IPv4, 2 HTTP over IPv6, 3 SOCKS5 over IPv6.

One of 0, 1, 2, 3
data.user_groupstringoptional

Proxy username of the group (empty for none).

data.pass_groupstringoptional

Proxy password of the group (empty for none).

data.ip_groupstringoptional

Client IPs allowed without a password, comma separated.

data.randomize_ip_groupbooleanoptional

When true, each new connection picks a random slot instead of the next one.

Errors returned in msg

msgMeaningWhat to do
This function is available on higher plan license only. Please contact Administrator!The license has no proxy-group feature.Upgrade the license.
Verified against XProxy v21.3.2 on Nov 17, 2026