Referência da REST API
A API HTTP exposta pelo daemon do Saba-chan. Esquema de autenticação e catálogo dos principais endpoints.
Referência da REST API
O daemon do Saba-chan (saba-core) expõe uma API HTTP REST em 127.0.0.1:57474. A GUI e a CLI chamam apenas esta API, e os comandos do Discord que chegam pelo relay em nuvem são processados pelas mesmas funções dentro do daemon. Você pode criar um cliente próprio com base no mesmo contrato.
Esta referência resume as rotas de que um usuário ou integrador provavelmente vai precisar, extraídas das definições de rota do daemon (src/ipc/). Algumas rotas internas foram omitidas, e os esquemas de campos podem mudar, então consulte o código para ver a versão mais recente.
1. Básico
- URL base:
http://127.0.0.1:57474(padrão). Pode ser alterada pela variável de ambienteSABA_IPC_PORTou porgui.ipcPortnoconfig.json(passa a valer depois que o daemon reinicia). - Endereço de bind: fixo em
127.0.0.1, então não é acessível de fora. Requisições cujo cabeçalhoHostnão seja de loopback (127.0.0.1,localhost,::1) recebem 403. - Autenticação: toda requisição, exceto
/health, precisa do cabeçalhoX-Saba-Token. O daemon gera um novo token a cada início e o grava no arquivo.ipc_tokenda pasta de dados (Windows:%APPDATA%\saba-chan\.ipc_token). Um token ausente ou errado recebe 401 sem corpo. - Content-Type: os corpos das requisições são
application/json. A maioria das respostas também é JSON (pacotes de GUI de extensões, ícones etc. são exceções). - Formato de erro: varia por rota. Os formatos comuns são
{"error": "...", "error_code": "..."},{"success": false, "error": ..., "error_code": ...}e{"ok": false, "error": ...}. Algumas rotas devolvem HTTP 200 comok:falseem caso de falha, então confira também o corpo.
2. Verificação de saúde e daemon
GET /health # não exige token
GET /api/version
GET /api/diagnostics
GET /api/events # fluxo de eventos (SSE)
POST /api/daemon/shutdown
/health:{"ok": true, "version": "x.y.z", "pid": 1234, "token": "valid" | "invalid" | "missing"}.tokensó diz se oX-Saba-Tokenque você enviou está correto; ele nunca revela o valor./api/version:{version, components: {...}}(versões do núcleo, dos módulos e das extensões)./api/events: Server-Sent Events. Os principais tipos sãoinstance.exit(saída do servidor / veredito de crash),backup.done,update.available,schedule.warn,provision.progresseaction.run. Ao reconectar, você pode recuperar os eventos perdidos com o cabeçalhoLast-Event-IDou com?since=<n>./api/daemon/shutdown: desliga o daemon.
3. Servidores (instâncias)
O Saba-chan gerencia cada servidor como uma instância, identificada por um UUID (id).
3.1 Listar, criar, atualizar, excluir
GET /api/servers # lista de servidores + estado de execução
GET /api/instances # lista de instâncias
POST /api/instances # cria
PUT /api/instances/reorder # corpo: { "order": [id, ...] }
GET /api/instance/:id # detalhes (+ estado de aceitação dos termos em agreements)
PATCH /api/instance/:id # altera configurações (objeto chave-valor)
DELETE /api/instance/:id # exclui
POST /api/instance/:id/rename # corpo: { "name": "..." }
- Principais campos de
POST /api/instances:{ "name", "module_name", "port"?, "preset"?, "module_settings"?, "version"?, "working_dir"?, "managed_start"?, "accept_agreements"?: [id] }. Seversionficar vazio, vale a versão mais recente;working_diré uma pasta vazia (caminho absoluto) onde o novo servidor será instalado;managed_start: falseindica execução gerenciada por você mesmo. Valores de instalação fora do que o módulo define eminstall_optionsdão 400not_installable. Em caso de sucesso, devolve 201{success, id, ...}e, se o módulo definir uma etapa de instalação, a instalação dos arquivos do servidor começa em segundo plano (§3.5). - Além da porta e das configurações do módulo,
PATCH /api/instance/:idtambém aceita configurações do daemon, como:auto_restart,restart_on_unknown_exit: se deve reiniciar automaticamente após um crash / uma saída desconhecidaextra_args: argumentos de inicialização extras (uma string ou um array de strings;nullos limpa)memory_limit_mb: limite de memória (MiB, no mínimo 256; as formas"4G"/"4096M"são aceitas;null/0significa sem limite). Vale apenas no Windows.
- Renomear exige que o servidor esteja parado; um nome já em uso devolve 409
name_taken.
3.2 Iniciar / parar / reiniciar
POST /api/instance/:id/start
POST /api/instance/:id/stop # corpo opcional: { "force": true }
POST /api/instance/:id/restart # corpo opcional: { "force": true }
GET /api/instance/:id/events # histórico recente de saídas
GET /api/server/:name/status # status pelo nome
- Antes de iniciar, o daemon confere a aceitação dos termos e executa as verificações do módulo. Termos não aceitos devolvem 409
agreement_required(comagreements); uma falha crítica na verificação devolve 409preflight_failed. - A parada envia o comando de parada graciosa do jogo, aguarda o tempo limite do módulo (30 segundos por padrão) e finaliza o processo à força se ele ainda estiver vivo. Com
force: true, ele é finalizado imediatamente. eventsdevolve{events: [...]}com o veredito da saída (user_stop,in_game_stop,crash,unknown_exit), as evidências, um eventual reinício automático agendado e assim por diante.
3.3 Console e comandos
GET /api/instance/:id/console?since=<id>&count=<n>
POST /api/instance/:id/stdin # corpo: { "command": "say hello" }
POST /api/instance/:id/command # corpo: { "command": "<name>", "args"?: {...} }
GET /api/instance/:id/commands # comandos disponíveis para este servidor
POST /api/instance/:id/rest # jogos só com REST (por exemplo, Palworld)
POST /api/instance/:id/rcon # nome de compatibilidade; segue o caminho de comandos abaixo (stdin → REST → RCON)
- Consulta ao console: a resposta é
{success, lines: [{id, timestamp, source, content, level}], running, ...}. Comsince, são devolvidas as linhas cujoidé maior ou igual a ele, então envie da próxima vez o últimoidrecebido+ 1. Semsince, você recebe ascountlinhas mais recentes (padrão 100). O daemon mantém em memória as últimas 10.000 linhas de cada servidor. - Ordem dos caminhos de comando: stdin → REST → RCON. Os comandos vão primeiro para o console do servidor (stdin), e jogos que só suportam REST, como o Palworld, passam pela REST. O RCON só é usado para um jogo cujo módulo declara
supported = ["rcon"](sem console e sem REST API); nesse caso o daemon atribui a cada instância sua própria porta e uma senha aleatória e conecta apenas por loopback (127.0.0.1). Nos demais casos,/rconé um caminho mantido só pelo nome para clientes antigos e envia ao stdin. Servidores sem caminho de comando devolvem 409no_command_path. /stdindevolve 409stdin_not_supportedse o módulo não suportar stdin./commandexecuta um comando definido pelo módulo; se o servidor estiver parado, devolve 409server_not_running.
3.4 Configurações, termos, verificações
POST /api/instance/:id/launch-preview # corpo: { "settings"?: {...}, "extra_args"?: "..." }
POST /api/instance/:id/agreements # corpo: { "accept": ["eula"] }
GET /api/instance/:id/properties # lê o arquivo de configuração do jogo
PUT /api/instance/:id/properties # corpo: { "settings": {...} }
POST /api/instance/:id/validate # verificação do servidor
POST /api/instance/:id/diagnose # diagnóstico de log
launch-previewcalcula a linha de comando de inicialização sem iniciar o servidor. Exemplo de resposta:{success: true, has_launch_args, command_line, program, args, extra_args, errors: [...]}. Os valores de senha são mascarados como***. Se o módulo não declarar argumentos de inicialização, devolvehas_launch_args: false.agreementsregistra a aceitação dos termos que o módulo declara (por exemplo,eulado Minecraft). Funciona apenas localmente; requisições de origens remotas (Discord etc.) recebem 403agreement_local_only. Ids não declarados recebem 400invalid_format.
3.5 Progresso da instalação e atualizações do servidor de jogo
GET /api/provision-progress/:name # :name = nome da instância
DELETE /api/provision-progress/:name # dispensa um estado de progresso com falha
GET /api/instance/:id/check-update
POST /api/instance/:id/apply-update
Exemplo de resposta de provision-progress:
{
"active": true,
"step": 2,
"total": 5,
"label": "...",
"message": "...",
"percent": 40,
"done": false,
"error": null
}
Quando nada está em andamento, devolve {"active": false}. Um estado de progresso bem-sucedido é limpo automaticamente após 5 segundos; um com falha permanece até você dispensá-lo com DELETE (se o servidor estava sendo criado, ele é revertido nesse momento). O progresso também está disponível como provision.progress em /api/events.
apply-update devolve 409 server_running se o servidor estiver rodando. Um backup é feito antes da atualização (em módulos com suporte a backup).
3.6 Backups e tarefas agendadas
GET /api/instance/:id/backups # { success, backups: [{ name, kind, created, size }] }
POST /api/instance/:id/backups # faz backup agora
DELETE /api/instance/:id/backups/:name
POST /api/instance/:id/backups/:name/restore # o servidor precisa estar parado
GET /api/instance/:id/schedule
PUT /api/instance/:id/schedule # corpo: { "schedule": [...], "backup_keep"?: 10 }
kinddo backup:manual,scheduled,pre-update,pre-restore. Se o módulo não suportar backups, você recebe 400backup_unsupported; se ainda não houver nada para fazer backup, 400nothing_to_back_up.- A restauração devolve 409
server_runningse o servidor estiver rodando, e o estado atual é salvo comopre-restoreantes da restauração. - O formato de uma tarefa agendada:
{ "action": "restart", "at": "05:00", "warn_minutes": [10, 5, 1], "enabled": true }
action é backup | restart | announce | update, e você usa exatamente um entre every_minutes (a cada N minutos) e at (diariamente às HH:MM). announce precisa de um message, e warn_minutes só se aplica a restart e update. Tarefas inválidas devolvem 400 validation_failed (com details).
4. Módulos
GET /api/modules # módulos instalados
POST /api/modules/refresh # relê a pasta de módulos
GET /api/module/:name # metadados do módulo
GET /api/module/:name/versions # versões instaláveis do servidor de jogo
GET /api/module/:name/locales
GET /api/modules/manifest # catálogo de módulos instaláveis
POST /api/modules/manifest/:id/install # instala um módulo a partir do catálogo
DELETE /api/modules/:id # remove um módulo
O catálogo de módulos vem da lista de releases assinada, e os arquivos baixados só são instalados depois que o hash deles é conferido.
5. Extensões
GET /api/extensions # lista com estado de instalação/ativação
POST /api/extensions/rescan
GET /api/extensions/manifest # catálogo de extensões instaláveis
GET /api/extensions/updates
POST /api/extensions/:id/install
DELETE /api/extensions/:id
POST /api/extensions/:id/enable # executa o hook daemon.startup de forma assíncrona
POST /api/extensions/:id/disable
GET /api/extensions/:id/config
PUT /api/extensions/:id/config
GET /api/extensions/:id/gui # pacote da GUI (JavaScript UMD)
GET /api/extensions/:id/gui/styles # CSS
GET /api/extensions/:id/i18n/:locale # ko / en / ja / ...
Os erros das rotas de extensões usam o formato {success: false, error, error_code, ...}.
6. Configurações
GET /api/config/gui
PUT /api/config/gui # JSON parcial (merge raso)
GET /api/config/bot
PUT /api/config/bot # configurações do bot, como prefixo e apelidos (JSON parcial)
GET /api/system/metrics # CPU, memória, disco, uso por servidor
Todas as configurações do usuário são guardadas por namespace em um único arquivo config.json na pasta de dados. O daemon sincroniza as configurações do bot com o relay. O próprio bot do Discord roda no relay em nuvem, então o daemon não tem API para iniciar ou parar um processo de bot.
7. Atualizações
GET /api/updates/status # estado atual e versões por componente
POST /api/updates/check # verifica atualizações agora
POST /api/updates/download # corpo opcional: { "components": [...] }
GET /api/updates/download/progress
POST /api/updates/apply # corpo opcional: { "components": [...] }
POST /api/updates/launch-updater # aplica pelo instalador (o daemon para)
GET /api/updates/config
PUT /api/updates/config
As informações de atualização vêm da lista de releases assinada. Componentes cujos arquivos em execução precisam ser substituídos são marcados na resposta de apply como precisando de aplicação separada; chamar launch-updater faz o instalador (saba-chan-installer --apply) parar e substituir o daemon e subir de novo só o que mudou. Essas rotas respondem no formato {ok: ...}.
8. Pareamento com o relay em nuvem
Para o fluxo de pareamento GUI ↔ servidor de relay. Veja a página Bot do Discord para o fluxo detalhado.
POST /api/relay/pair/initiate # emite um código de pareamento (repassado ao relay)
GET /api/relay/pair/:code/status # consulta se o pareamento foi concluído
GET /api/relay/agent # status do agente de relay
POST /api/relay/agent/start
POST /api/relay/agent/stop
DELETE /api/config/node-token # apaga o token de nó deste PC (para o agente)
Quando o pareamento é concluído (status: "claimed"), o daemon salva o token de nó automaticamente e reconecta o agente de relay com o novo token. O daemon cuida da autenticação com o relay, então os clientes não precisam lidar com isso.
9. Exemplo de autenticação (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> é o id da resposta de GET /api/servers ou de GET /api/instances.
10. Compatibilidade de versões
- Esta API é classificada como IPC privado. Ela não é um contrato público, então caminhos e esquemas podem mudar até em versões menores.
- Se você distribuir um cliente próprio, confira a versão do daemon (
versiondeGET /health) e trate isso de forma conservadora.
Se tiver problemas, vá para Solução de problemas.