Servers and network

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.

Servers

The server endpoints take the network id as organizationId, not orgId.

The server object

{
  "id": "11111111-2222-4333-8444-555555555555",
  "name": "Survival",
  "organizationId": "5b1d8a52-3c1e-4f7a-9d2b-6e0c4a8f1b37",
  "createdAt": "2026-08-01T12:00:00.000Z",
  "isActive": true,
  "game": "Minecraft",
  "mcVersion": "1.21.11",
  "software": "Paper"
}

Field	Meaning
`isActive`	In the list: whether the server’s plugin is connected right now. In create and update responses: whether the server is enabled.
`game`	`Minecraft` (or `Rust` for legacy servers).
`mcVersion`, `software`	Reported by the plugin when it connects; `null` until then.

List servers

GET /servers?organizationId={orgId} · scope ViewServers

curl -s -H "Authorization: Bearer $THORIUM_API_KEY" \
  "https://api.thorium.ac/api/v1/servers?organizationId=$ORG_ID"

[
  {
    "id": "11111111-2222-4333-8444-555555555555",
    "name": "Survival",
    "organizationId": "5b1d8a52-3c1e-4f7a-9d2b-6e0c4a8f1b37",
    "createdAt": "2026-08-01T12:00:00.000Z",
    "isActive": true,
    "game": "Minecraft",
    "mcVersion": "1.21.11",
    "software": "Paper"
  },
  {
    "id": "a4c2e6f8-0b1d-4e3f-8a5c-7d9e1f3b5a70",
    "name": "Lobby",
    "organizationId": "5b1d8a52-3c1e-4f7a-9d2b-6e0c4a8f1b37",
    "createdAt": "2026-08-01T12:05:00.000Z",
    "isActive": false,
    "game": "Minecraft",
    "mcVersion": null,
    "software": null
  }
]

Register a server

POST /servers?organizationId={orgId} · scope ManageServers

Body field	Meaning
`serverName`	Required.
`game`	Optional, defaults to `Minecraft`.
`organizationId`	Optional. If sent it must match the query parameter.

curl -s -X POST \
  -H "Authorization: Bearer $THORIUM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"serverName": "Skyblock"}' \
  "https://api.thorium.ac/api/v1/servers?organizationId=$ORG_ID"

{
  "id": "c7e1a3b5-9d2f-4c6e-8b0a-1f3d5e7a9c2b",
  "name": "Skyblock",
  "organizationId": "5b1d8a52-3c1e-4f7a-9d2b-6e0c4a8f1b37",
  "createdAt": "2026-09-28T18:20:31.772Z",
  "isActive": true,
  "game": "Minecraft",
  "mcVersion": null,
  "software": null
}

No token is returned. Plugins authenticate with the network token under Networks → your network → Servers.

Plans that include the API have no server limit. 400 if serverName is missing, 403 if the body’s organizationId does not match the query.

Rename a server

PATCH /servers/{serverId}?organizationId={orgId}&serverName={name} · scope ManageServers

The new values are query parameters; there is no body.

Query	Meaning
`serverName`	New name. Omit to keep the current one.
`game`	`Minecraft` or `Rust`. Only allowed before the server’s plugin has ever connected.

curl -s -X PATCH -H "Authorization: Bearer $THORIUM_API_KEY" \
  "https://api.thorium.ac/api/v1/servers/c7e1a3b5-9d2f-4c6e-8b0a-1f3d5e7a9c2b?organizationId=$ORG_ID&serverName=Skyblock%20EU"

Returns the updated server object. 404 Server not found for an unknown id, 400 for a game change after the server has connected.

Plan and usage

GET /organizations/{orgId}/entitlement · scope ViewNetworks

curl -s -H "Authorization: Bearer $THORIUM_API_KEY" \
  "https://api.thorium.ac/api/v1/organizations/$ORG_ID/entitlement"

{
  "status": "Active",
  "planTier": 3,
  "planName": "Pro",
  "isTrial": false,
  "serverLimit": null,
  "serverCount": 4,
  "historyDays": 90,
  "retentionDays": 120,
  "features": {
    "spectate": true,
    "customWebhooks": true,
    "botCommands": true,
    "enforcement": true
  },
  "endsAt": "2026-10-28T00:00:00.000Z",
  "daysRemaining": 30,
  "unverified": false,
  "alertsPaused": false,
  "usage": {
    "playerLimit": 1000,
    "peakCcuToday": 212,
    "peakCcu30d": 388,
    "overDays": 0,
    "state": "Ok",
    "noticeAt": null,
    "gatedAt": null,
    "gateEffectiveAt": null,
    "enforced": true
  }
}

Field	Meaning
`status`	`Active`, `Trialing`, `Free`, or `None` (no plan chosen yet)
`planTier`	0 Free, 1 Starter, 2 Network, 3 Pro, 4 Scale, 5 Enterprise
`serverLimit`, `daysRemaining`, `usage.playerLimit`	`null` means unlimited
`endsAt`	End of the current trial or billing period
`usage.peakCcuToday`, `usage.peakCcu30d`	Peak concurrent players today and over 30 days
`usage.overDays`	Days in the last 30 over `playerLimit`
`usage.state`	`Ok`, `Warned` or `Gated`. While `Gated`, every API call returns `402 usage_gated`.

