Gérer votre VPS avec l'API REST et curl : état, alimentation, réinstallation, renouvellement

Commander un serveur via l'API prend une requête. C'est expliqué dans Commander un VPS en 4 appels API. Cette page porte sur tout ce qui suit : les actions courantes que vous feriez sinon en cliquant dans le tableau de bord, écrites en commandes curl à coller dans un script.

Chaque commande ci-dessous a été exécutée contre notre API avant publication, et les réponses sont des copies raccourcies de ce qui est revenu.

Préparation

Deux variables gardent les commandes courtes :

export API=https://api.eqvps.com/api/v1/eqvps
export EQVPS_TOKEN='paste-your-token-here'

Le token vient de POST /auth/register ou de Settings → API tokens dans le tableau de bord. Gardez-le hors de l'historique du shell si d'autres personnes utilisent la machine ; le lire depuis un fichier avec export EQVPS_TOKEN=$(cat ~/.eqvps_token) suffit.

Trouver vos serveurs

curl -s $API/services -H "Authorization: Bearer $EQVPS_TOKEN"

Chaque entrée a un id comme 47HZ7YF. C'est le code de service que prennent tous les autres appels. Ensuite, la vue complète d'un serveur :

curl -s $API/services/47HZ7YF -H "Authorization: Bearer $EQVPS_TOKEN"

{ "data": {
    "id": "47HZ7YF", "status": "active", "queued": false,
    "product": { "slug": "nano", "name": "Nano" },
    "specs": { "vcpu": 2, "memory_mb": 1024, "disk_gb": 15 },
    "hostname": "agent-box",
    "vm": { "state": "running", "uptime": 5340 },
    "access": { "method": "ssh", "host": "203.0.113.10", "port": 21521, "user": "root", "nat": true, ... } } }

access vous dit comment vous connecter. Sur une offre avec sa propre IPv4, le port est 22 ; sur une offre NAT, c'est votre port redirigé personnel. Cet appel est en lecture seule, l'interroger en boucle est donc sans risque.

Si vous avez commandé sans clé SSH, le mot de passe root s'affiche une seule fois :

curl -s "$API/services/47HZ7YF?reveal=1" -H "Authorization: Bearer $EQVPS_TOKEN"

Tant que le serveur démarre encore, la réponse indique password_pending et l'affichage unique n'est pas consommé. Attendez une demi-minute et redemandez.

Alimentation : start, stop, reboot

curl -s -X POST $API/services/47HZ7YF/power \
  -H "Authorization: Bearer $EQVPS_TOKEN" -H "Content-Type: application/json" \
  -d '{"action": "reboot"}'

action vaut start, stop ou reboot. Un serveur pas encore actif (encore en création, ou suspendu pour impayé) répond 409 Service is not active. Ce n'est pas une erreur de votre script. Vérifiez d'abord status.

Métriques

curl -s "$API/services/47HZ7YF/metrics?timeframe=day" -H "Authorization: Bearer $EQVPS_TOKEN"

CPU, mémoire, réseau et disque en série temporelle. timeframe vaut hour (par défaut), day, week ou month. Pratique pour une tâche cron qui vous prévient quand le disque ne cesse de grossir. Les compteurs de trafic de la période de facturation en cours sont dans Vérifier la vitesse et le trafic.

Renommer le serveur

curl -s -X POST $API/services/47HZ7YF/hostname \
  -H "Authorization: Bearer $EQVPS_TOKEN" -H "Content-Type: application/json" \
  -d '{"hostname": "web-01"}'

Le nouveau nom est appliqué dans le système en marche par l'agent invité, sans redémarrage sous Linux. Si le serveur est arrêté, ou si vous avez supprimé qemu-guest-agent, l'appel renvoie 409 agent_unavailable et rien ne change.

Réinstaller l'OS

Celle-ci efface le disque. L'API vous oblige à saisir le hostname actuel du serveur dans confirm, pour qu'un script avec un mauvais id de service ne puisse pas effacer la mauvaise machine :

