# Game Sessions

## Get all game sessions of an app

> Retrieve all game sessions 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":{"GameSessionsSchemaListResponse":{"type":"object","required":["gameSessions"],"properties":{"gameSessions":{"type":"array","items":{"$ref":"#/components/schemas/GameSessionSchema"}}}},"GameSessionSchema":{"type":"object","required":["id","status","startTime","createdAt","updatedAt","playerCount"],"properties":{"id":{"type":"string","description":"Unique game session identifier"},"name":{"type":"string","nullable":true,"description":"Game session name"},"description":{"type":"string","nullable":true,"description":"Game session description"},"status":{"type":"string","enum":["ACTIVE","COMPLETED"],"description":"Game session status"},"startTime":{"type":"string","format":"date-time","description":"Game session start time"},"endTime":{"type":"string","format":"date-time","nullable":true,"description":"Game session end time"},"createdAt":{"type":"string","format":"date-time","description":"Creation timestamp"},"updatedAt":{"type":"string","format":"date-time","description":"Last update timestamp"},"miniGameType":{"allOf":[{"$ref":"#/components/schemas/MiniGameTypeSchema"}],"nullable":true,"description":"Associated mini game type"},"playerCount":{"type":"number","default":0,"description":"Number of players in the game session"}}},"MiniGameTypeSchema":{"type":"object","required":["id","name","description","createdAt"],"properties":{"id":{"type":"string","description":"Unique mini game type identifier"},"name":{"type":"string","description":"Mini game type name"},"description":{"type":"string","description":"Mini game type description"},"imageUrl":{"type":"string","nullable":true,"description":"Mini game type image URL"},"createdAt":{"type":"string","format":"date-time","description":"Creation 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/game-sessions":{"get":{"summary":"Get all game sessions of an app","description":"Retrieve all game sessions for the authenticated app","tags":["Game Sessions"],"responses":{"200":{"description":"Game sessions retrieved successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GameSessionsSchemaListResponse"}}}},"401":{"description":"Unauthorized - invalid or missing session token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}}}
```

## Create a new game session

> Create a new game session for the authenticated app. Optionally specify a mini game type name or ID to associate with the game session. Cannot be both name and id.

```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":{"CreateGameSessionSchema":{"type":"object","properties":{"name":{"type":"string","nullable":true,"description":"Game session name"},"description":{"type":"string","nullable":true,"description":"Game session description"},"status":{"type":"string","enum":["ACTIVE","COMPLETED","PAUSED"],"default":"ACTIVE","description":"Game session status"},"miniGameTypeId":{"type":"string","nullable":true,"description":"Optional mini game type ID to associate with this game session."},"miniGameTypeName":{"type":"string","nullable":true,"description":"Optional mini game type name to associate with this game session."}}},"GameSessionSchema":{"type":"object","required":["id","status","startTime","createdAt","updatedAt","playerCount"],"properties":{"id":{"type":"string","description":"Unique game session identifier"},"name":{"type":"string","nullable":true,"description":"Game session name"},"description":{"type":"string","nullable":true,"description":"Game session description"},"status":{"type":"string","enum":["ACTIVE","COMPLETED"],"description":"Game session status"},"startTime":{"type":"string","format":"date-time","description":"Game session start time"},"endTime":{"type":"string","format":"date-time","nullable":true,"description":"Game session end time"},"createdAt":{"type":"string","format":"date-time","description":"Creation timestamp"},"updatedAt":{"type":"string","format":"date-time","description":"Last update timestamp"},"miniGameType":{"allOf":[{"$ref":"#/components/schemas/MiniGameTypeSchema"}],"nullable":true,"description":"Associated mini game type"},"playerCount":{"type":"number","default":0,"description":"Number of players in the game session"}}},"MiniGameTypeSchema":{"type":"object","required":["id","name","description","createdAt"],"properties":{"id":{"type":"string","description":"Unique mini game type identifier"},"name":{"type":"string","description":"Mini game type name"},"description":{"type":"string","description":"Mini game type description"},"imageUrl":{"type":"string","nullable":true,"description":"Mini game type image URL"},"createdAt":{"type":"string","format":"date-time","description":"Creation 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/game-sessions":{"post":{"summary":"Create a new game session","description":"Create a new game session for the authenticated app. Optionally specify a mini game type name or ID to associate with the game session. Cannot be both name and id.","tags":["Game Sessions"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateGameSessionSchema"}}}},"responses":{"201":{"description":"Game session created successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GameSessionSchema"}}}},"400":{"description":"Invalid request data","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized - invalid or missing session token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}}}
```

## Get a game session by ID

> Retrieve a specific game session by its ID

```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":{"GameSessionSchema":{"type":"object","required":["id","status","startTime","createdAt","updatedAt","playerCount"],"properties":{"id":{"type":"string","description":"Unique game session identifier"},"name":{"type":"string","nullable":true,"description":"Game session name"},"description":{"type":"string","nullable":true,"description":"Game session description"},"status":{"type":"string","enum":["ACTIVE","COMPLETED"],"description":"Game session status"},"startTime":{"type":"string","format":"date-time","description":"Game session start time"},"endTime":{"type":"string","format":"date-time","nullable":true,"description":"Game session end time"},"createdAt":{"type":"string","format":"date-time","description":"Creation timestamp"},"updatedAt":{"type":"string","format":"date-time","description":"Last update timestamp"},"miniGameType":{"allOf":[{"$ref":"#/components/schemas/MiniGameTypeSchema"}],"nullable":true,"description":"Associated mini game type"},"playerCount":{"type":"number","default":0,"description":"Number of players in the game session"}}},"MiniGameTypeSchema":{"type":"object","required":["id","name","description","createdAt"],"properties":{"id":{"type":"string","description":"Unique mini game type identifier"},"name":{"type":"string","description":"Mini game type name"},"description":{"type":"string","description":"Mini game type description"},"imageUrl":{"type":"string","nullable":true,"description":"Mini game type image URL"},"createdAt":{"type":"string","format":"date-time","description":"Creation 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/game-sessions/{sessionId}":{"get":{"summary":"Get a game session by ID","description":"Retrieve a specific game session by its ID","tags":["Game Sessions"],"parameters":[{"name":"sessionId","in":"path","required":true,"schema":{"type":"string"},"description":"Game session ID"}],"responses":{"200":{"description":"Game session retrieved successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GameSessionSchema"}}}},"401":{"description":"Unauthorized - invalid or missing session token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Game session not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}}}
```

## Get all players in a game session

> Retrieve all players registered to a specific game session

```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":{"GameSessionPlayersListResponse":{"type":"object","required":["players"],"properties":{"players":{"type":"array","items":{"$ref":"#/components/schemas/GameSessionPlayerSchema"}}}},"GameSessionPlayerSchema":{"type":"object","required":["score","createdAt","updatedAt","playerId","displayName"],"properties":{"score":{"type":"number","description":"Player score"},"createdAt":{"type":"string","format":"date-time","description":"Creation timestamp"},"updatedAt":{"type":"string","format":"date-time","description":"Last update timestamp"},"playerId":{"type":"string","description":"Associated player ID"},"displayName":{"type":"string","description":"Player display name"},"imageUrl":{"type":"string","nullable":true,"description":"URL to player's profile image"},"user":{"type":"object","nullable":true,"description":"Associated user information","properties":{"id":{"type":"string","description":"User ID"},"username":{"type":"string","nullable":true,"description":"User's username"}}}}},"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/game-sessions/{sessionId}/players":{"get":{"summary":"Get all players in a game session","description":"Retrieve all players registered to a specific game session","tags":["Game Sessions"],"parameters":[{"name":"sessionId","in":"path","required":true,"schema":{"type":"string"},"description":"Game session ID"}],"responses":{"200":{"description":"Game session players retrieved successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GameSessionPlayersListResponse"}}}},"401":{"description":"Unauthorized - invalid or missing session token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Game session not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}}}
```

## Register a player to a game session

> Register an existing player to a specific game session

```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":{"RegisterPlayerToSessionRequest":{"type":"object","required":["playerId"],"properties":{"playerId":{"type":"string","description":"Player ID to register"}}},"GameSessionPlayerSchema":{"type":"object","required":["score","createdAt","updatedAt","playerId","displayName"],"properties":{"score":{"type":"number","description":"Player score"},"createdAt":{"type":"string","format":"date-time","description":"Creation timestamp"},"updatedAt":{"type":"string","format":"date-time","description":"Last update timestamp"},"playerId":{"type":"string","description":"Associated player ID"},"displayName":{"type":"string","description":"Player display name"},"imageUrl":{"type":"string","nullable":true,"description":"URL to player's profile image"},"user":{"type":"object","nullable":true,"description":"Associated user information","properties":{"id":{"type":"string","description":"User ID"},"username":{"type":"string","nullable":true,"description":"User's username"}}}}},"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/game-sessions/{sessionId}/players":{"post":{"summary":"Register a player to a game session","description":"Register an existing player to a specific game session","tags":["Game Sessions"],"parameters":[{"name":"sessionId","in":"path","required":true,"schema":{"type":"string"},"description":"Game session ID"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RegisterPlayerToSessionRequest"}}}},"responses":{"201":{"description":"Player registered to game session successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GameSessionPlayerSchema"}}}},"400":{"description":"Invalid request data","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized - invalid or missing session token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}}}
```

## Update a player's score in a game session

> Update the score of a specific player in a game session

```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":{"UpdateGameSessionPlayerRequest":{"type":"object","required":["score"],"properties":{"score":{"type":"number","description":"Player score"}}},"GameSessionPlayerSchema":{"type":"object","required":["score","createdAt","updatedAt","playerId","displayName"],"properties":{"score":{"type":"number","description":"Player score"},"createdAt":{"type":"string","format":"date-time","description":"Creation timestamp"},"updatedAt":{"type":"string","format":"date-time","description":"Last update timestamp"},"playerId":{"type":"string","description":"Associated player ID"},"displayName":{"type":"string","description":"Player display name"},"imageUrl":{"type":"string","nullable":true,"description":"URL to player's profile image"},"user":{"type":"object","nullable":true,"description":"Associated user information","properties":{"id":{"type":"string","description":"User ID"},"username":{"type":"string","nullable":true,"description":"User's username"}}}}},"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/game-sessions/{sessionId}/players/{playerId}":{"patch":{"summary":"Update a player's score in a game session","description":"Update the score of a specific player in a game session","tags":["Game Sessions"],"parameters":[{"name":"sessionId","in":"path","required":true,"schema":{"type":"string"},"description":"Game session ID"},{"name":"playerId","in":"path","required":true,"schema":{"type":"string"},"description":"Player ID"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateGameSessionPlayerRequest"}}}},"responses":{"200":{"description":"Player score updated successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GameSessionPlayerSchema"}}}},"400":{"description":"Invalid request data","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized - invalid or missing session token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Game session or player not found","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/game-sessions.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.