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

Get a new public IP for one slot

Use this to rotate the IP of a slot by its number. Returns at once; poll the slot status until it reports MODEM_READY. A slot stopped by the box (auto-stop) is refused with MODEM_STOPPED. With a rotation delay configured the answer is status: true with an empty msg.

  • Action · reversible
  • Basic auth when API auth is on
  • Public API · since v20.8.0
  • Hub: needs owner approval
  • rotateIpForPosition
GET/api/v1/rotate_ip/position/{position}

Path parameters

positionintegerrequired

Slot number (position) on the box, starting at 1. A value that is not an integer makes the box answer HTTP 500.

Example 1

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
MODEM_STOPPEDThe box stopped this slot (auto-stop after repeated failures).Clear the stop in the panel first.
command_sentWith status true, the rotation started. With status false, the modem did not accept the command.On status false wait a few seconds and check the slot status before retrying.
modem_resettingA rotation is already running on this slot.Wait for MODEM_READY before rotating again.
reset_too_muchThe last rotation was less than the minimum interval ago (5 seconds by default).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 modem in this slot.Use a position from /api/v1/info_list.
Verified against XProxy v21.3.2 on Nov 17, 2026