MCSR Ranked REST API

https://docs.mcsrranked.com/
Admin
MCSR Ranked REST API provides endpoints to access Minecraft Speedrunning Ranked data, including...
Tokens:8,533
Snippets:54
Trust Score:7.2
Update:1 month ago
Show doc for...
Tokens:
Raw
### GET /leaderboard

Source: https://docs.mcsrranked.com/openapi.yaml

Get the ELO leaderboard.

```APIDOC
## GET /leaderboard

### Description
Get elo leaderboard.

### Method
GET

### Endpoint
/leaderboard
```

--------------------------------

### GET /live

Source: https://docs.mcsrranked.com/openapi.yaml

Get online players and public live matches.

```APIDOC
## GET /live

### Description
Get online players and public live matches.

### Method
GET

### Endpoint
/live
```

--------------------------------

### GET /phase-leaderboard

Source: https://docs.mcsrranked.com/openapi.yaml

Get the season phase points leaderboard.

```APIDOC
## GET /phase-leaderboard

### Description
Get season phase points leaderboard.

### Method
GET

### Endpoint
/phase-leaderboard
```

--------------------------------

### GET /users/{identifier}/live

Source: https://docs.mcsrranked.com/openapi.yaml

Returns real-time match data from the private room the player is in.

```APIDOC
## GET /users/{identifier}/live

### Description
Returns real-time match data from the private room the player is in.

### Method
GET

### Endpoint
/users/{identifier}/live

### Parameters
#### Path Parameters
- **identifier** (string) - Required - The user identifier.
```

--------------------------------

### GET /record-leaderboard

Source: https://docs.mcsrranked.com/openapi.yaml

Get the season best time leaderboard.

```APIDOC
## GET /record-leaderboard

### Description
Get season best time leaderboard.

### Method
GET

### Endpoint
/record-leaderboard
```

--------------------------------

### GET /matches/{match_id}

Source: https://docs.mcsrranked.com/openapi.yaml

Get detailed information for a specific match.

```APIDOC
## GET /matches/{match_id}

### Description
Get match info.

### Method
GET

### Endpoint
/matches/{match_id}

### Parameters
#### Path Parameters
- **match_id** (string) - Required - The match identifier.
```

--------------------------------

### GET /matches

Source: https://docs.mcsrranked.com/openapi.yaml

Get recent matches based on various filters.

```APIDOC
## GET /matches

### Description
Get recent matches.

### Method
GET

### Endpoint
/matches
```

--------------------------------

### GET /users/{identifier1}/versus/{identifier2}

Source: https://docs.mcsrranked.com/openapi.yaml

Retrieves head-to-head statistics between two users.

```APIDOC
## GET /users/{identifier1}/versus/{identifier2}

### Description
Retrieves the versus statistics between two specified users.

### Method
GET

### Endpoint
/users/{identifier1}/versus/{identifier2}

### Parameters
#### Path Parameters
- **identifier1** (string) - Required - The first user's identifier.
- **identifier2** (string) - Required - The second user's identifier.

#### Query Parameters
- **season** (string) - Optional - The season to retrieve data for.
```

--------------------------------

### Service Heartbeat Sample Response

Source: https://docs.mcsrranked.com/

Example JSON response structure for the service heartbeat endpoint.

```json
{
    "heartbeatList": {
        "2": [
            {
                "status": 1,
                "time": "2026-07-21 13:11:27",
                "msg": "",
                "ping": 85
            }
        ]
    },
    "uptimeList": {
        "2_24": 1
    }
}
```

--------------------------------

### GET https://api.mcsrranked.com/phase-leaderboard

Source: https://docs.mcsrranked.com/

Returns the top 100 players ranked by their Phase Points.

