Players API

View and manage online players and their inventories.

List Online Players

Get a list of all currently online players.

Endpoint: GET /api/players

Authentication: Required (JWT)

Success Response (200):

{
  "success": true,
  "players": [
    {
      "username": "Player123",
      "uuid": "069a79f4-44e9-4726-a5be-fca90e38aaf5",
      "displayName": "Player123",
      "level": 35,
      "health": 20.0,
      "food": 20,
      "gameMode": "SURVIVAL",
      "location": {
        "world": "world",
        "x": 100.5,
        "y": 64.0,
        "z": -250.3
      },
      "online": true
    }
  ],
  "count": 1,
  "maxPlayers": 20
}

Example:

curl http://localhost:8080/api/players \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

---

Get Player Inventory

Retrieve a player's inventory contents.

Endpoint: GET /api/player/inventory?username=Player123

Authentication: Required (JWT)

Query Parameters:

• username - Minecraft username (optional, defaults to authenticated user)

Success Response (200):

{
  "success": true,
  "username": "Player123",
  "inventory": [
    {
      "slot": 0,
      "material": "DIAMOND_SWORD",
      "amount": 1,
      "displayName": "Legendary Sword",
      "enchantments": [
        {
          "type": "SHARPNESS",
          "level": 5
        }
      ]
    }
  ],
  "totalValue": 5000.0
}

Example:

curl "http://localhost:8080/api/player/inventory?username=Player123" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

Error Responses:

• 400 - Invalid username
• 403 - Can only view own inventory (unless admin)
• 404 - Player not found

---

Sell Inventory Items

Sell items from inventory to the server shop.

Endpoint: POST /api/player/inventory/sell

Authentication: Required (JWT)

Request Body:

{
  "items": [
    {
      "material": "DIAMOND",
      "amount": 10
    }
  ]
}

Success Response (200):

{
  "success": true,
  "totalEarned": 1000.0,
  "newBalance": 5000.0,
  "itemsSold": [
    {
      "material": "DIAMOND",
      "amount": 10,
      "price": 100.0,
      "total": 1000.0
    }
  ]
}

Example:

curl -X POST http://localhost:8080/api/player/inventory/sell \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "items": [
      {"material": "DIAMOND", "amount": 10}
    ]
  }'

Error Responses:

• 400 - Invalid items or insufficient quantity
• 404 - Item not sellable

---

Get Player Maps

Retrieve map items owned by a player.

Endpoint: GET /api/player/maps?username=Player123

Authentication: Required (JWT)

Query Parameters:

• username - Minecraft username (optional, defaults to authenticated user)

Success Response (200):

{
  "success": true,
  "maps": [
    {
      "mapId": 0,
      "world": "world",
      "centerX": 0,
      "centerZ": 0,
      "scale": 1,
      "locked": false
    }
  ]
}

Example:

curl "http://localhost:8080/api/player/maps?username=Player123" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

---

Code Examples

TypeScript

interface Player {
  username: string;
  uuid: string;
  level: number;
  health: number;
  gameMode: string;
  location: {
    world: string;
    x: number;
    y: number;
    z: number;
  };
}

async function getOnlinePlayers(token: string): Promise<Player[]> {
  const response = await fetch('http://localhost:8080/api/players', {
    headers: { 'Authorization': `Bearer ${token}` }
  });
  const data = await response.json();
  return data.players;
}

async function getPlayerInventory(token: string, username?: string) {
  const url = username 
    ? `http://localhost:8080/api/player/inventory?username=${username}`
    : 'http://localhost:8080/api/player/inventory';
    
  const response = await fetch(url, {
    headers: { 'Authorization': `Bearer ${token}` }
  });
  return await response.json();
}

async function sellItems(token: string, items: Array<{material: string, amount: number}>) {
  const response = await fetch('http://localhost:8080/api/player/inventory/sell', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${token}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({ items })
  });
  return await response.json();
}

Python

def get_online_players(token):
    response = requests.get(
        'http://localhost:8080/api/players',
        headers={'Authorization': f'Bearer {token}'}
    )
    return response.json()

def get_player_inventory(token, username=None):
    params = {'username': username} if username else {}
    response = requests.get(
        'http://localhost:8080/api/player/inventory',
        headers={'Authorization': f'Bearer {token}'},
        params=params
    )
    return response.json()

def sell_items(token, items):
    response = requests.post(
        'http://localhost:8080/api/player/inventory/sell',
        headers={
            'Authorization': f'Bearer {token}',
            'Content-Type': 'application/json'
        },
        json={'items': items}
    )
    return response.json()

Notes

• Inventory viewing restricted to own inventory unless admin
• Sell prices determined by server economy settings
• Items must be in player inventory to sell
• Map data includes center coordinates and scale
• Player location is real-time when online

Related

• Economy API - Balance and transactions
• Shop API - Purchase items
• Admin API - Admin player management