Leaderboards
Score
Set, add to, reset, or remove a user's score on a leaderboard. Call from your game server after match-end or milestone events.
POST
/api/leaderboards/score.php
Requires
Authorization: AppID:AppKey headerIdentify the leaderboard (one of)
| Field | Type | Description |
|---|---|---|
| slug | string | Leaderboard slug from your app |
| leaderboard_id | int | Numeric ID returned by create.php |
Identify the user (one of)
| Field | Type | Description |
|---|---|---|
| user_id | int | Numeric user ID |
| userkey | string | User's userKey |
| token | string | User's session token |
Action
| action | value | Description |
|---|---|---|
set | required | Set an absolute score, replacing the current value |
add | required | Increment the score. Use a negative number to subtract. |
reset | — | Set the score to 0 (user remains on the leaderboard) |
remove | — | Remove the user entirely from the leaderboard |
Test this endpoint
Headers
Body
Success response 200
{
"success": true,
"action": "add",
"leaderboard_id": 1,
"user_id": 42,
"new_score": 47
}Errors
| Code | Message | Cause |
|---|---|---|
| 400 | Leaderboard identifier required. | Neither slug nor leaderboard_id provided |
| 400 | User identifier required. | No user identification field |
| 400 | value is required for this action. | set or add without value |
| 404 | Leaderboard not found. | Slug/ID doesn't exist for this app |