The Leaderboards API allows you to create and manage leaderboards for your games. Players can submit scores and retrieve rankings. All leaderboard endpoints require authentication.

​
Base URL

All leaderboard endpoints are prefixed with /api/game/leaderboard/{leaderboardId}/.

​
Authentication

All leaderboard endpoints require a valid JWT token in the Authorization header:

Authorization: Bearer <your-jwt-token>

​
Get Leaderboard

Retrieve the current leaderboard rankings for a specific leaderboard.

Endpoint: GET /api/game/leaderboard/{leaderboardId}

Headers:

Authorization: Bearer <your-jwt-token>

Query Parameters:

  • page (optional): Page number for pagination (default: 1)

Example Request:

GET /api/game/leaderboard/my-leaderboard?page=1

Response:

{
  "statusCode": 200,
  "data": {
    "leaderboardId": "my-leaderboard",
    "page": 1,
    "totalPages": 5,
    "totalEntries": 100,
    "entries": [
      {
        "rank": 1,
        "playerId": "player-123",
        "score": 10000,
        "playerName": "Player1",
        "submittedAt": "2024-01-01T12:00:00Z"
      },
      {
        "rank": 2,
        "playerId": "player-456",
        "score": 9500,
        "playerName": "Player2",
        "submittedAt": "2024-01-01T11:30:00Z"
      }
    ]
  }
}

​
Submit Score

Submit a player’s score to the leaderboard.

Endpoint: POST /api/game/leaderboard/{leaderboardId}

Headers:

Authorization: Bearer <your-jwt-token>
Content-Type: application/json

Request Body:

{
  "score": "10000"
}

Example Request:

POST /api/game/leaderboard/my-leaderboard
{
  "score": "10000"
}

Response:

{
  "statusCode": 200,
  "data": {
    "message": "Score submitted"
  }
}

​
Leaderboard Management

Leaderboards are created and managed through the CrateBytes dashboard. Each leaderboard has a unique ID that you’ll use in the API calls.

​
Error Responses

​
Unauthorized

{
  "statusCode": 401,
  "error": {
    "message": "Unauthorized"
  }
}

​
Invalid Leaderboard

{
  "statusCode": 404,
  "error": {
    "message": "Leaderboard not found"
  }
}

​
Invalid Score

{
  "statusCode": 400,
  "error": {
    "message": "Invalid score format"
  }
}

​
Missing Parameters

{
  "statusCode": 400,
  "error": {
    "message": "Project key, player id, or score not provided"
  }
}

​
Best Practices

  1. Score Format: Scores should be submitted as strings to handle large numbers
  2. Pagination: Use pagination for large leaderboards to improve performance
  3. Rate Limiting: Avoid submitting scores too frequently
  4. Error Handling: Always handle potential errors when submitting scores