API REST XProxy : renouveler l’IP, statut et liste des proxys
L’API REST XProxy permet à votre propre code de lister vos proxys mobiles, de renouveler leurs IP, de lire leur statut et de redémarrer les modems par de simples appels HTTP. Appelez l’adresse de votre box, ajoutez les identifiants du tableau de bord là où ils sont requis, et c’est tout.
Ce qu’il vous faut : l’offre Basic ou supérieure (Tarifs ; l’offre Free n’inclut pas la rotation d’IP) et l’adresse de votre box. Depuis l’extérieur de votre réseau, il vous faut aussi le nom d’utilisateur et le mot de passe du tableau de bord.
En bref
L’adresse de votre box, par exemple http://192.168.1.100. Il n’y a pas de serveur d’API séparé.
Les appels utilisent le nom d’utilisateur et le mot de passe du tableau de bord (HTTP Basic). Les appels de rotation et de statut ne demandent aucun identifiant, sauf si vous activez Force API Auth.
info_list liste les modems, rotate_ip obtient une nouvelle IP, status vous indique quand elle est prête.
Quelle est l’URL de base de l’API XProxy ?
L’URL de base est l’adresse de votre box XProxy, avec le port du tableau de bord s’il est différent de 80 :
| D’où vous appelez | URL de base |
|---|---|
| Votre réseau local | http://192.168.1.100 (l’adresse de la box) |
| Un autre port de tableau de bord | http://192.168.1.100:8080 (voir Sécuriser le tableau de bord) |
| Internet | http://myproxy.duckdns.org, votre adresse publique ou l’adresse du VPS. Accédez à la box via NAT Forwarding, VPS Forwarding ou Tailscale. |
N’utilisez https:// que si votre domaine sert du HTTPS. Vous pouvez définir un domaine distinct pour les liens et les appels d’API dans Proxy Settings → Address.
Comment s’authentifier auprès de l’API REST ?
Il n’y a pas de clé d’API séparée. Un appel qui demande une authentification utilise le nom d’utilisateur et le mot de passe du tableau de bord en authentification HTTP Basic, les mêmes identifiants que ceux définis dans Sécuriser le tableau de bord.
| Appel | Identifiants |
|---|---|
Rotation, statut et redémarrage : /api/v1/rotate_ip/…, /api/v1/status/…, /api/v1/reboot/…, ainsi que les anciens liens /reset et /status | Aucun, tant que vous n’activez pas Force API Auth. Ensuite, HTTP Basic. |
Listes et tout le reste : /api/v1/info_list, /api/v1/proxy_list/…, /proxy_list, /reset_all, /reset_by_port, /status_by_port | HTTP Basic, depuis l’extérieur de votre réseau local. |
| Un appareil de votre réseau local, une IP en liste blanche ou un appareil Tailscale (si autorisé) | Aucun identifiant. Force LAN Auth et Force API Auth changent cela. |
| Un proxy client avec son propre jeton (offre Business) | Le jeton inclus dans le lien. Voir Utiliser la Selling Platform. |
Existe-t-il un jeton d’API ?
Le tableau de bord lui-même s’authentifie avec POST /v2/auth/login. Il renvoie un jeton qui n’est que votre nom d’utilisateur et votre mot de passe encodés en Base64 : gardez-le donc aussi secret que le mot de passe. Vos scripts peuvent envoyer les mêmes identifiants en HTTP Basic à chaque appel.
# optional: check a login (answer: status true and a token)
curl -X POST 'http://192.168.1.100/v2/auth/login' \
--header 'Content-Type: application/json' \
--data '{"username": "admin", "password": "YOUR_PASSWORD"}'Où se trouve l’API dans le tableau de bord ?
Ouvrez API Reference dans la barre latérale. Cette page renvoie vers la documentation complète sur apidocs.xproxy.io et liste les trois appels par lesquels la plupart des utilisateurs commencent.
info_list, rotate_ip/position, status/position.Quels endpoints puis-je appeler ?
Tous les appels sont en GET, sauf mention contraire. <position> est le numéro du modem (1 = premier modem). <proxy> est le host:port de son proxy.
| Endpoint | Rôle | Identifiants requis ? |
|---|---|---|
/api/v1/info_list?page=&limit= | Liste les modems : ports, IP publique, dernière rotation, infos de l’appareil. Réponse : data et total. | Oui |
/api/v1/proxy_list/<type> | Texte brut, un proxy par ligne. Types : proxy, socks5, proxy_ipv6, socks5_ipv6, vless, vless_ipv6, ss. | Oui |
/api/v1/rotate_ip/position/<position> | Obtient une nouvelle IP pour ce modem. | Non* |
/api/v1/rotate_ip/proxy/<proxy> | Idem, par proxy. | Non* |
/api/v1/status/position/<position>/api/v1/status/proxy/<proxy> | IP publique et état du modem. | Non* |
/api/v1/reboot/position/<position>/api/v1/reboot/proxy/<proxy> | Redémarre le modem. | Non* |
/reset?proxy=<proxy>, /status?proxy=<proxy> | Les anciens liens de rotation et de statut. Le bouton LINK du tableau de bord en copie un. | Non* |
/reset_all | Renouvelle l’IP de tous les modems. | Oui |
POST /reset_by_port avec {"port": 4001} | Renouvelle l’IP du modem de ce port proxy. | Oui |
/status_by_port?port=4001 | Statut par port proxy. | Oui |
Oui = les identifiants du tableau de bord, depuis l’extérieur de votre réseau local. Non* = aucun identifiant tant que Force API Auth n’est pas activé. La liste complète, avec tous les paramètres, se trouve dans la documentation de l’API.
Comment lister mes proxys avec l’API ?
# all modems, first page of 20
curl -u admin:YOUR_PASSWORD 'http://192.168.1.100/api/v1/info_list?page=1&limit=20'
# every modem at once (leave page and limit out)
curl -u admin:YOUR_PASSWORD 'http://192.168.1.100/api/v1/info_list'Depuis votre propre réseau local, ou depuis une IP en liste blanche, vous pouvez omettre -u.
La réponse, abrégée :
{
"data": [
{
"position": 1,
"host": "192.168.1.100",
"proxy_port": 4001,
"socks5_port": 5001,
"public_ip": "203.0.113.25",
"public_ip_ipv6": null,
"device_manufacture": "XProxy-Hilink",
"device_rebooting": false,
"device_resetting": false
}
],
"total": 1
}Autres champs de chaque élément : proxy_port_v6, socks5_port_ipv6, vless_port, vless_port_v6, ss_port, ss_port_v6, last_updated_ip, device_imei, device_number, device_ip et device_extra_info.
Comment renouveler l’IP avec l’API ?
Appelez rotate_ip, puis lisez status jusqu’à ce que le modem soit MODEM_READY avec une nouvelle IP. Les mêmes appels, le minuteur et le lien de rotation sont décrits dans Changer l’IP.
# by position (1 = first modem)
curl 'http://192.168.1.100/api/v1/rotate_ip/position/1'
# or by proxy (host:port)
curl 'http://192.168.1.100/api/v1/rotate_ip/proxy/192.168.1.100:4001'
# the box answers at once:
# {"status": true, "msg": "command_sent"}
# check on the new IP a few seconds later
curl 'http://192.168.1.100/api/v1/status/position/1'
# {"status": true, "public_ip": "203.0.113.77", "public_ip_v6": null,
# "last_public_ip": "203.0.113.25", "msg": "MODEM_READY"}Aucun identifiant n’est nécessaire, sauf si Force API Auth est activé. Ajoutez alors -u admin:YOUR_PASSWORD.
Comment obtenir une liste brute de proxys pour mon outil ?
# plain text, one host:port per line
curl -u admin:YOUR_PASSWORD 'http://192.168.1.100/api/v1/proxy_list/proxy'
curl -u admin:YOUR_PASSWORD 'http://192.168.1.100/api/v1/proxy_list/socks5'
# 192.168.1.100:4001
# 192.168.1.100:4002Autres types : proxy_ipv6, socks5_ipv6, vless, vless_ipv6 et ss. VLESS et Shadowsocks renvoient des liens de partage et nécessitent l’offre Premium ou supérieure.
Comment obliger l’API à demander des identifiants ?
Ouvrez General Settings → System Setting → Security, activez Force API Auth ① et enregistrez ③. Enregistrez d’abord un nom d’utilisateur et un mot de passe ②, pour que vos appels aient des identifiants à envoyer.
Que signifient les réponses ?
| Vous recevez | Signification |
|---|---|
{"status": true, "msg": "command_sent"} | La rotation a commencé. La nouvelle IP arrive quelques secondes plus tard. |
need_upgrade | Votre offre n’inclut pas la rotation d’IP. Voir Gérer votre abonnement. |
modem_resetting ou MODEM_RESETTING | Une rotation est déjà en cours sur ce modem. |
MODEM_STOPPED | Le modem est arrêté : il ne peut pas changer d’IP. |
slot_not_found, MODEM_NOT_FOUND | Aucun modem sur ce port ou à cette position. |
invalid_format_proxy | Le proxy doit être au format host:port. |
MODEM_DISCONNECTED | Le modem est éteint ou débranché. |
COLLISION_IP | Même IP qu’avant la rotation (uniquement si IP unchanged detect est activé). |
HTTP 401, {"message": "Unauthorized…"} | L’appel nécessite les identifiants du tableau de bord. Ajoutez-les, ou appelez depuis une IP en liste blanche. |
| HTTP 403, Access Denied | Domain Only est activé. Appelez avec un nom de domaine, pas une adresse IP. |
FAQ
Où obtenir une clé d’API XProxy ?
Il n’y a pas de clé d’API. Utilisez le nom d’utilisateur et le mot de passe du tableau de bord en authentification HTTP Basic, ou appelez sans identifiants depuis votre réseau local. Pour les liens de rotation et de statut, des identifiants ne sont nécessaires qu’après l’activation de Force API Auth.
Comment renouveler l’IP d’un proxy mobile depuis du code ?
Envoyez GET /api/v1/rotate_ip/position/1 à votre box. Elle répond immédiatement command_sent. Appelez ensuite /api/v1/status/position/1 jusqu’à ce que msg vaille MODEM_READY et que public_ip ait changé.
À quelle fréquence puis-je renouveler l’IP ?
Une rotation est refusée tant qu’une autre est en cours sur le même modem (modem_resetting). Vous pouvez aussi définir le délai minimal entre deux rotations d’un port dans Rotation Settings.
Puis-je appeler l’API depuis l’extérieur de mon réseau ?
Oui, dès que la box est joignable depuis l’extérieur. Utilisez un domaine ou une adresse publique comme URL de base et ajoutez les identifiants du tableau de bord. Activez Force API Auth, pour que les liens de rotation les demandent aussi.
Mes clients peuvent-ils utiliser l’API ?
Ils reçoivent leur propre lien avec un jeton pour leur proxy (offre Business) : ils n’ont donc jamais besoin de vos identifiants du tableau de bord. Voir Utiliser la Selling Platform.
Et ensuite ?
Renouvelez l’IP avec un minuteur, protégez vos appels ou branchez les proxys dans un outil.