# 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) |