Players API

Endpoints for managing players across your cluster.

List Players

Get all players in a cluster.

GET /api/v1/clusters/{clusterId}/players

Query Parameters

Parameter	Type	Description
page	number	Page number (default: 1)
limit	number	Results per page (default: 20, max: 100)
search	string	Search by username or Steam ID
online	boolean	Filter by online status
serverId	string	Filter by server
sort	string	Sort field: playtime, -playtime, lastSeen, etc.

Response

{
  "data": [
    {
      "id": "ply_123",
      "username": "PlayerOne",
      "steamId": "76561198012345678",
      "uuid": null,
      "playtime": 1234567,
      "firstSeen": "2024-01-01T00:00:00Z",
      "lastSeen": "2024-01-20T15:30:00Z",
      "online": true,
      "currentServer": {
        "id": "srv_xyz",
        "name": "ARK-Island"
      },
      "flags": ["VIP", "Donor"]
    }
  ],
  "meta": {
    "page": 1,
    "limit": 20,
    "total": 150,
    "totalPages": 8
  }
}

Get Player

Get detailed player information.

GET /api/v1/players/{playerId}

Response

{
  "id": "ply_123",
  "username": "PlayerOne",
  "steamId": "76561198012345678",
  "discordId": "123456789012345678",
  "playtime": 1234567,
  "firstSeen": "2024-01-01T00:00:00Z",
  "lastSeen": "2024-01-20T15:30:00Z",
  "sessions": [
    {
      "serverId": "srv_xyz",
      "serverName": "ARK-Island",
      "joinedAt": "2024-01-20T14:00:00Z",
      "leftAt": "2024-01-20T16:00:00Z",
      "duration": 7200
    }
  ],
  "purchases": [
    {
      "id": "pur_abc",
      "productName": "VIP Rank",
      "amount": 9.99,
      "createdAt": "2024-01-15T10:00:00Z"
    }
  ],
  "notes": [
    {
      "id": "note_xyz",
      "content": "Helpful player, active community member",
      "createdBy": "usr_admin",
      "createdAt": "2024-01-18T12:00:00Z"
    }
  ]
}

Get Server Players

Get currently online players on a specific server.

GET /api/v1/servers/{serverId}/players

Response

{
  "online": 12,
  "max": 50,
  "players": [
    {
      "id": "ply_123",
      "username": "PlayerOne",
      "steamId": "76561198012345678",
      "joinedAt": "2024-01-20T14:00:00Z",
      "ping": 45
    }
  ]
}

Update Player

Update player metadata.

PATCH /api/v1/players/{playerId}

Request Body

{
  "flags": ["VIP", "Moderator"],
  "notes": "Updated player information"
}

Response

{
  "id": "ply_123",
  "flags": ["VIP", "Moderator"],
  "updatedAt": "2024-01-20T15:30:00Z"
}

Kick Player

Kick player from server.

POST /api/v1/players/{playerId}/kick

Request Body

{
  "serverId": "srv_xyz",
  "reason": "Violation of server rules"
}

Response

{
  "success": true,
  "message": "Player kicked from ARK-Island"
}

Ban Player

Ban player from server or cluster.

POST /api/v1/players/{playerId}/ban

Request Body

{
  "serverId": "srv_xyz",
  "reason": "Cheating",
  "duration": 86400,
  "clusterWide": false
}

Field	Type	Description
serverId	string	Server to ban from (required if not cluster-wide)
reason	string	Ban reason
duration	number	Duration in seconds (null = permanent)
clusterWide	boolean	Ban from all servers in cluster

Response

{
  "success": true,
  "ban": {
    "id": "ban_abc",
    "playerId": "ply_123",
    "reason": "Cheating",
    "expiresAt": "2024-01-21T15:30:00Z",
    "clusterWide": false
  }
}

Unban Player

Remove ban from player.

DELETE /api/v1/bans/{banId}

Response

{
  "success": true,
  "message": "Ban removed"
}

Player Statistics

Get player statistics and analytics.

GET /api/v1/clusters/{clusterId}/players/stats

Response

{
  "total": 1523,
  "active": {
    "today": 234,
    "week": 567,
    "month": 892
  },
  "new": {
    "today": 12,
    "week": 45,
    "month": 123
  },
  "topPlayers": [
    {
      "id": "ply_123",
      "username": "PlayerOne",
      "playtime": 1234567
    }
  ],
  "retention": {
    "day1": 0.78,
    "day7": 0.45,
    "day30": 0.23
  }
}

Next Steps

• Authentication
• API Endpoints
• Players Concept