curl -s -X POST $API/services/47HZ7YF/reinstall \
  -H "Authorization: Bearer $EQVPS_TOKEN" -H "Content-Type: application/json" \
  -d '{"os_id": 4, "confirm": "web-01"}'

os_id provient de la liste available_os de votre offre dans GET /products ou des détails du serveur lui-même. La réinstallation tourne en arrière-plan ; interrogez GET /services/{id} jusqu'à ce que status redevienne active.

Renouvellement et solde

Les serveurs se renouvellent chaque mois depuis votre solde prépayé. Pour voir ce que coûtent des durées plus longues pour ce serveur :

curl -s $API/services/47HZ7YF/renew-options -H "Authorization: Bearer $EQVPS_TOKEN"

Pour payer d'avance, disons trois mois, en un appel :

curl -s -X POST $API/services/47HZ7YF/renew \
  -H "Authorization: Bearer $EQVPS_TOKEN" -H "Content-Type: application/json" \
  -d '{"months": 3}'

months vaut 1, 3, 6 ou 12, et 12 est facturé au prix annuel avec sa remise. La réponse indique paid_from_balance: true et la nouvelle date d'expiration. Si le solde ne couvre pas le montant, rien n'est débité : vous recevez paid_from_balance: false et une checkout_url pour cette facture. Une fois le solde rechargé, POST $API/invoices/{invoice_id}/pay paie cette facture depuis le solde ; s'il reste insuffisant, il renvoie le même type de checkout_url et ne débite rien. Consulter et recharger le solde :

curl -s $API/balance -H "Authorization: Bearer $EQVPS_TOKEN"

curl -s -X POST $API/balance/topup \
  -H "Authorization: Bearer $EQVPS_TOKEN" -H "Content-Type: application/json" \
  -d '{"amount": 25}'

La réponse de recharge contient une checkout_url. C'est un paiement crypto : USDT, USDC ou ETH sur Base, Ethereum ou Polygon. Le solde est crédité une fois le paiement confirmé on-chain. Payer est la seule étape qu'un script ne peut pas faire à votre place, sauf s'il détient un portefeuille.

Monero fonctionne aussi, mais uniquement comme recharge de solde avec vérification manuelle : vous envoyez des XMR, transmettez l'id de transaction, et nous créditons après vérification. Voir Payer en Monero.

Résilier, et changer d'avis

La résiliation sûre laisse le serveur tourner jusqu'à la fin de la période payée et ne le renouvelle simplement pas :

curl -s -X POST $API/services/47HZ7YF/cancel \
  -H "Authorization: Bearer $EQVPS_TOKEN" -H "Content-Type: application/json" \
  -d '{"type": "end_of_period", "reason": "moving the project elsewhere"}'

reason est obligatoire. Quelques mots suffisent. Changé d'avis avant la date ?

curl -s -X POST $API/services/47HZ7YF/cancel/undo -H "Authorization: Bearer $EQVPS_TOKEN"

"type": "immediate" existe aussi. Il supprime le serveur et ses données sur-le-champ, exige "confirm": "<hostname>" et ne peut pas être annulé. À moins d'en être vraiment sûr, utilisez end_of_period.

Garder le token en vie

Les nouveaux tokens vivent un an par défaut. Chaque réponse authentifiée porte un en-tête X-Token-Expires-At, pour qu'un script puisse s'en apercevoir tôt. Échanger le token contre un neuf :

curl -s -X POST $API/auth/token/refresh -H "Authorization: Bearer $EQVPS_TOKEN"

L'ancien token cesse de fonctionner immédiatement, alors enregistrez le nouveau avant toute autre chose.

Erreurs à gérer

Vous faites cela depuis un client IA plutôt qu'un script ? Les mêmes actions existent en outils MCP — voir Comment un agent gère son propre VPS via MCP et la référence de l'API. Pas encore de serveur ? Choisissez une offre.