팰월드 REST API 명령어 전체 정리
작성일 2026-07-26 · SameOS Tools
팰월드 전용 서버에는 게임에 접속하지 않고도 서버를 조작할 수 있는 REST API(웹 주소로 명령을 보내는 방식 - 브라우저나 스크립트 어디서든 호출할 수 있습니다)가 내장되어 있습니다. 공지 보내기, 플레이어 강퇴, 월드 저장, 안전한 종료까지 전부 이 통로로 됩니다. 저희 서버의 자동 백업과 브라우저 관리 페이지도 전부 이 API 위에서 돌아갑니다. 이 글은 그 명령 전체를 표 하나로 정리한 것입니다.
켜는 법
설정 파일 PalWorldSettings.ini 의 OptionSettings 안에 RESTAPIEnabled=True 를 넣고 서버를 재시작하면 8212 포트(RESTAPIPort 로 변경 가능)에서 API가 열립니다. 인증은 HTTP Basic(주소를 부를 때 아이디와 비밀번호를 함께 보내는 가장 단순한 방식)이고, 아이디는 admin, 비밀번호는 서버 설정의 AdminPassword 입니다.
한 가지 주의할 점이 있습니다. 이 포트는 절대 인터넷에 그대로 노출하면 안 됩니다. 관리자 비밀번호 하나로 서버 종료까지 되는 통로라서, 공식 문서도 외부 공개를 금지하고 있습니다. 반드시 같은 컴퓨터(127.0.0.1)나 집 안 네트워크에서만 호출하고, 외부에서 접근해야 한다면 3탄에서 만든 관리 페이지처럼 중간에 인증을 둔 서버를 거치도록 구성합니다.
엔드포인트 전체 (12개)
주소는 전부 http://서버주소:8212/v1/api/ 뒤에 붙습니다. GET은 읽기, POST는 실행입니다.
| 방식 | 주소 | 하는 일 | 보내는 값(JSON) |
|---|---|---|---|
| GET | /v1/api/info |
서버 이름·버전 확인 | - |
| GET | /v1/api/players |
접속 중인 플레이어 목록 | - |
| GET | /v1/api/settings |
서버 설정 읽기 | - |
| GET | /v1/api/metrics |
서버 상태 수치(FPS·인원·가동 시간) | - |
| GET | /v1/api/game-data |
월드 안 개체 스냅샷 (최근 추가됨) | - |
| POST | /v1/api/announce |
전체 공지 보내기 | message |
| POST | /v1/api/kick |
플레이어 강퇴 | userid, message |
| POST | /v1/api/ban |
플레이어 밴 | userid, message |
| POST | /v1/api/unban |
밴 해제 | userid |
| POST | /v1/api/save |
월드 저장 | - |
| POST | /v1/api/shutdown |
예고 후 종료(저장됨) | waittime, message |
| POST | /v1/api/stop |
즉시 강제 종료(저장 안 됨!) | - |
userid 는 players 목록에 나오는 steam_ 으로 시작하는 값을 그대로 씁니다. 종료는 반드시 shutdown 을 씁니다. stop 은 저장 없이 끊어 버려서, 2탄에서 다룬 "진행이 날아가는 사고"가 그대로 재현됩니다.
바로 써 보기
# 공지 보내기 (아이디 admin, 비밀번호는 AdminPassword 값)
curl -u admin:비밀번호 -H "Content-Type: application/json" \
-d '{"message": "10분 뒤 서버를 재시작합니다"}' \
http://127.0.0.1:8212/v1/api/announce
# 월드 저장 → 60초 예고 후 안전하게 종료 (재시작 전 순서)
curl -u admin:비밀번호 -X POST http://127.0.0.1:8212/v1/api/save
curl -u admin:비밀번호 -H "Content-Type: application/json" \
-d '{"waittime": 60, "message": "잠시 후 재시작"}' \
http://127.0.0.1:8212/v1/api/shutdown이 두 줄(저장 후 예고 종료)이 저희 서버 자동 백업의 핵심이기도 합니다. API를 브라우저 버튼으로 바꾸는 방법은 3탄에, REST로 안 되는 설정 편집과 전원 켜기는 4탄에 있습니다.