REST API 레퍼런스
사바쨩 데몬이 노출하는 HTTP API. 인증 방식과 주요 엔드포인트 카탈로그.
REST API 레퍼런스
사바쨩 데몬(saba-core)은 127.0.0.1:57474에서 HTTP REST API를 제공합니다. GUI·CLI는 이 API만 호출하며, 서버쨩으로 들어온 디스코드 명령도 데몬 안에서 같은 기능을 거쳐 처리됩니다. 커스텀 클라이언트도 동일한 계약으로 만들 수 있습니다.
이 레퍼런스는 데몬의 라우트 정의(src/ipc/)에서 사용자·연동 개발자가 쓸 만한 라우트를 추려 요약한 것입니다. 내부용 라우트는 일부 생략했고, 필드 스키마는 바뀔 수 있으므로 최신 내용은 코드를 참조하세요.
1. 기본 사항
- 베이스 URL:
http://127.0.0.1:57474(기본).SABA_IPC_PORT환경변수 또는config.json의gui.ipcPort로 바꿀 수 있습니다(데몬 재시작 후 적용). - 바인딩 주소:
127.0.0.1로 고정되어 외부에서는 접근할 수 없습니다.Host헤더가 루프백(127.0.0.1,localhost,::1)이 아니면 403을 돌려줍니다. - 인증:
/health를 제외한 모든 요청에X-Saba-Token헤더가 필요합니다. 토큰은 데몬이 시작할 때마다 새로 만들어 데이터 폴더의.ipc_token파일(Windows:%APPDATA%\saba-chan\.ipc_token)에 씁니다. 토큰이 없거나 틀리면 본문 없는 401입니다. - Content-Type: 요청 본문은
application/json입니다. 응답도 대부분 JSON입니다(익스텐션 GUI 번들·아이콘 등은 예외). - 에러 형식: 라우트에 따라 형식이 다릅니다. 대표적으로
{"error": "...", "error_code": "..."},{"success": false, "error": ..., "error_code": ...},{"ok": false, "error": ...}가 쓰입니다. 일부 라우트는 실패해도 HTTP 200에ok:false를 돌려주므로 본문도 확인하세요.
2. 헬스체크 & 데몬
GET /health # 토큰 불필요
GET /api/version
GET /api/diagnostics
GET /api/events # 이벤트 스트림 (SSE)
POST /api/daemon/shutdown
/health:{"ok": true, "version": "x.y.z", "pid": 1234, "token": "valid" | "invalid" | "missing"}.token은 보낸X-Saba-Token이 맞는지만 알려 주며 값은 드러내지 않습니다./api/version:{version, components: {...}}(코어·모듈·익스텐션 버전)./api/events: Server-Sent Events. 주요 종류는instance.exit(서버 종료·크래시 판정),backup.done,update.available,schedule.warn,provision.progress,action.run입니다. 끊겼다가 다시 붙을 때Last-Event-ID헤더나?since=<n>으로 놓친 이벤트를 받을 수 있습니다./api/daemon/shutdown: 데몬을 종료합니다.
3. 서버(인스턴스)
사바쨩은 서버 하나를 인스턴스로 관리합니다. 인스턴스는 UUID(id)로 가리킵니다.
3.1 목록과 생성·수정·삭제
GET /api/servers # 서버 목록 + 실행 상태
GET /api/instances # 인스턴스 목록
POST /api/instances # 생성
POST /api/instances/check # 만들기 전 확인 (이름·폴더·포트 겹침, 아무것도 만들지 않음)
PUT /api/instances/reorder # body: { "order": [id, ...] }
GET /api/instance/:id # 상세 (+ 약관 동의 상태 agreements)
PATCH /api/instance/:id # 설정 변경 (키-값 객체)
DELETE /api/instance/:id # 삭제
POST /api/instance/:id/rename # body: { "name": "..." }
POST /api/instances주요 필드:{ "name", "module_name", "port"?, "preset"?, "module_settings"?, "version"?, "working_dir"?, "managed_start"?, "accept_agreements"?: [id] }.version을 비우면 최신 버전,working_dir은 새 서버를 설치할 빈 폴더(절대 경로),managed_start: false는 직접 관리 실행입니다. 모듈이install_options로 정한 값 밖의 설치 값은 400not_installable입니다. 성공 시 201{success, id, ...}이며, 모듈이 설치를 정의하면 서버 파일 설치가 백그라운드로 시작됩니다(§3.5).PATCH /api/instance/:id에는 포트, 모듈 설정 외에 다음 같은 데몬 설정도 넣을 수 있습니다.auto_restart,restart_on_unknown_exit: 크래시·원인 모를 종료 뒤 자동 재시작 여부extra_args: 추가 실행 인자 (문자열 또는 문자열 배열,null이면 비움)memory_limit_mb: 메모리 상한(MiB, 256 이상."4G"·"4096M"형식도 허용,null·0은 제한 없음). Windows에서만 적용됩니다.
- 이름 변경은 서버가 꺼져 있어야 하며, 이미 쓰는 이름이면 409
name_taken입니다.
3.2 시작 / 정지 / 재시작
POST /api/instance/:id/start
POST /api/instance/:id/stop # 선택 body: { "force": true }
POST /api/instance/:id/restart # 선택 body: { "force": true }
GET /api/instance/:id/events # 최근 종료 이력
GET /api/instance/:id/status # 상태 조회
- 시작 전에 데몬이 약관 동의와 모듈 점검을 확인합니다. 동의하지 않은 약관이 있으면 409
agreement_required(agreements포함), 점검에서 치명적 문제가 나오면 409preflight_failed입니다. - 정지는 게임의 정상 종료 명령을 보내고 모듈이 정한 시간(기본 30초)만큼 기다린 뒤, 그래도 살아 있으면 강제 종료합니다.
force: true면 바로 강제 종료합니다. events는{events: [...]}로, 종료 판정(user_stop,in_game_stop,crash,unknown_exit)과 근거, 자동 재시작 예정 등을 담습니다.
3.3 콘솔과 명령
GET /api/instance/:id/console?since=<id>&count=<n>
POST /api/instance/:id/stdin # body: { "command": "say hello" }
POST /api/instance/:id/command # body: { "command": "<이름>", "args"?: {...} }
GET /api/instance/:id/commands # 이 서버에서 쓸 수 있는 명령 목록
POST /api/instance/:id/rest # REST 전용 게임(예: 팰월드)
POST /api/instance/:id/rcon # 호환용 이름. 아래 명령 경로(stdin → REST → RCON)를 따름
- 콘솔 폴링: 응답은
{success, lines: [{id, timestamp, source, content, level}], running, ...}입니다.since를 주면 그id이상의 줄을 돌려주므로, 다음 요청에는 마지막으로 받은id + 1을 보내세요.since없이 부르면 최근count줄(기본 100)을 줍니다. 데몬은 서버마다 최근 1만 줄을 메모리에 둡니다. - 명령 경로 순서는 stdin → REST → RCON입니다. 명령은 먼저 서버 콘솔(stdin)로 가고, 팰월드처럼 REST만 지원하는 게임은 REST로 갑니다. RCON은 모듈이
supported = ["rcon"]으로 선언한 게임(콘솔도 REST API도 없는 게임)에만 쓰이며, 이때 데몬이 인스턴스마다 포트와 무작위 비밀번호를 정하고 루프백(127.0.0.1)으로만 연결합니다. 그 밖의 경우/rcon은 예전 클라이언트를 위해 이름만 남은 경로로, stdin으로 보냅니다. 명령 경로가 없는 서버면 409no_command_path입니다. /stdin은 모듈이 stdin을 지원하지 않으면 409stdin_not_supported입니다./command는 모듈이 정의한 명령을 실행하고, 서버가 꺼져 있으면 409server_not_running입니다.
3.4 설정·약관·점검
POST /api/instance/:id/launch-preview # body: { "settings"?: {...}, "extra_args"?: "..." }
POST /api/instance/:id/agreements # body: { "accept": ["eula"] }
GET /api/instance/:id/properties # 게임 설정 파일 읽기
PUT /api/instance/:id/properties # body: { "settings": {...} }
POST /api/instance/:id/validate # 서버 점검
POST /api/instance/:id/diagnose # 로그 진단
launch-preview는 서버를 켜지 않고 실행 명령줄을 계산합니다. 응답 예:{success: true, has_launch_args, command_line, program, args, extra_args, errors: [...]}. 비밀번호 값은***로 가립니다. 모듈이 실행 인자를 선언하지 않았으면has_launch_args: false입니다.agreements는 모듈이 선언한 약관(예: 마인크래프트eula)에 동의를 기록합니다. 로컬에서만 할 수 있고, 원격(디스코드 등)에서 오면 403agreement_local_only입니다. 선언되지 않은 id는 400invalid_format입니다.
3.5 설치 진행률과 게임 서버 업데이트
GET /api/provision-progress/:name # :name = 인스턴스 이름
DELETE /api/provision-progress/:name # 실패한 진행 상태 닫기
GET /api/instance/:id/check-update
POST /api/instance/:id/apply-update
provision-progress 응답 예:
{
"active": true,
"step": 2,
"total": 5,
"label": "...",
"message": "...",
"percent": 40,
"done": false,
"error": null
}
진행 중인 작업이 없으면 {"active": false}입니다. 성공한 진행 상태는 5초 뒤 자동으로 정리되고, 실패한 상태는 DELETE로 닫을 때까지 남습니다(새로 만들던 서버였다면 이때 롤백됩니다). 진행률은 /api/events의 provision.progress로도 받을 수 있습니다.
apply-update는 서버가 켜져 있으면 409 server_running입니다. 업데이트 전에 백업을 먼저 만듭니다(백업을 지원하는 모듈).
3.6 백업과 예약 작업
GET /api/instance/:id/backups # { success, backups: [{ name, kind, created, size }] }
POST /api/instance/:id/backups # 지금 백업
DELETE /api/instance/:id/backups/:name
POST /api/instance/:id/backups/:name/restore # 서버가 꺼져 있어야 함
GET /api/instance/:id/schedule
PUT /api/instance/:id/schedule # body: { "schedule": [...], "backup_keep"?: 10 }
- 백업
kind:manual,scheduled,pre-update,pre-restore. 모듈이 백업을 지원하지 않으면 400backup_unsupported, 아직 백업할 파일이 없으면 400nothing_to_back_up입니다. - 복원은 서버가 켜져 있으면 409
server_running이며, 복원 전에 지금 상태를pre-restore로 백업합니다. - 예약 작업 한 건의 형식:
{ "action": "restart", "at": "05:00", "warn_minutes": [10, 5, 1], "enabled": true }
action은 backup | restart | announce | update이고, every_minutes(N분마다)와 at(매일 HH:MM) 중 하나만 씁니다. announce에는 message가 필요하고, warn_minutes는 restart·update에만 쓸 수 있습니다. 규칙에 맞지 않으면 400 validation_failed(details 포함)입니다.
4. 모듈
GET /api/modules # 설치된 모듈 목록
POST /api/modules/refresh # 모듈 폴더 다시 읽기
GET /api/module/:name # 모듈 메타데이터
GET /api/module/:name/versions # 설치 가능한 게임 서버 버전
GET /api/module/:name/locales
GET /api/modules/manifest # 설치할 수 있는 모듈 카탈로그
POST /api/modules/manifest/:id/install # 카탈로그에서 모듈 설치
DELETE /api/modules/:id # 모듈 제거
모듈 카탈로그는 서명된 릴리스 목록에서 오며, 받은 파일은 해시를 확인한 뒤 설치합니다.
5. 익스텐션
GET /api/extensions # 설치/활성 상태 포함 목록
POST /api/extensions/rescan
GET /api/extensions/manifest # 설치할 수 있는 익스텐션 카탈로그
GET /api/extensions/updates
POST /api/extensions/:id/install
DELETE /api/extensions/:id
POST /api/extensions/:id/enable # daemon.startup 훅 비동기 실행
POST /api/extensions/:id/disable
GET /api/extensions/:id/config
PUT /api/extensions/:id/config
GET /api/extensions/:id/gui # GUI 번들 (UMD JavaScript)
GET /api/extensions/:id/gui/styles # CSS
GET /api/extensions/:id/i18n/:locale # ko / en / ja / ...
익스텐션 라우트의 에러는 {success: false, error, error_code, ...} 형식입니다.
6. 설정
GET /api/config/gui
PUT /api/config/gui # 부분 JSON (얕은 머지)
GET /api/config/bot
PUT /api/config/bot # 접두사·별명 등 봇 설정 (부분 JSON)
GET /api/system/metrics # CPU·메모리·디스크·서버별 사용량
모든 사용자 설정은 데이터 폴더의 config.json 한 파일에 네임스페이스별로 저장됩니다. 봇 설정은 데몬이 서버쨩에 동기화합니다. 디스코드 봇 자체는 서버쨩에서 돌기 때문에 데몬에 봇 프로세스를 시작/정지하는 API는 없습니다.
7. 업데이트
GET /api/updates/status # 현재 상태와 구성요소별 버전
POST /api/updates/check # 지금 업데이트 확인
POST /api/updates/download # 선택 body: { "components": [...] }
GET /api/updates/download/progress
POST /api/updates/apply # 선택 body: { "components": [...] }
POST /api/updates/launch-updater # 설치 프로그램으로 적용 (데몬 종료 동반)
GET /api/updates/config
PUT /api/updates/config
업데이트 정보는 서명된 릴리스 목록에서 옵니다. 실행 중인 파일을 바꿔야 하는 구성요소는 apply 응답에 별도 적용이 필요하다고 표시되며, launch-updater를 부르면 설치 프로그램(saba-chan-installer --apply)이 데몬을 종료·교체하고 바뀐 것만 다시 띄웁니다. 이 라우트들의 응답은 {ok: ...} 형식입니다.
8. 서버쨩 페어링
GUI ↔ 서버쨩 페어링 흐름용입니다. 자세한 흐름은 디스코드 봇 문서를 참고하세요.
POST /api/relay/pair/initiate # 페어링 코드 발급 (서버쨩으로 전달)
GET /api/relay/pair/:code/status # 페어링 완료 여부 폴링
GET /api/relay/agent # 서버쨩 에이전트 상태
POST /api/relay/agent/start
POST /api/relay/agent/stop
DELETE /api/config/node-token # 이 PC의 노드 토큰 삭제 (에이전트 정지)
페어링이 완료되면(status: "claimed") 데몬이 노드 토큰을 자동으로 저장하고 서버쨩 에이전트를 새 토큰으로 다시 연결합니다. 서버쨩 인증은 데몬이 처리하므로 클라이언트가 직접 다룰 필요는 없습니다.
9. 인증 예제 (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>는 GET /api/servers 또는 GET /api/instances 응답의 id입니다.
10. 버전 호환성
- 이 API는 프라이빗 IPC로 분류됩니다. 공용 계약이 아니므로 마이너 버전에서도 경로/스키마가 바뀔 수 있습니다.
- 커스텀 클라이언트를 배포한다면 데몬 버전을 확인(
GET /health의version)하고 보수적으로 다루세요.
문제가 있다면 문제 해결로.