Référence des endpoints

Chaque route, ce qu'elle attend et ce qu'elle renvoie.

Tous les chemins ci-dessous sont relatifs à https://api.ecloudserv.fr/api/v1 et demandent l'en-tête Authorization: Bearer …. Voir la vue d'ensemble pour les codes d'erreur.

À noter

Cette page couvre les routes stables. Le panel expose davantage d'actions ; celles qui ne sont pas listées ici peuvent encore changer de forme, mieux vaut ne pas bâtir dessus tout de suite.

Compte#

GET/meportée read

Renvoie le compte associé à la clé. C'est la requête à utiliser pour vérifier qu'une clé est valide.

requête

curl https://api.ecloudserv.fr/api/v1/me \
  -H "Authorization: Bearer $ECLOUD_API_KEY"

réponse

{
  "id": "usr_1a2b3c",
  "username": "lucas",
  "email": "lucas@exemple.fr"
}

Services#

GET/serversportée read

Liste les services du compte.

réponse

[
  {
    "id": "srv_9f8e7d",
    "name": "mon-bot",
    "status": "RUNNING",
    "runtime": "nodejs"
  }
]

GET/servers/:idportée read

Détail d'un service : configuration, offre, état courant.

GET/servers/:id/resourcesportée read

Consommation instantanée : processeur, mémoire, disque, réseau. La réponse est amortie quelques secondes côté serveur — inutile de sonder plus vite qu'une fois par seconde, vous obtiendriez la même valeur.

réponse

{
  "cpu_percent": 3.4,
  "memory_bytes": 148897792,
  "disk_bytes": 512000000,
  "network": { "rx_bytes": 91234, "tx_bytes": 44120 },
  "uptime_ms": 864000
}

GET/servers/:id/startupportée read

Variables de démarrage du service (ce que le panel affiche sous « Variables »).

PATCH/servers/:id/variables/:keyportée write

Modifie une variable de démarrage. Le corps porte la nouvelle valeur : { "value": "..." }. La plupart des services doivent redémarrer pour en tenir compte.

GET/servers/:id/backupsportée read

Liste les sauvegardes du service.

POST/servers/:id/backupsportée write

Déclenche une sauvegarde. Corps optionnel : { "name": "avant-migration" }.

DELETE/servers/:id/backups/:uuidportée write

Supprime une sauvegarde. Définitif.

GET/servers/:id/activityportée read

Journal d'activité du service (connexions console, actions récentes).

DELETE/servers/:idportée write

Supprime le service — la machine ET l'entrée dans votre compte. Définitif, pas de corbeille.

POST/serversportée write

Crée un service. Le corps décrit le nom, l'environnement et les ressources voulues.

requête

curl -X POST https://api.ecloudserv.fr/api/v1/servers \
  -H "Authorization: Bearer $ECLOUD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "mon-service",
    "runtime": "nodejs",
    "ram": 512,
    "disk": 2048,
    "cpu": 100
  }'

La réponse est un 201 avec le service créé. Sa création n'est pas instantanée : interrogez /servers/:id jusqu'à ce que son état passe d'installation à démarré.

POST/servers/:id/powerportée write

Change l'état d'un service : démarrage, arrêt, redémarrage.

requête

curl -X POST https://api.ecloudserv.fr/api/v1/servers/srv_9f8e7d/power \
  -H "Authorization: Bearer $ECLOUD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "signal": "restart" }'

Signal	Effet
`start`	Démarre un service arrêté.
`stop`	Demande un arrêt propre au programme.
`restart`	Arrêt puis démarrage.
`kill`	Arrêt brutal, sans laisser le programme se fermer.

Attention

kill coupe le processus net. Si votre programme écrivait un fichier ou une base à cet instant, les données peuvent être laissées à moitié écrites. Réservez-le aux cas où stop ne répond plus.

Attendre qu'un service soit prêt

Une action d'alimentation renvoie immédiatement, avant que l'état ait changé. Le bon réflexe est d'interroger l'état, avec un délai qui s'allonge :

attente d'un état

async function attendreEtat(id, attendu, timeoutMs = 120000) {
  const base = "https://api.ecloudserv.fr/api/v1";
  const debut = Date.now();
  let delai = 1000;

  while (Date.now() - debut < timeoutMs) {
    const res = await fetch(`${base}/servers/${id}`, {
      headers: { Authorization: `Bearer ${process.env.ECLOUD_API_KEY}` },
    });
    if (res.ok && (await res.json()).status === attendu) return true;

    await new Promise((r) => setTimeout(r, delai));
    delai = Math.min(delai * 1.5, 10000); // on ralentit au lieu de marteler
  }
  throw new Error(`${id} n'a pas atteint l'état ${attendu} à temps`);
}