Dashboard stats

GET /organizations/{orgId}/stats · scope ViewNetworks

The numbers on the network dashboard: who is online where, and recent detections.

Query	Meaning
`since`	Optional. `detectionCount` counts detections created after this time. Omit to count the whole history window.

curl -s -H "Authorization: Bearer $THORIUM_API_KEY" \
  "https://api.thorium.ac/api/v1/organizations/$ORG_ID/stats?since=2026-09-28T00:00:00Z"

{
  "serverPlayerCounts": {
    "11111111-2222-4333-8444-555555555555": { "name": "Survival", "players": 184 },
    "a4c2e6f8-0b1d-4e3f-8a5c-7d9e1f3b5a70": { "name": "Lobby", "players": 28 }
  },
  "serversTotal": 4,
  "connectedBackends": 2,
  "onlinePlayers": 212,
  "detectionCount": 15,
  "lastFiveAlerts": [
    {
      "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",
      "playerUsername": "Notch",
      "playerSteamId": "",
      "playerUuid": "069a79f4-44e9-4726-a5be-fca90e38aaf5",
      "serverName": "Survival"
    }
  ]
}

serverPlayerCounts is keyed by server id and only lists servers with players online. connectedBackends is the number of server plugins connected right now.

Analytics

GET /organizations/{orgId}/analytics · scope ViewDetections

Detection trends: a daily series, and breakdowns by check and by server.

Query	Default	Meaning
`days`	30	1 to 90, and never further back than your plan’s history window
`serverId`	all	Only this server

curl -s -H "Authorization: Bearer $THORIUM_API_KEY" \
  "https://api.thorium.ac/api/v1/organizations/$ORG_ID/analytics?days=3"

{
  "since": "2026-09-26T00:00:00Z",
  "until": "2026-09-28T18:24:10.113Z",
  "days": 3,
  "history": { "days": 90, "retentionDays": 120 },
  "totals": {
    "detections": 54,
    "playersFlagged": 23,
    "acknowledged": 21,
    "bannedPlayers": 41
  },
  "daily": [
    { "date": "2026-09-26T00:00:00Z", "detections": 17, "playersFlagged": 9 },
    { "date": "2026-09-27T00:00:00Z", "detections": 22, "playersFlagged": 11 },
    { "date": "2026-09-28T00:00:00Z", "detections": 15, "playersFlagged": 8 }
  ],
  "byType": [
    { "type": "MCSpeed", "detections": 19, "players": 7 },
    { "type": "MCMultiAura", "detections": 12, "players": 5 }
  ],
  "byServer": [
    { "serverId": "11111111-2222-4333-8444-555555555555", "name": "Survival", "detections": 41 },
    { "serverId": "a4c2e6f8-0b1d-4e3f-8a5c-7d9e1f3b5a70", "name": "Lobby", "detections": 13 }
  ]
}

A detection counts once however many times it repeated (see count on the detection object). bannedPlayers is everyone currently banned, not only those banned inside the window. Days with no detections are included with zeros. A server deleted since is named "Deleted server".

Audit log

Everything members and API keys have done on the network. Reads made through the API are logged too, under the name of the member who created the key. These endpoints are not rate limited.

List entries

GET /audit/{orgId}/logs · scope ViewAuditLogs

Query	Default	Meaning
`page`, `pageSize`	1, 50	`pageSize` max 100
`startDate`, `endDate`		ISO 8601 bounds
`action`	all	Exact action, e.g. `banned_player`. See list actions.
`category`	all	`read` or `write`
`userId`	all	Only this member
`resourceType`	all	e.g. `Player`, `Alert`, `Server`
`search`		Free text

curl -s -H "Authorization: Bearer $THORIUM_API_KEY" \
  "https://api.thorium.ac/api/v1/audit/$ORG_ID/logs?category=write&pageSize=1"

{
  "items": [
    {
      "id": "3d5f7a9c-1e2b-4c6d-8f0a-2b4d6f8a0c1e",
      "userId": "8e2f4a6c-0d1b-4c3e-9a5f-7b9d1e3f5a2c",
      "userDisplayName": "Alex",
      "action": "banned_player",
      "category": "write",
      "resourceType": "Player",
      "resourceId": "0f6e2c1a-8b4d-4e57-9a3c-2d1f7b6e5a90",
      "details": "reason=Confirmed killaura in replay 9a1d0a0e",
      "isSudo": false,
      "ipAddress": "203.0.113.24",
      "createdAt": "2026-09-28T18:02:11.4410000Z"
    }
  ],
  "total": 386,
  "page": 1,
  "pageSize": 1,
  "totalPages": 386
}

isSudo is true when Thorium staff acted on the network through support access.

List actions

GET /audit/{orgId}/actions · scope ViewAuditLogs

Every distinct action recorded on the network, for building a filter.

["acknowledged_alert", "banned_player", "created_server", "dismissed_alert", "unbanned_player", "updated_server", "viewed_detections", "viewed_player_details", "viewed_player_sessions"]