OpenAPI 3.1.1

MPRTiers API v2

Public API documentation for the version 2 surface. V1 at /api/v1/* is deprecated and should be treated as transitional only.

Base URL

https://mpr.choice21.site/api/v2

Gamemode

Gamemode Endpoints

Ladder discovery, overall standings, and per-gamemode tier boards.

GET/mode/list

List all available gamemodes.

None

Object keyed by gamemode slug with title, info_text, kit_image, and discord_url.

GET/mode/overall?count={0-50}&from={0+}

List overall rankings sorted by points.

`count` is required. `from` is optional and defaults to 0.

Array of overall player objects including rankings maps.

GET/mode/{gamemode}?count={0-50}&from={0+}

List active rankings for a gamemode.

`count` is required. Returns up to `count` players for each tier bucket.

Object keyed by tier number (`1` through `5`) with arrays of players in each tier.

GET/mode/{gamemode}/retired?count={0-50}&from={0+}

List retired rankings for a gamemode.

Same pagination rules as the active gamemode route.

Object keyed by tier number with retired players only.

Player

Player Endpoints

Profile lookup by Minecraft UUID, username, or Discord ID.

GET/profile/{uuid}

Retrieve a full player profile.

Optional flag params: `tests`, `badges`.

Player object with points, overall rank, rankings map, and optional test history.

GET/profile/{uuid}/rankings

Retrieve just the player rankings map.

Path param only.

Object keyed by gamemode slug with ranking objects.

GET/profile/by-name/{name}

Lookup a profile by Java username.

Optional flag params: `tests`, `badges`.

Same player object shape as `/profile/{uuid}`.

GET/profile/by-discord/{discord_id}

Lookup a profile by linked Discord ID.

Optional flag params: `tests`, `badges`.

Same player object shape as `/profile/{uuid}`.

Tests

Tests Endpoints

Tester history and recent public results.

GET/tests/{uuid}?count={0-50}&from={0+}&gamemode={slug}

Get tester history by Minecraft UUID.

`count` is required. `from` and `gamemode` are optional.

Array of test result objects with the tested player attached.

GET/tests/recent?count={0-20}&gamemode={slug}

Get the most recent tests.

`count` is required. `gamemode` is optional.

Array of recent test objects with player and tester data.

GET/tests/recent/high?count={0-20}&gamemode={slug}

Get the most recent high-tier tests.

Same params as `/tests/recent` but filtered to tiers 1-2.

Array of recent high-tier test objects.

Examples

Quick request samples

GET https://mpr.choice21.site/api/v2/mode/list

GET https://mpr.choice21.site/api/v2/mode/overall?count=25&from=0

GET https://mpr.choice21.site/api/v2/mode/vanilla?count=10&from=0

GET https://mpr.choice21.site/api/v2/profile/by-name/choice21?tests&badges

GET https://mpr.choice21.site/api/v2/tests/recent/high?count=10&gamemode=uhc

Schemas

Core payload shapes

Player

{ uuid, name, region, points, overall, discord_id, rankings, badges, tests }

Ranking

{ tier, pos, peak_tier, peak_pos, attained, retired }

Test

{ player?, gamemode, at, result_tier, result_pos, prev_tier, prev_pos, tester? }

Gamemode

{ title, info_text, kit_image, discord_url }

Errors

Shared error objects

Invalid request parameters return { code: "error.bad_request", message }.

Invalid gamemode requests return { code: "error.invalid_gamemode", message: null }.

Server failures return { code: "error.internal", message }.

Profile lookup routes return a bare 404 when the player does not exist.