# Referencia de la API

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

# Referencia de la API

La API de Webgune es una API REST en JSON. Existen dos superficies:

- `https://api.webgune.cloud/api/*` es usada internamente por el dashboard y no tiene versión.
- `https://api.webgune.cloud/api/v1/*` es la **superficie pública**, estable, pensada para integraciones de terceros (CI/CD, scripts, tus propias herramientas). Usa esta.

La [referencia interactiva](/developers/api-reference), generada desde el spec OpenAPI (`GET /api/v1/openapi.json`), lista cada endpoint con sus esquemas exactos de petición y respuesta.

## Autenticación

Dos métodos, a elegir:

**Clave de API**, recomendada para un script o una integración de terceros (creación y scopes: [Claves de API](/docs/cles-api)):

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

**Cookie de sesión** (usada por el propio dashboard):

```bash
POST /api/auth/login
Content-Type: application/json

{ "email": "tu@ejemplo.com", "password": "..." }
```

La respuesta fija la cookie `sid`; debe transmitirse en cada llamada siguiente (`credentials: "include"` en el lado de fetch). Una sesión no está limitada por scopes, porque representa tu cuenta conectada.

## Errores

Toda respuesta de error sigue el mismo formato:

```json
{ "error": "Mensaje legible", "code": "codigo_maquina_opcional" }
```

Códigos HTTP estándar: `400` payload inválido, `401` autenticación faltante/inválida, `403` scope o rol insuficiente, `404` recurso no encontrado o inaccesible (no se distinguen ambos casos, para no revelar la existencia de un recurso a quien no tiene acceso), `409` conflicto, `429` límite de tasa superado.

## Límite de tasa

Cada clave de API tiene su propio límite (60 peticiones/minuto por defecto, configurable hasta 6000 en la creación). Cada respuesta lleva las cabeceras:

```
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 57
X-RateLimit-Reset: 1732549800
```

Una cookie de sesión nunca está limitada por este mecanismo.

## Proyectos

```text
GET    /api/v1/projects              listar tus proyectos (propietario o miembro)
POST   /api/v1/projects              crear un proyecto
GET    /api/v1/projects/:id          detalle de un proyecto (servicios, canvas)
PUT    /api/v1/projects/:id          renombrar / modificar la descripción
DELETE /api/v1/projects/:id          eliminar un proyecto
```

```bash
curl -X POST https://api.webgune.cloud/api/v1/projects \
  -H "Authorization: Bearer wgk_xxxxxxxxxxxx" -H "Content-Type: application/json" \
  -d '{ "name": "mi-proyecto" }'
```

Gestión de miembros, del canvas (posiciones/enlaces) y de las redirecciones de dominio a nivel de proyecto: ver la [referencia interactiva](/developers/api-reference), aún no cubiertas por el spec generado.

## Servicios

```text
GET    /api/v1/services/project/:projectId   servicios de un proyecto
GET    /api/v1/services/:id                  detalle de un servicio (estado K8s en vivo)
POST   /api/v1/services                      crear un servicio (GitHub, subida, Docker, base de datos)
DELETE /api/v1/services/:id                  eliminar un servicio
POST   /api/v1/services/:id/redeploy         redesplegar
GET    /api/v1/services/:id/logs             logs recientes de ejecución
GET    /api/v1/services/:id/metrics          CPU / memoria instantáneos
GET    /api/v1/services/:id/env              variables de entorno
PUT    /api/v1/services/:id/env              reemplazar las variables (reinicia el servicio)
PUT    /api/v1/services/:id/scale            fijar el número de réplicas
GET    /api/v1/services/:id/deployments      historial de despliegues
POST   /api/v1/services/:id/deployments/:deploymentId/rollback   volver a un despliegue anterior
```

```bash
curl -X POST https://api.webgune.cloud/api/v1/services/svc_123/redeploy \
  -H "Authorization: Bearer wgk_xxxxxxxxxxxx"
```

Previews por rama, exposición de base de datos, volúmenes, puertos personalizados, autoscaling, bots de Discord: endpoints existentes, aún no incluidos en el spec OpenAPI generado. Ver [Bases de datos](/docs/bases-de-donnees), [Autoscaling](/docs/autoscaling), [Despliegues y rollback](/docs/deploiements-rollback).

## Dominios

```text
POST   /api/v1/domains/check              verificar la disponibilidad de un dominio
GET    /api/v1/domains                    listar tus dominios
POST   /api/v1/domains/register           registrar un dominio disponible
GET    /api/v1/domains/:id                detalle de un dominio
DELETE /api/v1/domains/:id                eliminar un dominio
GET    /api/v1/domains/:id/dns            listar los registros DNS
POST   /api/v1/domains/:id/dns            añadir un registro DNS
DELETE /api/v1/domains/:id/dns/:idx       eliminar un registro DNS
```

Servidores de nombres, auto-renovación, renovación manual: ver la [referencia interactiva](/developers/api-reference).

## Facturación

```text
GET    /api/v1/billing/plans          listar los planes disponibles
GET    /api/v1/billing/subscription   suscripción activa (cuenta, o ?projectId= para un proyecto dedicado)
GET    /api/v1/billing/invoices       listar tus facturas
```

Suscripción, pago y webhook siguen siendo flujos internos del dashboard (Mollie), no expuestos como operaciones de API de terceros.

## Dashboard

```text
GET    /api/v1/dashboard/stats                estadísticas agregadas (servicios, CPU/memoria vs límites del plan)
GET    /api/v1/dashboard/deployment-history    historial de despliegues, últimos 30 días
```

## Claves de API

```text
GET    /api/v1/api-keys                     listar tus claves
POST   /api/v1/api-keys                     crear una clave
DELETE /api/v1/api-keys/:id                 revocar una clave
GET    /api/v1/api-keys/:id/audit-log       registro de auditoría (últimas 100 peticiones)
```

Detalle de los scopes, de la tasa y de la cabecera `X-Act-As-User-Id` (revendedores): ver [Claves de API](/docs/cles-api).

## Revendedor

Reservado a las cuentas propietarias de una organización (`isOrgOwner`):

```text
GET    /api/v1/reseller/organization    mi organización
GET    /api/v1/reseller/sub-clients     listar mis subclientes
GET    /api/v1/reseller/overview        vista general (contadores por subcliente)
```

Creación/eliminación de subclientes y facturación de revendedor: ver la [referencia interactiva](/developers/api-reference).

## WebSocket: logs en directo

```javascript
const ws = new WebSocket("wss://api.webgune.cloud/ws/services/:id/logs");
ws.onmessage = (e) => console.log(e.data); // una línea de log por mensaje
```

## WebSocket: métricas en directo

```javascript
const ws = new WebSocket("wss://api.webgune.cloud/ws/projects/:id/metrics");
ws.onmessage = (e) => {
  const metrics = JSON.parse(e.data);
  // { "id-del-servicio": { cpu: 1.2, memory: 256 }, ... }
};
```

Los WebSockets requieren una sesión de navegador: una clave de API no puede conectarse a ellos (ver [Claves de API](/docs/cles-api)).