# 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"}}}}}}}}}
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.meshmap.com/api/core/players.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.