diff --git a/content/docs/admin/leaderboard-api.mdx b/content/docs/admin/leaderboard-api.mdx new file mode 100644 index 0000000..829ba06 --- /dev/null +++ b/content/docs/admin/leaderboard-api.mdx @@ -0,0 +1,81 @@ +--- +description: Manage leaderboards via the admin API. Create, update, reset and read leaderboards and their entries. +title: Leaderboard admin API +--- + +import { ServiceDocumentation } from '@/components/documentation/ServiceDocumentation' +import { generateServiceTOC } from '@/lib/api-docs' + +export const service = 'LeaderboardAdminAPI' + +export const pageToc = [ + { title: 'Overview', url: '#overview', depth: 2 }, + { title: 'Endpoints', url: '#endpoints', depth: 2 }, + ...generateServiceTOC(service), + { title: 'Types', url: '#types', depth: 2 }, + { title: 'Leaderboard', url: '#leaderboard', depth: 3 }, + { title: 'LeaderboardEntry', url: '#leaderboardentry', depth: 3 }, +] + +## Overview + +The leaderboard admin API lets you create, update, delete and reset [leaderboards](/docs/http/leaderboard-api) programmatically, as well as read leaderboards and their entries. This is useful for automation like creating a new leaderboard ahead of a patch, resetting entries between competitive seasons or hiding suspicious entries. + +## Endpoints + + + +## Types + +### Leaderboard + +```ts +type Leaderboard = { + id: number + internalName: string + name: string + sortMode: 'asc' | 'desc' + unique: boolean + uniqueByProps: boolean + refreshInterval: 'never' | 'daily' | 'weekly' | 'monthly' | 'yearly' + createdAt: string + updatedAt: string +} +``` + +### LeaderboardEntry + +```ts +type LeaderboardEntry = { + id: number + score: number + position?: number // this is only returned when listing a leaderboard's entries + leaderboardName: string + leaderboardInternalName: string + leaderboardSortMode: 'asc' | 'desc' + playerAlias: PlayerAlias + hidden: boolean + props: Prop[] + createdAt: string + updatedAt: string + deletedAt: string | null +} + +type PlayerAlias = { + id: number + service: string + identifier: string + displayName: string + lastSeenAt: string + createdAt: string + updatedAt: string +} + +type Prop = { + key: string + value: string +} +``` diff --git a/content/docs/admin/meta.json b/content/docs/admin/meta.json index ee65edf..4de2c3a 100644 --- a/content/docs/admin/meta.json +++ b/content/docs/admin/meta.json @@ -1,5 +1,5 @@ { - "pages": ["authentication", "game-stat-api"], + "pages": ["authentication", "game-stat-api", "leaderboard-api"], "title": "Admin API reference", "icon": "admin" }