159 lines
3.2 KiB
Markdown
159 lines
3.2 KiB
Markdown
# 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
|
|
|
|
```json
|
|
{
|
|
"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.
|
|
|
|
```json
|
|
{ "ok": true, "state": "installing" }
|
|
```
|
|
|
|
---
|
|
|
|
## POST /start
|
|
|
|
Manual start. Requires config already saved. Not available for `dev` containers.
|
|
|
|
```json
|
|
{ "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.
|
|
|
|
```json
|
|
{ "ok": true, "state": "starting" }
|
|
```
|
|
|
|
---
|
|
|
|
## GET /health
|
|
|
|
Always returns `200 ok`. Used by API poller to check agent liveness.
|
|
|
|
---
|
|
|
|
## GET /version
|
|
|
|
```json
|
|
{ "version": "v1.2.3" }
|
|
```
|
|
|
|
---
|
|
|
|
## GET /game/players
|
|
|
|
Minecraft only. Returns player presence.
|
|
|
|
```json
|
|
{
|
|
"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) |
|