# Leaderboards

## Get app global leaderboards

> Get leaderboards for all mini game types and default games for the authenticated app. Optionally filter by a specific mini game type ID. For games without a mini game type, the miniGameTypeName is not present.

```json
{"openapi":"3.0.0","info":{"title":"Meshmap API v1","version":"1.0.0"},"servers":[{"url":"/api/v1","description":"API v1 base URL"}],"security":[{"AppAPIKey":[]}],"components":{"securitySchemes":{"AppAPIKey":{"type":"apiKey","in":"header","name":"x-app-api-key","description":"App API key in format: <key>"}},"schemas":{"GlobalLeaderboardSchema":{"type":"object","required":["leaderboards"],"properties":{"leaderboards":{"type":"array","items":{"$ref":"#/components/schemas/MiniGameLeaderboardSchema"},"nullable":true,"description":"List of leaderboards for each mini game type and default. Each leaderboard includes player profile images and additional player details."}}},"MiniGameLeaderboardSchema":{"type":"object","properties":{"miniGameTypeId":{"type":"string","nullable":true,"description":"Mini game type ID (null for default leaderboard)"},"miniGameTypeName":{"type":"string","nullable":true,"description":"Mini game type name (null for default leaderboard)"},"leaderboard":{"type":"array","items":{"$ref":"#/components/schemas/LeaderboardPlayerSchema"},"nullable":true,"description":"List of top players for this mini game type"}}},"LeaderboardPlayerSchema":{"type":"object","required":["playerId","playerDisplayName","playerScore","createdAt","updatedAt","gameSessionId"],"properties":{"playerId":{"type":"string","description":"Player ID"},"playerDisplayName":{"type":"string","description":"Player display name"},"playerScore":{"type":"number","description":"Player score"},"playerImageUrl":{"type":"string","nullable":true,"description":"URL to player's profile image"},"createdAt":{"type":"string","format":"date-time","description":"Score creation timestamp"},"updatedAt":{"type":"string","format":"date-time","description":"Score last update timestamp"},"gameSessionId":{"type":"string","description":"Game session ID"},"userId":{"type":"string","nullable":true,"description":"Associated user ID"}}},"ErrorResponse":{"type":"object","required":["error"],"properties":{"error":{"oneOf":[{"type":"string","description":"Error message"},{"type":"array","items":{"type":"object","required":["code","message","path"],"properties":{"code":{"type":"string","description":"Error code"},"message":{"type":"string","description":"Error message"},"path":{"type":"array","items":{"oneOf":[{"type":"string"},{"type":"number"}]},"description":"Error path"}}}}]}}}}},"paths":{"/apps/global-leaderboards":{"get":{"summary":"Get app global leaderboards","description":"Get leaderboards for all mini game types and default games for the authenticated app. Optionally filter by a specific mini game type ID. For games without a mini game type, the miniGameTypeName is not present.","tags":["Leaderboards"],"parameters":[{"name":"miniGameTypeId","in":"query","required":false,"schema":{"type":"string"},"description":"Optional mini game type ID to filter leaderboards for a specific game type. If not provided, leaderboards for all game types will be returned."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"default":10},"description":"Maximum number of players to return per leaderboard. Defaults to 10 if not specified."}],"responses":{"200":{"description":"Leaderboards retrieved successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GlobalLeaderboardSchema"}}}},"401":{"description":"Unauthorized - invalid or missing API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"App not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}}}
```