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

Change the MAC address of one or more modems

Use this to give modems new MAC addresses. Supported on XProxy XH20/XH22 modems; others are skipped silently. Mode 1 generates a random address based on mac.mac; mode 2 sets mac.mac as given. Each changed modem reboots. The answer is success even when some modems were skipped.

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

Request body application/json · required

positionsinteger[]required
macobjectrequired
mac.modeintegerrequired

1 random based on mac; 2 exact mac.

One of 1, 2
mac.macstringrequired

MAC address with colons or dashes.

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

Result.

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
Sent change MAC failed. Please try again later!positions or mac missing or malformed.Send positions and mac with mode and mac.
Verified against XProxy v21.3.2 on Nov 17, 2026