> ## 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.

# Sessions

> Manage player sessions with the CrateBytes Game API for tracking player activity and engagement.

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:**

```json theme={null}
{
  "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:**

```json theme={null}
{
  "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:**

```json theme={null}
{
  "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

```json theme={null}
{
  "statusCode": 401,
  "error": {
    "message": "Unauthorized"
  }
}
```

### Session Already Active

```json theme={null}
{
  "statusCode": 400,
  "error": {
    "message": "Session already active"
  }
}
```

### No Active Session

```json theme={null}
{
  "statusCode": 400,
  "error": {
    "message": "No active session found"
  }
}
```