Skip to main content

REST API Reference

HTTP endpoints for user management, authentication, and data queries.

Authentication​

Register User​

POST /api/auth/register
Content-Type: application/json

{
  "username": "player1",
  "email": "player1@example.com",
  "password": "securePassword123",
  "displayName": "Player One"
}

Response:

{
  "success": true,
  "token": "eyJhbG...",
  "user": {
    "userId": "uuid",
    "username": "player1",
    "displayName": "Player One"
  }
}

Login​

POST /api/auth/login
Content-Type: application/json

{
  "username": "player1",
  "password": "securePassword123"
}

Register Anonymous User​

POST /api/auth/register-anonymous
Content-Type: application/json

{
  "playerId": "uuid",
  "displayName": "Guest Player"
}

Get Current User​

GET /api/auth/me
Authorization: Bearer <token>

Users​

Get User by ID​

GET /api/users/{userId}

Update Profile​

PUT /api/users/profile
Authorization: Bearer <token>
Content-Type: application/json

{
  "displayName": "New Display Name",
  "email": "newemail@example.com",
  "profilePrivacy": "Public"
}

Search Users​

GET /api/users/search?q=player
Authorization: Bearer <token>

Friends​

Get Friends List​

GET /api/friends
Authorization: Bearer <token>

Get Friend Requests​

GET /api/friends/requests
Authorization: Bearer <token>

Send Friend Request​

POST /api/friends/request/{toUserId}
Authorization: Bearer <token>

Accept Friend Request​

POST /api/friends/accept/{friendUserId}
Authorization: Bearer <token>

Decline Friend Request​

POST /api/friends/decline/{friendUserId}
Authorization: Bearer <token>

Remove Friend​

DELETE /api/friends/{friendUserId}
Authorization: Bearer <token>

Games​

List Games​

GET /api/games

Response:

{
  "activeGames": [...],
  "waitingGames": [...]
}

Get Game by ID​

GET /api/game/{gameId}

Get Player's Active Games​

GET /api/player/{playerId}/active-games

Get Player's Game History​

GET /api/player/{playerId}/games?limit=20&skip=0

Get Player Statistics​

GET /api/player/{playerId}/stats

Themes​

List Public Themes​

GET /api/themes?limit=50&cursor=xyz

Get Default Themes​

GET /api/themes/defaults

Get Theme by ID​

GET /api/themes/{themeId}

Create Theme​

POST /api/themes
Authorization: Bearer <token>
Content-Type: application/json

{
  "name": "My Theme",
  "description": "A custom board theme",
  "visibility": "Public",
  "colors": {
    "boardBackground": "#8B4513",
    "lightPoint": "#DEB887",
    "darkPoint": "#654321",
    "whiteChecker": "#FFFFFF",
    "redChecker": "#8B0000"
  }
}

Update Theme​

PUT /api/themes/{themeId}
Authorization: Bearer <token>

Delete Theme​

DELETE /api/themes/{themeId}
Authorization: Bearer <token>

Like/Unlike Theme​

POST /api/themes/{themeId}/like
DELETE /api/themes/{themeId}/like
Authorization: Bearer <token>

Bots and Evaluators​

List Available Bots​

GET /api/bots

List Available Evaluators​

GET /api/evaluators

Statistics​

Server Statistics​

GET /stats

Database Statistics​

GET /api/stats/db

Health​

Health Check​

GET /health

Response:

{
  "status": "healthy",
  "timestamp": "2025-01-18T12:00:00Z"
}