REST API

weiqi-server exposes everything under the /api prefix. All endpoints require an authenticated session unless marked public.

Auth

Session cookie: better-auth.session_token. The __Secure- prefix is tried first. The guard lives in apps/weiqi-server/src/modules/accounts/presentation/guards/auth.guard.ts:30.

Roles (passed to Auth(...roles) decorator):

Role	Notes
user	Default for any signed-in account.
mod	Challenge moderation queue access.
admin	Admin console access.
super_admin	Reserved for emergency overrides.

accounts

Method	Path	Auth	Notes
GET	/accounts/me	Yes	Current user profile.
PATCH	/accounts/me	Yes	Update display name etc.

games (PvP)

Method	Path	Auth	Notes
POST	/games	Yes	Create a PvP game record.
GET	/games	Yes	List games for the caller.
GET	/games/:id	Yes	Game metadata.
PATCH	/games/:id	Yes	Update metadata (e.g. archive).
POST	/games/:id/moves	Yes	Append a move; validates with weiqi-engine.
GET	/games/:id/moves	Yes	Move history.

game/bot

Method	Path	Auth	Notes
GET	/game/bot/levels	Yes	Catalog of the ten levels. See Bot Ladder.
POST	/game/bot/games	Yes	Start a new bot game.
GET	/game/bot/games/:id	Yes	Game state.
GET	/game/bot/games/:id/moves	Yes	Move list.
GET	/game/bot/games/:id/review	Yes	Latest KataGo review.
POST	/game/bot/games/:id/move	Yes	Player move; bot replies.
POST	/game/bot/games/:id/resign	Yes	Resign.
POST	/game/bot/games/:id/hint	Yes	One-move hint. Entitlement-gated.
POST	/game/bot/games/:id/undo	Yes	Undo last move.
GET	/game/bot/ladder/me	Yes	Caller’s ladder state.
POST	/game/bot/ladder/opt-in	Yes	Toggle ladder participation.
GET	/game/bot/ladder/history?limit=50	Yes	Recent rating deltas.

analysis

Method	Path	Auth	Notes
POST	/analysis/games/:id/runFullReview	Yes	One-call whole-game review. See KataGo Review.
GET	/analysis/games/:id/snapshots	Yes	Per-node KataGo snapshots.
GET	/analysis/games/:id/graph	Yes	Winrate / score-lead series.

challenges

Method	Path	Auth	Notes
POST	/challenges	Yes	Submit a new challenge.
GET	/challenges	Public	Browse approved challenges.
POST	/challenges/:id/solution-attempts	Yes	Submit a solution.
GET	/challenges/moderation/list	mod	Moderator queue.
POST	/challenges/moderation/approve	mod	Approve a submission.
POST	/challenges/moderation/reject	mod	Reject a submission.
GET	/challenges/my-submissions/list	Yes	Caller’s own submissions.

agent

Method	Path	Auth	Notes
POST	/agent/run	admin	Run a natural-language analytics query.
GET	/agent/tasks/:id	admin	Poll status of an agent task.

Real-time

Socket.IO endpoint at /socket.io/ on the same origin. Auth is via the same session cookie. Events emitted: gameState, botMove, classified, gameEnded, plus analysis:turn while a runFullReview is in progress.

Error envelope

All errors share the same envelope:

{
  "statusCode": 400,
  "error": "Bad Request",
  "message": "GameMessages.YOU_CANT_PLACE_STONE_ON_THIS_POSITION",
  "code": "INVALID_MOVE"
}

code is a stable, machine-readable identifier. message is human-readable and may change between versions. Clients should branch on code.