# API — Current State

This file records what is believed to be implemented now.

## Readiness / agent state model
- API is the heartbeat authority by polling agents.
- Agent does not push state to API.
- API consumes:
  - `/health` for liveness
  - `/ready` for semantic readiness
  - `/status` for detailed state snapshot
- Portal should rely on API-normalized state, not direct agent state.

## Readiness cleanup already done
- `agentClient.js` centralizes non-streaming agent transport.
- `getAgentReady()` remains low-level transport.
- `isAgentReadyResult()` is the shared semantic readiness helper.
- `assertAgentReady()` uses semantic readiness.
- Poller only caches `ready: true` when `/ready` returns semantic success.
- Provisioning requires semantic readiness before success/persist/publish.

## Backup support
- API forwards game backup operations.
- Current API route shape:
  - `GET /api/game/servers/:id/backups`
  - `POST /api/game/servers/:id/backups`
  - `POST /api/game/servers/:id/backups/restore?id=<backup_id>`
  - `DELETE /api/game/servers/:id/backups/:backupId`
- API preserves useful agent semantics such as `404`, `409`, and readiness-oriented failures where possible.

## Agent contract alignment already done
- `/start`, `/stop`, `/restart` forwarded as POST.
- `/console/command` forwarded as POST JSON.
- `/ready` is part of poller/readiness logic.

## Still true
- websocket console proxy wiring remains outside `agentClient.js`
- raw streaming upload proxy behavior remains outside `agentClient.js`