# XProxy API — full reference for AI agents > Every documented operation of the XProxy Box API (the HTTP API of one XProxy box) and the XProxy Hub API, with its safety level. Full pages: https://xproxy.io/docs/api. Each operation also has a Markdown page (its URL + ".md"). OpenAPI 3.1 specs: https://xproxy.io/docs/api/box.openapi.yaml and https://xproxy.io/docs/api/hub.openapi.yaml. ## Rules for AI agents Every operation below has a "Safety:" line: - read: no state change. Call it freely. - action: affects one modem or one proxy and the system can undo it (rotate the IP, reboot one modem). Ask the user before you call it. - destructive: changes credentials, configuration or license-relevant state, deletes data, or acts on the whole box or all modems. Ask the user before you call it, say exactly what will change, and wait for a clear yes. 1. Ask the user before every action or destructive call. Read calls need no confirmation. 2. Never bulk-call without confirmation: do not loop an action over many modems, proxies or boxes unless the user approved that exact list. 3. Wait, then poll. Actions such as rotate and reboot answer at once (for example `{"status": true, "msg": "command_sent"}`) while the work continues for seconds to minutes. Wait at least 5 seconds, then poll the matching status call no more than once every 5 seconds, and stop after about 2 minutes. Never repeat the action while one is still running. 4. Verify via status: after an action, call the read operation named in its "For AI agents" note (or the status call of that modem) and report the result you observed, not the one you expected. 5. Never print, log or echo passwords, API keys or tokens back to the user. ## Box API authentication - By default the Box API asks for no credentials: any client that can reach the box (LAN, port forwarding, VPS forwarding, Tailscale) can call it. - When "Force API Auth" is on in General Settings → System Setting → Security, send HTTP Basic auth with the dashboard username and password (`curl -u admin:PASSWORD`). - Token links carry a per-port token in the URL path; the selling platform uses a per-proxy `?token=`; the VPN rotation link uses its own `?token=`. These tokens work without a login. Treat each one like a password. - Base URL: `http://` (the dashboard address, for example `http://192.168.1.10`). Most routes live under `/api/v1`; the exact path of each operation is shown below. ## Box API Version v21.3.2, verified on 2026-11-17. Base URL: http://192.0.2.10. ### Public API · Proxies List proxies and read the status of one proxy or slot. #### Check whether a proxy is online (legacy query-string form) `GET /status` operationId: getLegacyStatus Safety: read — no state change. Authentication: Basic auth when API auth is on Docs: https://xproxy.io/docs/api/box/get-legacy-status.md Use this only for existing integrations; new code should use `/api/v1/status/proxy/{proxy}`, which answers the same. When the host part of `proxy` is a registered external XProxy server, the box forwards the call to that server unless `internal` is present. A missing or malformed `proxy` answers `invalid_format_proxy`. #### Check whether a proxy is online by its port number `GET /status_by_port` operationId: getLegacyStatusByPort Safety: read — no state change. Authentication: Basic auth when API auth is on Docs: https://xproxy.io/docs/api/box/get-legacy-status-by-port.md Use this when you only know the port. Same answer as the status operations; a missing or non-integer `port` answers HTTP 400 `invalid_port`. #### Get the full internal state of every slot (legacy) `GET /proxy_list` operationId: getLegacyProxyList Safety: read — no state change. Authentication: Basic auth when API auth is on Docs: https://xproxy.io/docs/api/box/get-legacy-proxy-list.md Use this only when you need raw modem fields that `/api/v1/info_list` does not return. Lists every slot, including empty ones, with the box's internal modem record. The field set is the box's internal format and changes between versions. #### List connected proxies with ports, public IPs and modem details `GET /api/v1/info_list` operationId: getInfoList Safety: read — no state change. Authentication: Basic auth when API auth is on Docs: https://xproxy.io/docs/api/box/get-info-list.md Use this to discover which slots are online and which ports to use. Only slots whose modem has an active data connection are returned; empty or offline slots are left out. `total` counts all listed slots before paging. Paging applies only when both `page` and `limit` are valid integers. #### Get a plain-text list of proxy addresses of one type, one per line `GET /api/v1/proxy_list/{port_type}` operationId: getProxyListByType Safety: read — no state change. Authentication: Basic auth when API auth is on Docs: https://xproxy.io/docs/api/box/get-proxy-list-by-type.md Use this to import all online proxies into a tool that reads one proxy per line. Lists every slot with an active data connection as `HOST:PORT` for `proxy`, `socks5`, `proxy_ipv6` and `socks5_ipv6`. `vless` and `vless_ipv6` return VLESS REALITY share links and `ss` returns Shadowsocks links; those lines appear only when the license includes the protocol and the slot has the port. An unknown type returns an empty body. The body is plain text even though the box labels it `text/html`. #### Check whether a proxy is online and read its public IP `GET /api/v1/status/proxy/{proxy}` operationId: getStatusOfProxy Safety: read — no state change. Authentication: Basic auth when API auth is on Docs: https://xproxy.io/docs/api/box/get-status-of-proxy.md Use this to poll a proxy after a rotation until it reports `MODEM_READY` with the new IP. Looks the slot up by the port in `HOST:PORT`. #### Check whether a slot is online and read its public IP `GET /api/v1/status/position/{position}` operationId: getStatusOfPosition Safety: read — no state change. Authentication: Basic auth when API auth is on Docs: https://xproxy.io/docs/api/box/get-status-of-position.md Use this to poll a slot by its number after a rotation. An empty slot answers `MODEM_DISCONNECTED`; a number above the box's slot count answers `MODEM_NOT_FOUND`. ### Public API · Rotation Get a new public IP for a proxy, a slot, a group or the whole box. #### Get a new public IP for one proxy (legacy query-string form) `GET /reset` operationId: rotateIpLegacy Safety: action — affects one modem or one proxy and the system can undo it. Authentication: Basic auth when API auth is on Docs: https://xproxy.io/docs/api/box/rotate-ip-legacy.md 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. For AI agents: Changes the public IP and drops connections on the proxy for 10-60 seconds. Do not loop; check `status`, not the HTTP code. This is a GET: never put it where a browser could prefetch it. #### Get a new public IP for a proxy given its port number `POST /reset_by_port` operationId: rotateIpByPort Safety: action — affects one modem or one proxy and the system can undo it. Authentication: Basic auth when API auth is on Docs: https://xproxy.io/docs/api/box/rotate-ip-by-port.md Use this when you only know the port. Same result codes as the other rotation operations. A missing or non-integer `port` answers HTTP 500. For AI agents: Changes the public IP and drops connections on the proxy for 10-60 seconds. Do not loop; check `status`. #### Get new public IPs for several proxies at once `GET /reset_group` operationId: rotateIpGroup Safety: action — affects one modem or one proxy and the system can undo it. Authentication: Basic auth when API auth is on Docs: https://xproxy.io/docs/api/box/rotate-ip-group.md Use this to rotate a list of ports in one call: `proxy=HOST:4001,4002,4003`. Every slot with a SIM whose HTTP, SOCKS5 or other proxy port is in the list is rotated in parallel. The answer is always `status: true` once the requests are sent; check each proxy's status for the outcome. A missing `proxy` answers HTTP 500. For AI agents: Rotates every listed proxy at once and drops their connections. The answer does not say which rotations succeeded; poll each proxy's status afterwards. #### Get new public IPs for every proxy on the box `GET /reset_all` operationId: rotateIpAllLegacy Safety: destructive — changes credentials, configuration or license-relevant state, deletes data, or acts on the whole box. Authentication: Basic auth when API auth is on Docs: https://xproxy.io/docs/api/box/rotate-ip-all-legacy.md Use this to rotate every slot that has a SIM in one call. Rotations run in parallel; the answer is `status: true` once all requests are sent and does not report per-slot results. Without the IP rotation feature in the license the answer is `msg: need upgrade` (with a space) and no `status` field. For AI agents: Rotates every proxy on the box and drops every open connection at once. Never call it for a single proxy; confirm with the owner first. #### Get a new public IP for one proxy `GET /api/v1/rotate_ip/proxy/{proxy}` operationId: rotateIpForProxy Safety: action — affects one modem or one proxy and the system can undo it. Authentication: Basic auth when API auth is on Docs: https://xproxy.io/docs/api/box/rotate-ip-for-proxy.md Use this to rotate the IP of the slot behind a proxy port. The call starts the rotation and returns at once; poll the status operation until it reports `MODEM_READY`. When a rotation delay is configured on the box, the answer is `status: true` with an empty `msg` and the rotation starts after the delay. For IPv6-multiple ports the IPv6 address is rotated. For AI agents: Changes the public IP and drops open connections on this proxy for 10-60 seconds. Do not call it in a loop: the box refuses rotations closer than the minimum interval (reset_too_much). Check `status`, not the HTTP code. This is a GET, so never place it where a browser could prefetch it. #### Get a new public IP for one slot `GET /api/v1/rotate_ip/position/{position}` operationId: rotateIpForPosition Safety: action — affects one modem or one proxy and the system can undo it. Authentication: Basic auth when API auth is on Docs: https://xproxy.io/docs/api/box/rotate-ip-for-position.md 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`. For AI agents: Changes the public IP and drops open connections on this slot for 10-60 seconds. Do not loop: rotations closer than the minimum interval are refused. Check `status`, not the HTTP code. ### Public API · Modem reboot Reboot one modem by proxy or slot. #### Reboot the modem behind one proxy (legacy query-string form) `GET /reboot_usb` operationId: rebootDongleLegacy Safety: action — affects one modem or one proxy and the system can undo it. Authentication: Basic auth when API auth is on Docs: https://xproxy.io/docs/api/box/reboot-dongle-legacy.md Use this only for existing integrations; new code should use `/api/v1/reboot/proxy/{proxy}`. Needs the IP rotation feature in the license (`need_upgrade` otherwise). A non-answering router-type modem gets a USB reset instead. For AI agents: Takes the proxy offline for up to a few minutes. Use only when status shows the modem offline or broken. #### Reboot the modem behind a proxy given its port number `POST /reboot_usb_by_port` operationId: rebootDongleByPort Safety: action — affects one modem or one proxy and the system can undo it. Authentication: Basic auth when API auth is on Docs: https://xproxy.io/docs/api/box/reboot-dongle-by-port.md Use this when you only know the port. Unknown port answers `proxy_not_found`; a missing or non-integer `port` answers HTTP 500. No license check. For AI agents: Takes the proxy offline for up to a few minutes. Use only when the modem is offline or broken. #### Reboot the modem behind one proxy `GET /api/v1/reboot/proxy/{proxy}` operationId: rebootDongleForProxy Safety: action — affects one modem or one proxy and the system can undo it. Authentication: Basic auth when API auth is on Docs: https://xproxy.io/docs/api/box/reboot-dongle-for-proxy.md Use this when a proxy stays offline or slow and a rotation does not help. Reboots the modem of the slot behind the port. When a router-type modem does not answer, the box resets its USB port instead. The proxy is offline until the modem is back (usually 30-120 seconds). For AI agents: Takes the proxy offline for up to a few minutes and drops all its connections. Use only after status shows the modem offline or broken, not as a way to rotate. #### Reboot the modem in one slot `GET /api/v1/reboot/position/{position}` operationId: rebootDongleForPosition Safety: action — affects one modem or one proxy and the system can undo it. Authentication: Basic auth when API auth is on Docs: https://xproxy.io/docs/api/box/reboot-dongle-for-position.md Use this when a slot stays offline and a rotation does not help. Reboots the modem by slot number; a non-answering router-type modem gets a USB reset instead. For AI agents: Takes the slot offline for up to a few minutes and drops all its connections. Use only after status shows the modem offline or broken. ### Public API · Token links Per-port token links for end users (per-port authentication must be on). #### Check a proxy's status with its per-port token link `GET /{token}/status` operationId: getStatusWithPortToken Safety: read — no state change. Authentication: Port token in the URL Docs: https://xproxy.io/docs/api/box/get-status-with-port-token.md Use this to give an end user a status link for one proxy without sharing the dashboard login. Works only while per-port authentication (`port_auth_config`) is on. The token must belong to the port in `proxy`. The answer is the same as `/status`. #### Get a new public IP for a proxy with its per-port token link `GET /{token}/reset` operationId: rotateIpWithPortToken Safety: action — affects one modem or one proxy and the system can undo it. Authentication: Port token in the URL Docs: https://xproxy.io/docs/api/box/rotate-ip-with-port-token.md Use this to let an end user rotate one proxy without the dashboard login. Works only while per-port authentication is on. Refuses with HTTP 401 `reset_too_much` when the last rotation was less than the minimum interval (5 seconds by default) ago; otherwise behaves like `/reset`. For AI agents: Changes the proxy's public IP and drops its connections for 10-60 seconds. Do not loop; a 401 reset_too_much means wait. #### Reboot the modem behind a proxy with its per-port token link `GET /{token}/reboot_usb` operationId: rebootDongleWithPortToken Safety: action — affects one modem or one proxy and the system can undo it. Authentication: Port token in the URL Docs: https://xproxy.io/docs/api/box/reboot-dongle-with-port-token.md Use this to let an end user reboot the modem of one proxy. Works only while per-port authentication is on. Unlike `/reboot_usb` there is no license check. Same result messages as `/reboot_usb`. For AI agents: Takes the proxy offline for up to a few minutes. Use only when the modem is offline or broken. #### Get new public IPs for a proxy group with its group token link `GET /{token}/reset_group` operationId: rotateIpGroupWithToken Safety: action — affects one modem or one proxy and the system can undo it. Authentication: Port token in the URL Docs: https://xproxy.io/docs/api/box/rotate-ip-group-with-token.md Use this to let an end user rotate a whole proxy group. `proxy` is `HOST:PORT` of the group's primary port; the token is the group token shown with the group in the panel. Every slot of the group is rotated in parallel and the answer is `status: true` once the requests are sent. A port that is no group's primary port rotates nothing and still answers `status: true`. This link does not depend on per-port authentication. For AI agents: Rotates every proxy in the group and drops their connections. The answer does not report per-slot results; poll each proxy's status. ### Public API · Min API Compact API used by some reseller panels. #### List every slot with its ports, public IP and access settings `GET /api/min/get-list-position` operationId: minGetListPosition Safety: read — no state change. Authentication: Basic auth when API auth is on Docs: https://xproxy.io/docs/api/box/min-get-list-position.md Use this from a reseller panel to see all slots, including empty ones. `status` is `connected` when the slot has a public IPv4 or IPv6, `disconnected` when a modem is present without IP, and `unplugged` when no modem is detected. #### Read a slot's proxy and set its users and whitelist in one call `GET /api/min/get-current-proxy` operationId: minGetCurrentProxy Safety: destructive — changes credentials, configuration or license-relevant state, deletes data, or acts on the whole box. Authentication: Basic auth when API auth is on Docs: https://xproxy.io/docs/api/box/min-get-current-proxy.md Use this from a reseller panel to hand a slot to a customer. Returns the slot's ports and public IP. If `authentication_users` or `authorization_ips` differ from the slot's current values, the box first replaces the slot's proxy users and IP whitelist with the given ones (an omitted parameter counts as empty and clears it). `code` is 1 on success, 2 when `check_proxy=1` and the live proxy test failed, 0 when the slot has no public IP or the update failed. For AI agents: Not a pure read: calling it without the same users and whitelist the slot already has replaces them and can lock the current customer out. Always pass both parameters with the intended values. #### Set a slot's users and whitelist, then rotate its IP `GET /api/min/get-new-proxy` operationId: minGetNewProxy Safety: action — affects one modem or one proxy and the system can undo it. Authentication: Basic auth when API auth is on Docs: https://xproxy.io/docs/api/box/min-get-new-proxy.md Intended for reseller panels to rotate a slot. It first replaces the slot's proxy users and IP whitelist with the given values (omitted means empty), then asks for a rotation. In the code at the verified commit the rotation call is missing a required argument, so after the users and whitelist are replaced the box answers HTTP 500 and no rotation happens; use `/api/v1/rotate_ip/position/{position}` to rotate. For AI agents: Replaces the slot's users and whitelist on every call, and at the verified version fails with HTTP 500 before rotating. Prefer /api/v1/rotate_ip/position/{position}. ### Public API · VPN rotation Rotation link for the box VPN. #### Get a new public IP for the slot behind a box VPN, using its rotation link `GET /vpn/rotate` operationId: rotateVpnIp Safety: action — affects one modem or one proxy and the system can undo it. Authentication: VPN rotation token (?token=) Docs: https://xproxy.io/docs/api/box/rotate-vpn-ip.md Use this to rotate the IP of the slot a VPN profile exits through, for example from a phone connected to the box VPN. The token is the rotation token shown on the box's VPN page. Token and VPN problems answer with `message`; the rotation itself answers with `msg` and the same codes as `/api/v1/rotate_ip/position/{position}`. For AI agents: Changes the public IP of the VPN's slot and interrupts the VPN traffic for 10-60 seconds. Do not loop. Check `status`; the HTTP code is 200 even on refusal. ### Public API · Health Liveness and readiness probes. #### Check that the box web server is running `GET /health/live` operationId: healthLive Safety: read — no state change. Authentication: No authentication Docs: https://xproxy.io/docs/api/box/health-live.md Use this as a liveness probe: any answer means the panel process is up. It does not check modems or the proxy engine. #### Check that the box finished starting and can serve proxies `GET /health/ready` operationId: healthReady Safety: read — no state change. Authentication: No authentication Docs: https://xproxy.io/docs/api/box/health-ready.md Use this as a readiness probe after a restart or update. `core_ready` turns true once the controller core finished starting; until then `status` is `degraded`. HTTP 500 with `status: error` means the check itself failed. ### Panel API · Overview Box resources, system information and slot lists. #### Read CPU, memory, uptime, version and plan of the box `GET /linux_resource` operationId: getLinuxResource Safety: read — no state change. Authentication: Basic auth Stability: Panel API — may change between versions. Docs: https://xproxy.io/docs/api/box/get-linux-resource.md Use this for a quick health and licence overview. `memory` and `cpu` are percentages, `time` is hours since the operating system booted. At most every 15 minutes the call also asks the update server whether a newer version exists and refreshes `update_info`. Plan fields are present only once the licence module is loaded. Returns the buyer email (personal data). #### Read licence, plan, enabled features and software version of the box `GET /system_information` operationId: getSystemInformation Safety: read — no state change. Authentication: Basic auth Stability: Panel API — may change between versions. Docs: https://xproxy.io/docs/api/box/get-system-information.md Use this to check which licence features are on (IPv6, VLESS, selling, SMS/USSD, VPS forwarding and so on) before calling a feature route, and to read the installed version and build. Returns secrets and personal data: the licence key, the subscription secret key and the buyer email. Only trusted tools should call it; never log or display the response. If reading the licence fails, the box answers `status: false` with an empty `data`. #### List every slot with ports, IP state, schedules and Smart IP Guard data `GET /v2/proxy_list` operationId: getPanelProxyList Safety: read — no state change. Authentication: Basic auth Stability: Panel API — may change between versions. Docs: https://xproxy.io/docs/api/box/get-panel-proxy-list.md Use this for the full panel view of all slots, including offline and stopped ones (unlike /api/v1/info_list, which lists only connected slots). Paging is 1-based; `limit` 0 returns every row. `search` filters rows by text match before paging; `total` counts the filtered rows. Returns secrets: each row carries the slot's VLESS id and Shadowsocks password. #### Read a one-word connection state for every slot `GET /v2/status_list` operationId: getPanelStatusList Safety: read — no state change. Authentication: Basic auth Stability: Panel API — may change between versions. Docs: https://xproxy.io/docs/api/box/get-panel-status-list.md Use this for a light-weight status poll. `position` is the row index (1-based) in the modem table. States: data-updown (public IPv4 and IMEI known), module-noresponse (public IP but no IMEI), sim-unplug, sim-nodata (rotating or resetting), slot_empty, data-down. #### List the USB modems (not Android phones) with their device details `GET /v2/dongle_device_list` operationId: getDongleDeviceList Safety: read — no state change. Authentication: Basic auth Stability: Panel API — may change between versions. Docs: https://xproxy.io/docs/api/box/get-dongle-device-list.md Use this for the modem hardware table. Lists slots with a detected USB modem, plus Sierra modems that are flashing firmware (shown as `Sierra (flashing firmware)` with `extra_info.upgrade_firmware_status`). Android phones and empty slots are left out. Paging is 1-based; `limit` 0 returns all rows. Rows include the IMEI, ICCID and phone number of each SIM (personal data). ### Panel API · Modems Modem actions and settings (connect, label, APN, IMEI, bands, diagnostics). #### Give one modem a new public IP from the panel `POST /v2/rotate_ip` operationId: rotateIpByPosition Safety: action — affects one modem or one proxy and the system can undo it. Authentication: Basic auth Stability: Panel API — may change between versions. Docs: https://xproxy.io/docs/api/box/rotate-ip-by-position.md 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. For AI agents: The proxy on this slot drops connections while the modem reconnects (about 10-60 s). Ask the user before rotating many slots. Verify by polling GET /api/v1/status/position/{position} until it reports MODEM_READY with a new IP. #### Rotate the IP of every modem on the box at once `POST /v2/rotate_ip_all` operationId: rotateIpAll Safety: destructive — changes credentials, configuration or license-relevant state, deletes data, or acts on the whole box. Authentication: Basic auth Stability: Panel API — may change between versions. Docs: https://xproxy.io/docs/api/box/rotate-ip-all.md Use this to give all modems new IPs in one call. Starts a rotation on every slot (up to 20 in parallel) and returns the outcome per position in `results`, keyed by position. Each entry has the same `msg` codes as POST /v2/rotate_ip. Refused with `need_upgrade` when the license has no IP rotation. For AI agents: Every proxy on the box drops its connections at the same time. Always ask the user before calling it. Verify with GET /api/v1/info_list after a minute; rows whose result has status false were not rotated. #### Reboot one modem when its connection is stuck `POST /v2/reboot_dongle` operationId: rebootDongle Safety: action — affects one modem or one proxy and the system can undo it. Authentication: Basic auth Stability: Panel API — may change between versions. Docs: https://xproxy.io/docs/api/box/reboot-dongle.md Use this when a modem stops passing traffic. AT-command sticks are power-cycled over USB; router-type modems (Hilink, XH20/XH22, CPE) get a reboot command, and when they do not answer the box resets their USB port instead. Needs the IP-rotation license feature. For AI agents: The proxy on this slot is down for about a minute. Ask the user before rebooting many modems. Verify with GET /api/v1/status/position/{position} until MODEM_READY. #### Reset the USB port of a modem that a normal reboot cannot recover `POST /v2/reset_bus_dongle` operationId: resetBusDongle Safety: destructive — changes credentials, configuration or license-relevant state, deletes data, or acts on the whole box. Authentication: Basic auth Stability: Panel API — may change between versions. Docs: https://xproxy.io/docs/api/box/reset-bus-dongle.md Use this when POST /v2/reboot_dongle does not bring a modem back. Runs a USB reset of the modem's port. For NextGen Android phones it restarts the XProxy app instead; for XLE adapters it resets the adapter's bus. Needs the IP-rotation license feature. `msg` is empty on success and failure. For AI agents: The modem disappears from USB and re-enumerates; the slot is down for up to a minute. Ask the user first, never loop it. Verify with GET /api/v1/status/position/{position}. #### Start a stopped modem so its proxy works again `POST /v2/connect_dongle` operationId: connectDongle Safety: action — affects one modem or one proxy and the system can undo it. Authentication: Basic auth Stability: Panel API — may change between versions. Docs: https://xproxy.io/docs/api/box/connect-dongle.md Use this to bring a modem back after it was stopped by the user or by Smart IP Guard. Clears the stopped state, logs a `resumed` event and connects the modem. Always answers `status` true unless the license lacks IP rotation. For AI agents: The proxy starts serving traffic again. Confirm with the user if they stopped it on purpose. Verify with GET /api/v1/status/position/{position}. #### Stop a modem and take its proxy offline `POST /v2/disconnect_dongle` operationId: disconnectDongle Safety: destructive — changes credentials, configuration or license-relevant state, deletes data, or acts on the whole box. Authentication: Basic auth Stability: Panel API — may change between versions. Docs: https://xproxy.io/docs/api/box/disconnect-dongle.md Use this to stop a modem on purpose, for example to save data. Marks the slot as stopped by `web`, logs a `stopped` event and disconnects the modem; the stop survives a restart and rotations are refused until POST /v2/connect_dongle. Needs the IP-rotation license feature. For AI agents: Customers on this proxy lose service until someone reconnects it. Ask the user first. Verify with GET /v2/modem_stop_history or GET /api/v1/status/position/{position} (MODEM_DISCONNECTED). #### Clear the stopped state of a modem so it can run again `POST /v2/clear_auto_stop` operationId: clearAutoStop Safety: action — affects one modem or one proxy and the system can undo it. Authentication: Basic auth Stability: Panel API — may change between versions. Docs: https://xproxy.io/docs/api/box/clear-auto-stop.md Use this to undo a stop made by Smart IP Guard or the user. Same effect as POST /v2/connect_dongle (clears the stop, logs `resumed`, connects the modem) but without the license check. Always answers `status` true. For AI agents: The proxy starts serving traffic again. Confirm with the user if they stopped it on purpose. Verify with GET /api/v1/status/position/{position}. #### See when and why a modem was stopped or resumed `GET /v2/modem_stop_history` operationId: getModemStopHistory Safety: read — no state change. Authentication: Basic auth Stability: Panel API — may change between versions. Docs: https://xproxy.io/docs/api/box/get-modem-stop-history.md Use this to explain why a slot is offline. Returns up to 50 latest stop and resume events of the modem now at this position, newest first. `status` false with an empty list when no modem is at the position. #### Run a full health check of one slot to find why its proxy fails `POST /v2/diagnose_slot` operationId: diagnoseSlot Safety: action — affects one modem or one proxy and the system can undo it. Authentication: Basic auth Stability: Panel API — may change between versions. Docs: https://xproxy.io/docs/api/box/diagnose-slot.md Use this when a proxy does not work and you need the cause. Checks hardware bus, SIM and radio, interface and IP, data plan egress, DNS, proxy services, rotation readiness and upstream network, and returns each check plus a summary with the most important problem first. Takes several seconds. Only reads state but runs network probes through the modem. `tech_diagnostics` includes the caller IP and raw logs. For AI agents: Runs probes that use a little mobile data; no state is changed. Run it for one slot at a time. Read summary.status and summary.description for the answer. #### Queue a speed test through the proxies of some modems `POST /v2/speedtest_proxy` operationId: speedtestProxy Safety: action — affects one modem or one proxy and the system can undo it. Authentication: Basic auth Stability: Panel API — may change between versions. Docs: https://xproxy.io/docs/api/box/speedtest-proxy.md Use this to measure download speed of slots. Only queues the test (a slot already queued less than a minute ago is skipped); results appear later in the slot data of the panel. One unknown position fails the whole call with the generic error. For AI agents: Each test downloads data over the mobile connection and can cost the user data allowance. Ask before testing many slots. Verify later in GET /v2/dongle_device_list (speedtest fields). #### Read radio signal values (RSRP, SINR, band, cell) of one Huawei Hilink modem `GET /signal_info` operationId: getSignalInfo Safety: read — no state change. Authentication: Basic auth Stability: Panel API — may change between versions. Docs: https://xproxy.io/docs/api/box/get-signal-info.md Use this to check reception of a Huawei Hilink modem. Works only for `HW-Hilink` modems; other router-type modems return the text `Dongle do not support!` and AT/QMI modems return null data. The position is read from a JSON request body even though the method is GET; a query parameter is ignored and the call then answers `status` false. #### List the network modes and bands a Huawei Hilink modem supports `GET /band_list` operationId: getBandList Safety: read — no state change. Authentication: Basic auth Stability: Panel API — may change between versions. Docs: https://xproxy.io/docs/api/box/get-band-list.md Use this before POST /set_band to see valid values. Works only for `HW-Hilink` modems; others return `Dongle do not support!` or null data. The position is read from a JSON request body even though the method is GET. #### Read the network mode and band lock a Huawei Hilink modem uses now `GET /current_band` operationId: getCurrentBand Safety: read — no state change. Authentication: Basic auth Stability: Panel API — may change between versions. Docs: https://xproxy.io/docs/api/box/get-current-band.md Use this to check the current band lock. Works only for `HW-Hilink` modems; others return `Dongle do not support!` or null data. The position is read from a JSON request body even though the method is GET. #### Lock a Huawei Hilink modem to some bands or a network mode `POST /set_band` operationId: setBand Safety: destructive — changes credentials, configuration or license-relevant state, deletes data, or acts on the whole box. Authentication: Basic auth Stability: Panel API — may change between versions. Docs: https://xproxy.io/docs/api/box/set-band.md Use this to force a modem onto a band or 4G only. Works only for `HW-Hilink` modems. Values are hexadecimal masks as returned by GET /band_list; a missing field resets to all (`NetworkMode` 00 auto, `NetworkBand` 3FFFFFFF, `LTEBand` 7FFFFFFFFFFFFFFF). The modem re-registers on the network. For AI agents: A wrong band lock can leave the modem without signal until it is reset. Ask the user and keep the old values from GET /current_band to restore them. Verify with GET /current_band and GET /signal_info. #### Set the APN of one or more modems `POST /v2/change_apn` operationId: changeApn Safety: destructive — changes credentials, configuration or license-relevant state, deletes data, or acts on the whole box. Authentication: Basic auth Stability: Panel API — may change between versions. Docs: https://xproxy.io/docs/api/box/change-apn.md Use this when a SIM needs a specific APN to get data. Saves the APN for each modem's label and applies it to the modem; `result` lists which positions succeeded and failed. `status` is true even when some positions failed. The modem reconnects with the new APN. The request contains the APN password. For AI agents: A wrong APN cuts mobile data on those modems. Ask the user for the carrier's APN values before calling. Verify with result.failed being empty and GET /api/v1/status/position/{position}. #### Change the label number of a modem `POST /v2/change_label` operationId: changeLabel Safety: destructive — changes credentials, configuration or license-relevant state, deletes data, or acts on the whole box. Authentication: Basic auth Stability: Panel API — may change between versions. Docs: https://xproxy.io/docs/api/box/change-label.md Use this to give a modem a fixed label number (used for sorting and per-label settings such as APN). Hilink, ZTE, XProxy (XH20/XH22) and Alcatel modems store it on the device; other modems with a serial number store it in the box database. On success the modem reboots to apply it. For AI agents: The modem reboots and its proxy is down for about a minute; per-label settings follow the new label. Ask the user first. Verify with GET /v2/dongle_device_list. #### Add or change the free-text note of a modem `POST /v2/change_device_note` operationId: changeDeviceNote Safety: destructive — changes credentials, configuration or license-relevant state, deletes data, or acts on the whole box. Authentication: Basic auth Stability: Panel API — may change between versions. Docs: https://xproxy.io/docs/api/box/change-device-note.md Use this to attach a note (owner, SIM plan, location) to a modem. Stored in the box database by device id, so it follows the modem if it moves to another slot. No reboot. For AI agents: Overwrites the existing note. Read the current note from GET /v2/dongle_device_list first if it should be kept. Verify there afterwards. #### Swap two slots so a modem moves to another slot number `POST /v2/change_position` operationId: changePosition Safety: destructive — changes credentials, configuration or license-relevant state, deletes data, or acts on the whole box. Authentication: Basic auth Stability: Panel API — may change between versions. Docs: https://xproxy.io/docs/api/box/change-position.md Use this to reorder modems. Swaps the device data of the two positions; ports, VLESS/Shadowsocks credentials and other slot-bound settings stay with the slot number. Both slots' proxies are taken down and brought up again. Both positions must exist within the licensed modem count. For AI agents: Customers using these two ports get the other modem's IP and both proxies restart. Ask the user first. Verify with GET /v2/dongle_device_list. #### Read the MTU, TTL and active SIM slot of one modem `POST /get_dongle_settings` operationId: getDongleSettings Safety: read — no state change. Authentication: Basic auth Stability: Panel API — may change between versions. Docs: https://xproxy.io/docs/api/box/get-dongle-settings.md Use this before POST /update_dongle_settings. Returns the stored MTU (default 1500), TTL (0 means not changed) and the active SIM slot (1 when the modem cannot report it). On an internal error the defaults are returned with `status` true. #### Change the MTU, TTL or active SIM slot of one modem `POST /update_dongle_settings` operationId: updateDongleSettings Safety: destructive — changes credentials, configuration or license-relevant state, deletes data, or acts on the whole box. Authentication: Basic auth Stability: Panel API — may change between versions. Docs: https://xproxy.io/docs/api/box/update-dongle-settings.md Use this to tune one modem. `type` picks the setting: `mtu` saves and applies `data.mtu` to the interface, `ttl` saves and applies `data.ttl` (0 turns TTL rewriting off), `sim` switches the modem to `data.simSlot` (dual-SIM modems only; the modem reconnects on the other SIM). For AI agents: A bad MTU or a SIM switch can break the proxy of this slot. Ask the user first and note the old values from POST /get_dongle_settings. Verify there afterwards. #### Change the MAC address of one or more modems `POST /v2/change_mac_address` operationId: changeMacAddress Safety: destructive — changes credentials, configuration or license-relevant state, deletes data, or acts on the whole box. Authentication: Basic auth Stability: Panel API — may change between versions. Docs: https://xproxy.io/docs/api/box/change-mac-address.md 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. For AI agents: Modems reboot and get new LAN identities; the proxies are down for about a minute. Ask the user first. Verify after 15 s in GET /v2/dongle_device_list. #### Change the IMEI of one or more modems `POST /v2/imei_change_in_bulk` operationId: changeImei Safety: destructive — changes credentials, configuration or license-relevant state, deletes data, or acts on the whole box. Authentication: Basic auth Stability: Panel API — may change between versions. Docs: https://xproxy.io/docs/api/box/change-imei.md Use this only when the user asks to change modem IMEIs. Option 1 uses IMEIs from `imei_list` (one per position in order when the counts match, otherwise random picks); option 2 generates an IMEI from a random TAC in `phone_models`; option 3 generates one from the first 8 digits of `based_imei`. Each changed modem reboots. Stops at the first modem that rejects the change. Positions without a modem are skipped and still reported as success, and errors inside the loop (for example option 1 without `imei_list`) are swallowed, so a success answer does not prove any IMEI changed. For AI agents: Risky: the carrier may block the SIM, and changing IMEI may be illegal in the user's country. Always get explicit approval for each batch. Verify the new IMEI in GET /v2/dongle_device_list after the reboot. #### Turn the Wi-Fi of one or more modems on or off `POST /v2/wifi_change_in_bulk` operationId: changeWifi Safety: action — affects one modem or one proxy and the system can undo it. Authentication: Basic auth Stability: Panel API — may change between versions. Docs: https://xproxy.io/docs/api/box/change-wifi.md Use this to switch modem Wi-Fi hotspots. XProxy XH20/XH22 modems set Wi-Fi to `state`; NextGen Android phones toggle it; other modems are skipped. The answer is success even when modems were skipped. For AI agents: Devices connected to the modem Wi-Fi lose access when it is turned off. Ask the user first. There is no read-back route; check the modem itself. #### Read the phone number of a modem's SIM `POST /v2/get_dongle_info` operationId: getDongleInfo Safety: action — affects one modem or one proxy and the system can undo it. Authentication: Basic auth Stability: Panel API — may change between versions. Docs: https://xproxy.io/docs/api/box/get-dongle-info.md Use this to find the SIM's phone number. Asks the modem for its own number (AT+CNUM or the modem API) and returns the request body with `phone_number` filled in. Many SIMs do not store their number, which gives the failure message. `phone_number` must be present and truthy in the request; without it the box answers HTTP 500. For AI agents: Only reads from the modem but sends a command to it; avoid calling it for many modems in a row. The result is in data.phone_number. #### Read which TCP/OS fingerprint profile a slot uses `GET /v2/slot_config/tcp_os_get` operationId: getSlotTcpOs Safety: read — no state change. Authentication: Basic auth Stability: Panel API — may change between versions. Docs: https://xproxy.io/docs/api/box/get-slot-tcp-os.md Use this to see the OS fingerprint a proxy presents. `profile` is a profile id from GET /v2/tcp_os_profiles, or null when none was set. #### Set the TCP/OS fingerprint profile of one or more slots `POST /v2/slot_config/tcp_os_set` operationId: setSlotTcpOs Safety: destructive — changes credentials, configuration or license-relevant state, deletes data, or acts on the whole box. Authentication: Basic auth Stability: Panel API — may change between versions. Docs: https://xproxy.io/docs/api/box/set-slot-tcp-os.md Use this to make proxies look like another OS (Windows, macOS, iOS, Android). Saves the profile per slot and applies it without restarting the proxy; empty slots keep the setting for their next modem. Needs the TCP/OS license feature and cgroup (WebRTC) support enabled on the box. For AI agents: Changes the fingerprint customers see on these ports. Ask the user first. Verify with GET /v2/slot_config/tcp_os_get. #### List the TCP/OS fingerprint profiles available on the box `GET /v2/tcp_os_profiles` operationId: getTcpOsProfiles Safety: read — no state change. Authentication: Basic auth Stability: Panel API — may change between versions. Docs: https://xproxy.io/docs/api/box/get-tcp-os-profiles.md Use this to get valid `profile` values for POST /v2/slot_config/tcp_os_set. Lists built-in (`system`) and custom profiles in display order. `data` is null when the profile table cannot be read. ### Panel API · Devices USB adapters and Android NextGen phones. #### List the NextGen Android phones used as modems and their state `GET /androidng/list_device_info` operationId: listAndroidDevices Safety: read — no state change. Authentication: Basic auth Stability: Panel API — may change between versions. Docs: https://xproxy.io/docs/api/box/list-android-devices.md Use this to see which Android phones are attached, authorized and on the right app version. Rows are sorted by position and paged; `total` counts all rows. Each row is the phone's live record (fields vary by app version) plus `auto_install`, `processing_disabled`, `target_swver` and `swver_mismatch`. In Remote VPS mode rows also carry `problem_reason` and `hw_serial`, and enrolled phones that are offline get a row without position. Returns an empty list when NextGen Android support is off. #### Reboot one or more Android phones used as modems `POST /androidng/reboot_phone` operationId: rebootAndroidPhones Safety: action — affects one modem or one proxy and the system can undo it. Authentication: Basic auth Stability: Panel API — may change between versions. Docs: https://xproxy.io/docs/api/box/reboot-android-phones.md Use this when a phone stops serving its proxy and restarting the app did not help. Sends a reboot to each phone over ADB and counts successes and failures. `status` is true when at least one phone rebooted. For AI agents: The proxies of these phones are down for one to three minutes. Ask the user before rebooting many phones. Verify with GET /androidng/list_device_info. #### Restart the XProxy app on one or more Android phones `POST /androidng/restart_app` operationId: restartAndroidApp Safety: action — affects one modem or one proxy and the system can undo it. Authentication: Basic auth Stability: Panel API — may change between versions. Docs: https://xproxy.io/docs/api/box/restart-android-app.md Use this first when an Android phone's proxy stops working; it is faster than a reboot. Restarts the XProxy app on each phone over ADB and counts successes and failures. `status` is true when at least one phone restarted. For AI agents: The proxies of these phones drop for about 30 s. Ask the user before restarting many phones. Verify with GET /androidng/list_device_info. #### List the XLE network adapters and which of their modems answer `GET /get_adapter_list` operationId: getAdapterList Safety: read — no state change. Authentication: Basic auth Stability: Panel API — may change between versions. Docs: https://xproxy.io/docs/api/box/get-adapter-list.md Use this to check XLE multi-modem adapters attached over the network. Each entry has the stored adapter config (`info`) and its state: `main_st` tells whether the adapter answers, `ok` and `err` list its modem labels. `data` is null when no adapter is configured. #### Restart or reboot an XLE network adapter `POST /action_adapter` operationId: actionAdapter Safety: action — affects one modem or one proxy and the system can undo it. Authentication: Basic auth Stability: Panel API — may change between versions. Docs: https://xproxy.io/docs/api/box/action-adapter.md Use this when an XLE adapter's modems stop answering. `reset` restarts the adapter service after 2 s; `reboot` reboots the adapter; `delete` does nothing here (use the panel to remove an adapter). Refused in slave mode. Always answers success otherwise, without checking the adapter. For AI agents: Every modem behind the adapter goes offline for a minute or more. Ask the user first. Verify with GET /get_adapter_list (main_st true). ### Panel API · Rotation settings Auto-rotation settings, schedules and history. #### Read the global rotation, duplicate-IP, Smart IP Guard and IMEI/MAC changer settings `GET /v2/rotation_setting` operationId: getRotationSettings Safety: read — no state change. Authentication: Basic auth Stability: Panel API — may change between versions. Docs: https://xproxy.io/docs/api/box/get-rotation-settings.md Use this before changing rotation behaviour, and to build the full body that POST /v2/rotation_setting needs. Base IMEIs and MAC addresses are joined with new lines. #### Save the global rotation settings (full replace of the main fields) `POST /v2/rotation_setting` operationId: setRotationSettings Safety: destructive — changes credentials, configuration or license-relevant state, deletes data, or acts on the whole box. Authentication: Basic auth Stability: Panel API — may change between versions. Docs: https://xproxy.io/docs/api/box/set-rotation-settings.md Use this to change rotation timing, collision handling, duplicate-IP rotation, Smart IP Guard or the IMEI/MAC changer. Read GET /v2/rotation_setting first and send the whole object back with your change: the timing fields, `detect_collision_ip`, `imei_changer` and `mac_changer` are required, and missing duplicate-IP fields are reset to their defaults (off, 30 seconds, 5 attempts). Smart IP Guard fields, `never_change_ip_automatically` and `reconnect_ipv6_failure` are saved only when present. Takes effect immediately for all slots. A missing required field or a non-numeric main value fails with HTTP 500 before anything is saved; a non-numeric Smart IP Guard value fails with HTTP 500 after the main fields were already saved. For AI agents: Changes rotation behaviour of every slot. Ask the user before saving; send back the full object from GET and verify with GET /v2/rotation_setting afterwards. #### Read how each modem type rotates its IP and the offline-hold settings `GET /hilink_change_renew_method` operationId: getRenewMethods Safety: read — no state change. Authentication: Basic auth Stability: Panel API — may change between versions. Docs: https://xproxy.io/docs/api/box/get-renew-methods.md Use this to see the rotation method per modem family (Huawei Hilink, legacy Android, NextGen Android, XH22) and the offline-hold options used when a carrier keeps the same IP for a short offline time. #### Change the IP rotation method of Hilink, legacy Android or XH22 modems and the offline-hold settings `POST /hilink_change_renew_method` operationId: setRenewMethods Safety: destructive — changes credentials, configuration or license-relevant state, deletes data, or acts on the whole box. Authentication: Basic auth Stability: Panel API — may change between versions. Docs: https://xproxy.io/docs/api/box/set-renew-methods.md Use this to switch how a modem family gets a new IP. Every field is optional; only the ones sent are checked and saved. Offline-hold values are all validated first and one bad value saves none of them; an invalid method is refused, but fields saved earlier in the same call stay saved (order: XH22 method, offline hold, Huawei, legacy Android). Applies to the next rotation of every modem of that type. For AI agents: Changes how every modem of the type rotates. Ask the user first and verify with GET /hilink_change_renew_method. #### Change the rotation method and auto reset/reconnect of USB stick (QMI/serial) modems `POST /stick_change_renew_method` operationId: setStickRenewMethod Safety: destructive — changes credentials, configuration or license-relevant state, deletes data, or acts on the whole box. Authentication: Basic auth Stability: Panel API — may change between versions. Docs: https://xproxy.io/docs/api/box/set-stick-renew-method.md Use this to choose how stick modems get a new IP and whether they reset or reconnect automatically. `method` must be the string "1", "2" or "3". `stick_adjust_time` is saved only when not empty. `stick_auto_reset` and `stick_auto_reconnect` are applied at once. A missing field fails with HTTP 500. For AI agents: Changes rotation of every stick modem. Ask the user first; there is no GET for these values, so record the previous ones from the panel. #### List past IP rotations of one slot in a time range `GET /v2/rotation_history` operationId: getRotationHistory Safety: read — no state change. Authentication: Basic auth Stability: Panel API — may change between versions. Docs: https://xproxy.io/docs/api/box/get-rotation-history.md Use this to audit when a slot rotated, which IP it got and how long it took. Only rotations with a public IPv4 are listed, newest first. When Smart IP Guard is on, each row also has the IP score and freshness. A missing or non-numeric `position`, `start_date` or `end_date` returns `status false` with a generic message. #### List scheduled rotation jobs of one or more slots `POST /v2/schedule/rotation_jobs` operationId: getRotationScheduleJobs Safety: read — no state change. Authentication: Basic auth Docs: https://xproxy.io/docs/api/box/get-rotation-schedule-jobs.md Use this to see which automatic rotations are planned and when they run next. Lists both system jobs (created with rotation_add_job) and selling-port interval jobs. POST is used only to carry the body; nothing changes. Returns an empty list while the scheduler is not running. A missing field returns `status false` without data. #### Schedule automatic IP rotation every N seconds/minutes/hours for slots `POST /v2/schedule/rotation_add_job` operationId: addRotationScheduleJob Safety: destructive — changes credentials, configuration or license-relevant state, deletes data, or acts on the whole box. Authentication: Basic auth Docs: https://xproxy.io/docs/api/box/add-rotation-schedule-job.md Use this to make slots rotate on a timer. One job is created and started per position. `run_per_day` forever runs all day (start/end ignored); range runs only between `start_time` and `end_time`. `specific_time` must not be null. Jobs add up: call rotation_jobs first to avoid duplicates and rotation_remove_job to replace a job. For AI agents: Creates recurring rotations that change the IP of live slots. Ask the user for the slots and interval before bulk use; verify with /v2/schedule/rotation_jobs. #### Remove one scheduled rotation job, or all system jobs of the given slots `POST /v2/schedule/rotation_remove_job` operationId: removeRotationScheduleJob Safety: destructive — changes credentials, configuration or license-relevant state, deletes data, or acts on the whole box. Authentication: Basic auth Stability: Panel API — may change between versions. Docs: https://xproxy.io/docs/api/box/remove-rotation-schedule-job.md Use this to stop automatic rotation. With a job `id` it removes that job from each listed position; with an empty or null `id` it removes every system job of those positions. Selling-port interval jobs are not touched. For AI agents: Without an id this deletes every system schedule of the slots. Confirm the slots with the user; verify with /v2/schedule/rotation_jobs. ### Panel API · System settings Box-wide settings, restart and reboot. #### List the CPE device labels configured on the box `GET /get_label_list` operationId: getLabelList Safety: read — no state change. Authentication: Basic auth Stability: Panel API — may change between versions. Docs: https://xproxy.io/docs/api/box/get-label-list.md Use this to see which CPE labels (virtual LAN interfaces) exist before adding or deleting one. #### Add a CPE device label and bring up its virtual interface `POST /add_new_label` operationId: addLabel Safety: destructive — changes credentials, configuration or license-relevant state, deletes data, or acts on the whole box. Authentication: Basic auth Stability: Panel API — may change between versions. Docs: https://xproxy.io/docs/api/box/add-label.md Use this to register a CPE device. Without VLAN the label must be below 100. The interface is created at once. A missing field or a non-numeric label fails with HTTP 500. For AI agents: Creates a network interface on the box. Ask the user first; verify with GET /get_label_list. #### Delete a CPE device label and take down its interface `POST /delete_label` operationId: deleteLabel Safety: destructive — changes credentials, configuration or license-relevant state, deletes data, or acts on the whole box. Authentication: Basic auth Stability: Panel API — may change between versions. Docs: https://xproxy.io/docs/api/box/delete-label.md Use this to remove a CPE label. The label must match the stored value exactly (same type as in /get_label_list). For AI agents: Removes a network interface that CPE traffic may use. Ask the user first; verify with GET /get_label_list. #### Read every system setting of the box (timezone, network, login, DDNS, telemetry, recovery) `GET /get_system_settings` operationId: getSystemSettings Safety: read — no state change. Authentication: Basic auth Stability: Panel API — may change between versions. Docs: https://xproxy.io/docs/api/box/get-system-settings.md Use this to show or back up the system settings page. Returns secrets: the dashboard password, the DuckDNS token and the SigNoz ingestion key, in clear text. Only trusted tools should call it; never log or display the response. `timezones` lists every timezone name the box accepts. #### Change one section of the system settings (selected by type) `POST /update_system_settings` operationId: updateSystemSettings Safety: destructive — changes credentials, configuration or license-relevant state, deletes data, or acts on the whole box. Authentication: Basic auth Stability: Panel API — may change between versions. Docs: https://xproxy.io/docs/api/box/update-system-settings.md Use this to save one settings section. `type` picks the section and `data` carries the same shape GET /get_system_settings returns for it. Side effects by type: current_timezone restarts the panel (msg success_app_restart); static_ip reboots the box (success_app_reboot) and can make it unreachable on a wrong address; dashboard_port restarts the panel on the new port; dashboard_auth replaces the dashboard login and whitelist at once (and on the VPS when forwarding is on); duckdns tests the token before saving; telemetry restarts log shipping; system_recovery updates the dongle and USB recovery service. Other types: force_dhcp, controller_log_retention, watch_dog, bridging_service, ttl, gui_theme. An unknown type, or a timezone change whose link command fails, still answers `status true`. The request may carry secrets (dashboard password, DDNS token, ingestion key). For AI agents: Never call without explicit user confirmation for the section and values. static_ip, timezone and dashboard_port reboot or restart the box; a wrong dashboard_auth or static_ip can lock everyone out. Verify with GET /get_system_settings after the box is back. #### Read how often the VPS relay connection is checked `GET /v2/get_monitor_time` operationId: getMonitorTime Safety: read — no state change. Authentication: Basic auth Stability: Panel API — may change between versions. Docs: https://xproxy.io/docs/api/box/get-monitor-time.md Use this to read the VPS relay monitoring interval in seconds. #### Change how often the VPS relay connection is checked `POST /v2/set_monitor_time` operationId: setMonitorTime Safety: destructive — changes credentials, configuration or license-relevant state, deletes data, or acts on the whole box. Authentication: Basic auth Stability: Panel API — may change between versions. Docs: https://xproxy.io/docs/api/box/set-monitor-time.md Use this to set the VPS relay monitoring interval. The value must be greater than 5 seconds and applies at once. A missing or non-numeric value fails with HTTP 500. For AI agents: Changes VPS relay monitoring for all forwarded ports. Ask the user first; verify with GET /v2/get_monitor_time. #### Reboot the whole box (operating system) `POST /xproxy_reboot` operationId: rebootSystem Safety: destructive — changes credentials, configuration or license-relevant state, deletes data, or acts on the whole box. Authentication: Basic auth Docs: https://xproxy.io/docs/api/box/reboot-system.md Use this only when a full restart is needed. The box answers first, then reboots; every proxy and the panel are offline for one to a few minutes. Takes no body. For AI agents: Never call without explicit user confirmation. All proxies drop. Verify by polling /health/ready until core_ready is true. #### Restart the XProxy service without rebooting the operating system `POST /xproxy_soft_reboot` operationId: restartPanel Safety: destructive — changes credentials, configuration or license-relevant state, deletes data, or acts on the whole box. Authentication: Basic auth Docs: https://xproxy.io/docs/api/box/restart-panel.md Use this to reload the controller after a stuck state. The box answers first, then restarts the XProxy service; proxies and the panel drop for about a minute. Takes no body. For AI agents: Never call without explicit user confirmation. All proxies drop briefly. Verify by polling /health/ready until core_ready is true. ### Panel API · Software Version, updates and logs. #### Look up the latest (or a given) XProxy release for this box's architecture `GET /v2/release_info` operationId: getReleaseInfo Safety: read — no state change. Authentication: Basic auth when API auth is on Stability: Panel API — may change between versions. Docs: https://xproxy.io/docs/api/box/get-release-info.md Use this before updating to see which build would be installed. The box asks the xproxy.io release server for its own CPU architecture; with `version` it looks up that version, otherwise the latest public build (dev builds when `install_branch` is dev). Nothing is installed. Network or server errors return `status false` with the reason. #### Start updating the box software to the latest or a given version `GET /v2/updater_new_version` operationId: startSoftwareUpdate Safety: destructive — changes credentials, configuration or license-relevant state, deletes data, or acts on the whole box. Authentication: Basic auth Stability: Panel API — may change between versions. Docs: https://xproxy.io/docs/api/box/start-software-update.md Use this only to install new software. Despite being a GET, it downloads and runs the installer in the background; the panel and proxies restart when it finishes. With `version` the version is first checked against the release server and refused if not found. Returns `scheduled` when started, `updating` when an update is already running. Follow progress with /v2/updater_new_version_status. For AI agents: Never call without explicit user confirmation. The box restarts and all proxies drop during the update. Verify with /v2/updater_new_version_status until updating is false, then /system_information for the version. #### Follow the progress of a running software update or rollback `GET /v2/updater_new_version_status` operationId: getSoftwareUpdateStatus Safety: read — no state change. Authentication: Basic auth when API auth is on Stability: Panel API — may change between versions. Docs: https://xproxy.io/docs/api/box/get-software-update-status.md Use this to poll an update. `update_log` is the installer log so far; `updating` turns false when the installer is no longer running. On an internal error it answers an empty log and false. #### Abort a running software update `POST /v2/updater_stop` operationId: stopSoftwareUpdate Safety: destructive — changes credentials, configuration or license-relevant state, deletes data, or acts on the whole box. Authentication: Basic auth Stability: Panel API — may change between versions. Docs: https://xproxy.io/docs/api/box/stop-software-update.md Use this to stop an update that hangs. It kills the installer download and installer processes and writes an abort line into the update log. Stopping in the middle of installing can leave the box between versions. Takes no body. For AI agents: Never call without explicit user confirmation; aborting an install can break the box. Verify with /v2/updater_new_version_status. #### Reinstall an earlier software build (rollback) `POST /v2/rollback_version` operationId: rollbackSoftwareVersion Safety: destructive — changes credentials, configuration or license-relevant state, deletes data, or acts on the whole box. Authentication: Basic auth Stability: Panel API — may change between versions. Docs: https://xproxy.io/docs/api/box/rollback-software-version.md Use this to go back to a previous build, for example one listed in `history_versions` of /system_information. The installer runs in the background with the given old build version; the panel and proxies restart. Returns `scheduled` when started or `updating` when an update is already running. For AI agents: Never call without explicit user confirmation. The box restarts and all proxies drop. Verify with /v2/updater_new_version_status and then the version in /system_information. ### Panel API · Stats & logs Uptime, rotation analysis and proxy access logs. #### Read per-10-minute uptime of one slot for each day in a range `GET /v2/stats/uptime_stats` operationId: getUptimeStats Safety: read — no state change. Authentication: Basic auth Stability: Panel API — may change between versions. Docs: https://xproxy.io/docs/api/box/get-uptime-stats.md Use this to draw an uptime chart. The range may span at most about 3 months (93 days). `data` is keyed by the epoch second of each day, walking back from `end_date` in 24-hour steps; each day has 144 ten-minute buckets with status 1 (up), 0 (down) or null (no data). #### Summarise rotations of one slot in a range (success rate, unique IPs, average time) `GET /v2/rotation_history_analysis` operationId: getRotationHistoryAnalysis Safety: read — no state change. Authentication: Basic auth Stability: Panel API — may change between versions. Docs: https://xproxy.io/docs/api/box/get-rotation-history-analysis.md Use this to judge rotation quality of a slot. Counts success, failed and duplicated rotations, the average rotation time in seconds, and lists each distinct IPv4 with how often it was seen (least seen first). #### Read recent proxy access log lines with filters `GET /v2/proxy_log` operationId: getProxyLog Safety: read — no state change. Authentication: Basic auth Stability: Panel API — may change between versions. Docs: https://xproxy.io/docs/api/box/get-proxy-log.md Use this to see which clients went where through the proxies, newest first. Reads back through rotated log files until `lines` entries match (default 20, at most 1000). Filters combine: position and port accept repeated values (position[]=1 or position=1), client_ip, client_username, target_host and method match partially, error_code matches exactly or `error` for any non-zero code, log_type is MAIN, SELL or GROUP; start_time/end_time are epoch seconds. Returns client IPs, usernames and visited hosts (personal data). #### Read developer logging on/off and the level of each controller logger `GET /v2/dev_logging` operationId: getDevLogging Safety: read — no state change. Authentication: Basic auth Stability: Panel API — may change between versions. Docs: https://xproxy.io/docs/api/box/get-dev-logging.md Use this before changing log verbosity for debugging. Each logger shows its default and selected level. #### Turn developer logging on or off and set logger levels `POST /v2/dev_logging` operationId: setDevLogging Safety: destructive — changes credentials, configuration or license-relevant state, deletes data, or acts on the whole box. Authentication: Basic auth Stability: Panel API — may change between versions. Docs: https://xproxy.io/docs/api/box/set-dev-logging.md Use this to raise log verbosity while debugging and to lower it afterwards. The body may be wrapped in `data`. Loggers without a name or level are skipped. Settings are saved and applied at once; verbose levels make logs grow quickly. For AI agents: Ask the user first and switch it back off after debugging; verbose logging fills disk. Verify with GET /v2/dev_logging. ### Panel API · SMS & USSD Read and send SMS, run USSD codes. #### Read the latest SMS messages received by the SIM of one slot `GET /sms/read` operationId: readSms Safety: read — no state change. Authentication: Basic auth Docs: https://xproxy.io/docs/api/box/read-sms.md Use this to fetch verification codes or carrier messages. Returns personal data: sender numbers and message text. Both parameters are required; a missing one, or a modem that cannot be read, returns `status false` with an empty list. The Hub never relays this route; call the box directly. #### Send an SMS from the SIM of one slot `POST /sms/send` operationId: sendSms Safety: destructive — changes credentials, configuration or license-relevant state, deletes data, or acts on the whole box. Authentication: Basic auth Docs: https://xproxy.io/docs/api/box/send-sms.md Use this to send one text message. Needs the SMS/USSD licence feature. Sending costs carrier credit and cannot be undone. Returns `Sent failed!` when the modem refuses or a field is missing. The Hub never relays this route. For AI agents: Sending is irreversible and may cost money. Ask the user to confirm the number and text for every message; never loop over many numbers without explicit approval. #### Delete SMS messages stored on the SIM or modem of one slot `POST /sms/delete` operationId: deleteSms Safety: destructive — changes credentials, configuration or license-relevant state, deletes data, or acts on the whole box. Authentication: Basic auth Docs: https://xproxy.io/docs/api/box/delete-sms.md Use this to clear the inbox. Needs the SMS/USSD licence feature. Without `index` the modem's messages are deleted; Android phones accept `index` to delete one message. Deleted messages cannot be recovered. A body without `position` fails with HTTP 500. The Hub never relays this route. For AI agents: Deletion is irreversible. Ask the user first; verify with /sms/read. #### Send a USSD code (for example a balance check) from the SIM of one slot `POST /ussd/send` operationId: sendUssd Safety: destructive — changes credentials, configuration or license-relevant state, deletes data, or acts on the whole box. Authentication: Basic auth Docs: https://xproxy.io/docs/api/box/send-ussd.md Use this to run a carrier USSD code. Needs the SMS/USSD licence feature. Some codes change the subscription or spend credit and cannot be undone. `data` is the modem's reply (returns personal data such as balance or number); read later replies with /ussd/read. The Hub never relays this route. For AI agents: USSD codes can buy plans or move credit irreversibly. Ask the user to confirm the exact code first. #### Read the last USSD reply of one slot `GET /ussd/read` operationId: readUssd Safety: read — no state change. Authentication: Basic auth Docs: https://xproxy.io/docs/api/box/read-ussd.md Use this after /ussd/send when the reply arrives later. Returns personal data (balance, number). A missing or non-numeric position returns `status false`. The Hub never relays this route. ### Panel API · Selling platform Shared proxies for your own customers and their self-service links. #### List the proxies you sell, with customer credentials, expiry and data used `GET /selling/shared_proxies` operationId: listSellingProxies Safety: read — no state change. Authentication: Basic auth Stability: Panel API — may change between versions. Docs: https://xproxy.io/docs/api/box/list-selling-proxies.md Returns one page of sold proxies with filters. Each row contains the customer's proxy credentials and API token, so the answer holds secrets. Needs the Selling Platform license. #### Create new proxies to sell, on one slot each or as group proxies `POST /selling/generate` operationId: generateSellingProxies Safety: destructive — changes credentials, configuration or license-relevant state, deletes data, or acts on the whole box. Authentication: Basic auth Stability: Panel API — may change between versions. Docs: https://xproxy.io/docs/api/box/generate-selling-proxies.md Creates sold proxies (new listening ports) and starts them. With `genMethod` 1 it creates `numberOfPorts` ports per slot in `selected_positions` (or `positionFrom`..`positionTo`); with 2 it creates `numberOfPorts` ports that spread over all selected slots. Answers with the created rows, which contain credentials and API tokens. VLESS and Shadowsocks port types need a Premium or Business license and are refused with HTTP 403 otherwise. For AI agents: Opens new public proxy ports and may change auth on the box. Confirm slots, count and expiry with the user before calling; verify with /selling/shared_proxies. A missing `numberOfPorts` or `expiredDate` makes the box answer HTTP 500. #### Change settings of several sold proxies at once `POST /selling/bulk_edit` operationId: bulkEditSellingProxies Safety: destructive — changes credentials, configuration or license-relevant state, deletes data, or acts on the whole box. Authentication: Basic auth Stability: Panel API — may change between versions. Docs: https://xproxy.io/docs/api/box/bulk-edit-selling-proxies.md Updates only the fields present in the body (or forced with `default_FIELD: false`) on every id in `ids`, then restarts those ports. Answers with the updated rows, which contain credentials and API tokens. VLESS and Shadowsocks need a Premium or Business license (HTTP 403). For AI agents: Restarts the listed ports, dropping customer connections, and can change their credentials or expiry. Confirm the ids and fields with the user; verify with /selling/shared_proxies. #### Delete sold proxies and close their ports `POST /selling/bulk_delete` operationId: bulkDeleteSellingProxies Safety: destructive — changes credentials, configuration or license-relevant state, deletes data, or acts on the whole box. Authentication: Basic auth Stability: Panel API — may change between versions. Docs: https://xproxy.io/docs/api/box/bulk-delete-selling-proxies.md Stops and deletes the listed sold proxies. Their customers lose access at once and their links stop working. Echoes the request body. A body without `ids` makes the box answer HTTP 500. For AI agents: Irreversible: customers lose their proxies. Confirm every id with the user, never delete in bulk without explicit approval; verify with /selling/shared_proxies. #### Move the expiry date of sold proxies, by days, hours or to a fixed time `POST /selling/bulk_extend_expired` operationId: extendSellingProxiesExpiry Safety: destructive — changes credentials, configuration or license-relevant state, deletes data, or acts on the whole box. Authentication: Basic auth Stability: Panel API — may change between versions. Docs: https://xproxy.io/docs/api/box/extend-selling-proxies-expiry.md Sets a new expiry on the listed sold proxies, either `expired_unix_time` or adding `expired_extend_days` / `expired_extend_hours`, then restarts them. Answers with the updated rows, which contain credentials and API tokens. Does not reset data counters (use /selling/renew_proxy for that). For AI agents: Changes what customers are entitled to and restarts their ports. Confirm ids and period with the user; verify `expired_at` in the answer. #### Renew sold proxies for another period, optionally resetting their data counters `POST /selling/renew_proxy` operationId: renewSellingProxies Safety: destructive — changes credentials, configuration or license-relevant state, deletes data, or acts on the whole box. Authentication: Basic auth Stability: Panel API — may change between versions. Docs: https://xproxy.io/docs/api/box/renew-selling-proxies.md Extends each listed proxy by `period_value` `period_type` (max 3650 days, 520 weeks or 120 months), records it in the renewal history under the dashboard user, and with `reset_counters` zeroes their data counters. Ports stopped by expiry start again. `status` is true when at least one proxy was renewed; `data.failed` lists the others with a reason. For AI agents: Changes customer entitlements and can zero their counters. Confirm ids and period with the user; check `data.failed` in the answer. #### Zero the data counters of sold proxies so a customer who hit the quota can use them again `POST /selling/reset_data_counter` operationId: resetSellingDataCounter Safety: destructive — changes credentials, configuration or license-relevant state, deletes data, or acts on the whole box. Authentication: Basic auth Stability: Panel API — may change between versions. Docs: https://xproxy.io/docs/api/box/reset-selling-data-counter.md Resets the upload, download and total counters of the listed proxies and writes a manual entry to their quota reset history. Ports on the older counter are stopped and restarted. Echoes the request body. A body without `ids` makes the box answer HTTP 500. For AI agents: Erases the usage the customer has consumed this period. Confirm ids with the user; verify with /selling/shared_proxies (`counter_all_used_mb`). #### Let a customer get a new IP for the proxy they rent, with its token link `GET /selling/rotate` operationId: rotateSellingProxyIp Safety: action — affects one modem or one proxy and the system can undo it. Authentication: Selling token (?token=) Docs: https://xproxy.io/docs/api/box/rotate-selling-proxy-ip.md Rotates the slot behind one sold proxy. Works only when the seller allowed API rotation for that proxy and the last rotation is older than its minimum interval; group proxies are refused. Refusals come in `data` (not allowed) or `message` (all others). For AI agents: Changes the public IP and drops connections for 10-60 seconds. Do not loop; on "Please waiting for next" wait the given seconds. Check `status`, the HTTP code is 200 even on refusal. #### Let a customer set or turn off automatic IP rotation of the proxy they rent `GET /selling/change_interval_rotation` operationId: changeSellingRotationInterval Safety: action — affects one modem or one proxy and the system can undo it. Authentication: Selling token (?token=) Docs: https://xproxy.io/docs/api/box/change-selling-rotation-interval.md Sets the auto-rotation interval in seconds; `seconds=0` turns auto-rotation off. A non-zero value needs the seller's permission and must be at least the proxy's minimum interval and below one year. Group proxies are refused. Refusals come in `data` (token, permission, validation) or `message` (save failures). For AI agents: Changes how often the customer's IP changes. Ask before changing; verify with /selling/info (`interval_rotation`). #### Show a customer everything about the proxy they rent, including all their self-service links `GET /selling/info` operationId: getSellingProxyInfo Safety: read — no state change. Authentication: Selling token (?token=) Docs: https://xproxy.io/docs/api/box/get-selling-proxy-info.md Returns the proxy address, type, credentials, limits, expiry, permissions, TCP OS profile, quota reset info and the ready-made links of every other customer route. Returns secrets (the token and the proxy credentials). An unknown token answers with the error in `data`. #### Let a customer replace the username and password of the proxy they rent `GET /selling/change_user` operationId: changeSellingProxyUser Safety: destructive — changes credentials, configuration or license-relevant state, deletes data, or acts on the whole box. Authentication: Selling token (?token=) Docs: https://xproxy.io/docs/api/box/change-selling-proxy-user.md Replaces the proxy's user:pass with the given pair and restarts the port. Both values must be 3-15 letters or digits. When `user` or `pass` is missing the box answers `status:false` with an empty `message`. For AI agents: The old credentials stop working at once and open connections drop. Ask the user before changing; verify with /selling/info (`proxy_user`). #### Let a customer set which IPs may use the proxy they rent without a password `GET /selling/change_whitelist` operationId: changeSellingProxyWhitelist Safety: destructive — changes credentials, configuration or license-relevant state, deletes data, or acts on the whole box. Authentication: Selling token (?token=) Docs: https://xproxy.io/docs/api/box/change-selling-proxy-whitelist.md Replaces the proxy's IP whitelist with the IPs in `ips` (comma-separated) and restarts the port. Without `ips` the whitelist is cleared. For AI agents: IPs not in the new list lose password-less access at once. Ask the user before changing; verify by connecting from a listed IP. #### Show a customer which IPs the proxy they rent had, and when `GET /selling/rotation_history` operationId: getSellingRotationHistory Safety: read — no state change. Authentication: Selling token (?token=) Docs: https://xproxy.io/docs/api/box/get-selling-rotation-history.md Lists successful rotations since the proxy was created, by default over the last 30 days. Use `last_days`, or `start_date`/`end_date` (epoch seconds). The success answer has no `status` field. #### Let a customer change the operating system the proxy's TCP fingerprint imitates `GET /selling/change_tcp_os` operationId: changeSellingTcpOs Safety: action — affects one modem or one proxy and the system can undo it. Authentication: Selling token (?token=) Docs: https://xproxy.io/docs/api/box/change-selling-tcp-os.md Sets the TCP OS fingerprint profile of the proxy and restarts the port. Profile ids come from /selling/tcp_os_profiles. Group proxies are refused (in `data`); other refusals come in `message`. For AI agents: Restarts the customer's port. Ask before changing; verify with /selling/info (`tcp_os`). #### List the TCP OS fingerprint profiles a customer can choose `GET /selling/tcp_os_profiles` operationId: listSellingTcpOsProfiles Safety: read — no state change. Authentication: No authentication Docs: https://xproxy.io/docs/api/box/list-selling-tcp-os-profiles.md Returns the id and name of every TCP OS fingerprint profile on the box. Needs no token; still refused when the license has no Selling Platform. #### Show a customer per-day uptime of the proxy they rent `GET /selling/uptime_stats` operationId: getSellingUptimeStats Safety: read — no state change. Authentication: Selling token (?token=) Docs: https://xproxy.io/docs/api/box/get-selling-uptime-stats.md Returns per-day time slots marked up (1) or down for the proxy's slot (for group proxies a slot is up when any member is up). Default range is the last 24 hours; at most 7 days. #### Show a customer the up and down events of the proxy they rent `GET /selling/uptime_log` operationId: getSellingUptimeLog Safety: read — no state change. Authentication: Selling token (?token=) Docs: https://xproxy.io/docs/api/box/get-selling-uptime-log.md Returns paged up/down events, newest first, for the proxy's slot (all member slots for group proxies). Default range is the last 24 hours; at most 7 days. A non-integer `page` or `limit` makes the box answer HTTP 500. #### Show a customer when the data quota of the proxy they rent was reset and how much was used before `GET /selling/quota_reset_history_by_token` operationId: getSellingQuotaResetHistory Safety: read — no state change. Authentication: Selling token (?token=) Docs: https://xproxy.io/docs/api/box/get-selling-quota-reset-history.md Returns paged quota reset records (automatic and manual) of the proxy. A non-integer `page` or `limit` makes the box answer HTTP 500. #### Show a customer the data used, quota left and next reset time of the proxy they rent `GET /selling/quota_info_by_token` operationId: getSellingQuotaInfo Safety: read — no state change. Authentication: Selling token (?token=) Docs: https://xproxy.io/docs/api/box/get-selling-quota-info.md Returns, for each limited counter (DL, UL, ALL), the quota, data used, data left, last and next reset, plus the last reset record per counter. ### Panel API · Proxy settings Proxy users, groups, ports, TCP fingerprint and IP pools. #### Read every global proxy setting shown on the panel's Proxy settings page `GET /get_proxies_settings` operationId: getProxiesSettings Safety: read — no state change. Authentication: Basic auth Stability: Panel API — may change between versions. Docs: https://xproxy.io/docs/api/box/get-proxies-settings.md Returns the global proxy configuration in one object: proxy login, IP whitelist, IPv6 options, per-port authentication, port layout, VLESS and Shadowsocks options, VPS relay summary, group health-check options, website white/blacklists, sticky IP, auto-reboot rules, WebRTC leak protection and the "proxy through WAN" listener. This response returns secrets (proxy password, VLESS public key, WAN VLESS UUID, WAN Shadowsocks password); do not log or share it. On an internal error the box answers `status: false` with the error text in `msg`. #### Change one section of the global proxy settings `POST /update_proxies_settings` operationId: updateProxiesSettings Safety: destructive — changes credentials, configuration or license-relevant state, deletes data, or acts on the whole box. Authentication: Basic auth Stability: Panel API — may change between versions. Docs: https://xproxy.io/docs/api/box/update-proxies-settings.md Saves one section of the Proxy settings page, chosen by `type`; `data` carries that section's fields with the same names `/get_proxies_settings` returns. Sections: `ipv6Config` (ipv6Config, multipleIpv6Config; needs the IPv6 license feature to turn on), `proxyStartPort` (proxyStartPort, autoPort, ipv6Mode, proxyWatchdogInterval, optional vlessEnabled, vlessSni, ssEnabled, ssMethod), `proxyGroupConfig` (group_* health-check fields), `rotationConfig` (needs the rotation feature), `enableProxyAuth` (enableProxyAuth, disableProxyCache, proxyUser, proxyPass), `enableIPAuth` (enableIPAuth, forceLocalAuthen, ipList, optional allowTailscaleNoAuth), `enablePerPortAuth` (needs the selling feature to turn on), `enableWhiteList` / `enableBlackList` / `bandwidthEnable` (need the website-access feature to turn on; bandwidth rules go in `data.data`), `globalWebsiteAuthorizationMode`, `stickyIPEnable`, `enableLogging`, `forceServerResolveDNS`, `webrtc`, `auto_reboot`, `exportConfig`, `wanProxy`. Side effects: `msg: success_app_restart` means the controller restarts (all proxies drop for some seconds) — this happens for an IPv6 change, a port-layout change (start port, auto port, IPv6 mode, VLESS or Shadowsocks on/off), group health-check settings and WebRTC changes. Most other sections reload every proxy config. An unknown `type` changes nothing but still reloads all proxies and answers success. Turning on Shadowsocks or VLESS without the license answers HTTP 403. For AI agents: Ask the user before calling: several sections restart the controller and drop every proxy, and the auth sections can lock clients out. Send all fields of the section (missing required fields answer "Configuration failed!"). Verify with /get_proxies_settings afterwards; after success_app_restart wait until the panel answers again. #### List the proxy groups (one port that spreads traffic over several slots) `GET /proxy_group_config` operationId: getProxyGroupConfig Safety: read — no state change. Authentication: Basic auth Stability: Panel API — may change between versions. Docs: https://xproxy.io/docs/api/box/get-proxy-group-config.md Returns every configured proxy group. Each group includes its proxy username and password, so the response can contain secrets. #### Add a proxy group `POST /proxy_group_config` operationId: createProxyGroupConfig Safety: destructive — changes credentials, configuration or license-relevant state, deletes data, or acts on the whole box. Authentication: Basic auth Stability: Panel API — may change between versions. Docs: https://xproxy.io/docs/api/box/create-proxy-group-config.md 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. For AI agents: Ask the user before creating groups; every call reloads all proxies. Read /proxy_group_config first to avoid duplicates, and verify the new group there afterwards. #### Change an existing proxy group `POST /edit_proxy_group_config` operationId: editProxyGroupConfig Safety: destructive — changes credentials, configuration or license-relevant state, deletes data, or acts on the whole box. Authentication: Basic auth Stability: Panel API — may change between versions. Docs: https://xproxy.io/docs/api/box/edit-proxy-group-config.md Finds the group by `primary_port` and merges the posted fields into it, then reloads all proxies. Needs the proxy-group license feature and a non-empty `position_list`. For AI agents: Ask the user before editing; clients of the group reconnect when proxies reload. Verify with GET /proxy_group_config. #### Delete a proxy group by its port `POST /del_proxy_group_config` operationId: deleteProxyGroupConfig Safety: destructive — changes credentials, configuration or license-relevant state, deletes data, or acts on the whole box. Authentication: Basic auth Stability: Panel API — may change between versions. Docs: https://xproxy.io/docs/api/box/delete-proxy-group-config.md Removes every group whose `primary_port` matches and saves the list. Proxies are not reloaded by this call, so the group port can keep serving until the next proxy reload or restart. Always answers success, also when no group matched. For AI agents: Ask the user before deleting a group; customers using its port lose access. Verify with GET /proxy_group_config. #### Turn sticky IP on or off and set its keep-alive server `POST /sticky_ip_config` operationId: setStickyIpConfig Safety: destructive — changes credentials, configuration or license-relevant state, deletes data, or acts on the whole box. Authentication: Basic auth Stability: Panel API — may change between versions. Docs: https://xproxy.io/docs/api/box/set-sticky-ip-config.md Sticky IP keeps each modem's session busy (by pinging `sticky_server`) so the carrier keeps the same public IP. Turning it off stops all sticky jobs; turning it on starts the sticky service with the saved settings. A non-empty `sticky_server` that differs from the saved one is pushed to the running service. Intervals, size and TTL are set through /update_proxies_settings type stickyIPEnable. For AI agents: Ask the user before changing; it affects every modem. Verify with /get_proxies_settings (stickyIPEnable, stickyServer). #### Deprecated — OS spoofing settings (always refused) `GET /xproxy_config_os_spoofing` operationId: getOsSpoofingConfig Safety: read — no state change. Authentication: Basic auth Stability: Panel API — may change between versions. Deprecated. Docs: https://xproxy.io/docs/api/box/get-os-spoofing-config.md Deprecated. The route still exists but always answers `status: false, msg: Deprecated!`. TCP/OS fingerprint profiles are managed per proxy in the panel instead. #### Deprecated — save OS spoofing settings (always refused) `POST /xproxy_config_os_spoofing` operationId: setOsSpoofingConfig Safety: destructive — changes credentials, configuration or license-relevant state, deletes data, or acts on the whole box. Authentication: Basic auth Stability: Panel API — may change between versions. Deprecated. Docs: https://xproxy.io/docs/api/box/set-os-spoofing-config.md Deprecated. Changes nothing and always answers `status: false, msg: Deprecated!`. For AI agents: Do not use; the route is a no-op kept for old clients. #### Page through every public IP the modems have had, with reuse scores `GET /v2/ip_pools` operationId: getIpPools Safety: read — no state change. Authentication: Basic auth Stability: Panel API — may change between versions. Docs: https://xproxy.io/docs/api/box/get-ip-pools.md Returns the full public-IP history (no time window), grouped by IP, with how often each IP came back. `score` drops by one per repeat; `freshness` is `fresh` when the score is at or above the IP history guard's threshold, else `warning`. Summary fields cover all IPs matching `search`. ### Panel API · Network DNS, IP checker, DDNS, WAN and IPv6. #### Read the DNS servers used by the box and by the proxies `GET /update_dns_config` operationId: getDnsConfig Safety: read — no state change. Authentication: Basic auth Stability: Panel API — may change between versions. Docs: https://xproxy.io/docs/api/box/get-dns-config.md Returns the system DNS list, the DNS list the proxies resolve with, whether proxies use the modem's DNS, and whether VPN clients get the modem DNS. #### Change the DNS servers of the box and the proxies `POST /update_dns_config` operationId: updateDnsConfig Safety: destructive — changes credentials, configuration or license-relevant state, deletes data, or acts on the whole box. Authentication: Basic auth Stability: Panel API — may change between versions. Docs: https://xproxy.io/docs/api/box/update-dns-config.md Saves the proxy DNS list and modem-DNS options, writes the system resolver configuration and reloads every proxy. All four fields are required. For AI agents: Ask the user first: a wrong resolver breaks name resolution for the box and every proxy, and all proxies reload. Verify with GET /update_dns_config and a test request through a proxy. #### Read how the box detects each modem's public IP `GET /xproxy_config_public_ipchecker` operationId: getPublicIpCheckerConfig Safety: read — no state change. Authentication: Basic auth Stability: Panel API — may change between versions. Docs: https://xproxy.io/docs/api/box/get-public-ip-checker-config.md Returns the IP-check servers (IPv4 and IPv6), the check method, the check period and timeout in seconds, and the HTTP-status-only and native async check switches. #### Change how the box detects each modem's public IP `POST /xproxy_config_public_ipchecker` operationId: setPublicIpCheckerConfig Safety: destructive — changes credentials, configuration or license-relevant state, deletes data, or acts on the whole box. Authentication: Basic auth Stability: Panel API — may change between versions. Docs: https://xproxy.io/docs/api/box/set-public-ip-checker-config.md Saves the IP-check servers, method, period and timeout. `pubip_period` and `pubip_timedout` must be integers from 2 to 99999. A wrong IP server makes every modem look disconnected. For AI agents: Ask the user first; a bad server or method marks all modems as having no public IP. Verify with GET /xproxy_config_public_ipchecker and /status of one proxy. #### List the DDNS providers and whether their updates are healthy `GET /v2/ddns/providers` operationId: getDdnsProviders Safety: read — no state change. Authentication: Basic auth Stability: Panel API — may change between versions. Docs: https://xproxy.io/docs/api/box/get-ddns-providers.md Returns every saved DDNS provider with its settings, last result and a computed `health`. This response returns secrets: each provider's `config` holds its API token or password. #### Create or change one DDNS provider `POST /v2/ddns/providers` operationId: saveDdnsProvider Safety: destructive — changes credentials, configuration or license-relevant state, deletes data, or acts on the whole box. Authentication: Basic auth Stability: Panel API — may change between versions. Docs: https://xproxy.io/docs/api/box/save-ddns-provider.md Updates the provider named by `type`; only the fields present (enabled, interval_seconds, ip_source, manual_ip, config) change. Starts or stops the DDNS service to match whether any provider is enabled, and, when the provider is enabled, sends an update right away (a failed update is only logged). For AI agents: Ask the user before saving; it changes a public DNS record. `config` replaces the whole credential object, so send every credential field. Verify with GET /v2/ddns/providers (health, last_status). #### Push the current IP to every enabled DDNS provider now `POST /v2/ddns/trigger_all` operationId: triggerAllDdnsUpdates Safety: action — affects one modem or one proxy and the system can undo it. Authentication: Basic auth Stability: Panel API — may change between versions. Docs: https://xproxy.io/docs/api/box/trigger-all-ddns-updates.md Forces one update of every enabled provider. On boxes with the xddns helper the answer includes per-provider `results`; older boxes run the update without returning results. For AI agents: Safe to run once; avoid loops (providers rate-limit updates). Verify with GET /v2/ddns/providers. #### Read the WAN (PPPoE) setup and its connection log `GET /get_wan_config` operationId: getWanConfig Safety: read — no state change. Authentication: Basic auth Stability: Panel API — may change between versions. Docs: https://xproxy.io/docs/api/box/get-wan-config.md Returns whether the box's own WAN service is on, the interface and method, the saved PPPoE settings (`config`), the box's interfaces and, for PPPoE, the tail of the connection log. This response can return secrets: `config.password` is the PPPoE password. #### Read the tail of the dongle DHCP-fix recovery log `GET /get_dhcp_fix_log` operationId: getDhcpFixLog Safety: read — no state change. Authentication: Basic auth Stability: Panel API — may change between versions. Docs: https://xproxy.io/docs/api/box/get-dhcp-fix-log.md Returns the last lines of the DHCP fix log written by the box's dongle recovery. `lines` outside 1–2000 falls back to 200. #### Page through the IPv6 Multiple proxies (server IPv6 sub-proxies) `GET /v2/ipv6_multiple_list` operationId: getIpv6MultipleList Safety: read — no state change. Authentication: Basic auth Stability: Panel API — may change between versions. Docs: https://xproxy.io/docs/api/box/get-ipv6-multiple-list.md Lists the proxies created by IPv6 Multiple, sorted by slot, with paging. Missing or invalid `page`/`limit` fall back to page 1 and 10 rows. This response returns secrets: each entry contains the proxy's `auth_pass`. ### Panel API · VPN Box VPN configuration. #### Read the VPN server settings of every slot `GET /vpn_config` operationId: getVpnConfig Safety: read — no state change. Authentication: Basic auth Stability: Panel API — may change between versions. Docs: https://xproxy.io/docs/api/box/get-vpn-config.md Returns a map from slot position to its VPN settings, or `data: null` when no slot has a VPN configured. This response returns secrets (`vpn_pass`, `vpn_rotation_token`). #### Turn a slot's VPN server on or off and change its settings `POST /vpn_server_config` operationId: setVpnServerConfig Safety: destructive — changes credentials, configuration or license-relevant state, deletes data, or acts on the whole box. Authentication: Basic auth Stability: Panel API — may change between versions. Docs: https://xproxy.io/docs/api/box/set-vpn-server-config.md Creates or updates the VPN server of one slot and regenerates its configuration. Needs the VPN license feature. While a slot's VPN is on its type cannot change; turn it off first. `vpn_mtu` `FF` means 1420. Changing the quota or re-enabling resets the used bytes. Existing client profiles are regenerated unless `keep_vpn_file` is true, which invalidates profiles already handed out. For AI agents: Ask the user before calling; regenerating a slot's VPN cuts connected VPN clients and can invalidate their profiles. Verify with GET /vpn_config. #### Read the base ports of the WireGuard and OpenVPN servers `GET /v2/get_vpn_port` operationId: getVpnPort Safety: read — no state change. Authentication: Basic auth Stability: Panel API — may change between versions. Docs: https://xproxy.io/docs/api/box/get-vpn-port.md Returns the first port of the WireGuard range (`wg_port`) and of the OpenVPN range (`opvn_port`); each slot uses base + position. #### Change the base ports of the WireGuard and OpenVPN servers `POST /v2/set_vpn_port` operationId: setVpnPort Safety: destructive — changes credentials, configuration or license-relevant state, deletes data, or acts on the whole box. Authentication: Basic auth Stability: Panel API — may change between versions. Docs: https://xproxy.io/docs/api/box/set-vpn-port.md Saves both base ports, kills every OpenVPN process and restarts the controller. Both fields are required and are not range-checked by the box. For AI agents: Ask the user first: it restarts the controller (all proxies drop briefly) and every VPN client profile must be updated with the new ports. Verify with GET /v2/get_vpn_port once the panel answers again. ### Panel API · VPS forwarding Publish proxies through your own VPS. #### Read the VPS connection and forwarding rules `GET /v2/forwarding/get_vps_config` operationId: getVpsForwardingConfig Safety: read — no state change. Authentication: Basic auth Stability: Panel API — may change between versions. Docs: https://xproxy.io/docs/api/box/get-vps-forwarding-config.md Returns the VPS address, SSH port, user, whether forwarding is on, the auth method, the saved rules, the available tunnel engines and the VPS host-key fingerprint. Secrets are never returned: `vps_relay_pass` is always empty and only `*_set` flags and key fingerprints show whether a password, private key or sudo password is stored. #### List every forwarded port with its VPS port and state `GET /v2/forwarding/get_mapping_ports` operationId: getVpsForwardingMappingPorts Safety: read — no state change. Authentication: Basic auth Stability: Panel API — may change between versions. Docs: https://xproxy.io/docs/api/box/get-vps-forwarding-mapping-ports.md Returns one row per forwarding service (relay tunnels and per-port forwards) with the local port, public VPS port, status and the last error with its diagnosed cause. #### Check whether the box is safe to expose through the VPS `GET /v2/forwarding/preflight` operationId: getVpsForwardingPreflight Safety: read — no state change. Authentication: Basic auth Stability: Panel API — may change between versions. Docs: https://xproxy.io/docs/api/box/get-vps-forwarding-preflight.md Evaluates the security checklist (license, dashboard password when the dashboard is exposed, proxy login when proxies are exposed). `enable_web` and `enable_proxy` evaluate a draft service selection; when omitted the saved rules are used. The same check gates /v2/forwarding/config_rules. #### Change which services the VPS publishes and on which ports `POST /v2/forwarding/config_rules` operationId: setVpsForwardingRules Safety: destructive — changes credentials, configuration or license-relevant state, deletes data, or acts on the whole box. Authentication: Basic auth Stability: Panel API — may change between versions. Docs: https://xproxy.io/docs/api/box/set-vps-forwarding-rules.md Validates the rules (keys left out keep their saved value). Needs the VPS forwarding license feature. While forwarding is off the rules are only saved. While forwarding is on, the security preflight must pass and a go-live job starts that checks everything, sets up the VPS and applies the rules without a panel restart; the answer then carries `job_id` and the job reports progress in the panel. Stored VPS credentials are reused when the body leaves them empty. For AI agents: Ask the user first: while forwarding is live this republishes services on the public VPS (and can expose the dashboard or SSH). Run GET /v2/forwarding/preflight first. Verify with GET /v2/forwarding/get_vps_config and /v2/forwarding/get_mapping_ports after the job ends. #### Read the VPS's health (CPU, RAM, disk, relay) and service totals `GET /v2/forwarding/vps_health` operationId: getVpsForwardingHealth Safety: read — no state change. Authentication: Basic auth Stability: Panel API — may change between versions. Docs: https://xproxy.io/docs/api/box/get-vps-forwarding-health.md Returns the latest health snapshot of the VPS collected over SSH plus counts of the forwarding services. When the VPS cannot be reached `reachable` is false with an `error`. #### Inspect one forwarding service with its events, logs and diagnosed cause `GET /v2/forwarding/service_detail` operationId: getVpsForwardingServiceDetail Safety: read — no state change. Authentication: Basic auth Stability: Panel API — may change between versions. Docs: https://xproxy.io/docs/api/box/get-vps-forwarding-service-detail.md Returns the service row, its last error, recent VPS events, box and VPS log lines and a diagnosed cause and hint. Reads logs over SSH, so it can take some seconds. #### Recreate one forwarding service on the box and the VPS `POST /v2/forwarding/restart_service` operationId: restartVpsForwardingService Safety: action — affects one modem or one proxy and the system can undo it. Authentication: Basic auth Stability: Panel API — may change between versions. Docs: https://xproxy.io/docs/api/box/restart-vps-forwarding-service.md Re-creates the named service (box unit and/or VPS relay entry). Connections through that service drop while it restarts. For AI agents: Ask the user before restarting services in bulk; each restart drops that port's connections. Verify with GET /v2/forwarding/service_detail. #### Run the full VPS forwarding diagnosis `POST /v2/forwarding/doctor` operationId: runVpsForwardingDoctor Safety: action — affects one modem or one proxy and the system can undo it. Authentication: Basic auth Stability: Panel API — may change between versions. Docs: https://xproxy.io/docs/api/box/run-vps-forwarding-doctor.md Checks security, SSH, the relay, the firewall, services and public ports, and returns a list of items with a status and, where possible, a one-click fix action for /v2/forwarding/doctor_fix. When forwarding is off it returns a single warning item. Opens SSH and probes ports, so it takes some seconds; it does not change the setup. For AI agents: Safe to run; it only reads and probes. Do not run it in a loop. Apply fixes only after asking the user. #### Apply one repair suggested by the VPS forwarding doctor `POST /v2/forwarding/doctor_fix` operationId: applyVpsForwardingDoctorFix Safety: action — affects one modem or one proxy and the system can undo it. Authentication: Basic auth Stability: Panel API — may change between versions. Docs: https://xproxy.io/docs/api/box/apply-vps-forwarding-doctor-fix.md Runs one fix action from a doctor item: repair_relay (re-push every relay entry), fix_sshd, cleanup_legacy (remove the old agent from the VPS), open_firewall (open the forwarding ports in ufw/firewalld), restart_failed (restart services not running), repush_frontends (needs a prior doctor run), repair_wireguard, trust_host_key (accept the VPS's new SSH identity). The answer `status` is the fix result. For AI agents: Ask the user before every fix: they change the VPS (firewall, sshd, services), and trust_host_key accepts a changed SSH identity, which must be confirmed as expected. Run /v2/forwarding/doctor again to verify. #### Read whether the proxy ports are reachable from the internet (cached) `GET /v2/proxy/public_reach` operationId: getProxyPublicReach Safety: read — no state change. Authentication: Basic auth Stability: Panel API — may change between versions. Docs: https://xproxy.io/docs/api/box/get-proxy-public-reach.md Returns the last known reachability of every listening proxy port and the box's public and LAN IP, without probing. Ports are unknown (`open: null`) until POST /v2/proxy/public_reach/check has run. Detects the public IP once if it is not known yet. #### Probe now whether the proxy ports are reachable from the internet `POST /v2/proxy/public_reach/check` operationId: checkProxyPublicReach Safety: action — affects one modem or one proxy and the system can undo it. Authentication: Basic auth Stability: Panel API — may change between versions. Docs: https://xproxy.io/docs/api/box/check-proxy-public-reach.md Asks the xproxy.io probe server to TCP-connect back to the caller box's own public IP on every listening proxy port, then returns the same view as GET /v2/proxy/public_reach. Only the box's own source IP is probed. When the probe server is down or slow, the answer is still 200 with `unavailable: true`, and further probes are skipped for 60 seconds. For AI agents: Sends the box's port list to xproxy.io; run once per check, not in a loop. Read the result from the answer or GET /v2/proxy/public_reach. ## Hub API Coming soon. The Hub API reference is not published yet; see https://xproxy.io/docs/api for updates.