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.
Endpoints
https://api.mcsrranked.com/
https://mcsrranked.com/api/
You can use both, but we recommend using the first one.
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.
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.
401 Wrong Parameters
JSON response when incorrect parameters are provided. The data of the API response will explain what went wrong.
429 Too Many Requests
JSON response when an API request exceeds the ratelimit.
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 Elo rank |
| 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
Advanced parameters are only available with /matches/{match_id} endpoint.
| Parameter |
Type |
Description |
| id |
String |
|
| 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 |
Whether the match has decayed |
| 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 |
Integer Date
Displays a specific date as an epoch time (timestamp) in seconds. (NOT milliseconds!)
Integer Time
Displays a specific duration in milliseconds.