Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.cratebytes.com/llms.txt

Use this file to discover all available pages before exploring further.

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