Sessions API

The Sessions API manages game sessions — from launching a game to streaming it to stopping the session. All endpoints require authentication.

Launch a Game

Start a new game session.

POST /api/game/launch
Content-Type: application/json

Request Body

Examples

Continue from a save slot:

{
  "gameSlug": "garden-of-forking-paths",
  "saveSlotId": "cls001..."
}

Start a fresh playthrough:

{
  "gameSlug": "garden-of-forking-paths",
  "fresh": true
}

Response (202 Accepted)

{
  "sessionId": "ses001...",
  "status": "starting"
}

The session starts asynchronously. Use the session status endpoint to poll for readiness.

Launch Process

1. The scheduler selects the best game server (cache-aware, load-aware).
2. If the game isn't cached on the selected server, a download is triggered (may take up to 60 seconds).
3. A Docker container is launched with the game and the user's save data.
4. The session status transitions from starting to running.

Check Session Status

Poll the status of a game session.

GET /api/game/session-status?sessionId={sessionId}

Response

{
  "sessionId": "ses001...",
  "status": "running",
  "serverUrl": "https://gs01.play.ren.bd",
  "containerUrl": "https://gs01.play.ren.bd/session/ses001.../",
  "gameTitle": "The Garden of Forking Paths",
  "startedAt": "2025-03-09T10:15:00Z"
}

Status Values

The play page polls this endpoint every 2 seconds until the status reaches running, then establishes the WebRTC connection.

Keepalive

Extend an active session's idle timeout. The frontend sends this periodically while the user is playing.

POST /api/game/keepalive
Content-Type: application/json

Request Body

{
  "sessionId": "ses001..."
}

Response

{
  "status": "ok",
  "expiresAt": "2025-03-09T11:15:00Z"
}

If keepalive requests stop (user closes the tab or loses connection), the session will be reclaimed after the idle timeout (default: 30 minutes).

Stop a Session

End a game session and clean up the container.

POST /api/game/stop
Content-Type: application/json

Request Body

{
  "sessionId": "ses001..."
}

Response

{
  "status": "stopped",
  "duration": 3600,
  "cpuSeconds": 450.2,
  "peakMemoryMb": 1024
}

When a session is stopped:

1. Save data is persisted to the user's save slot.
2. Container CPU and memory stats are collected.
3. The game's resource profile is updated (exponential moving average).
4. The Docker container is removed.

List Active Sessions

Get all active sessions for the current user.

GET /api/game/sessions

Response

{
  "sessions": [
    {
      "sessionId": "ses001...",
      "gameSlug": "garden-of-forking-paths",
      "gameTitle": "The Garden of Forking Paths",
      "status": "running",
      "startedAt": "2025-03-09T10:15:00Z"
    }
  ]
}

Users can only have one active session at a time. If a session is already running, launching a new game will return a 409 Conflict error.

Error Responses

See Error Codes for the full list.

Next Steps

• Games API — Browse the game catalog.
• Authentication — How sessions and tokens work.