deploykit_docs

docs Referencia de la API

Referencia de la API

La API tRPC que impulsa el dashboard, además de los endpoints REST y Socket.IO que la rodean.

Arquitectura tRPC

La API de DeployKit está construida con tRPC 11 sobre Fastify 5. El dashboard usa exactamente los mismos procedimientos que tú puedes llamar, con la entrada validada por esquemas Zod compartidos entre cliente y servidor. Todo se sirve en el dominio de tu panel:

  • Los procedimientos viven bajo /trpc/<router>.<procedure>, p. ej. /trpc/application.deploy
  • Las queries son peticiones GET con la entrada como JSON codificado en URL en ?input=
  • Las mutations son peticiones POST con un cuerpo JSON; Content-Type: application/json es obligatorio (otros tipos reciben 415)
  • No se usa ningún transformer de datos: las entradas y salidas son JSON plano, y las respuestas correctas se envuelven como {"result":{"data":...}}
  • Los cuerpos de las peticiones están limitados a 1 MiB (4 MiB para config.import)

Autenticación

Las peticiones se autentican con un token de acceso JWT en la cabecera Authorization . No hay API keys separadas: los scripts inician sesión como un usuario y actúan con el rol de ese usuario. Los tokens de acceso duran 15 minutos y los de refresco 7 días; cada refresco devuelve un nuevo par e invalida el token de refresco anterior.

bash
# Log in — returns { user, accessToken, refreshToken }
curl -s https://deploy.example.com/trpc/auth.login \
  -H 'Content-Type: application/json' \
  -d '{"email":"admin@example.com","password":"..."}'

# Query: list your projects
curl -s https://deploy.example.com/trpc/project.list \
  -H "Authorization: Bearer $ACCESS_TOKEN"

# Query with input
curl -s -G https://deploy.example.com/trpc/application.byId \
  --data-urlencode 'input={"id":"<application-uuid>"}' \
  -H "Authorization: Bearer $ACCESS_TOKEN"

# Mutation: trigger a deploy
curl -s https://deploy.example.com/trpc/application.deploy \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"id":"<application-uuid>"}'

# Refresh when the access token expires
curl -s https://deploy.example.com/trpc/auth.refresh \
  -H 'Content-Type: application/json' \
  -d '{"refreshToken":"<refresh_token>"}'

auth.login y auth.register están limitados a 10 peticiones por minuto por IP, y todas las rutas de la API a 200 por minuto. auth.register solo funciona mientras la instancia no tiene usuarios.

Niveles de acceso

Cada procedimiento es público, autenticado, solo para operadores o solo para administradores según el rol global. La mayoría de los recursos de proyecto (aplicaciones, bases de datos, stacks, servidores de juegos) están abiertos a cualquier usuario autenticado a nivel de procedimiento y después se comprueban contra el rol del llamante en el proyecto propietario: los no miembros reciben NOT_FOUND, los miembros sin permisos suficientes reciben FORBIDDEN. Ejecutar código (tareas, consola de juegos, escritura de archivos, mods) requiere tanto un rol global de operador como permisos de operador en el proyecto. Consulta Usuarios y RBAC.

Routers disponibles

auth

Registro, inicio de sesión, cierre de sesión, refresco de tokens, perfil

Procedimientos: hasUsers, register, login, refresh (public) · me, logout, changePassword, updateProfile

project

Proyectos que agrupan aplicaciones, bases de datos, stacks y servidores de juegos

Procedimientos: list, byId · create, update, updateStatusPage (operator) · delete (admin)

projectMember

Gestión de roles por proyecto

Procedimientos: list, add, updateRole, remove, myRole, availableUsers

application

Ciclo de vida de la aplicación: configuración, variables de entorno, dominios, despliegues, rollback, previews, mantenimiento

Procedimientos: byId, create, update, delete, updateEnvVars, addDomain, removeDomain, deploy, deployBranch, rollback, start, stop, setMaintenance, logs, stats, instances, deployments, listPreviews, deletePreview

