Référence de l'API REST
L'API HTTP exposée par le démon Saba-chan : schéma d'authentification et catalogue des principaux endpoints.
Référence de l'API REST
Le démon Saba-chan (saba-core) expose une API REST HTTP sur 127.0.0.1:57474. La GUI et la CLI n'appellent que cette API, et les commandes Discord qui arrivent via le relais cloud sont traitées par les mêmes fonctionnalités à l'intérieur du démon. Vous pouvez créer un client personnalisé en suivant le même contrat.
Cette référence résume les routes dont un utilisateur ou un intégrateur aura probablement besoin, tirées des définitions de routes du démon (src/ipc/). Certaines routes internes sont omises, et les schémas des champs peuvent changer ; consultez le code pour la version la plus récente.
1. Généralités
- URL de base :
http://127.0.0.1:57474(par défaut). Modifiable via la variable d'environnementSABA_IPC_PORTougui.ipcPortdansconfig.json(prend effet après le redémarrage du démon). - Adresse d'écoute : fixée à
127.0.0.1, elle n'est donc pas accessible depuis l'extérieur. Les requêtes dont l'en-têteHostn'est pas une adresse de loopback (127.0.0.1,localhost,::1) reçoivent un 403. - Authentification : chaque requête, à l'exception de
/health, nécessite un en-têteX-Saba-Token. Le démon génère un nouveau jeton à chaque démarrage et l'écrit dans le fichier.ipc_tokendu dossier de données (Windows :%APPDATA%\saba-chan\.ipc_token). Un jeton absent ou erroné reçoit un 401 sans corps. - Content-Type : les corps de requête sont en
application/json. La plupart des réponses sont aussi en JSON (les bundles GUI des extensions, les icônes, etc. font exception). - Format des erreurs : varie selon la route. Les formes courantes sont
{"error": "...", "error_code": "..."},{"success": false, "error": ..., "error_code": ...}et{"ok": false, "error": ...}. Certaines routes renvoient HTTP 200 avecok:falseen cas d'échec ; vérifiez donc aussi le corps.
2. Healthcheck et démon
GET /health # aucun jeton requis
GET /api/version
GET /api/diagnostics
GET /api/events # flux d'événements (SSE)
POST /api/daemon/shutdown
/health:{"ok": true, "version": "x.y.z", "pid": 1234, "token": "valid" | "invalid" | "missing"}.tokenindique seulement si leX-Saba-Tokenque vous avez envoyé est correct ; il ne révèle jamais la valeur./api/version:{version, components: {...}}(versions du cœur, des modules et des extensions)./api/events: Server-Sent Events. Les principaux types sontinstance.exit(arrêt du serveur / verdict de crash),backup.done,update.available,schedule.warn,provision.progressetaction.run. Lors d'une reconnexion, vous pouvez rattraper les événements manqués avec l'en-têteLast-Event-IDou?since=<n>./api/daemon/shutdown: arrête le démon.
3. Serveurs (instances)
Saba-chan gère chaque serveur comme une instance, identifiée par un UUID (id).
3.1 Lister, créer, modifier, supprimer
GET /api/servers # liste des serveurs + état d'exécution
GET /api/instances # liste des instances
POST /api/instances # créer
PUT /api/instances/reorder # corps : { "order": [id, ...] }
GET /api/instance/:id # détails (+ état d'acceptation des conditions dans agreements)
PATCH /api/instance/:id # modifier les paramètres (objet clé-valeur)
DELETE /api/instance/:id # supprimer
POST /api/instance/:id/rename # corps : { "name": "..." }
- Principaux champs de
POST /api/instances:{ "name", "module_name", "port"?, "preset"?, "module_settings"?, "accept_agreements"?: [id] }. En cas de succès, renvoie 201{success, id, ...}, et si le module définit une étape d'installation, l'installation des fichiers du serveur démarre en arrière-plan (§3.5). - Outre le port et les paramètres du module,
PATCH /api/instance/:idaccepte aussi des paramètres du démon comme :auto_restart,restart_on_unknown_exit: redémarrer automatiquement ou non après un crash / un arrêt inconnuextra_args: arguments de lancement supplémentaires (une chaîne ou un tableau de chaînes ;nullles efface)memory_limit_mb: limite de mémoire (Mio, au moins 256 ; les formes"4G"/"4096M"sont acceptées ;null/0signifie aucune limite). S'applique uniquement sous Windows.
- Le renommage exige que le serveur soit arrêté ; un nom déjà utilisé renvoie 409
name_taken.
3.2 Démarrer / arrêter / redémarrer
POST /api/instance/:id/start
POST /api/instance/:id/stop # corps facultatif : { "force": true }
POST /api/instance/:id/restart # corps facultatif : { "force": true }
GET /api/instance/:id/events # historique des arrêts récents
GET /api/server/:name/status # état par nom
- Avant le démarrage, le démon vérifie l'acceptation des conditions et exécute les vérifications du module. Des conditions non acceptées renvoient 409
agreement_required(avecagreements) ; un échec de vérification critique renvoie 409preflight_failed. - L'arrêt envoie la commande d'arrêt propre du jeu, attend le délai du module (30 secondes par défaut) et tue le processus de force s'il est toujours en vie. Avec
force: true, il est tué immédiatement. eventsrenvoie{events: [...]}avec le verdict de l'arrêt (user_stop,in_game_stop,crash,unknown_exit), ses éléments probants, un éventuel redémarrage automatique planifié, etc.
3.3 Console et commandes
GET /api/instance/:id/console?since=<id>&count=<n>
POST /api/instance/:id/stdin # corps : { "command": "say hello" }
POST /api/instance/:id/command # corps : { "command": "<name>", "args"?: {...} }
GET /api/instance/:id/commands # commandes disponibles pour ce serveur
POST /api/instance/:id/rest # jeux REST uniquement (p. ex. Palworld)
POST /api/instance/:id/rcon # nom de compatibilité ; suit le chemin de commande ci-dessous (stdin → REST → RCON)
- Polling de la console : la réponse est
{success, lines: [{id, timestamp, source, content, level}], running, ...}. Avecsince, les lignes dont l'idest supérieur ou égal à cette valeur sont renvoyées ; envoyez donc la prochaine fois le dernieridreçu+ 1. Sanssince, vous obtenez lescountlignes les plus récentes (100 par défaut). Le démon conserve en mémoire les 10 000 dernières lignes par serveur. - Ordre des chemins de commande : stdin → REST → RCON. Les commandes vont d'abord à la console du serveur (stdin), et les jeux qui ne prennent en charge que REST, comme Palworld, passent par REST. RCON n'est utilisé que pour un jeu dont le module déclare
supported = ["rcon"](ni console ni API REST) ; le démon attribue alors à chaque instance son propre port et un mot de passe aléatoire, et se connecte uniquement en loopback (127.0.0.1). Sinon,/rconest un chemin conservé uniquement de nom pour les anciens clients et envoie vers stdin. Les serveurs sans chemin de commande renvoient 409no_command_path. /stdinrenvoie 409stdin_not_supportedsi le module ne prend pas en charge stdin./commandexécute une commande définie par le module ; si le serveur est arrêté, renvoie 409server_not_running.
3.4 Paramètres, conditions, vérifications
POST /api/instance/:id/launch-preview # corps : { "settings"?: {...}, "extra_args"?: "..." }
POST /api/instance/:id/agreements # corps : { "accept": ["eula"] }
GET /api/instance/:id/properties # lire le fichier de configuration du jeu
PUT /api/instance/:id/properties # corps : { "settings": {...} }
POST /api/instance/:id/validate # vérification du serveur
POST /api/instance/:id/diagnose # diagnostic des logs
launch-previewcalcule la ligne de commande de lancement sans démarrer le serveur. Exemple de réponse :{success: true, has_launch_args, command_line, program, args, extra_args, errors: [...]}. Les valeurs de mot de passe sont masquées sous la forme***. Si le module ne déclare aucun argument de lancement, renvoiehas_launch_args: false.agreementsenregistre l'acceptation des conditions déclarées par le module (p. ex.eulade Minecraft). Cela ne fonctionne qu'en local ; les requêtes de sources distantes (Discord, etc.) reçoivent 403agreement_local_only. Les id non déclarés reçoivent 400invalid_format.
3.5 Progression de l'installation et mises à jour du serveur de jeu
GET /api/provision-progress/:name # :name = nom de l'instance
DELETE /api/provision-progress/:name # fermer un état de progression en échec
GET /api/instance/:id/check-update
POST /api/instance/:id/apply-update
Exemple de réponse de provision-progress :
{
"active": true,
"step": 2,
"total": 5,
"label": "...",
"message": "...",
"percent": 40,
"done": false,
"error": null
}
Lorsque rien n'est en cours, renvoie {"active": false}. Un état de progression réussi est effacé automatiquement au bout de 5 secondes ; un état en échec reste jusqu'à ce que vous le fermiez avec DELETE (si le serveur était en cours de création, il est alors annulé). La progression est aussi disponible sous provision.progress sur /api/events.
apply-update renvoie 409 server_running si le serveur tourne. Une sauvegarde est effectuée avant la mise à jour (pour les modules qui prennent en charge les sauvegardes).
3.6 Sauvegardes et tâches planifiées
GET /api/instance/:id/backups # { success, backups: [{ name, kind, created, size }] }
POST /api/instance/:id/backups # sauvegarder maintenant
DELETE /api/instance/:id/backups/:name
POST /api/instance/:id/backups/:name/restore # le serveur doit être arrêté
GET /api/instance/:id/schedule
PUT /api/instance/:id/schedule # corps : { "schedule": [...], "backup_keep"?: 10 }
kinddes sauvegardes :manual,scheduled,pre-update,pre-restore. Si le module ne prend pas en charge les sauvegardes, vous obtenez 400backup_unsupported; s'il n'y a encore rien à sauvegarder, 400nothing_to_back_up.- La restauration renvoie 409
server_runningsi le serveur tourne, et l'état actuel est sauvegardé enpre-restoreavant la restauration. - La forme d'une tâche planifiée :
{ "action": "restart", "at": "05:00", "warn_minutes": [10, 5, 1], "enabled": true }
action vaut backup | restart | announce | update, et vous utilisez exactement l'un de every_minutes (toutes les N minutes) et at (chaque jour à HH:MM). announce nécessite un message, et warn_minutes ne s'applique qu'à restart et update. Les tâches invalides renvoient 400 validation_failed (avec details).
4. Modules
GET /api/modules # modules installés
POST /api/modules/refresh # relire le dossier des modules
GET /api/module/:name # métadonnées du module
GET /api/module/:name/versions # versions installables du serveur de jeu
GET /api/module/:name/locales
GET /api/modules/manifest # catalogue des modules installables
POST /api/modules/manifest/:id/install # installer un module depuis le catalogue
DELETE /api/modules/:id # supprimer un module
Le catalogue des modules provient de la liste de versions signée, et les fichiers téléchargés ne sont installés qu'après vérification de leur hachage.
5. Extensions
GET /api/extensions # liste avec état d'installation/activation
POST /api/extensions/rescan
GET /api/extensions/manifest # catalogue des extensions installables
GET /api/extensions/updates
POST /api/extensions/:id/install
DELETE /api/extensions/:id
POST /api/extensions/:id/enable # exécute le hook daemon.startup de façon asynchrone
POST /api/extensions/:id/disable
GET /api/extensions/:id/config
PUT /api/extensions/:id/config
GET /api/extensions/:id/gui # bundle GUI (JavaScript UMD)
GET /api/extensions/:id/gui/styles # CSS
GET /api/extensions/:id/i18n/:locale # ko / en / ja / ...
Les erreurs des routes d'extensions utilisent la forme {success: false, error, error_code, ...}.
6. Paramètres
GET /api/config/gui
PUT /api/config/gui # JSON partiel (fusion superficielle)
GET /api/config/bot
PUT /api/config/bot # paramètres du bot comme le préfixe et les alias (JSON partiel)
GET /api/system/metrics # CPU, mémoire, disque, utilisation par serveur
Tous les paramètres utilisateur sont stockés par espace de noms dans un seul fichier config.json du dossier de données. Le démon synchronise les paramètres du bot avec le relais. Le bot Discord lui-même tourne sur le relais cloud ; le démon n'a donc pas d'API pour démarrer ou arrêter un processus de bot.
7. Mises à jour
GET /api/updates/status # état actuel et versions par composant
POST /api/updates/check # vérifier les mises à jour maintenant
POST /api/updates/download # corps facultatif : { "components": [...] }
GET /api/updates/download/progress
POST /api/updates/apply # corps facultatif : { "components": [...] }
POST /api/updates/launch-updater # appliquer via l'installateur (le démon s'arrête)
GET /api/updates/config
PUT /api/updates/config
Les informations de mise à jour proviennent de la liste de versions signée. Les composants dont les fichiers en cours d'exécution doivent être remplacés sont signalés dans la réponse de apply comme nécessitant une application séparée ; appeler launch-updater lance l'installateur (saba-chan-installer --apply), qui arrête le démon, remplace les fichiers et ne relance que ce qui a changé. Ces routes répondent sous la forme {ok: ...}.
8. Appairage du relais cloud
Pour le flux d'appairage GUI ↔ serveur relais. Voir la page Bot Discord pour le déroulement détaillé.
POST /api/relay/pair/initiate # émettre un code d'appairage (transmis au relais)
GET /api/relay/pair/:code/status # vérifier par polling si l'appairage est terminé
GET /api/relay/agent # état de l'agent relais
POST /api/relay/agent/start
POST /api/relay/agent/stop
DELETE /api/config/node-token # supprimer le jeton de nœud de ce PC (arrête l'agent)
Une fois l'appairage terminé (status: "claimed"), le démon enregistre automatiquement le jeton de nœud et reconnecte l'agent relais avec le nouveau jeton. Le démon se charge de l'authentification auprès du relais ; les clients n'ont donc pas à s'en occuper.
9. Exemple d'authentification (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> est l'id de la réponse de GET /api/servers ou de GET /api/instances.
10. Compatibilité des versions
- Cette API est classée comme IPC privée. Ce n'est pas un contrat public ; les chemins et les schémas peuvent donc changer même dans des versions mineures.
- Si vous distribuez un client personnalisé, vérifiez la version du démon (
versiondeGET /health) et traitez-la avec prudence.
En cas de problème, rendez-vous sur Dépannage.