Skip to content
Thorium Docs

Players

All paths are relative to https://api.thorium.ac/api/v1 and need Authorization: Bearer thor_.... See the overview for paging, rate limits and errors.

The player object

Returned by the list and detail endpoints:

{
  "id": "0f6e2c1a-8b4d-4e57-9a3c-2d1f7b6e5a90",
  "steamId": "",
  "minecraftUuid": "069a79f4-44e9-4726-a5be-fca90e38aaf5",
  "username": "Notch",
  "firstSeenAt": "2026-08-02T14:11:09.412Z",
  "lastSeenAt": "2026-09-28T17:52:40.018Z",
  "trustScore": 72.5,
  "alertCount": 14,
  "isFlagged": true,
  "isBanned": false
}
FieldMeaning
idThorium’s id for this player on your network. Use it in paths.
steamIdEmpty for Minecraft players.
minecraftUuidThe Minecraft account UUID.
usernameMost recently seen name.
trustScore0 to 100. Starts at 100 and drops with each detection.
alertCountDetections recorded for this player.
isFlaggedHas been detected at least once.
isBannedBanned through Thorium. See ban a player.

List players

GET /players/paginated · scope ViewPlayers

QueryDefaultMeaning
orgIdrequiredNetwork id
page, pageSize1, 50pageSize max 100
searchUsername (word match), or an exact Minecraft UUID
statusallflagged (detected, not banned), banned or clear (never detected, not banned)
sortlastSeenplayer, detections, status, firstSeen or lastSeen
dirdescasc or desc
Terminal window
curl -s -H "Authorization: Bearer $THORIUM_API_KEY" \
  "https://api.thorium.ac/api/v1/players/paginated?orgId=$ORG_ID&status=flagged&sort=detections&pageSize=2"
{
  "players": [
    {
      "id": "0f6e2c1a-8b4d-4e57-9a3c-2d1f7b6e5a90",
      "steamId": "",
      "minecraftUuid": "069a79f4-44e9-4726-a5be-fca90e38aaf5",
      "username": "Notch",
      "firstSeenAt": "2026-08-02T14:11:09.412Z",
      "lastSeenAt": "2026-09-28T17:52:40.018Z",
      "trustScore": 72.5,
      "alertCount": 14,
      "isFlagged": true,
      "isBanned": false
    },
    {
      "id": "7c3b9e10-2f4a-4d88-b1e6-93a0c5d2f814",
      "steamId": "",
      "minecraftUuid": "853c80ef-3c37-49fd-aa49-938b674adae6",
      "username": "jeb_",
      "firstSeenAt": "2026-09-01T09:30:00.000Z",
      "lastSeenAt": "2026-09-28T16:03:12.551Z",
      "trustScore": 88,
      "alertCount": 6,
      "isFlagged": true,
      "isBanned": false
    }
  ],
  "pagination": {
    "currentPage": 1,
    "pageSize": 2,
    "totalPlayers": 31,
    "totalPages": 16,
    "hasNextPage": true,
    "hasPreviousPage": false
  }
}

Returns 404 with { "message": "No servers found for the specified organization." } if the network has no servers yet.

Get a player

GET /players/{playerId} · scope ViewPlayers

Returns the player and their detections within your plan’s history window, newest first.

Terminal window
curl -s -H "Authorization: Bearer $THORIUM_API_KEY" \
  "https://api.thorium.ac/api/v1/players/0f6e2c1a-8b4d-4e57-9a3c-2d1f7b6e5a90?orgId=$ORG_ID"
{
  "player": {
    "id": "0f6e2c1a-8b4d-4e57-9a3c-2d1f7b6e5a90",
    "steamId": "",
    "minecraftUuid": "069a79f4-44e9-4726-a5be-fca90e38aaf5",
    "username": "Notch",
    "firstSeenAt": "2026-08-02T14:11:09.412Z",
    "lastSeenAt": "2026-09-28T17:52:40.018Z",
    "trustScore": 72.5,
    "alertCount": 14,
    "isFlagged": true,
    "isBanned": false
  },
  "alerts": [
    {
      "id": "9a1d0a0e-2f3b-5c4d-8e6f-0123456789ab",
      "alertType": "MCSpeed",
      "count": 3,
      "acknowledged": false,
      "acknowledgedReason": "",
      "createdAt": "2026-09-28T17:50:02.114Z",
      "updatedAt": "2026-09-28T17:51:40.902Z",
      "sessionId": "e41b6c7d-0a92-4f3e-8d15-6b2c9f0e7a31",
      "serverId": "11111111-2222-4333-8444-555555555555",
      "serverName": "Survival"
    }
  ]
}

alerts uses the same fields as the detection object, without the player fields. 404 Player not found. if the id is not on this network.

Count players

GET /players/count · scope ViewPlayers

Terminal window
curl -s -H "Authorization: Bearer $THORIUM_API_KEY" \
  "https://api.thorium.ac/api/v1/players/count?orgId=$ORG_ID"
{ "count": 1843 }

Online players

GET /players/online · scope ViewPlayers

Players with an open session right now.

