Leaderboards

The leaderboard system is flexible and allows learning apps to define custom leaderboards based on their needs.

Features

Per-App Scoping: Use appId (e.g., trashcat, snake-wars) so each app has its own isolated leaderboard partition. Omit appId to query a cross-app leaderboard (rarely needed).
Categories & Subcategories: Use categoryId (e.g., skillId) to create leaderboards per skill, and optionally filter by subcategory (e.g., organizationId)
Flexible Units: Track any metric (points, seconds, stars, coins, etc.)
Sort Directions: Ascending (lower is better, for times) or descending (higher is better, for scores)
Weekly & Global Rankings: Each leaderboard maintains both weekly and all-time rankings

List Available Leaderboards

const res = await fetch(`${API_URL}/miscellaneous/v1/leaderboards`, {
  headers: { Authorization: `Bearer ${idToken}` },
});
const { leaderboards } = await res.json();
// Returns: [{ id: 'practice-scores', name: 'Top Scores', unit: 'points', sortDirection: 'desc' }, ...]

Current leaderboards:

practice-scores: Top scores (points, higher is better)
competition-times: Best times (seconds, lower is better)

Additional leaderboards can be defined as needed. Contact trashcat@trilogy.com to request new leaderboard configurations.

Submit a Score

// Example: Submit competition time
const totalTimeSeconds = activePlayTime + penaltyTime;
await fetch(
  `${API_URL}/miscellaneous/v1/leaderboards/competition-times/scores?categoryId=${skillId}&subcategory=${organizationId}&appId=${appId}`,
  {
    method: 'POST',
    headers: {
      Authorization: `Bearer ${idToken}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      score: Math.round(totalTimeSeconds),
    }),
  },
);

Always pass appId for in-game submissions so scores from different apps stay in separate leaderboards. Use the active app's identifier (e.g. trashcat, snake-wars, survivor-game).

Retrieve Rankings

Weekly Leaderboard

const weeklyRes = await fetch(
  `${API_URL}/miscellaneous/v1/leaderboards/competition-times/weekly/current?categoryId=${skillId}&subcategory=${organizationId}&appId=${appId}&limit=20`,
  {
    headers: { Authorization: `Bearer ${idToken}` },
  },
);
const { entries, currentUserEntry, totalCount } = await weeklyRes.json();

Global Leaderboard

const globalRes = await fetch(
  `${API_URL}/miscellaneous/v1/leaderboards/competition-times/global?categoryId=${skillId}&subcategory=${organizationId}&appId=${appId}&limit=20`,
  {
    headers: { Authorization: `Bearer ${idToken}` },
  },
);
const { entries, currentUserEntry, totalCount } = await globalRes.json();

Response Format

Both endpoints return:

{
  "entries": [
    { "rank": 1, "score": 180, "playerName": "Alice", "unit": "seconds" },
    { "rank": 2, "score": 195, "playerName": "Bob", "unit": "seconds" },
    // ... up to limit
  ],
  "currentUserEntry": {
    "rank": 47,
    "score": 240,
    "playerName": "CurrentUser",
    "unit": "seconds"
  },
  "totalCount": 156
}

Key fields:

entries: Top performers (limited by limit parameter)
currentUserEntry: Current user's ranking (included even if outside top entries)
totalCount: Total participants in this leaderboard

Leaderboard Scoping

Use appId, categoryId, and subcategory to create focused competitions:

Per-app competition (default for in-game submissions):

// Only Trashcat scores; Snake Wars / Survivor scores live in their own partitions
?categoryId=${skillId}&appId=trashcat

Cross-app competition (rare):

// All apps compete in the same bucket (omit appId)
?categoryId=${skillId}

School-level competition:

// Only students from the same organization compete, scoped to the active app
?categoryId=${skillId}&subcategory=${organizationId}&appId=${appId}

Skill-specific:

// Different leaderboards per skill
?categoryId=multiplication&appId=trashcat  // vs
?categoryId=division&appId=trashcat

Getting Started

Authentication setup required for accessing leaderboards and submitting scores.

Complete Example

Production code showing how to integrate leaderboard submissions into your learning session flow.

API Reference

Complete endpoint documentation for leaderboard operations, including all query parameters and response schemas.

Interventions

User Storage