Referencia de la API
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, 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):
curl https://api.webgune.cloud/api/v1/projects \
-H "Authorization: Bearer wgk_xxxxxxxxxxxx"
Cookie de sesión (usada por el propio dashboard):
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:
{ "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
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
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, aún no cubiertas por el spec generado.
Servicios
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
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, Autoscaling, Despliegues y rollback.
Dominios
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.
Facturación
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
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
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.
Revendedor
Reservado a las cuentas propietarias de una organización (isOrgOwner):
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.
WebSocket: logs en directo
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
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).