Terminal window
curl -s -H "Authorization: Bearer $THORIUM_API_KEY" \
  "https://api.thorium.ac/api/v1/players/online?orgId=$ORG_ID"
{
  "players": [
    {
      "playerId": "0f6e2c1a-8b4d-4e57-9a3c-2d1f7b6e5a90",
      "username": "Notch",
      "minecraftUuid": "069a79f4-44e9-4726-a5be-fca90e38aaf5",
      "serverId": "11111111-2222-4333-8444-555555555555",
      "serverName": "Survival",
      "connectedAt": "2026-09-28T17:31:07.000Z"
    }
  ]
}

Sessions

GET /players/sessions · scope ViewPlayers

Every connection a player has made, newest first.

QueryMeaning
orgIdNetwork id
playerIdPlayer id
Terminal window
curl -s -H "Authorization: Bearer $THORIUM_API_KEY" \
  "https://api.thorium.ac/api/v1/players/sessions?orgId=$ORG_ID&playerId=0f6e2c1a-8b4d-4e57-9a3c-2d1f7b6e5a90"
{
  "sessions": [
    {
      "id": "e41b6c7d-0a92-4f3e-8d15-6b2c9f0e7a31",
      "serverId": "11111111-2222-4333-8444-555555555555",
      "serverName": "Survival",
      "connectedAt": "2026-09-28T17:31:07.000Z",
      "disconnectedAt": null,
      "isCracked": false
    }
  ]
}

disconnectedAt is null while the session is open. isCracked is true when the server runs in offline mode and the player’s identity was never verified by Mojang.

Activity

GET /players/{playerId}/activity · scope ViewPlayers

What a player did: blocks broken and placed, kills, deaths, shots, item use and so on, newest first. Recorded only while Advanced Analytics is on for the network, and read within your plan’s history window.

QueryDefaultMeaning
orgIdrequiredNetwork id
kindallOne of block_break, block_place, kill, death, shoot, projectile, item_use, consume, drop, pickup, craft, fish, enchant
page, pageSize1, 50pageSize max 200
Terminal window
curl -s -H "Authorization: Bearer $THORIUM_API_KEY" \
  "https://api.thorium.ac/api/v1/players/0f6e2c1a-8b4d-4e57-9a3c-2d1f7b6e5a90/activity?orgId=$ORG_ID&kind=kill&pageSize=1"
{
  "items": [
    {
      "ts": "2026-09-28T17:44:19.250Z",
      "kind": "kill",
      "subject": "PLAYER",
      "detail": "DIAMOND_SWORD",
      "serverId": "11111111-2222-4333-8444-555555555555",
      "world": "world",
      "x": 128.4,
      "y": 64,
      "z": -311.7,
      "amount": 1,
      "session": {
        "id": "e41b6c7d-0a92-4f3e-8d15-6b2c9f0e7a31",
        "username": "Notch",
        "cracked": false
      },
      "target": {
        "playerId": "7c3b9e10-2f4a-4d88-b1e6-93a0c5d2f814",
        "sessionId": "2b7e4f19-6c3d-4a80-9e52-1f0d8c7b6a43",
        "username": "jeb_",
        "uuid": "853c80ef-3c37-49fd-aa49-938b674adae6",
        "cracked": false
      }
    }
  ],
  "total": 12,
  "page": 1,
  "pageSize": 1
}

subject and detail depend on kind and use Bukkit names: for a kill, subject is the victim’s entity type and detail the weapon. target is null unless another player was involved. Paging here is total, page and pageSize rather than a pagination object.

Ban a player

PATCH /players/ban/{playerId} · scope AddBans

Bans the player from every server on the network. If they are online they are removed at once; if not, the ban is applied the next time they join any of your servers. The body is the reason as a bare JSON string, up to 500 characters.

Terminal window
curl -s -X PATCH \
  -H "Authorization: Bearer $THORIUM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '"Confirmed killaura in replay 9a1d0a0e"' \
  "https://api.thorium.ac/api/v1/players/ban/0f6e2c1a-8b4d-4e57-9a3c-2d1f7b6e5a90?orgId=$ORG_ID"
{ "message": "Player has been banned." }

The server applies the ban the same way as an automatic one: its ban-command if one is configured, otherwise the server’s own ban list. Bans made by staff apply even when the plugin runs with enforce: false, but not on the Free plan, which never kicks or bans.

400 if the reason is empty or too long, 404 Player not found. if the id is not on this network.

Kick a player

PATCH /players/kick/{playerId} · scope AddBans

Disconnects a player who is online now. They can rejoin. The body is the reason as a bare JSON string, up to 500 characters; it is shown to the player.

Terminal window
curl -s -X PATCH \
  -H "Authorization: Bearer $THORIUM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '"Spamming chat"' \
  "https://api.thorium.ac/api/v1/players/kick/0f6e2c1a-8b4d-4e57-9a3c-2d1f7b6e5a90?orgId=$ORG_ID"
{ "message": "Player has been kicked." }

409 with { "message": "That player is not online right now." } if they are not on any of your servers.

Unban a player

PATCH /players/unban/{playerId} · scope ManageBans

No body. Lifts the ban in Thorium and on every server of the network that is connected at the time: each runs its unban-command if one is configured, otherwise removes the player from its own ban list. A server that is offline when you unban keeps its entry until you lift it there (for example /pardon <name>).

Terminal window
curl -s -X PATCH -H "Authorization: Bearer $THORIUM_API_KEY" \
  "https://api.thorium.ac/api/v1/players/unban/0f6e2c1a-8b4d-4e57-9a3c-2d1f7b6e5a90?orgId=$ORG_ID"
{ "message": "Player has been unbanned." }