API Reference
Dashboard
  1. API Reference
  2. Box API
  3. Rotation

Get a new public IP for one proxy (legacy query-string form)

Use this only for existing integrations; new code should use /api/v1/rotate_ip/proxy/{proxy}. When a rotation delay is configured the box answers command_sent at once and rotates after the delay. A host that is a registered external XProxy server is forwarded unless internal is present.

  • Action · reversible
  • Basic auth when API auth is on
  • Public API · since v20.8.0
  • Hub: needs owner approval
  • rotateIpLegacy
GET/reset

Query parameters

proxystringrequired

Proxy address as HOST:PORT, for example 192.0.2.10:4001. Only the port selects the slot.

Example 192.0.2.10:4001
internalstringoptional

Any value. Answer from this box even if the host is a registered external server.

Authentication

Open by default: with "Basic auth for all API" (api_auth_check) off, anyone who can reach the box can call it. When it is on, the caller must be trusted (loopback, LAN unless "force auth for local" is on, whitelisted IP, allowed Tailscale) or send dashboard Basic credentials, which are checked only when dashboard authentication (dashboard_disable_auth off) is enabled.

Responses

Rotation accepted or refused.

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
missing_proxy_parameterproxy is missing.Send proxy=HOST:PORT.
invalid_format_proxyproxy is not HOST:PORT.Send proxy=HOST:PORT.
command_sentWith status true, the rotation started. With status false, the modem did not accept the command.On status false check the slot status before retrying.
modem_resettingA rotation is already running.Wait for MODEM_READY.
reset_too_muchLess than the minimum interval (5 seconds by default) since the last rotation.Wait and retry.
modem_disconnectedThe modem type cannot rotate.Check the modem in the panel.
need_upgradeThe license does not include IP rotation.Upgrade the license.
slot_not_foundNo slot uses this port.Use a port from /api/v1/info_list.
external_server_errorThe external server did not answer.Check that server or add internal=1.
Verified against XProxy v21.3.2 on Nov 17, 2026