CactusTiers API Docs

CactusTiers API

Official API for retrieving CactusTiers player profiles and rankings. This is a public, read-only REST API that returns JSON.

Note

The response format was updated recently (v0.8.0). Some fields may return null for older or incomplete profiles including uuid, premium, discord, and the peak_* / test_id fields on rankings. Always handle nullable values defensively.

Base URL

All endpoints are served from:

https://tiers.cactusmc.xyz

Authentication

No authentication is required. Endpoints are publicly accessible.

Get a player profile

GET/api/profile/{username}

Returns a player's profile and per-mode rankings.

Path parameters

Name	Type	Required	Description
username	string	required	Minecraft username (case-insensitive).

Example request

curl https://tiers.cactusmc.xyz/api/profile/CuteeCactus

200 — Player found

{
  "uuid": "2dbe2b00-b72a-4d4c-b1c3-9c8afe9257ba",
  "premium": true,
  "name": "CuteeCactus",
  "discord": "1307231505109618719",
  "region": "EU",
  "points": 132,
  "overall": 1,
  "tests": [
    {
      "test-id": 1,
      "taken-at": 1783535806,
      "type": "high",
      "previous-tier": "LT4",
      "attained-tier": "HT2",
      "tester": [
        { "tester-discord": "1523411311696937080", "tester-ign": "CactusTiersTest" },
        { "tester-discord": "1307231505109618719", "tester-ign": "c4cactus" }
      ],
      "gamemode": "sword"
    }
  ],
  "rankings": {
    "sword": {
      "display": "HT1",
      "tier": 1,
      "pos": 0,
      "peak_tier": 1,
      "peak_pos": 0,
      "attained": 1783596092,
      "peak_attained": 1783594352,
      "test_id": 5,
      "peak_test_id": 4,
      "retired": false
    }
  }
}

404 — Player not found

{
  "error": "Player not found"
}

Try it

Enter a Minecraft username to call the endpoint live.

Profile

Field	Type	Description
uuid	string \| null	Minecraft UUID with dashes.
premium	boolean \| null	Whether the account is premium.
name	string	Minecraft username.
discord	string \| null	Discord user ID.
region	AS \| PK \| NA \| EU \| ME	Player region.
points	integer	Total ranking points.
overall	integer	Global leaderboard position.
tests	TestEntry[]	Test history for the player.
rankings	map<string, Ranking>	Per-mode rankings keyed by mode ID.

TestEntry

Field	Type	Description
test-id	integer	Unique test identifier.
taken-at	integer (unix)	Timestamp when the test was taken.
type	string	Test type (high, migration, eval, etc.).
previous-tier	string	Tier before the test.
attained-tier	string	Tier attained from this test.
tester	Tester[]	Testers who administered the test.
gamemode	string	Gamemode for this test.
tier-list	string?	Source tier list for migration tests, if applicable.

Tester

Field	Type	Description
tester-discord	string	Discord user ID of the tester.
tester-ign	string	Minecraft username of the tester.

Ranking

Field	Type	Description
display	string	Original tier string (e.g. HT1, LT3, RHT2).
tier	integer (1–5)	Tier number.
pos	0 \| 1	0 = High Tier, 1 = Low Tier.
peak_tier	integer \| null	Best tier achieved.
peak_pos	0 \| 1 \| null	Best position achieved.
attained	integer \| null (unix)	Timestamp when tier was earned.
peak_attained	integer \| null (unix)	Timestamp when peak tier was earned.
test_id	integer \| null	ID of the test that earned this tier.
peak_test_id	integer \| null	ID of the test that earned the peak tier.
retired	boolean	Whether the ranking is retired.

Error

Field	Type	Description
error	string	Human-readable error message.