# Players

## Get all players

> Retrieve all players for the authenticated app

```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":{"GetPlayersListResponse":{"type":"object","required":["players"],"properties":{"players":{"type":"array","items":{"$ref":"#/components/schemas/PlayerSchema"}}}},"PlayerSchema":{"type":"object","required":["id","displayName","createdAt","updatedAt"],"properties":{"id":{"type":"string","description":"Unique player identifier"},"displayName":{"type":"string","description":"Player display name"},"userId":{"type":"string","nullable":true,"description":"Associated user ID"},"imageUrl":{"type":"string","nullable":true,"description":"URL to player's profile image"},"createdAt":{"type":"string","format":"date-time","description":"Creation timestamp"},"updatedAt":{"type":"string","format":"date-time","description":"Last update timestamp"}}},"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/players":{"get":{"summary":"Get all players","description":"Retrieve all players for the authenticated app","tags":["Players"],"responses":{"200":{"description":"Players retrieved successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GetPlayersListResponse"}}}},"401":{"description":"Unauthorized - invalid or missing API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}}}
```

## Create a new player

> Create a new player for the authenticated app. Players with duplicate names are not allowed for the same app.

```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":{"CreatePlayerRequest":{"type":"object","required":["displayName"],"properties":{"userId":{"type":"string","nullable":true,"description":"Optional user ID"},"displayName":{"type":"string","description":"Player display name"}}},"PlayerSchema":{"type":"object","required":["id","displayName","createdAt","updatedAt"],"properties":{"id":{"type":"string","description":"Unique player identifier"},"displayName":{"type":"string","description":"Player display name"},"userId":{"type":"string","nullable":true,"description":"Associated user ID"},"imageUrl":{"type":"string","nullable":true,"description":"URL to player's profile image"},"createdAt":{"type":"string","format":"date-time","description":"Creation timestamp"},"updatedAt":{"type":"string","format":"date-time","description":"Last update timestamp"}}},"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/players":{"post":{"summary":"Create a new player","description":"Create a new player for the authenticated app. Players with duplicate names are not allowed for the same app.","tags":["Players"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreatePlayerRequest"}}}},"responses":{"201":{"description":"Player created successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PlayerSchema"}}}},"400":{"description":"Invalid request data","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized - invalid or missing API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}}}
```

## Delete player profile image

> Remove the profile image for a player

```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":{"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/players/{id}/profile-image":{"delete":{"summary":"Delete player profile image","description":"Remove the profile image for a player","tags":["Players"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Player ID"}],"responses":{"200":{"description":"Profile image deleted successfully","content":{"application/json":{"schema":{"type":"object","required":["success"],"properties":{"success":{"type":"boolean"}}}}}},"401":{"description":"Unauthorized - invalid or missing API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Player not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}}}
```

## Upload or update player profile image

> Upload or update a player's profile image. The image must meet specific requirements:\
> \- Minimum dimensions: 512x512 pixels\
> \- Maximum dimensions: 1024x1024 pixels (larger images will be automatically resized)\
> \- Maximum file size: 5MB\
> \- Supported formats: JPEG, PNG, GIF, WebP\
> \- Square aspect ratio recommended for best results

```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":{"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/players/{id}/profile-image":{"patch":{"summary":"Upload or update player profile image","description":"Upload or update a player's profile image. The image must meet specific requirements:\n- Minimum dimensions: 512x512 pixels\n- Maximum dimensions: 1024x1024 pixels (larger images will be automatically resized)\n- Maximum file size: 5MB\n- Supported formats: JPEG, PNG, GIF, WebP\n- Square aspect ratio recommended for best results","tags":["Players"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Player ID"}],"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object","required":["image"],"properties":{"image":{"type":"string","format":"binary","description":"Profile image file"}}}}}},"responses":{"200":{"description":"Profile image updated successfully","content":{"application/json":{"schema":{"type":"object","required":["imageUrl"],"properties":{"imageUrl":{"type":"string","description":"URL of the uploaded image"}}}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string","description":"Error message"}}}}}},"401":{"description":"Unauthorized - invalid or missing API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Player not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}}}
```

## Get a player by ID

> Retrieve a specific player by their ID. Optionally include global rankings across all mini-game types.