Redimensionner, réinstaller, dépanner

PATCH/servers/:id/resourcesportée write

Change la RAM, le disque ou le CPU alloués : { "ram": 1024 }. Chaque champ est optionnel — seuls ceux fournis sont modifiés.

PUT/servers/:id/startup/docker-imageportée write

Change l'image Docker utilisée par le service.

GET/servers/:id/settingsportée read

UUID, identifiants SFTP, et le reste des réglages techniques.

POST/servers/:id/settings/renameportée write

Renomme le service : { "name": "...", "description": "..." }.

POST/servers/:id/settings/auto-restartportée write

Active ou coupe le redémarrage automatique en cas de plantage.

GET/servers/:id/settings/alertsportée read

Seuils d'alerte de consommation (en % de l'enveloppe).

POST/servers/:id/settings/alertsportée write

Règle les seuils : { "ram": 90, "cpu": null }. null désactive l'alerte pour cette ressource.

GET/servers/:id/allocationsportée read

Ports assignés au service par le panel.

POST/servers/:id/allocations/firewallportée write

Active, coupe ou limite le débit d'un port : { "port": 25565, "active": true, "rateLimit": 200 }.

POST/servers/:id/reinstallportée write

Relance le script d'installation de l'image de départ. Le contenu existant du conteneur peut être affecté selon ce que fait ce script — c'est la même action que le bouton « Réinstaller » du panel.

POST/servers/:id/retryportée write

Relance une création restée bloquée en erreur.

GET/servers/:id/db-connectionportée read

Pour un service base de données : hôte, port et identifiants de connexion.

GET/servers/:id/consoleportée read

Jeton WebSocket signé, valable quelques minutes, pour se brancher sur la console en direct.

Terminal (exécuter une commande dans le conteneur)

À la différence de la console, qui n'écrit que sur l'entrée standard du processus, ces routes exécutent une vraie commande DANS le conteneur (docker exec). Le résultat n'est pas immédiat : la commande part en file d'attente vers l'agent du node, on interroge son état ensuite.

POST/servers/:id/execportée write

Lance une commande : { "command": "ls -la /home/container" }. Renvoie un identifiant de tâche.

GET/servers/:id/exec/:jobIdportée read

État et sortie d'une commande lancée.

GET/servers/:id/execportée read

Historique des commandes exécutées.

Tâches planifiées

GET/servers/:id/schedulesportée read

Liste les tâches planifiées du service.

POST/servers/:id/schedulesportée write

Crée une planification (champs cron classiques : minute, hour, day_of_month, day_of_week, month).

PATCH/servers/:id/schedules/:sidportée write

Modifie une planification existante.

DELETE/servers/:id/schedules/:sidportée write

Supprime une planification.

POST/servers/:id/schedules/:sid/executeportée write

Exécute la planification immédiatement, sans attendre son horaire.

POST/servers/:id/schedules/:sid/tasksportée write

Ajoute une tâche à la planification : { "action": "backup" }, { "action": "power", "payload": "restart" }, ou { "action": "command", "payload": "say Redémarrage dans 5 min" }.

DELETE/servers/:id/schedules/:sid/tasks/:tidportée write

Retire une tâche d'une planification.

Conteneurs LXC#

Des machines Linux complètes (Incus), à côté des services applicatifs — pour tout ce qui a besoin d'un vrai système : un accès SSH, plusieurs processus, un pare-feu à soi.

GET/lxcportée read

Liste vos conteneurs, avec les images et bornes disponibles pour en créer un nouveau.

GET/lxc/:idportée read

Détail d'un conteneur : état, ressources allouées, ports redirigés.

POST/lxcportée write

Crée un conteneur.

requête

curl -X POST https://api.ecloudserv.fr/api/v1/lxc \
  -H "Authorization: Bearer $ECLOUD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "build-runner",
    "image": "debian-12",
    "cpu": 100,
    "ramMb": 1024,
    "diskGb": 10,
    "sshKey": "ssh-ed25519 AAAA... moi@poste"
  }'

POST/lxc/:id/power/:actionportée write

:action vaut start, stop ou restart.

POST/lxc/:id/retryportée write

Relance une création restée en erreur, avec les mêmes paramètres.

DELETE/lxc/:idportée write

Supprime le conteneur. Définitif.

POST/lxc/:id/portsportée write

Ouvre une redirection de port public vers le conteneur : { "targetPort": 8080, "protocol": "tcp" }. Sans publicPort, un port libre est choisi automatiquement.

DELETE/lxc/:id/ports/:portIdportée write

Retire une redirection.

À noter