```APIDOC
## GET https://api.mcsrranked.com/phase-leaderboard

### Description
Returns the top 100 players ranked by their Phase Points.

### Method
GET

### Endpoint
https://api.mcsrranked.com/phase-leaderboard

### Parameters
#### Query Parameters
- **season** (Integer) - Optional - Filter by season (default: current season number)
- **country** (String) - Optional - Filter by country (format: ISO 3166-1 alpha-2)
- **predicted** (Any) - Optional - Get predicted phase points leaderboard. Only works with the current season

### Response
#### Success Response (200)
- **phase.endsAt** (Date?) - Date the season ends. If target season is not current season it is null
- **phase.number** (Integer?) - Phase number of the season. If target season is not current season it is null
- **phase.season** (Integer) - Season number
- **users** (UserProfile[]) - List of users
- **users[].seasonResult.eloRate** (Integer) - Final Elo rate of player in target season
- **users[].seasonResult.eloRank** (Integer) - Final leaderboard rank of player in target season
- **users[].seasonResult.phasePoint** (Integer) - Final phase points of player in target season
- **users[].predPhasePoint** (Integer) - Predicted phase points of player for next phase
```

--------------------------------

### GET /users/{identifier}/matches

Source: https://docs.mcsrranked.com/openapi.yaml

Retrieves a list of matches for a specific user.

```APIDOC
## GET /users/{identifier}/matches

### Description
Retrieves a list of matches associated with a specific user.

### Method
GET

### Endpoint
/users/{identifier}/matches

### Parameters
#### Path Parameters
- **identifier** (string) - Required - The user's identifier.

#### Query Parameters
- **before** (integer) - Optional - Filter matches before this timestamp.
- **after** (integer) - Optional - Filter matches after this timestamp.
- **sort** (string) - Optional - Sort order for the matches.
- **count** (integer) - Optional - Number of matches to return.
- **matchType** (string) - Optional - Filter by match type.
- **season** (string) - Optional - Filter by season.
- **excludeDecay** (boolean) - Optional - Whether to exclude decay matches.
```

--------------------------------

### GET /users/{identifier}

Source: https://docs.mcsrranked.com/openapi.yaml

Retrieves profile data for a specific user.

```APIDOC
## GET /users/{identifier}

### Description
Retrieves the profile data for a specified user.

### Method
GET

### Endpoint
/users/{identifier}

### Parameters
#### Path Parameters
- **identifier** (string) - Required - The user's identifier.

#### Query Parameters
- **season** (string) - Optional - The season to retrieve data for.
```

--------------------------------

### GET /weekly-race

Source: https://docs.mcsrranked.com/openapi.yaml

Retrieves the current weekly race leaderboard.

```APIDOC
## GET /weekly-race

### Description
Get current weekly race leaderboard.

### Method
GET

### Endpoint
/weekly-race

### Response
#### Success Response (200)
- **WeeklyRaceResponse** (object) - Weekly race returned successfully.
```

--------------------------------

### GET /users/{identifier1}/versus/{identifier2}/matches

Source: https://docs.mcsrranked.com/openapi.yaml

Retrieves a list of matches between two specific users.

```APIDOC
## GET /users/{identifier1}/versus/{identifier2}/matches

### Description
Retrieves a list of matches played between two specific users.

### Method
GET

### Endpoint
/users/{identifier1}/versus/{identifier2}/matches

### Parameters
#### Path Parameters
- **identifier1** (string) - Required - The first user's identifier.
- **identifier2** (string) - Required - The second user's identifier.

#### Query Parameters
- **before** (integer) - Optional - Filter matches before this timestamp.
- **after** (integer) - Optional - Filter matches after this timestamp.
- **count** (integer) - Optional - Number of matches to return.
- **matchType** (string) - Optional - Filter by match type.
- **season** (string) - Optional - Filter by season.
```

--------------------------------

### GET https://api.mcsrranked.com/record-leaderboard

Source: https://docs.mcsrranked.com/

Returns the 100 fastest runs of a season.

```APIDOC
## GET https://api.mcsrranked.com/record-leaderboard

### Description
Returns the 100 fastest runs of a season.

### Method
GET

### Endpoint
https://api.mcsrranked.com/record-leaderboard

### Parameters
#### Query Parameters
- **season** (Integer) - Optional - Filter by season. If it's 0, it will default to the current season. If it's not defined, it combines all seasons.
- **distinct** (any?) - Optional - Whether to only get distinct runners. If enabled, only the fastest run of each runner is returned.

### Response
#### Success Response (200)
- **[].rank** (Integer) - Rank of the run
- **[].season** (Integer) - Season number
- **[].date** (Date) - Date of the run
- **[].id** (Integer) - Match ID
- **[].time** (Time) - Time of the run
- **[].user** (UserProfile) - User profile of the runner
- **[].seed** (MatchSeed) - Seed information
```

