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