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

Give one modem a new public IP from the panel

Use this to rotate the IP of one slot by its position. Starts the rotation and returns at once; the new IP arrives later. When "rotation delay before process" is set the rotation is scheduled and msg is empty. Refused when the modem was stopped, when the license has no IP rotation (except in slave mode), while the modem is already resetting, or when the slot rotated too often.

  • Action · reversible
  • Basic auth
  • Panel API · since v20.8.0
  • Hub: routine call
  • rotateIpByPosition
POST/v2/rotate_ip

Request body application/json · required

positionintegerrequired

Slot number (position) on the box, starting at 1. A missing or non-integer value makes the box answer HTTP 500.

Authentication

Needs dashboard Basic credentials when dashboard authentication is enabled; trusted callers (loopback, LAN unless "force auth for local" is on, whitelisted IP, allowed Tailscale) pass without them.

Responses

Rotation started, or a refusal with status false.

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 modem was stopped (by the user or Smart IP Guard).Connect it with POST /v2/connect_dongle first.
need_upgradeThe license does not include IP rotation.Upgrade the license plan.
slot_not_foundNo modem at this position.Use a position from GET /v2/dongle_device_list.
modem_disconnectedThe modem has no connection to rotate.Reboot the modem and try again.
modem_resettingA rotation is already running on this slot.Wait until it finishes.
reset_too_muchThe slot rotated too recently (per-port rotation limit).Wait for the minimum rotation interval and try again.
Verified against XProxy v21.3.2 on Nov 17, 2026