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

# Player Metadata

> Store and retrieve player metadata with the CrateBytes Game API. Manage player-specific data and settings.

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

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

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

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

**Response:**

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

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

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

### Player Not Found

```json theme={null}
{
  "statusCode": 404,
  "error": {
    "message": "Player not found"
  }
}
```

### Invalid Data

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