--------------------------------

### GET https://api.mcsrranked.com/users/{identifier}

Source: https://docs.mcsrranked.com/

Returns the entire profile data for a specified user identifier.

```APIDOC
## GET https://api.mcsrranked.com/users/{identifier}

### Description
Returns the entire profile data for the user specified by the identifier.

### Method
GET

### Endpoint
https://api.mcsrranked.com/users/{identifier}

### Parameters
#### Path Parameters
- **identifier** (UserIdentifier) - Required - The user's UUID, nickname, or Discord ID (formatted as discord.[ID]).

#### Query Parameters
- **season** (Integer) - Optional - Specific season match for statistics (default: current season number).

### Response
#### Success Response (200)
- **uuid** (String) - UUID (without Dashes)
- **nickname** (String) - User nickname
- **roleType** (Integer) - User role type
- **eloRate** (Integer?) - Elo rate of current season
- **eloRank** (Integer?) - Current season leaderboard rank
- **country** (String?) - Country code in lowercased ISO 3166-1 alpha-2 format
- **achievements.display** (Achievement[]) - Achievements displayed in-game
- **achievements.total** (Achievement[]) - Achievements not displayed in-game
- **timestamp.firstOnline** (Date) - Date of user's first connection
- **timestamp.lastOnline** (Date) - Date of user's last connection
- **timestamp.lastRanked** (Date) - Date of user's last ranked match
- **timestamp.nextDecay** (Date?) - Date of user's next decay time
```

--------------------------------

### GET /weekly-race/{id}

Source: https://docs.mcsrranked.com/openapi.yaml

Retrieves a specific weekly race leaderboard by its ID.

```APIDOC
## GET /weekly-race/{id}

### Description
Get a specific weekly race leaderboard.

### Method
GET

### Endpoint
/weekly-race/{id}

### Parameters
#### Path Parameters
- **id** (integer) - Required - Weekly race number.

### Response
#### Success Response (200)
- **WeeklyRaceResponse** (object) - Weekly race returned successfully.
```

--------------------------------

### GET https://api.mcsrranked.com/matches/{match_id}

Source: https://docs.mcsrranked.com/

Retrieves detailed information for a specific match by its ID.

```APIDOC
## GET https://api.mcsrranked.com/matches/{match_id}

### Description
Returns the detailed match info.

### Method
GET

### Endpoint
https://api.mcsrranked.com/matches/{match_id}

### Parameters
#### Path Parameters
- **match_id** (Integer) - Required - ID of the match

### Response
#### Success Response (200)
- **Object** (MatchInfo) - Detailed match information
```

--------------------------------

### GET https://api.mcsrranked.com/live

Source: https://docs.mcsrranked.com/

Retrieves the current online player count and a list of live matches with public streams.

```APIDOC
## GET https://api.mcsrranked.com/live

### Description
Returns the online playercount and live matches with public streams.

### Method
GET

### Endpoint
https://api.mcsrranked.com/live

### Response
#### Success Response (200)
- **players** (Integer) - Concurrent number of players connected to the server
- **liveMatches[].currentTime** (Time) - Current match time
- **liveMatches[].players** (UserProfile[]) - List of players with public stream enabled
- **liveMatches[].data.{UUID}.liveUrl** (String?) - Live stream URL of player
- **liveMatches[].data.{UUID}.timeline.time** (Time) - Match time of last player split update
- **liveMatches[].data.{UUID}.timeline.type** (String) - Timeline identifier of last player split update
```

--------------------------------

### GET /users/{identifier}/seasons

Source: https://docs.mcsrranked.com/openapi.yaml

Retrieves all season results for a specific user.

```APIDOC
## GET /users/{identifier}/seasons

### Description
Retrieves the complete season history for a specified user.

### Method
GET

### Endpoint
/users/{identifier}/seasons

### Parameters
#### Path Parameters
- **identifier** (string) - Required - The user's identifier.
```

