MCSR Ranked Rest API Documentation
All endpoints have a ratelimit of 500 requests per 10 minutes unless otherwise specified.
If you want to use an API Key with an expanded ratelimit, please make a #ticket in our Discord Server.
If you want to use an API Key with an expanded ratelimit, please make a #ticket in our Discord Server.
Endpoints
https://api.mcsrranked.com/
https://mcsrranked.com/api/
https://status.mcsrranked.com/ (Status Page endpoint only)
You can use both, but we recommend using the first one because it has a shorter cache period.
Responses from
The Status Page endpoint is served separately from
OpenAPI YAML
Responses from
https://api.mcsrranked.com are cached for 5 seconds, except GET /users/{identifier}/live, which is not cached. Responses from https://mcsrranked.com/api are cached for 30 seconds.The Status Page endpoint is served separately from
https://status.mcsrranked.com. See the human-readable status page for incidents and maintenance details.OpenAPI YAML
Get Service Heartbeats
Returns the 100 most recent public heartbeats for each service on the MCSR Ranked status page, plus each service's rolling 24-hour uptime ratio.
Monitor IDs currently map to 2 Game Server, 3 API, 4 Store, and 5 Wiki. Heartbeat status values are 0 down, 1 up, 2 pending, and 3 maintenance.
GET https://status.mcsrranked.com/api/status-page/heartbeat/mcsrranked
This endpoint has no parameters.
Response Type
| Parameter | Type | Description |
|---|---|---|
| heartbeatList.{monitorId}[] | StatusHeartbeat[] | Heartbeat history keyed by monitor ID, ordered oldest to newest and limited to 100 entries per monitor |
| heartbeatList.{monitorId}[].status | Integer | 0 down, 1 up, 2 pending, or 3 maintenance |
| heartbeatList.{monitorId}[].time | String | Heartbeat time in YYYY-MM-DD HH:mm:ss format |
| heartbeatList.{monitorId}[].msg | String | Public message; currently redacted to an empty string |
| heartbeatList.{monitorId}[].ping | Number? | Response time in milliseconds, or null when unavailable |
| uptimeList.{monitorId}_24 | Number | Rolling 24-hour uptime as a ratio from 0 to 1 |
Show Sample Response
{
"heartbeatList": {
"2": [
{
"status": 1,
"time": "2026-07-21 13:11:27",
"msg": "",
"ping": 85
}
]
},
"uptimeList": {
"2_24": 1
}
}Authentication
Many of the endpoints do not require authentication. To get a key for those that do, open an MCSR Ranked instance, go to Profile → Settings → Generate & Copy API Private Key.
That key can then be passed in a Private-Key header.
200 Success Response
JSON response when an API request is successfully processed.
Response Type
Sample Response
400 Data Not Found
JSON response when there's no data. However, as an exception, array type returns an empty array instead of this error.
Response Type
Sample Response
401 Wrong Parameters
JSON response when incorrect parameters are provided. The data of the API response will explain what went wrong.
Response Type
Sample Response
429 Too Many Requests
JSON response when an API request exceeds the ratelimit.
Response Type
Sample Response
Class UserProfile
| Parameter | Type | Description |
|---|---|---|
| uuid | String |
User's UUID |
| nickname | String |
User's nickname |
| roleType | Integer |
User's role type |
| eloRate | Integer? |
User's Elo rate. It is null if the user hasn't finished placement matches. |
| eloRank | Integer? |
User's leaderboard rank. It is null if the user hasn't finished placement matches. |
| country | String? |
User's country code in lowercased ISO 3166-1 alpha-2 format. |
Class Achievement
| Parameter | Type | Description |
|---|---|---|
| id | String |
Achievement Identifier |
| date | Date |
Timestamp of when the achievement was earned |
| data | String[] |
Additional data array |
| level | Integer |
Level of achievement |
| value | Integer? |
Contains the current player's progression of the achievement. It is null if the achievement is not a leveling one. |
| goal | Integer? |
Next level goal of the achievement. It is null if the achievement is at max level or not a leveling one. |
Class MatchInfo
| Parameter | Type | Description |
|---|---|---|
| id | Integer |
|
| type | MatchType |
|
| season | Integer |
|
| category | String? |
Match completions category. Default is ANY |
| date | Date |
|
| players | UserProfile[] |
|
| spectators | UserProfile[] |
|
| seed | MatchSeed? |
Seed ID if it's a ranked filtered seed. This is not the seed number. It is null if the seed is not filtered. |
| result.uuid | String? |
Winner's UUID. It is null if the match was a draw. |
| result.time | Time |
|
| forfeited | Boolean |
Whether the match has no completions |
| decayed | Boolean |
Indicates a synthetic match inserted to simulate rank decay due to inactivity, rather than a real match |
| rank.season | Integer? |
Record rank of the match's season |
| rank.allTime | Integer? |
Record rank of all-time |
| changes[].uuid | String |
UUID of player |
| changes[].change | Integer? |
Amount of changed Elo rate. It is null if the match is a placement. |
| changes[].eloRate | Integer? |
Elo rate of the player. It is null if the match is a placement. |
| tag | String? |
Special tag of this match. Used to get matches by tag. |
| beginner | Boolean |
Whether beginner mode is enabled in the match. |
| vod[].uuid | String |
UUID of VOD owner. Only players with public stream activated will be included. |
| vod[].url | String |
VOD URL of this match |
| vod[].startsAt | Date |
VOD start date. You can get a timestamp with {date} - {vod[].startsAt} |
| completions[].uuid | String |
(Advanced) Player uuid of completion |
| completions[].time | Time |
(Advanced) Match time of completion |
| timelines[].uuid | String |
(Advanced) Player uuid of timeline |
| timelines[].time | Time |
(Advanced) Match time of timeline |
| timelines[].type | String |
(Advanced) Identifier of timeline |
| replayExist | Boolean |
(Advanced) Whether the match replay exists in the server |
Class MatchSeed
| Parameter | Type | Description |
|---|---|---|
| id | String? |
Seed id if it's a ranked filtered seed. This is not the seed number. It is null if the seed is not filtered. |
| overworld | String? |
Overworld structure type of the seed. It is null if the seed is not filtered. |
| nether | String? |
Bastion remnants type of the seed. It is null if the seed is not filtered. |
| endTowers | Integer[] |
The zero related tower heights of in The End dimension. It is an empty array if the seed is not filtered. |
| variations | String[] |
Noticeable variations of the seed. It is an empty array if the seed is not filtered. |
String UserIdentifier
Identifier used when getting user information. You must use one of the formats below.
| Type | Description | Example |
|---|---|---|
| UUID | UUID of User. You can also use it with dashes (-). |
bbc886da1b024739b4b80f1542e9f61d |
| Nickname | Nickname of User. It is not case-sensitive. | RED_LIME |
| Discord ID | Linked Discord ID (Snowflake) of User. Must be discord.[ID] format. |
discord.338669823167037440 |
Integer MatchType
| Value | Description |
|---|---|
1 |
Casual Match |
2 |
Ranked Match |
3 |
Private Room Match |
4 |
Event Mode Match |