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 entorno SABA_IPC_PORT o con gui.ipcPort en config.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 cabecera Host no es de loopback (127.0.0.1, localhost, ::1) reciben un 403.
  • Autenticación: todas las solicitudes salvo /health necesitan la cabecera X-Saba-Token. El demonio genera un token nuevo cada vez que arranca y lo escribe en el archivo .ipc_token de 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 con ok:false cuando 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"}. token solo indica si el X-Saba-Token que 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 son instance.exit (salida del servidor / veredicto de fallo), backup.done, update.available, schedule.warn, provision.progress y action.run. Al reconectar, puede recuperar los eventos perdidos con la cabecera Last-Event-ID o 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] }. Si version se deja vacío, se usa la última versión; working_dir es la carpeta vacía (ruta absoluta) donde se instalará el servidor nuevo, y managed_start: false es la ejecución con gestión manual. Un valor de instalación fuera de lo que el módulo fija en install_options devuelve 400 not_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/:id acepta también ajustes del demonio como:
    • auto_restart, restart_on_unknown_exit: si se reinicia automáticamente tras un fallo / una salida desconocida
    • extra_args: argumentos de inicio adicionales (una cadena o un array de cadenas; null los borra)
    • memory_limit_mb: límite de memoria (MiB, al menos 256; se aceptan las formas "4G"/"4096M"; null/0 significa 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 (con agreements); un fallo crítico en la comprobación devuelve 409 preflight_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: true se cierra de inmediato.
  • events devuelve {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, ...}. Con since se devuelven las líneas cuyo id es mayor o igual que ese valor, así que la próxima vez envíe el último id recibido + 1. Sin since, obtiene las count lí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, /rcon es una ruta que se conserva solo de nombre para clientes antiguos y envía a stdin. Los servidores sin ruta de comandos devuelven 409 no_command_path.
  • /stdin devuelve 409 stdin_not_supported si el módulo no admite stdin.
  • /command ejecuta un comando definido por el módulo; si el servidor está detenido devuelve 409 server_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-preview calcula 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, devuelve has_launch_args: false.
  • agreements registra la aceptación de las condiciones que declara el módulo (p. ej., eula de Minecraft). Solo funciona en local; las solicitudes de orígenes remotos (Discord, etc.) reciben 403 agreement_local_only. Los id no declarados reciben 400 invalid_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 }
  • kind de la copia: manual, scheduled, pre-update, pre-restore. Si el módulo no admite copias de seguridad obtiene 400 backup_unsupported; si todavía no hay nada que copiar, 400 nothing_to_back_up.
  • Restaurar devuelve 409 server_running si el servidor está en marcha, y antes de restaurar se hace una copia del estado actual como pre-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 (version de GET /health) y trátela de forma conservadora.

Si tiene problemas, vaya a Resolución de problemas.