--------------------------------

### GET https://api.mcsrranked.com/weekly-race/{id?}

Source: https://docs.mcsrranked.com/

Retrieves the weekly race information and the associated leaderboard for a specific week or the current week.

```APIDOC
## GET https://api.mcsrranked.com/weekly-race/{id?}

### Description
Returns Weekly Race info and leaderboard.

### Method
GET

### Endpoint
https://api.mcsrranked.com/weekly-race/{id?}

### Parameters
#### Path Parameters
- **id** (Integer) - Optional - Specific week number (default: current weekly race)

### Response
#### Success Response (200)
- **id** (Integer) - Week ID
- **seed.overworld** (String) - Overworld seed
- **seed.nether** (String) - Nether seed
- **seed.theEnd** (String) - The End seed
- **seed.rng** (String) - RNG seed
- **endsAt** (Date) - Race end date
- **leaderboard[].rank** (Integer) - Player rank
- **leaderboard[].player** (User) - Player object
- **leaderboard[].time** (Time) - Race time
- **leaderboard[].replayExist** (Boolean) - Whether a replay exists
```

--------------------------------

### GET https://api.mcsrranked.com/leaderboard

Source: https://docs.mcsrranked.com/

Retrieves the top 150 players on the leaderboard, filtered by season or country.

```APIDOC
## GET https://api.mcsrranked.com/leaderboard

### Description
Returns the top 150 players on the leaderboard, ranked by their Elo rate.

### Method
GET

### Endpoint
https://api.mcsrranked.com/leaderboard

### Parameters
#### Query Parameters
- **season** (Integer) - Optional - Specific season (default: current season number)
- **country** (String) - Optional - Specific country code with lowercased ISO 3166-1 alpha-2 format

### Response
#### Success Response (200)
- **season.startsAt** (Date) - Date of season start
- **season.endsAt** (Date) - Date of season end
- **season.number** (Integer) - Season number
- **users** (UserProfile[]) - List of users on the leaderboard
- **users[].seasonResult.eloRate** (Integer) - Final Elo rate of player
- **users[].seasonResult.eloRank** (Integer) - Final leaderboard rank of player
- **users[].seasonResult.phasePoint** (Integer) - Final phase points of player
```

--------------------------------

### Get Service Heartbeats Endpoint

Source: https://docs.mcsrranked.com/

Retrieves the 100 most recent public heartbeats and 24-hour uptime ratios for services.

```http
GET https://status.mcsrranked.com/api/status-page/heartbeat/mcsrranked
```

--------------------------------

### GET /api/status-page/heartbeat/mcsrranked

Source: https://docs.mcsrranked.com/openapi.yaml

Retrieves the 100 most recent public heartbeats for each service on the MCSR Ranked status page, plus each service's rolling 24-hour uptime ratio.

```APIDOC
## GET /api/status-page/heartbeat/mcsrranked

### Description
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.

### Method
GET

### Endpoint
/api/status-page/heartbeat/mcsrranked

### Response
#### Success Response (200)
- **StatusHeartbeatResponse** (object) - Public heartbeat history and 24-hour uptime ratios returned successfully.
```

--------------------------------

### Define CompletionEntry and TimelineEntry Schemas

Source: https://docs.mcsrranked.com/openapi.yaml

Defines basic structures for completion and timeline tracking.

```yaml
    CompletionEntry:
      type: object
      required:
        - uuid
        - time
      properties:
        uuid:
          type: string
        time:
          $ref: '#/components/schemas/Time'
    TimelineEntry:
      type: object
```

--------------------------------

### Define 400 Data Not Found Response Structure

Source: https://docs.mcsrranked.com/

Schema and sample for requests where no data is found, noting that arrays return empty lists instead.

```json
{
    status: string,
    data: null
}
```

```json
{
    "status": "error",
    "data": null
}
```

--------------------------------

### Define Leaderboard and Season Schemas

Source: https://docs.mcsrranked.com/openapi.yaml

Schema definitions for leaderboard seasons and user rankings.

