Leaderboard API

Talo aims to work across many different game genres and as such our leaderboards are highly-customisable. Leaderboards can be sorted by descending or ascending order. You can also customise whether players can only have one or multiple entries in a single leaderboard.

Learn more about leaderboards here.

Endpoints

---

Get a leaderboard's entries

read:leaderboards

GET https://api.trytalo.com/v1/leaderboards/:internalName/entries

50 results are returned per page, in the sort order defined by the leaderboard

Headers

Key	Required	Description
x-talo-alias	❌ No	The ID of the player's alias

Route params

Key	Required	Description
internalName	✅ Yes	The internal name of the leaderboard

Query keys

Key	Required	Description
aliasId	❌ No	Only return entries for this alias ID
endDate	❌ No	A UTC Date (YYYY-MM-DD), DateTime (ISO 8601) or millisecond timestamp
page	❌ No	The current pagination index (starting at 0)
propKey	❌ No	Only return entries with this prop key
propValue	❌ No	Only return entries with a matching prop key and value
service	❌ No	Only return entries for this player alias service (e.g. steam, epic, username)
startDate	❌ No	A UTC Date (YYYY-MM-DD), DateTime (ISO 8601) or millisecond timestamp
withDeleted	❌ No	Include entries that were deleted by a refresh interval

Sample response

{ ... }

Sample request with prop key filtering

{ ... }

Sample request with prop key and value filtering

{ ... }

Sample request with deleted entries

{ ... }

Sample request with date filtering

{ ... }

Sample request with service filtering

{ ... }

---

Create or update a leaderboard's entry

write:leaderboards

POST https://api.trytalo.com/v1/leaderboards/:internalName/entries

If an entry exists for the player and the leaderboard mode is set to unique, that entry will be updated with the new score (and the updated key will return true)

Headers

Key	Required	Description
x-talo-alias	✅ Yes

Route params

Key	Required	Description
internalName	✅ Yes	The internal name of the leaderboard

Query keys

None available

Body keys

Key	Required	Description
props	❌ No
score	✅ Yes	A numeric score for the entry

Sample response

{ ... }

---