Player Find Endpoints

Search for and discover Minecraft players across the network. All endpoints require authentication and specific Patreon tiers.

Overview Authentication Endpoints Rate Limiting Examples

Authentication Required

All endpoints require user authentication and specific Patreon tier access:

  • VIP Treatment - Highest tier, grants access to all endpoints
  • Advanced API Access - Mid tier, grants access to most endpoints
  • Admins - Bypass tier requirements
GET /players/find/uuid/:uuid AUTH

Required Tier: VIP Treatment or Advanced API Access

Find a player by their UUID. Returns exact match with complete player history and connected servers.

URL Parameters

Parameter Type Description
uuid string The player's UUID (with or without hyphens)

Example Request

GET /api/v0.1/players/find/uuid/550e8400-e29b-41d4-a716-446655440000

Example Response

{
  "success": true,
  "player": {
    "uuid": "550e8400-e29b-41d4-a716-446655440000",
    "current_username": "PlayerName",
    "name_history": [
      {
        "uuid": "550e8400-e29b-41d4-a716-446655440000",
        "username": "OldName",
        "changed_at": "2025-06-15T10:30:00Z"
      }
    ],
    "connected_servers": [
      {
        "address": "play.example.com",
        "port": 25565,
        "name": "Example Server"
      },
      {
        "address": "mc.another.com",
        "port": 25565,
        "name": "Another Server"
      }
    ]
  }
}
GET /players/find/name/:username[/partial] AUTH

Required Tier: VIP Treatment or Advanced API Access

Find players by username. Supports exact match or partial/fuzzy matching. Add /partial to the URL for fuzzy search.

URL Parameters

Parameter Type Description
username string The player's username (or partial username for fuzzy search)
/partial flag Optional. Add to URL path to enable fuzzy/partial matching

Example Requests

Exact match:

GET /api/v0.1/players/find/name/PlayerName

Partial/fuzzy match:

GET /api/v0.1/players/find/name/Player/partial

Example Response

{
  "success": true,
  "count": 3,
  "searchType": "exact",
  "players": [
    {
      "uuid": "550e8400-e29b-41d4-a716-446655440000",
      "current_username": "PlayerName",
      "name_history": [
        {
          "uuid": "550e8400-e29b-41d4-a716-446655440000",
          "username": "OldName",
          "changed_at": "2025-06-15T10:30:00Z"
        }
      ],
      "connected_servers": [
        {
          "address": "play.example.com",
          "port": 25565,
          "name": "Example Server"
        }
      ]
    }
  ]
}
GET /players/find/multi-server/:minServers AUTH

Required Tier: VIP Treatment

Find highly active players who have connected to a minimum number of distinct servers. Perfect for discovering prolific community members.

URL Parameters

Parameter Type Description
minServers integer Minimum number of connected servers (e.g., 10 to find players with 10+ servers)

Example Request

GET /api/v0.1/players/find/multi-server/10

Example Response

{
  "success": true,
  "count": 42,
  "minServers": 10,
  "players": [
    {
      "uuid": "550e8400-e29b-41d4-a716-446655440000",
      "current_username": "ActivePlayer",
      "server_count": 15,
      "connected_servers": [
        {
          "address": "play.example.com",
          "port": 25565,
          "name": "Example Server 1"
        },
        {
          "address": "mc.another.com",
          "port": 25565,
          "name": "Example Server 2"
        }
      ]
    }
  ]
}