Le mot de passe root d'un conteneur LXC ne passe pas par l'API publique — il se consulte depuis le panel uniquement, pour ne pas le faire transiter par un script tiers.

Pages (sites statiques)#

Hébergement de sites déjà compilés (HTML/CSS/JS) : vous envoyez une archive, elle est publiée sur le domaine du site, avec un historique de déploiements et un retour en arrière possible à tout moment.

GET/pagesportée read

Liste vos sites. Ne couvre que ceux que vous possédez en propre — un site partagé via une organisation n'apparaît pas ici pour l'instant.

GET/pages/:idportée read

Détail d'un site : domaine, état TLS, déploiement en cours.

GET/pages/:id/deploymentsportée read

Historique des mises en ligne du site.

POST/pagesportée write

Crée un site (le domaine doit déjà pointer chez nous — voir la documentation Pages).

requête

curl -X POST https://api.ecloudserv.fr/api/v1/pages \
  -H "Authorization: Bearer $ECLOUD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "mon-site", "domain": "exemple.fr", "spa": false }'

PATCH/pages/:idportée write

Modifie le nom, le mode SPA, ou active/désactive le site.

DELETE/pages/:idportée write

Supprime le site. Définitif.

POST/pages/:id/deployportée write

Met en ligne une nouvelle version. Le corps est un multipart/form-data avec un champ fichier portant l'archive ZIP (30 Mo maximum, compressée).

requête

curl -X POST https://api.ecloudserv.fr/api/v1/pages/pg_4d5e6f/deploy \
  -H "Authorization: Bearer $ECLOUD_API_KEY" \
  -F "file=@dist.zip"

POST/pages/:id/rollback/:deployIdportée write

Republie un déploiement passé tel quel — le retour en arrière le plus simple.

Stockage objet (buckets)#

Des seaux de fichiers, façon S3 — un bucket privé se lit avec la même clé d'API ; un bucket public expose ses objets sans authentification, à une URL stable.

GET/storage/summaryportée read

Volume total utilisé, tous buckets confondus.

GET/storage/bucketsportée read

Liste vos buckets.

POST/storage/bucketsportée write

Crée un bucket : { "name": "avatars", "isPublic": false }.

PATCH/storage/buckets/:idportée write

Bascule un bucket en public ou privé : { "isPublic": true }.

DELETE/storage/buckets/:idportée write

Supprime un bucket et tout son contenu. Définitif.

GET/storage/buckets/:id/objectsportée read

Liste les objets d'un bucket. Paramètres optionnels : ?prefix= pour filtrer par dossier, ?cursor= pour paginer.

GET/storage/buckets/:id/objectportée read

Métadonnées d'un objet précis : ?key=chemin/du/fichier.

PUT/storage/buckets/:id/objectsportée write

Envoie un fichier. Le corps est le fichier LUI-MÊME (pas de multipart) ; la clé s'indique en requête : ?key=chemin/du/fichier.

requête

curl -X PUT "https://api.ecloudserv.fr/api/v1/storage/buckets/bkt_7a8b9c/objects?key=logo.png" \
  -H "Authorization: Bearer $ECLOUD_API_KEY" \
  -H "Content-Type: image/png" \
  --data-binary @logo.png

GET/storage/buckets/:id/downloadportée read

Télécharge le contenu d'un objet : ?key=chemin/du/fichier.

DELETE/storage/buckets/:id/objectsportée write

Supprime un objet : ?key=chemin/du/fichier.

Astuce

Un bucket public sert ses objets sans clé, à https://cdn.ecloudserv.fr/storage/public/:bucketId/:cle — pratique pour des images ou des fichiers téléchargeables directement depuis un site.

Bases de données#

Les bases MySQL provisionnées avec vos services (voir withDatabase à la création d'un service).

GET/databasesportée read

Liste vos bases, tous services confondus.

GET/databases/:id/tablesportée read

Liste les tables d'une base.

POST/databases/:id/queryportée write

Exécute une requête SQL et renvoie son résultat. La portée write est exigée même pour un SELECT : l'API ne peut pas savoir avant exécution qu'une requête ne modifie rien.

requête

curl -X POST https://api.ecloudserv.fr/api/v1/databases/db_2c3d4e/query \
  -H "Authorization: Bearer $ECLOUD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "sql": "SELECT id, email FROM users LIMIT 10" }'

POST/databases/:id/importportée write

Importe un fichier .sql (dump), envoyé comme texte dans le corps : { "sql": "..." }. 8 Mo maximum.

Attention

Il n'y a pas de confirmation côté API : un DROP TABLE envoyé par erreur s'exécute tel quel. Testez vos requêtes sur une base secondaire avant de les rejouer en production.