The Player Metadata API allows you to store and retrieve custom data for each player. This can include player preferences, game progress, settings, or any other player-specific information.

​
Base URL

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

​
Authentication

All metadata endpoints require a valid JWT token in the Authorization header:

Authorization: Bearer <your-jwt-token>

​
Get Player Metadata

Retrieve the current player’s metadata.

Endpoint: GET /api/game/metadata

Headers:

Authorization: Bearer <your-jwt-token>

Response:

{
  "statusCode": 200,
  "data": {
    "playerId": "player-123",
    "sequentialId": 12345,
    "metadata": {
      "level": 5,
      "coins": 1000,
      "settings": {
        "soundEnabled": true,
        "musicVolume": 0.8
      },
      "lastPlayed": "2024-01-01T12:00:00Z"
    }
  }
}

​
Get Metadata by Sequential ID

Retrieve metadata for a specific player using their sequential ID.

Endpoint: GET /api/game/metadata/{sequentialId}

Headers:

Authorization: Bearer <your-jwt-token>

Example Request:

GET /api/game/metadata/12345

Response:

{
  "statusCode": 200,
  "data": {
    "playerId": "player-123",
    "sequentialId": 12345,
    "metadata": {
      "level": 5,
      "coins": 1000,
      "settings": {
        "soundEnabled": true,
        "musicVolume": 0.8
      }
    }
  }
}

​
Set Player Metadata

Store or update the current player’s metadata.

Endpoint: POST /api/game/metadata

Headers:

Authorization: Bearer <your-jwt-token>
Content-Type: application/json

Request Body:

{
  "data": {
    "level": 5,
    "coins": 1000,
    "settings": {
      "soundEnabled": true,
      "musicVolume": 0.8
    },
    "lastPlayed": "2024-01-01T12:00:00Z"
  }
}

Response:

{
  "statusCode": 200,
  "data": {
    "playerId": "player-123",
    "sequentialId": 12345,
    "metadata": {
      "level": 5,
      "coins": 1000,
      "settings": {
        "soundEnabled": true,
        "musicVolume": 0.8
      },
      "lastPlayed": "2024-01-01T12:00:00Z"
    }
  }
}

​
Delete Player Metadata

Remove all metadata for the current player.

Endpoint: DELETE /api/game/metadata

Headers:

Authorization: Bearer <your-jwt-token>

Response:

{
  "statusCode": 200,
  "data": "Data deleted"
}

​
Metadata Structure

The metadata can contain any JSON-serializable data. Common use cases include:

  • Game Progress: Level, experience points, achievements
  • Player Settings: Audio settings, graphics preferences, controls
  • Game State: Current position, inventory, unlocked content
  • Statistics: Play time, high scores, completion rates

​
Error Responses

​
Unauthorized

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

​
Player Not Found

{
  "statusCode": 404,
  "error": {
    "message": "Player not found"
  }
}

​
Invalid Data

{
  "statusCode": 400,
  "error": {
    "message": "Invalid metadata format"
  }
}

​
Best Practices

  1. Data Structure: Use consistent data structures for better organization
  2. Size Limits: Keep metadata reasonably sized (under 1MB)
  3. Privacy: Don’t store sensitive personal information
  4. Backup: Consider backing up important metadata locally
  5. Validation: Validate metadata structure before sending