```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":{"PlayerSchema":{"type":"object","required":["id","displayName","createdAt","updatedAt"],"properties":{"id":{"type":"string","description":"Unique player identifier"},"displayName":{"type":"string","description":"Player display name"},"userId":{"type":"string","nullable":true,"description":"Associated user ID"},"imageUrl":{"type":"string","nullable":true,"description":"URL to player's profile image"},"createdAt":{"type":"string","format":"date-time","description":"Creation timestamp"},"updatedAt":{"type":"string","format":"date-time","description":"Last update timestamp"}}},"PlayerWithGlobalRankingsSchema":{"type":"object","required":["id","displayName","createdAt","updatedAt","globalRankings"],"properties":{"id":{"type":"string","description":"Unique player identifier"},"displayName":{"type":"string","description":"Player display name"},"userId":{"type":"string","nullable":true,"description":"Associated user ID"},"imageUrl":{"type":"string","nullable":true,"description":"URL to player's profile image"},"createdAt":{"type":"string","format":"date-time","description":"Creation timestamp"},"updatedAt":{"type":"string","format":"date-time","description":"Last update timestamp"},"globalRankings":{"type":"array","items":{"$ref":"#/components/schemas/GlobalRankingSchema"},"description":"Array of global rankings for each mini-game type the player has participated in"},"appName":{"type":"string","description":"Name of the app the player belongs to (optional)"}}},"GlobalRankingSchema":{"type":"object","required":["highestScore","ranking"],"properties":{"highestScore":{"type":"number","description":"Player's highest score for this mini-game type"},"ranking":{"type":"integer","minimum":1,"description":"Player's global ranking for this mini-game type"},"miniGameTypeName":{"type":"string","nullable":true,"description":"Mini game type name (null for default game type)"},"miniGameTypeId":{"type":"string","nullable":true,"description":"Mini game type ID (null for default game type)"}}},"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/players/{id}":{"get":{"summary":"Get a player by ID","description":"Retrieve a specific player by their ID. Optionally include global rankings across all mini-game types.","tags":["Players"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Player ID"},{"name":"includeGlobalRankings","in":"query","required":false,"schema":{"type":"boolean","default":false},"description":"If true, includes the player's global rankings for all mini-game types they have participated in"}],"responses":{"200":{"description":"Player retrieved successfully","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/PlayerSchema"},{"$ref":"#/components/schemas/PlayerWithGlobalRankingsSchema"}]}}}},"401":{"description":"Unauthorized - invalid or missing API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Player not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}}}
```

## Update a player

> Update a player's information (display name and user association)

```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":{"CreatePlayerRequest":{"type":"object","required":["displayName"],"properties":{"userId":{"type":"string","nullable":true,"description":"Optional user ID"},"displayName":{"type":"string","description":"Player display name"}}},"PlayerSchema":{"type":"object","required":["id","displayName","createdAt","updatedAt"],"properties":{"id":{"type":"string","description":"Unique player identifier"},"displayName":{"type":"string","description":"Player display name"},"userId":{"type":"string","nullable":true,"description":"Associated user ID"},"imageUrl":{"type":"string","nullable":true,"description":"URL to player's profile image"},"createdAt":{"type":"string","format":"date-time","description":"Creation timestamp"},"updatedAt":{"type":"string","format":"date-time","description":"Last update timestamp"}}},"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/players/{id}":{"patch":{"summary":"Update a player","description":"Update a player's information (display name and user association)","tags":["Players"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Player ID"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreatePlayerRequest"}}}},"responses":{"200":{"description":"Player updated successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PlayerSchema"}}}},"400":{"description":"Invalid request data","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized - invalid or missing API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden - can only update players belonging to your app","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Player not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}}}
```

## Get player's global ranking

> Get a player's global ranking across all default games or all games for a specific mini game type

```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":{"PlayerRankingResponse":{"type":"object","required":["highestScore","ranking"],"properties":{"highestScore":{"type":"number","description":"Player's highest score"},"ranking":{"type":"integer","minimum":1,"description":"Player's global ranking"},"miniGameTypeId":{"type":"string","nullable":true,"description":"Mini game type ID (null for default game type)"},"miniGameTypeName":{"type":"string","nullable":true,"description":"Mini game type name (null for default game type)"}}},"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/players/{playerId}/global-ranking":{"get":{"summary":"Get player's global ranking","description":"Get a player's global ranking across all default games or all games for a specific mini game type","tags":["Players"],"parameters":[{"name":"playerId","in":"path","required":true,"schema":{"type":"string"},"description":"Player ID"},{"name":"miniGameTypeId","in":"query","required":false,"schema":{"type":"string"},"description":"Optional mini game type ID to get ranking for a specific game type. If not provided, the ranking for all default games will be returned."},{"name":"miniGameTypeName","in":"query","required":false,"schema":{"type":"string"},"description":"Optional mini game type name to get ranking for a specific game type. If not provided, the ranking for all default games will be returned."}],"responses":{"200":{"description":"Player ranking retrieved successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PlayerRankingResponse"}}}},"401":{"description":"Unauthorized - invalid or missing API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Player not found or has no ranking","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}}}
```