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 ambiente SABA_IPC_PORT ou por gui.ipcPort no config.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çalho Host não seja de loopback (127.0.0.1, localhost, ::1) recebem 403.
  • Autenticação: toda requisição, exceto /health, precisa do cabeçalho X-Saba-Token. O daemon gera um novo token a cada início e o grava no arquivo .ipc_token da 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 com ok:false em 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"}. token só diz se o X-Saba-Token que 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ão instance.exit (saída do servidor / veredito de crash), backup.done, update.available, schedule.warn, provision.progress e action.run. Ao reconectar, você pode recuperar os eventos perdidos com o cabeçalho Last-Event-ID ou 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] }. Se version ficar vazio, vale a versão mais recente; working_dir é uma pasta vazia (caminho absoluto) onde o novo servidor será instalado; managed_start: false indica execução gerenciada por você mesmo. Valores de instalação fora do que o módulo define em install_options dão 400 not_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/:id também aceita configurações do daemon, como:
    • auto_restart, restart_on_unknown_exit: se deve reiniciar automaticamente após um crash / uma saída desconhecida
    • extra_args: argumentos de inicialização extras (uma string ou um array de strings; null os limpa)
    • memory_limit_mb: limite de memória (MiB, no mínimo 256; as formas "4G"/"4096M" são aceitas; null/0 significa 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 (com agreements); uma falha crítica na verificação devolve 409 preflight_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.
  • events devolve {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, ...}. Com since, são devolvidas as linhas cujo id é maior ou igual a ele, então envie da próxima vez o último id recebido + 1. Sem since, você recebe as count linhas 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 409 no_command_path.
  • /stdin devolve 409 stdin_not_supported se o módulo não suportar stdin.
  • /command executa um comando definido pelo módulo; se o servidor estiver parado, devolve 409 server_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-preview calcula 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, devolve has_launch_args: false.
  • agreements registra a aceitação dos termos que o módulo declara (por exemplo, eula do Minecraft). Funciona apenas localmente; requisições de origens remotas (Discord etc.) recebem 403 agreement_local_only. Ids não declarados recebem 400 invalid_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 }
  • kind do backup: manual, scheduled, pre-update, pre-restore. Se o módulo não suportar backups, você recebe 400 backup_unsupported; se ainda não houver nada para fazer backup, 400 nothing_to_back_up.
  • A restauração devolve 409 server_running se o servidor estiver rodando, e o estado atual é salvo como pre-restore antes 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 (version de GET /health) e trate isso de forma conservadora.

Se tiver problemas, vá para Solução de problemas.