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"
}