Referencia de la API REST
La API HTTP que expone el demonio de Saba-chan. Esquema de autenticación y catálogo de los endpoints principales.
Referencia de la API REST
El demonio de Saba-chan (saba-core) expone una API REST HTTP en 127.0.0.1:57474. La GUI y la CLI solo llaman a esta API, y los comandos de Discord que llegan a través del relay en la nube los procesa la misma funcionalidad dentro del demonio. Puede crear un cliente propio siguiendo el mismo contrato.
Esta referencia resume las rutas que probablemente necesite un usuario o integrador, tomadas de las definiciones de rutas del demonio (src/ipc/). Se omiten algunas rutas internas y los esquemas de los campos pueden cambiar, así que consulte el código para la versión más reciente.
1. Conceptos básicos
- URL base:
http://127.0.0.1:57474(predeterminada). Se puede cambiar con la variable de entornoSABA_IPC_PORTo congui.ipcPortenconfig.json(surte efecto tras reiniciar el demonio). - Dirección de escucha: fija en
127.0.0.1, por lo que no es accesible desde fuera. Las solicitudes cuya cabeceraHostno es de loopback (127.0.0.1,localhost,::1) reciben un 403. - Autenticación: todas las solicitudes salvo
/healthnecesitan la cabeceraX-Saba-Token. El demonio genera un token nuevo cada vez que arranca y lo escribe en el archivo.ipc_tokende la carpeta de datos (Windows:%APPDATA%\saba-chan\.ipc_token). Un token ausente o incorrecto recibe un 401 sin cuerpo. - Content-Type: los cuerpos de las solicitudes son
application/json. La mayoría de las respuestas también son JSON (con excepciones como los paquetes GUI de las extensiones, los iconos, etc.). - Formato de error: varía según la ruta. Las formas habituales son
{"error": "...", "error_code": "..."},{"success": false, "error": ..., "error_code": ...}y{"ok": false, "error": ...}. Algunas rutas devuelven HTTP 200 conok:falsecuando fallan, así que compruebe también el cuerpo.
2. Comprobación de estado y demonio
GET /health # no requiere token
GET /api/version
GET /api/diagnostics
GET /api/events # flujo de eventos (SSE)
POST /api/daemon/shutdown
/health:{"ok": true, "version": "x.y.z", "pid": 1234, "token": "valid" | "invalid" | "missing"}.tokensolo indica si elX-Saba-Tokenque envió es correcto; nunca revela el valor./api/version:{version, components: {...}}(versiones del núcleo, los módulos y las extensiones)./api/events: Server-Sent Events. Los tipos principales soninstance.exit(salida del servidor / veredicto de fallo),backup.done,update.available,schedule.warn,provision.progressyaction.run. Al reconectar, puede recuperar los eventos perdidos con la cabeceraLast-Event-IDo con?since=<n>./api/daemon/shutdown: apaga el demonio.
3. Servidores (instancias)
Saba-chan gestiona cada servidor como una instancia, identificada por un UUID (id).
3.1 Listar, crear, actualizar, eliminar
GET /api/servers # lista de servidores + estado de ejecución
GET /api/instances # lista de instancias
POST /api/instances # crear
PUT /api/instances/reorder # cuerpo: { "order": [id, ...] }
GET /api/instance/:id # detalles (+ estado de aceptación de condiciones en agreements)
PATCH /api/instance/:id # cambiar ajustes (objeto clave-valor)
DELETE /api/instance/:id # eliminar
POST /api/instance/:id/rename # cuerpo: { "name": "..." }
- Campos principales de
POST /api/instances:{ "name", "module_name", "port"?, "preset"?, "module_settings"?, "version"?, "working_dir"?, "managed_start"?, "accept_agreements"?: [id] }. Siversionse deja vacío, se usa la última versión;working_dires la carpeta vacía (ruta absoluta) donde se instalará el servidor nuevo, ymanaged_start: falsees la ejecución con gestión manual. Un valor de instalación fuera de lo que el módulo fija eninstall_optionsdevuelve 400not_installable. Si tiene éxito devuelve 201{success, id, ...}y, si el módulo define un paso de instalación, la instalación de los archivos del servidor empieza en segundo plano (§3.5). - Además del puerto y los ajustes del módulo,
PATCH /api/instance/:idacepta también ajustes del demonio como:auto_restart,restart_on_unknown_exit: si se reinicia automáticamente tras un fallo / una salida desconocidaextra_args: argumentos de inicio adicionales (una cadena o un array de cadenas;nulllos borra)memory_limit_mb: límite de memoria (MiB, al menos 256; se aceptan las formas"4G"/"4096M";null/0significa sin límite). Solo se aplica en Windows.
- Para renombrar, el servidor debe estar detenido; un nombre que ya está en uso devuelve 409
name_taken.
3.2 Iniciar / detener / reiniciar
POST /api/instance/:id/start
POST /api/instance/:id/stop # cuerpo opcional: { "force": true }
POST /api/instance/:id/restart # cuerpo opcional: { "force": true }
GET /api/instance/:id/events # historial de salidas recientes
GET /api/server/:name/status # estado por nombre
- Antes de iniciar, el demonio comprueba la aceptación de condiciones y ejecuta las comprobaciones del módulo. Las condiciones no aceptadas devuelven 409
agreement_required(conagreements); un fallo crítico en la comprobación devuelve 409preflight_failed. - La parada envía el comando de parada ordenada del juego, espera el tiempo del módulo (30 segundos por defecto) y fuerza el cierre del proceso si sigue vivo. Con
force: truese cierra de inmediato. eventsdevuelve{events: [...]}con el veredicto de la salida (user_stop,in_game_stop,crash,unknown_exit), sus pruebas, un posible reinicio automático programado, etc.
3.3 Consola y comandos
GET /api/instance/:id/console?since=<id>&count=<n>
POST /api/instance/:id/stdin # cuerpo: { "command": "say hello" }
POST /api/instance/:id/command # cuerpo: { "command": "<name>", "args"?: {...} }
GET /api/instance/:id/commands # comandos disponibles para este servidor
POST /api/instance/:id/rest # juegos solo REST (p. ej. Palworld)
POST /api/instance/:id/rcon # nombre de compatibilidad; usa la ruta de comandos de abajo (stdin → REST → RCON)
- Sondeo de la consola: la respuesta es
{success, lines: [{id, timestamp, source, content, level}], running, ...}. Consincese devuelven las líneas cuyoides mayor o igual que ese valor, así que la próxima vez envíe el últimoidrecibido+ 1. Sinsince, obtiene lascountlíneas más recientes (100 por defecto). El demonio conserva en memoria las últimas 10 000 líneas por servidor. - Orden de rutas de comandos: stdin → REST → RCON. Los comandos van primero a la consola del servidor (stdin), y los juegos que solo admiten REST, como Palworld, pasan por REST. RCON solo se usa para un juego cuyo módulo declara
supported = ["rcon"](sin consola ni API REST); entonces el demonio asigna a cada instancia su propio puerto y una contraseña aleatoria, y se conecta solo por loopback (127.0.0.1). En otros casos,/rcones una ruta que se conserva solo de nombre para clientes antiguos y envía a stdin. Los servidores sin ruta de comandos devuelven 409no_command_path. /stdindevuelve 409stdin_not_supportedsi el módulo no admite stdin./commandejecuta un comando definido por el módulo; si el servidor está detenido devuelve 409server_not_running.
3.4 Ajustes, condiciones, comprobaciones
POST /api/instance/:id/launch-preview # cuerpo: { "settings"?: {...}, "extra_args"?: "..." }
POST /api/instance/:id/agreements # cuerpo: { "accept": ["eula"] }
GET /api/instance/:id/properties # leer el archivo de configuración del juego
PUT /api/instance/:id/properties # cuerpo: { "settings": {...} }
POST /api/instance/:id/validate # revisión del servidor
POST /api/instance/:id/diagnose # diagnóstico de logs
launch-previewcalcula la línea de comandos de inicio sin arrancar el servidor. Ejemplo de respuesta:{success: true, has_launch_args, command_line, program, args, extra_args, errors: [...]}. Los valores de contraseña se ocultan como***. Si el módulo no declara argumentos de inicio, devuelvehas_launch_args: false.agreementsregistra la aceptación de las condiciones que declara el módulo (p. ej.,eulade Minecraft). Solo funciona en local; las solicitudes de orígenes remotos (Discord, etc.) reciben 403agreement_local_only. Los id no declarados reciben 400invalid_format.
3.5 Progreso de instalación y actualizaciones del servidor de juego
GET /api/provision-progress/:name # :name = nombre de la instancia
DELETE /api/provision-progress/:name # descartar un estado de progreso fallido
GET /api/instance/:id/check-update
POST /api/instance/:id/apply-update
Ejemplo de respuesta de provision-progress:
{
"active": true,
"step": 2,
"total": 5,
"label": "...",
"message": "...",
"percent": 40,
"done": false,
"error": null
}
Cuando no hay nada en curso, devuelve {"active": false}. Un estado de progreso correcto se borra automáticamente a los 5 segundos; uno fallido permanece hasta que lo descarte con DELETE (si el servidor se estaba creando, se revierte en ese momento). El progreso también está disponible como provision.progress en /api/events.
apply-update devuelve 409 server_running si el servidor está en marcha. Antes de actualizar se hace una copia de seguridad (en los módulos que admiten copias de seguridad).
3.6 Copias de seguridad y tareas programadas
GET /api/instance/:id/backups # { success, backups: [{ name, kind, created, size }] }
POST /api/instance/:id/backups # hacer copia ahora
DELETE /api/instance/:id/backups/:name
POST /api/instance/:id/backups/:name/restore # el servidor debe estar detenido
GET /api/instance/:id/schedule
PUT /api/instance/:id/schedule # cuerpo: { "schedule": [...], "backup_keep"?: 10 }
kindde la copia:manual,scheduled,pre-update,pre-restore. Si el módulo no admite copias de seguridad obtiene 400backup_unsupported; si todavía no hay nada que copiar, 400nothing_to_back_up.- Restaurar devuelve 409
server_runningsi el servidor está en marcha, y antes de restaurar se hace una copia del estado actual comopre-restore. - La forma de una tarea programada:
{ "action": "restart", "at": "05:00", "warn_minutes": [10, 5, 1], "enabled": true }
action es backup | restart | announce | update, y se usa exactamente uno de every_minutes (cada N minutos) y at (cada día a las HH:MM). announce necesita un message, y warn_minutes solo se aplica a restart y update. Las tareas no válidas devuelven 400 validation_failed (con details).
4. Módulos
GET /api/modules # módulos instalados
POST /api/modules/refresh # volver a leer la carpeta de módulos
GET /api/module/:name # metadatos del módulo
GET /api/module/:name/versions # versiones instalables del servidor de juego
GET /api/module/:name/locales
GET /api/modules/manifest # catálogo de módulos instalables
POST /api/modules/manifest/:id/install # instalar un módulo desde el catálogo
DELETE /api/modules/:id # eliminar un módulo
El catálogo de módulos procede de la lista de versiones firmada, y los archivos descargados solo se instalan después de verificar su hash.
5. Extensiones
GET /api/extensions # lista con estado de instalación/activación
POST /api/extensions/rescan
GET /api/extensions/manifest # catálogo de extensiones instalables
GET /api/extensions/updates
POST /api/extensions/:id/install
DELETE /api/extensions/:id
POST /api/extensions/:id/enable # ejecuta el hook daemon.startup de forma asíncrona
POST /api/extensions/:id/disable
GET /api/extensions/:id/config
PUT /api/extensions/:id/config
GET /api/extensions/:id/gui # paquete de la GUI (JavaScript UMD)
GET /api/extensions/:id/gui/styles # CSS
GET /api/extensions/:id/i18n/:locale # ko / en / ja / ...
Los errores de las rutas de extensiones usan la forma {success: false, error, error_code, ...}.
6. Ajustes
GET /api/config/gui
PUT /api/config/gui # JSON parcial (fusión superficial)
GET /api/config/bot
PUT /api/config/bot # ajustes del bot como el prefijo y los alias (JSON parcial)
GET /api/system/metrics # CPU, memoria, disco, uso por servidor
Todos los ajustes del usuario se guardan por espacio de nombres en un único archivo config.json de la carpeta de datos. El demonio sincroniza los ajustes del bot con el relay. El bot de Discord se ejecuta en el relay en la nube, así que el demonio no tiene ninguna API para iniciar o detener un proceso de bot.
7. Actualizaciones
GET /api/updates/status # estado actual y versiones por componente
POST /api/updates/check # buscar actualizaciones ahora
POST /api/updates/download # cuerpo opcional: { "components": [...] }
GET /api/updates/download/progress
POST /api/updates/apply # cuerpo opcional: { "components": [...] }
POST /api/updates/launch-updater # aplicar con el instalador (el demonio se detiene)
GET /api/updates/config
PUT /api/updates/config
La información de actualizaciones procede de la lista de versiones firmada. Los componentes cuyos archivos en ejecución deben sustituirse se marcan en la respuesta de apply como que necesitan una aplicación aparte; al llamar a launch-updater el instalador (saba-chan-installer --apply) detiene el demonio, reemplaza los archivos y vuelve a iniciar solo lo que ha cambiado. Estas rutas responden con la forma {ok: ...}.
8. Emparejamiento con el relay en la nube
Para el flujo de emparejamiento GUI ↔ servidor relay. Consulte la página Bot de Discord para el flujo detallado.
POST /api/relay/pair/initiate # emitir un código de emparejamiento (se reenvía al relay)
GET /api/relay/pair/:code/status # sondear si el emparejamiento ha terminado
GET /api/relay/agent # estado del agente relay
POST /api/relay/agent/start
POST /api/relay/agent/stop
DELETE /api/config/node-token # eliminar el token de nodo de este PC (detiene el agente)
Cuando termina el emparejamiento (status: "claimed"), el demonio guarda automáticamente el token de nodo y vuelve a conectar el agente relay con el token nuevo. El demonio se encarga de la autenticación ante el relay, así que los clientes no tienen que ocuparse de ello.
9. Ejemplo de autenticación (curl)
TOKEN=$(cat "$APPDATA/saba-chan/.ipc_token")
curl -H "X-Saba-Token: $TOKEN" \
http://127.0.0.1:57474/api/servers
curl -X POST \
-H "X-Saba-Token: $TOKEN" \
-H "Content-Type: application/json" \
-d '{"command":"list"}' \
http://127.0.0.1:57474/api/instance/<instance-id>/stdin
<instance-id> es el id de la respuesta de GET /api/servers o GET /api/instances.
10. Compatibilidad de versiones
- Esta API está clasificada como IPC privada. No es un contrato público, así que las rutas y los esquemas pueden cambiar incluso en versiones menores.
- Si distribuye un cliente propio, compruebe la versión del demonio (
versiondeGET /health) y trátela de forma conservadora.
Si tiene problemas, vaya a Resolución de problemas.