```yaml
    LeaderboardSeason:
      type: object
      required:
        - startsAt
        - endsAt
        - number
      properties:
        startsAt:
          $ref: '#/components/schemas/Date'
        endsAt:
          $ref: '#/components/schemas/Date'
        number:
          type: integer
    UserProfileWithSeasonResult:
      allOf:
        - $ref: '#/components/schemas/UserProfile'
        - type: object
          required:
            - seasonResult
          properties:
            seasonResult:
              $ref: '#/components/schemas/SeasonStanding'
    Leaderboard:
      type: object
      required:
        - season
        - users
      properties:
        season:
          $ref: '#/components/schemas/LeaderboardSeason'
        users:
          type: array
          items:
            $ref: '#/components/schemas/UserProfileWithSeasonResult'
```

--------------------------------

### LiveMatch Schema Definition

Source: https://docs.mcsrranked.com/openapi.yaml

Defines the structure for live match state and player data.

```yaml
    LiveMatch:
      type: object
      required:
        - currentTime
        - players
        - data
      properties:
        currentTime:
          $ref: '#/components/schemas/Time'
        players:
          type: array
          items:
            $ref: '#/components/schemas/UserProfile'
        data:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/LiveMatchPlayerData'
```

--------------------------------

### Define Record and Weekly Race Schemas

Source: https://docs.mcsrranked.com/openapi.yaml

Schema definitions for individual record entries and weekly race leaderboards.

```yaml
    RecordLeaderboardEntry:
      type: object
      required:
        - rank
        - id
        - season
        - date
        - time
        - user
        - seed
      properties:
        rank:
          type: integer
        id:
          type: integer
        season:
          type: integer
        date:
          $ref: '#/components/schemas/Date'
        time:
          $ref: '#/components/schemas/Time'
        user:
          $ref: '#/components/schemas/UserProfile'
        seed:
          $ref: '#/components/schemas/MatchSeed'
    WeeklyRaceEntry:
      type: object
      required:
        - rank
        - player
        - time
        - replayExist
      properties:
        rank:
          type: integer
        player:
          $ref: '#/components/schemas/UserProfile'
        time:
          $ref: '#/components/schemas/Time'
        replayExist:
          type: boolean
    WeeklyRace:
      type: object
      required:
        - id
        - seed
        - endsAt
        - leaderboard
      properties:
        id:
          type: integer
        seed:
          $ref: '#/components/schemas/WeeklyRaceSeed'
        endsAt:
          $ref: '#/components/schemas/Date'
        leaderboard:
          type: array
          items:
            $ref: '#/components/schemas/WeeklyRaceEntry'
```

--------------------------------

### Define SeasonStanding and SeasonPhaseResult Schemas

Source: https://docs.mcsrranked.com/openapi.yaml

Defines the structure for season-specific standings and phase-based results.

```yaml
    SeasonStanding:
      type: object
      required:
        - eloRate
        - eloRank
        - phasePoint
      properties:
        eloRate:
          type: integer
        eloRank:
          type:
            - integer
            - 'null'
        phasePoint:
          type: integer
    SeasonPhaseResult:
      type: object
      required:
        - phase
        - eloRate
        - eloRank
        - point
      properties:
        phase:
          type: integer
        eloRate:
          type: integer
        eloRank:
          type: integer
        point:
          type: integer
```

--------------------------------

### Define UserDetails and UserSeasonSummary Schemas

Source: https://docs.mcsrranked.com/openapi.yaml

Defines complex user profile structures including statistics, achievements, and season summaries.

