> ## 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.

# Leaderboards

> Implement global leaderboards and rankings with the CrateBytes Game API to boost player competitiveness and engagement.

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:**

```json theme={null}
{
  "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:**

```json theme={null}
{
  "score": "10000"
}
```

**Example Request:**

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

**Response:**

```json theme={null}
{
  "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

```json theme={null}
{
  "statusCode": 401,
  "error": {
    "message": "Unauthorized"
  }
}
```

### Invalid Leaderboard

```json theme={null}
{
  "statusCode": 404,
  "error": {
    "message": "Leaderboard not found"
  }
}
```

### Invalid Score

```json theme={null}
{
  "statusCode": 400,
  "error": {
    "message": "Invalid score format"
  }
}
```

### Missing Parameters

```json theme={null}
{
  "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