database

Aprovisionamiento de bases de datos, backups y restauración

Procedimientos: byId, create, delete, start, stop, stats, updateBackupConfig, triggerBackup, listBackups, deleteBackup, restoreBackup

compose

Stacks de Docker Compose

Procedimientos: list, byId, containers, containerLogs, deployments, create, deployFromTemplate, updateComposeFile, updateEnvVars, addDomain, removeDomain, deploy, stop, start, restart, delete

template

Catálogo de plantillas de un clic

Procedimientos: list, byId · import (operator) · registry, refreshCatalog (admin)

gameServer

Servidores de juegos, con routers anidados de catálogo, archivos, backups y mods

Procedimientos: listByProject, byId, stats, create, update, start, stop, restart, delete, consoleSend · catalog.{list, byId, refresh} · files.{list, read, write, mkdir, delete, rename} · backups.{list, create, restore, delete, updateConfig} · mods.{sources, sourcesForGame, search, searchModpacks, versions, list, checkUpdates, add, update, remove, setModpack, applyChanges}

task

Tareas programadas y comandos puntuales

Procedimientos: list, previewCron, runs, runOutput · create, update, delete, runNow, runAdHoc (operator)

server

Servidores: conexiones SSH, instalación de Docker, limpieza de imágenes

Procedimientos: list, byId · testConnection, healthCheck (operator) · create, createLocal, update, delete, installDocker, pruneImages, pruneImagesAll (admin)

sshKey

Catálogo de claves SSH (solo administradores)

Procedimientos: list, byId, generate, create, update, delete

github

Registro de la GitHub App, instalaciones y repositorios

Procedimientos: status, listInstallations, listRepositories, listBranches · startManifest, completeManifest, connectExisting, test, syncInstallation, syncInstallations, disconnect (admin)

config

Exportación e importación de la configuración como YAML (todas son mutations)

Procedimientos: exportInstance, import (admin) · exportProject (project operator)

metrics

Historial de métricas y reglas de alerta

Procedimientos: history, timeseries, listRules, recentEvents, alertStats · createRule, updateRule (operator) · deleteRule (admin)

logs

Búsqueda de logs persistentes

Procedimientos: search

notification

Canales de notificación

Procedimientos: list, byId, availableEvents · create, update, delete, toggle, test (operator)

user

Gestión de usuarios y asignación de roles (solo administradores)

Procedimientos: list, create, updateRole, resetPassword, delete

audit

Consulta del registro de auditoría (solo administradores)

Procedimientos: list, stats

settings

Ajustes de la instancia: API keys de CurseForge / Steam (solo administradores)

Procedimientos: modKeys.status, modKeys.set

dashboard

Estadísticas generales

Procedimientos: summary

status

Datos de la página de estado pública (sin iniciar sesión)

Procedimientos: getPublic

Endpoints REST

Unos pocos endpoints quedan fuera de tRPC: los webhooks de los proveedores Git (verificados por firma o token, consulta Webhooks; limitados a 120 peticiones por minuto por IP) y las transferencias de archivos de servidores de juegos en streaming (token Bearer, con acceso al proyecto comprobado).

POST/api/webhooks/github
POST/api/webhooks/gitlab
POST/api/webhooks/generic
POST/api/game-servers/:id/files/upload
GET/api/game-servers/:id/files/download
GET/api/game-servers/:id/backups/:backupId/download

Eventos en tiempo real (Socket.IO)

Socket.IO se sirve en la ruta /ws y se autentica con el token de acceso pasado como auth.token en el handshake. Los clientes se unen a salas con subscribe:deployment, subscribe:logs, subscribe:metrics y subscribe:task-run (cada una comprobada contra el acceso al proyecto) y reciben eventos como deploy:status, deploy:log, container:log, metrics:update, task:status y alert:fired. El terminal web también funciona sobre esta conexión. Solo se acepta WEB_URL como origen.