Manage Player Profiles through the API

Create a Leaderboard

Required permission: organization:leaderboard:create
GraphQL Mutation:

mutation {
    createLeaderboard(input: {
        name: "Leaderboard name" # The leaderboard name
        description: "Leaderboard description" # A public description for the leaderboard
    }) {
        id # The ID of the created leaderboard
        name # The leaderboard name
        description # The leaderboard description
    }
}

Create a Season

Required permission: organization:leaderboard:season:create
GraphQL Mutation:

mutation {
    createLeaderboardSeason(leaderboardId: "Leaderboard ID"
        input: {
            name: "Season name" # The name of the season
            start: "2022-01-01" # Starting date
            end: "2023-01-01" # End date
            startingScore: 4242 # Define the starting score that the Player with start with (1200 for ELO as an example)
        }) {
        id # The newly generated ID for this season
        name # The season name
        start # The start date of the season
        end # The end date of the season
    }
}

Create a Bucket

Required permission: organization:leaderboard:season:create
GraphQL Mutation:

mutation {
    createLeaderboardSeasonBucket(
        seasonId: "Season ID" # The season ID to create the bucket at
        input: {
            scoreCalculationType: SCORE # The score calculation system that will use the bucket
            minScore: 1000 # The minimum score required to be in this bucket
            name: "BucketName" # The name of the bucket
        }
    ) {
        id # The ID of the newly created bucket
        name # The name of the bucket
        minScore # The minimum score required to be in this bucket
        scoreCalculationType # The score calculation system that will use the bucket
    }
}

Update Player Score

Required permission: organization:leaderboard:register_score
GraphQL Mutation:

mutation {
    leaderboardRegisterPlayerScore(input: {
        score: 4242 # The new player score
        leaderboardId: "LEaderboard ID" # The ID of the leaderboard to register the score on
        playerId: "Player profile ID" # The ID of the Player Profile to register the score for
    }) {
        rank # The updated player rank
        score # The updated player score
        leaderboardSeasonBucketId # The updated bucket ID of the player
    }
}

Retrieve specific player position

Required permission: organization:leaderboard:register_score
GraphQL Mutation:

query {
    leaderboardCurrentPlayerRanking(input: {
        playerId: "Player profile ID" # The Player Profile ID you wish to retrieve
        leaderboardId: "Leaderboard ID" # The leaderboard that you want to retrieve the score from
        seasonId: "Season ID" # The season where you want to retrieve the score from (optional, if not set, will take the current active season)
    }) {
        score # The player current score
        leaderboardSeasonBucketId # The bucket ID where the player is registered
        rank # The player current rank
        lastRank # The last rank the player has before his last score update
        lastScore # The last score the player has before his last score update
    }
}

Retrieve full leaderboard

Required permission: organization:leaderboard:view and organization:leaderboard:season:view
GraphQL Mutation:

query {
    leaderboard(id: "LEaderboard ID") {
        id
        name
        description
        seasons(page: {
            cursor: "LastPageCursor" # The last page cursor provided by the last output of this call
            size: 100 # The number of elements you wish to retrieve (limited to 100)
        }) {
            nextPageCursor # The page cursor to use for the next page
            data { # List of available seasons
                id # Season id
                name # Season name
                start # Season start date
                end # Season end date
                startingScore # The starting score
                buckets(page: {
                    cursor: "LastPageCursor" # The cursor to use for this pagination
                    size: 100 # The number of elements to retrieve
                }) {
                    nextPageCursor # The cursor for the next page
                    data { # List of buckets
                        id # Bucket ID
                        name # Bucket Name
                        minScore # Bucket minimum score
                        scoreCalculationType # How the score is calculated
                        scores(page: {
                            cursor: "LastPageCursor" # The cursor to use for this pagination
                            size: 100 # Number of elements to retrieve
                        }) { 
                            nextPageCursor # Cursor for the next page
                            data { # List of registered scores for this bucket
                                player {
                                    id # The player ID
                                    username # The player Username
                                    profilePicUrl # The player profile pic URL
                                }
                                score # Current player score
                                rank # Current player rank
                                lastScore # Last score of the player before the last score update
                                lastRank # Last rank of the player before the last score update
                                updatedAt # Last update date for this score
                            }
                        }
                    }
                }
            }
        }
    }
}