# Référence API

Source : https://webgune.cloud/oc-oc/docs/reference-api · Mis à jour le 2026-10-27

# 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](/developers/api-reference), 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](/docs/cles-api)) :

```bash
curl https://api.webgune.cloud/api/v1/projects \
  -H "Authorization: Bearer wgk_xxxxxxxxxxxx"
```

**Session cookie** (utilisée par le dashboard lui-même) :

```bash
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 :

```json
{ "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

```text
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
```

```bash
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](/developers/api-reference), pas encore couvertes par le spec généré.

## Services

```text
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
```

```bash
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](/docs/bases-de-donnees), [Autoscaling](/docs/autoscaling), [Déploiements & rollback](/docs/deploiements-rollback).

## Domaines

```text
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](/developers/api-reference).

## Facturation

```text
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

```text
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

```text
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](/docs/cles-api).

## Revendeur

Réservé aux comptes propriétaires d'une organisation (`isOrgOwner`) :

```text
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](/developers/api-reference).

## WebSocket : logs en direct

```javascript
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

```javascript
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](/docs/cles-api)).