```yaml
    UserDetails:
      allOf:
        - $ref: '#/components/schemas/UserProfile'
        - type: object
          required:
            - achievements
            - timestamp
            - statistics
            - connections
            - seasonResult
            - weeklyRaces
          properties:
            achievements:
              type: object
              required:
                - display
                - total
              properties:
                display:
                  type: array
                  items:
                    $ref: '#/components/schemas/Achievement'
                total:
                  type: array
                  items:
                    $ref: '#/components/schemas/Achievement'
            timestamp:
              type: object
              required:
                - firstOnline
                - lastOnline
                - lastRanked
                - nextDecay
              properties:
                firstOnline:
                  $ref: '#/components/schemas/Date'
                lastOnline:
                  $ref: '#/components/schemas/Date'
                lastRanked:
                  $ref: '#/components/schemas/Date'
                nextDecay:
                  type:
                    - integer
                    - 'null'
            statistics:
              type: object
              required:
                - season
                - total
              properties:
                season:
                  $ref: '#/components/schemas/StatisticCategoryMap'
                total:
                  $ref: '#/components/schemas/StatisticCategoryMap'
            connections:
              type: object
              additionalProperties:
                $ref: '#/components/schemas/UserConnection'
            seasonResult:
              oneOf:
                - $ref: '#/components/schemas/SeasonResultDetailed'
                - type: 'null'
            weeklyRaces:
              type: array
              items:
                $ref: '#/components/schemas/WeeklyRaceResult'
    UserSeasonSummary:
      allOf:
        - $ref: '#/components/schemas/UserProfile'
        - type: object
          required:
            - seasonResults
          properties:
            seasonResults:
              type: object
              additionalProperties:
                $ref: '#/components/schemas/SeasonResultDetailed'
```

--------------------------------

### Define 200 Success Response Structure

Source: https://docs.mcsrranked.com/

Schema and sample for successful API requests.

```json
{
    status: string,
    data: object
}
```

```json
{
    "status": "success",
    "data": {}
}
```

--------------------------------

### Define Phase and Prediction Schemas

Source: https://docs.mcsrranked.com/openapi.yaml

Schema definitions for phase-specific leaderboard information and predicted points.

```yaml
    PhaseInfo:
      type: object
      required:
        - endsAt
        - number
        - season
      properties:
        endsAt:
          type:
            - integer
            - 'null'
        number:
          type:
            - integer
            - 'null'
        season:
          type: integer
    UserProfileWithPredictedPoints:
      allOf:
        - $ref: '#/components/schemas/UserProfileWithSeasonResult'
        - type: object
          required:
            - predPhasePoint
          properties:
            predPhasePoint:
              type: integer
    PhaseLeaderboard:
      type: object
      required:
        - phase
        - users
      properties:
        phase:
          $ref: '#/components/schemas/PhaseInfo'
        users:
          type: array
          items:
            $ref: '#/components/schemas/UserProfileWithPredictedPoints'
```

--------------------------------

### UserLiveData Schema Definition

Source: https://docs.mcsrranked.com/openapi.yaml

Defines the structure for real-time user match data.

```yaml
    UserLiveData:
      type: object
      required:
        - lastId
        - type
        - status
        - time
        - players
        - spectators
        - timelines
        - completions
      properties:
        lastId:
          type:
            - integer
            - 'null'
        type:
          $ref: '#/components/schemas/MatchType'
        status:
          type: string
          enum:
            - idle
            - counting
            - generate
            - ready
            - running
            - done
        time:
          $ref: '#/components/schemas/Time'
        players:
          type: array
          items:
            $ref: '#/components/schemas/UserProfile'
        spectators:
          type: array
          items:
            $ref: '#/components/schemas/UserProfile'
        timelines:
          type: array
          items:
            $ref: '#/components/schemas/TimelineEntry'
        completions:
          type: array
          items:
            $ref: '#/components/schemas/CompletionEntry'
```

--------------------------------

### Define Match-related Schemas

Source: https://docs.mcsrranked.com/openapi.yaml

Defines structures for match results, rankings, changes, and VOD information.

```yaml
    MatchResult:
      type: object
      required:
        - uuid
        - time
      properties:
        uuid:
          type:
            - string
            - 'null'
        time:
          $ref: '#/components/schemas/Time'
    MatchRank:
      type: object
      required:
        - season
        - allTime
      properties:
        season:
          type:
            - integer
            - 'null'
        allTime:
          type:
            - integer
            - 'null'
    MatchChange:
      type: object
      required:
        - uuid
        - change
        - eloRate
      properties:
        uuid:
          type: string
        change:
          type:
            - integer
            - 'null'
        eloRate:
          type:
            - integer
            - 'null'
    MatchVod:
      type: object
      required:
        - uuid
        - url
        - startsAt
      properties:
        uuid:
          type: string
        url:
          type: string
        startsAt:
          $ref: '#/components/schemas/Date'
```

