Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.cratebytes.com/llms.txt

Use this file to discover all available pages before exploring further.

The Sessions API allows you to track player activity and engagement by managing session lifecycle. All session endpoints require authentication.

​
Base URL

All session endpoints are prefixed with /api/game/session/.

​
Authentication

All session endpoints require a valid JWT token in the Authorization header: 
Authorization: Bearer <your-jwt-token>

​
Start Session

Begin tracking a new player session. Endpoint: POST /api/game/session/start Headers: 
Authorization: Bearer <your-jwt-token>
Response: 
{
  "statusCode": 200,
  "data": {
    "sessionId": "session-uuid",
    "startTime": "2024-01-01T12:00:00Z",
    "playerId": "player-id"
  }
}

​
Heartbeat

Keep the session alive and update the last activity timestamp. Endpoint: POST /api/game/session/heartbeat Headers: 
Authorization: Bearer <your-jwt-token>
Response: 
{
  "statusCode": 200,
  "data": {
    "sessionId": "session-uuid",
    "lastActivity": "2024-01-01T12:30:00Z",
    "playerId": "player-id"
  }
}

​
End Session

Stop tracking the current session. Endpoint: POST /api/game/session/stop Headers: 
Authorization: Bearer <your-jwt-token>
Response: 
{
  "statusCode": 200,
  "data": {
    "sessionId": "session-uuid",
    "startTime": "2024-01-01T12:00:00Z",
    "endTime": "2024-01-01T13:00:00Z",
    "duration": 3600,
    "playerId": "player-id"
  }
}

​
Session Management Best Practices

  1. Start Session: Call when the player begins playing your game
  2. Heartbeat: Call periodically (every 5-10 minutes) to keep the session active
  3. End Session: Call when the player stops playing or closes the game

​
Error Responses

​
Unauthorized

{
  "statusCode": 401,
  "error": {
    "message": "Unauthorized"
  }
}

​
Session Already Active

{
  "statusCode": 400,
  "error": {
    "message": "Session already active"
  }
}

​
No Active Session

{
  "statusCode": 400,
  "error": {
    "message": "No active session found"
  }
}