Skip to main content
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
⌘I