Référence API
Référence API
L'API Webgune est une API REST en JSON. Deux surfaces existent :
https://api.webgune.cloud/api/*: utilisée en interne par le dashboard, non versionnée.https://api.webgune.cloud/api/v1/*: surface publique, stable, pensée pour les intégrations tierces (CI/CD, scripts, votre propre outillage). Utilisez celle-ci.
La référence interactive, générée depuis le spec OpenAPI (GET /api/v1/openapi.json), liste chaque endpoint avec ses schémas exacts de requête et de réponse.
Authentification
Deux méthodes, au choix :
Clé API, recommandée pour un script ou une intégration tierce (création et scopes : Clés API) :
curl https://api.webgune.cloud/api/v1/projects \
-H "Authorization: Bearer wgk_xxxxxxxxxxxx"
Session cookie (utilisée par le dashboard lui-même) :
POST /api/auth/login
Content-Type: application/json
{ "email": "vous@exemple.com", "password": "..." }
La réponse fixe le cookie sid ; il doit être transmis sur chaque appel suivant (credentials: "include" côté fetch). Une session n'est pas limitée par des scopes, car elle représente votre compte connecté.
Erreurs
Toute réponse d'erreur suit le même format :
{ "error": "Message lisible", "code": "code_machine_optionnel" }
Codes HTTP standards : 400 payload invalide, 401 authentification manquante/invalide, 403 scope ou rôle insuffisant, 404 ressource introuvable ou inaccessible (on ne distingue pas les deux, pour ne pas révéler l'existence d'une ressource à qui n'y a pas accès), 409 conflit, 429 limite de débit dépassée.
Limite de débit
Chaque clé API a sa propre limite (60 requêtes/minute par défaut, configurable jusqu'à 6000 à la création). Chaque réponse porte les en-têtes :
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 57
X-RateLimit-Reset: 1732549800
Une session cookie n'est jamais limitée par ce mécanisme.
Projets
GET /api/v1/projects lister vos projets (propriétaire ou membre)
POST /api/v1/projects créer un projet
GET /api/v1/projects/:id détail d'un projet (services, canvas)
PUT /api/v1/projects/:id renommer / modifier la description
DELETE /api/v1/projects/:id supprimer un projet
curl -X POST https://api.webgune.cloud/api/v1/projects \
-H "Authorization: Bearer wgk_xxxxxxxxxxxx" -H "Content-Type: application/json" \
-d '{ "name": "mon-projet" }'
Gestion des membres, du canvas (positions/liens) et des redirections de domaine au niveau projet : voir la référence interactive, pas encore couvertes par le spec généré.
Services
GET /api/v1/services/project/:projectId services d'un projet
GET /api/v1/services/:id détail d'un service (statut K8s live)
POST /api/v1/services créer un service (GitHub, upload, Docker, base de données)
DELETE /api/v1/services/:id supprimer un service
POST /api/v1/services/:id/redeploy redéployer
GET /api/v1/services/:id/logs logs runtime récents
GET /api/v1/services/:id/metrics CPU / mémoire instantanés
GET /api/v1/services/:id/env variables d'environnement
PUT /api/v1/services/:id/env remplacer les variables (redémarre le service)
PUT /api/v1/services/:id/scale fixer le nombre de réplicas
GET /api/v1/services/:id/deployments historique des déploiements
POST /api/v1/services/:id/deployments/:deploymentId/rollback revenir à un déploiement antérieur
curl -X POST https://api.webgune.cloud/api/v1/services/svc_123/redeploy \
-H "Authorization: Bearer wgk_xxxxxxxxxxxx"
Previews par branche, exposition de base de données, volumes, ports personnalisés, autoscaling, bots Discord : endpoints existants, pas encore dans le spec OpenAPI généré. Voir Bases de données, Autoscaling, Déploiements & rollback.
Domaines
POST /api/v1/domains/check vérifier la disponibilité d'un domaine
GET /api/v1/domains lister vos domaines
POST /api/v1/domains/register enregistrer un domaine disponible
GET /api/v1/domains/:id détail d'un domaine
DELETE /api/v1/domains/:id supprimer un domaine
GET /api/v1/domains/:id/dns lister les enregistrements DNS
POST /api/v1/domains/:id/dns ajouter un enregistrement DNS
DELETE /api/v1/domains/:id/dns/:idx supprimer un enregistrement DNS
Nameservers, auto-renouvellement, renouvellement manuel : voir la référence interactive.
Facturation
GET /api/v1/billing/plans lister les plans disponibles
GET /api/v1/billing/subscription abonnement actif (compte, ou ?projectId= pour un projet dédié)
GET /api/v1/billing/invoices lister vos factures
Souscription, paiement et webhook restent des flux internes au dashboard (Mollie), non exposés en tant qu'opérations API tierces.
Dashboard
GET /api/v1/dashboard/stats statistiques agrégées (services, CPU/mémoire vs limites du plan)
GET /api/v1/dashboard/deployment-history historique des déploiements, 30 derniers jours
Clés API
GET /api/v1/api-keys lister vos clés
POST /api/v1/api-keys créer une clé
DELETE /api/v1/api-keys/:id révoquer une clé
GET /api/v1/api-keys/:id/audit-log journal d'audit (100 dernières requêtes)
Détail des scopes, du débit et de l'en-tête X-Act-As-User-Id (revendeurs) : voir Clés API.
Revendeur
Réservé aux comptes propriétaires d'une organisation (isOrgOwner) :
GET /api/v1/reseller/organization mon organisation
GET /api/v1/reseller/sub-clients lister mes sous-clients
GET /api/v1/reseller/overview vue d'ensemble (compteurs par sous-client)
Création/suppression de sous-clients et facturation revendeur : voir la référence interactive.
WebSocket : logs en direct
const ws = new WebSocket("wss://api.webgune.cloud/ws/services/:id/logs");
ws.onmessage = (e) => console.log(e.data); // une ligne de log par message
WebSocket : métriques en direct
const ws = new WebSocket("wss://api.webgune.cloud/ws/projects/:id/metrics");
ws.onmessage = (e) => {
const metrics = JSON.parse(e.data);
// { "id-du-service": { cpu: 1.2, memory: 256 }, ... }
};
Les WebSockets exigent une session navigateur : une clé API ne peut pas s'y connecter (voir Clés API).