zlh-grind/Agent_Endpoint_Specifications_Phase1.md

Agent Endpoint Specifications — Phase 1

Status: ✅ Documented from source

All routes served on :18888. Internal only — API is the only caller.

---

GET /status

Returns the runtime state of the game server managed by the agent.

Response

{
  "state": "running",
  "processRunning": true,
  "ready": true,
  "readySource": "minecraft_ping",
  "readyError": "",
  "lastReadyAt": "2026-03-10T18:00:00Z",
  "installStep": "",
  "crashCount": 1,
  "lastCrashTime": "2026-03-10T18:10:22Z",
  "lastCrashExitCode": 1,
  "lastCrashSignal": 0,
  "lastCrashUptimeSeconds": 142,
  "lastCrashLogTail": [
    "[Server thread/ERROR]: Failed to start server",
    "java.lang.OutOfMemoryError"
  ],
  "error": null,
  "config": { "..." : "..." },
  "timestamp": 1234567890
}

Crash Semantics

• crashCount increments only on unexpected process exit
• Intentional stops (via /stop) do not increment crash count
• Readiness failure is reported as state = error

---

POST /config

Provision + start in a single async call. Returns 202 Accepted immediately.

{ "ok": true, "state": "installing" }

---

POST /start

Manual start. Requires config already saved. Not available for dev containers.

{ "ok": true, "state": "starting" }

---

POST /stop

Stops the server process. Returns 204 No Content.

---

POST /restart

Stop → wait for exit (20s) → start → wait for readiness. Not available for dev containers.

{ "ok": true, "state": "starting" }

---

GET /health

Always returns 200 ok. Used by API poller to check agent liveness.

---

GET /version

{ "version": "v1.2.3" }

---

GET /game/players

Minecraft only. Returns player presence.

{
  "online": 3,
  "max": 20,
  "players": ["Alice", "Bob", "Carol"]
}

---

Mods

Route	Method	Description
/game/mods	GET	List installed mods
/game/mods/install	POST	Install mod from Modrinth
/game/mods/{id}	GET / DELETE / PATCH	Get, delete, or toggle mod

---

Files

Route	Method	Description
/game/files/list?path=<rel>	GET	List directory (max 200 entries)
/game/files?path=<rel>	GET / POST / DELETE	Read, write, or delete a file
/game/files/stat?path=<rel>	GET	Stat file — returns isWritable, hasBackup, source
/game/files/read?path=<rel>	GET	Read file as string (≤2MB)
/game/files/download?path=<rel>	GET	Download file as binary (streamed)
/game/files/upload?path=<rel>	POST	Upload file (streamed, allowlist enforced)
/game/files/revert?path=<rel>	POST	Restore file from shadow backup

---

Console

Route	Description
GET /console/command?cmd=<cmd>	Send command to server stdin via PTY
WS /console/ws	PTY-backed interactive console

---

Agent Self-Management

Route	Method	Description
/agent/update	POST	Check and apply agent update
/agent/update/status	GET	Last update check result

---

Metrics

Route	Description
GET /metrics/process	Agent process metrics (CPU, memory)