--------------------------------

### Define 401 Wrong Parameters Response Structure

Source: https://docs.mcsrranked.com/

Schema and sample for requests with invalid parameters, where the data field contains error details.

```json
{
    status: string,
    data: string
}
```

```json
{
    "status": "error",
    "data": "invalid `type` query. it must be >= 0 or <= 3"
}
```

--------------------------------

### Define 429 Too Many Requests Response Structure

Source: https://docs.mcsrranked.com/

Schema and sample for rate-limited API requests.

```json
{
    status: string,
    data: string
}
```

```json
{
    "status": "error",
    "data": "Too many requests"
}
```

--------------------------------

### MatchInfo Schema Definition

Source: https://docs.mcsrranked.com/openapi.yaml

Defines the structure of a match, including players, spectators, results, and timeline data.

```yaml
    MatchInfo:
      type: object
      required:
        - id
        - type
        - season
        - date
        - players
        - spectators
        - result
        - forfeited
        - decayed
        - rank
        - changes
        - beginner
        - botSource
      properties:
        id:
          type: integer
        type:
          $ref: '#/components/schemas/MatchType'
        season:
          type: integer
        category:
          type:
            - string
            - 'null'
        gameMode:
          type:
            - string
            - 'null'
        date:
          $ref: '#/components/schemas/Date'
        players:
          type: array
          items:
            $ref: '#/components/schemas/UserProfile'
        spectators:
          type: array
          items:
            $ref: '#/components/schemas/UserProfile'
        seed:
          oneOf:
            - $ref: '#/components/schemas/MatchSeed'
            - type: 'null'
        result:
          $ref: '#/components/schemas/MatchResult'
        forfeited:
          type: boolean
        decayed:
          type: boolean
        rank:
          $ref: '#/components/schemas/MatchRank'
        changes:
          type: array
          items:
            $ref: '#/components/schemas/MatchChange'
        vod:
          type: array
          items:
            $ref: '#/components/schemas/MatchVod'
        completions:
          type: array
          items:
            $ref: '#/components/schemas/CompletionEntry'
        timelines:
          type: array
          items:
            $ref: '#/components/schemas/TimelineEntry'
        tag:
          type:
            - string
            - 'null'
        replayExist:
          type: boolean
        beginner:
          type: boolean
        botSource:
          type:
            - string
            - 'null'
        seedType:
          type:
            - string
            - 'null'
        bastionType:
          type:
            - string
            - 'null'
```

--------------------------------

### API Base URLs

Source: https://docs.mcsrranked.com/

The primary and secondary base URLs for accessing the MCSR Ranked API.

```text
https://api.mcsrranked.com/
```

```text
https://mcsrranked.com/api/
```

```text
https://status.mcsrranked.com/ (Status Page endpoint only)
```

--------------------------------

### Define SeasonResultDetailed and WeeklyRaceResult Schemas

Source: https://docs.mcsrranked.com/openapi.yaml

Defines the detailed season result object and the structure for individual weekly race results.

```yaml
    SeasonResultDetailed:
      type: object
      required:
        - last
        - highest
        - lowest
        - phases
      properties:
        last:
          $ref: '#/components/schemas/SeasonStanding'
        highest:
          type: integer
        lowest:
          type: integer
        phases:
          type: array
          items:
            $ref: '#/components/schemas/SeasonPhaseResult'
    WeeklyRaceResult:
      type: object
      required:
        - id
        - time
        - rank
      properties:
        id:
          type: integer
        time:
          $ref: '#/components/schemas/Time'
        rank:
          type: integer
```

--------------------------------

### VersusStats Schema Definition

Source: https://docs.mcsrranked.com/openapi.yaml

Defines the structure for versus statistics, including player results and changes.

