Leaderboards Service

Mushu Leaderboards provides flexible ranking systems for your app. Create boards, submit scores, and query rankings with time-windowed views.

Key Features

• Multiple boards - Create separate leaderboards per game mode, level, etc.
• Time windows - Daily, weekly, monthly, and all-time rankings
• Aggregation modes - Sum, max, min, average, or count
• Anti-cheat - Rate limits and score caps per entry

Endpoints

Board Management

Method	Endpoint	Description
POST	/apps/{app_id}/boards	Create a board
GET	/apps/{app_id}/boards	List boards
GET	/apps/{app_id}/boards/{board_id}	Get board details
DELETE	/apps/{app_id}/boards/{board_id}	Delete a board

Scores & Rankings

Method	Endpoint	Description
POST	/apps/{app_id}/boards/{board_id}/scores	Submit a score
GET	/apps/{app_id}/boards/{board_id}/rankings	Get rankings
GET	/apps/{app_id}/boards/{board_id}/users/{user_id}	Get user's rank

Creating a Board

Requires admin authentication (Bearer token with org admin role):

curl -X POST https://leaderboards.mushucorp.com/apps/app_123/boards \
  -H "Authorization: Bearer your-admin-token" \
  -H "Content-Type: application/json" \
  -d '{
    "board_id": "weekly-challenge",
    "name": "Weekly Challenge",
    "metric": "points",
    "aggregation": "sum",
    "time_windows": ["daily", "weekly", "all_time"],
    "anti_cheat": {
      "max_score_per_entry": 1000,
      "max_entries_per_day": 100,
      "min_interval_seconds": 5
    }
  }'

Aggregation Modes

Mode	Description	Example
sum	Total of all scores	Points collected
max	Highest score wins	High score
min	Lowest score wins	Speedrun time
avg	Average of scores	Rating average
count	Number of entries	Games played

Submitting Scores

curl -X POST https://leaderboards.mushucorp.com/apps/app_123/boards/weekly-challenge/scores \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "user_id": "user_456",
    "score": 150,
    "metadata": {"level": 5}
  }'

Getting Rankings

curl "https://leaderboards.mushucorp.com/apps/app_123/boards/weekly-challenge/rankings?\
time_window=weekly&limit=10" \
  -H "X-API-Key: your-api-key"

Response:

{
  "board_id": "weekly-challenge",
  "time_window": "weekly",
  "rankings": [
    {"rank": 1, "user_id": "user_789", "score": 5420},
    {"rank": 2, "user_id": "user_456", "score": 4850},
    {"rank": 3, "user_id": "user_123", "score": 4200}
  ],
  "total_participants": 1247
}

Get User's Rank

curl "https://leaderboards.mushucorp.com/apps/app_123/boards/weekly-challenge/users/user_456?\
time_window=weekly" \
  -H "X-API-Key: your-api-key"

Response includes rank, score, and nearby players.

Anti-Cheat

Configure limits when creating the board:

• max_score_per_entry - Cap on single score submission
• max_entries_per_day - Limit submissions per user per day
• min_interval_seconds - Minimum time between submissions

Submissions exceeding limits return 429 Too Many Requests.

API Reference

Full OpenAPI documentation: leaderboards.mushucorp.com/docs