```yaml
    VersusStats:
      type: object
      required:
        - players
        - results
        - changes
      properties:
        players:
          type: array
          items:
            $ref: '#/components/schemas/UserProfile'
        results:
          type: object
          required:
            - ranked
            - casual
          properties:
            ranked:
              $ref: '#/components/schemas/VersusResultMap'
            casual:
              $ref: '#/components/schemas/VersusResultMap'
        changes:
          type: object
          additionalProperties:
            type: integer
```

--------------------------------

### MCSR Ranked OpenAPI Specification

Source: https://docs.mcsrranked.com/openapi.yaml

The complete OpenAPI 3.1.0 definition for the MCSR Ranked REST API, including server configurations and path definitions.

```yaml
openapi: 3.1.0
info:
  title: MCSR Ranked API
  version: 1.0.0
  description: |
    OpenAPI description for the public MCSR Ranked REST API.

    All endpoints are limited to 500 requests per 10 minutes unless otherwise specified.
    If you need expanded rate limits, request an API key through the MCSR Ranked Discord server.

    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 primary server is recommended
    because it has a shorter cache period.

    All endpoints are public except `GET /users/{identifier}/live`, which requires a `Private-Key`
    header generated in-game.
servers:
  - url: https://api.mcsrranked.com
    description: Recommended production server; 5-second cache except for the live user endpoint
  - url: https://mcsrranked.com/api
    description: Alternate production server; 30-second cache
tags:
  - name: Users
  - name: Versus
  - name: Matches
  - name: Live
  - name: Leaderboards
  - name: Weekly Race
  - name: Status Page
paths:
  /users/{identifier}:
    get:
      tags:
        - Users
      summary: Get user data
      operationId: getUserData
      parameters:
        - $ref: '#/components/parameters/IdentifierParam'
        - $ref: '#/components/parameters/SeasonParam'
      responses:
        '200':
          description: User profile returned successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/WrongParameters'
        '429':
          $ref: '#/components/responses/TooManyRequests'
  /users/{identifier}/matches:
    get:
      tags:
        - Users
      summary: Get user matches
      operationId: getUserMatches
      parameters:
        - $ref: '#/components/parameters/IdentifierParam'
        - $ref: '#/components/parameters/BeforeParam'
        - $ref: '#/components/parameters/AfterParam'
        - $ref: '#/components/parameters/SortParam'
        - $ref: '#/components/parameters/CountParam'
        - $ref: '#/components/parameters/MatchTypeParam'
        - $ref: '#/components/parameters/SeasonParam'
        - $ref: '#/components/parameters/ExcludeDecayParam'
      responses:
        '200':
          description: User matches returned successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MatchListResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/WrongParameters'
        '429':
          $ref: '#/components/responses/TooManyRequests'
  /users/{identifier1}/versus/{identifier2}:
    get:
      tags:
        - Versus
      summary: Get versus stats
      operationId: getVersusStats
      parameters:
        - $ref: '#/components/parameters/Identifier1Param'
        - $ref: '#/components/parameters/Identifier2Param'
        - $ref: '#/components/parameters/SeasonParam'
      responses:
        '200':
          description: Versus statistics returned successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VersusResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/WrongParameters'
        '429':
          $ref: '#/components/responses/TooManyRequests'
  /users/{identifier1}/versus/{identifier2}/matches:
    get:
      tags:
        - Versus
      summary: Get versus matches
      operationId: getVersusMatches
      parameters:
        - $ref: '#/components/parameters/Identifier1Param'
        - $ref: '#/components/parameters/Identifier2Param'
        - $ref: '#/components/parameters/BeforeParam'
        - $ref: '#/components/parameters/AfterParam'
        - $ref: '#/components/parameters/CountParam'
        - $ref: '#/components/parameters/MatchTypeParam'
        - $ref: '#/components/parameters/SeasonParam'
      responses:
        '200':
          description: Versus matches returned successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MatchListResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/WrongParameters'
        '429':
          $ref: '#/components/responses/TooManyRequests'
  /users/{identifier}/seasons:
    get:
      tags:
        - Users
      summary: Get all user season results
      operationId: getUserSeasons
      parameters:
        - $ref: '#/components/parameters/IdentifierParam'
      responses:
        '200':
          description: User season history returned successfully.
          content:
            application/json:
```
Tokens:
Raw