TECHNICAL INTEGRATION SPECIFICATION

Ladder Tournament External API

Access Ladder Tournament data — ranking, player statistics, season results and casted videos — ready to integrate into your site, bot or stats tool. Choose an API in the menu.

V1.0 EXTERNAL REST · JSON API KEY AUTH

GETTING STARTED · AUTHENTICATION

Authentication

Every endpoint of the External API requires a valid API key sent in the HTTP request header. The same token works for all routes.

Header	Type	Value example
`X-Api-Token`	string	`XXXXXXX`

! Keep your token private. Never expose it in public front-end code or repositories; call the API from your server.

RANKING LADDER · ENDPOINT

Ranking Ladder

Player statistics, season results and division winners, with pagination and optional filters by player and season.

GET https://laddertournament.com.br:8099/api/external/ranking_ladder

RANKING LADDER · QUERY PARAMETERS

Query Parameters

Pagination is controlled through parameters passed in the URL query string. page and pageSize are required on every request; relicid and seasonid are optional filters.

Parameter	Type	Required	Default	Description
`page`	integer	YES	—	Index of the target page to retrieve (minimum: 1).
`pageSize`	integer	YES	—	Number of records returned per page (maximum allowed: 1000).
`relicid`	integer	NO	—	Filters the result by a specific player (Relic ID). When omitted, all players are returned.
`seasonid`	integer	NO	—	Filters the result by a specific season. When omitted, all seasons are returned.

1

Minimum value for page (required).

500

Suggested pageSize (required) — records returned per page.

1000

Maximum pageSize allowed per request.

hasNext

Keep requesting the next page while it is true to fetch every record.

Optional filters · relicid / seasonid

# Filter by player
curl --location 'https://laddertournament.com.br:8099/api/external/ranking_ladder?page=1&pageSize=500&relicid=366826' \
  --header 'X-Api-Token: XXXXXXX'

# Filter by season
curl --location 'https://laddertournament.com.br:8099/api/external/ranking_ladder?page=1&pageSize=500&seasonid=1' \
  --header 'X-Api-Token: XXXXXXX'

# Both filters combined
curl --location 'https://laddertournament.com.br:8099/api/external/ranking_ladder?page=1&pageSize=500&seasonid=1&relicid=366826' \
  --header 'X-Api-Token: XXXXXXX'

RANKING LADDER · USAGE EXAMPLE

Usage Example

Send a GET request with your token in the X-Api-Token header. Pick your language below.

curl --location 'https://laddertournament.com.br:8099/api/external/ranking_ladder?page=1&pageSize=500' \
  --header 'X-Api-Token: XXXXXXX'

const url = 'https://laddertournament.com.br:8099/api/external/ranking_ladder?page=1&pageSize=500';

const res = await fetch(url, {
  headers: { 'X-Api-Token': 'XXXXXXX' }
});

if (!res.ok) throw new Error(`HTTP ${res.status}`);
const data = await res.json();
console.log(data.items);

import requests

url = "https://laddertournament.com.br:8099/api/external/ranking_ladder"
headers = {"X-Api-Token": "XXXXXXX"}
params = {"page": 1, "pageSize": 500}
# optional filters:
# params["relicid"] = 366826   → only this player
# params["seasonid"] = 1       → only this season

r = requests.get(url, headers=headers, params=params, timeout=15)
r.raise_for_status()
for p in r.json()["items"]:
    print(p["relicid"], p["wins"], p["losses"], p["rating"])

<?php
$ch = curl_init('https://laddertournament.com.br:8099/api/external/ranking_ladder?page=1&pageSize=500');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER     => ['X-Api-Token: XXXXXXX'],
]);
$data = json_decode(curl_exec($ch), true);
curl_close($ch);

foreach ($data['items'] as $p) {
    echo $p['relicid'] . ' - ' . $p['score'] . PHP_EOL;
}

RANKING LADDER · RESPONSE PAYLOAD

Response Structure

JSON response containing pagination metadata and an array of ranking items.

HTTP 200 OK

Field	Type	Description
Pagination
`items`	Array[Object]	List of player ranking items and match statistics.
`page` / `pageSize`	integer	Current page number and record limit per page.
`total` / `totalPages`	integer	Total count of records and overall available pages.
`hasPrevious` / `hasNext`	boolean	Flags indicating presence of previous / next pages.
Item fields
`seasonid`	integer	Unique season identifier.
`relicid`	integer	Unique player / account identifier (Relic ID).
`matches` / `wins` / `losses`	integer	Total matches played, wins and losses count.
`score` / `rating`	int / float	Score accumulated and win rate as a decimal ratio (e.g. `0.86` = 86%).
`ladderwinner`	string	Ladder winner status (`"Yes"` / `"No"`).
`ironcladwinner`	string	Ironclad division winner status (`"Yes"` / `"No"`).
`metaplayswinner`	string	Meta Plays category winner status (`"Yes"` / `"No"`).
`championsOfheroeswinner`	string	Champions of Heroes division winner status (`"Yes"` / `"No"`).
`thelegend`	string	Special "The Legend" badge status (`"Yes"` / `"No"`).

RANKING LADDER · JSON EXAMPLE

JSON Response Example

response.json

{
  "items": [
    {
      "seasonid": 1,
      "relicid": 366826,
      "matches": 15,
      "wins": 13,
      "losses": 2,
      "score": 13,
      "rating": 0.86,
      "ladderwinner": "Yes",
      "ironcladwinner": "No",
      "metaplayswinner": "No",
      "championsOfheroeswinner": "No",
      "thelegend": "No"
    }
  ],
  "page": 1,
  "pageSize": 500,
  "total": 31,
  "totalPages": 1,
  "hasPrevious": false,
  "hasNext": false,
  "count": 31
}

CASTER VIDEOS · ENDPOINT

Caster Videos

Returns the narrated (casted) tournament videos: title, caster, publish date, YouTube and Twitch links, season, stage and the Relic IDs of the players in each match.

GET https://laddertournament.com.br:8099/api/external/casted_videos_ladder

i Uses the same X-Api-Token header described in Authentication.

CASTER VIDEOS · USAGE EXAMPLE

Usage Example

Send a GET request with your token in the X-Api-Token header. Pick your language below.

curl --location 'https://laddertournament.com.br:8099/api/external/casted_videos_ladder' \
  --header 'X-Api-Token: XXXXXXX'

const res = await fetch('https://laddertournament.com.br:8099/api/external/casted_videos_ladder', {
  headers: { 'X-Api-Token': 'XXXXXXX' }
});

if (!res.ok) throw new Error(`HTTP ${res.status}`);
const videos = await res.json();

videos.forEach(v => {
  const players = v.playerRelicId.split(',');  // "111,222" → ["111","222"]
  console.log(v.title, v.castedBy, v.videoUrlYoutube || v.videoUrlTwitch, players);
});

import requests

url = "https://laddertournament.com.br:8099/api/external/casted_videos_ladder"
headers = {"X-Api-Token": "XXXXXXX"}

r = requests.get(url, headers=headers, timeout=15)
r.raise_for_status()

for v in r.json():
    players = v["playerRelicId"].split(",")
    link = v["videoUrlYoutube"] or v["videoUrlTwitch"]
    print(v["title"], v["castedBy"], v["stage"], link, players)

<?php
$ch = curl_init('https://laddertournament.com.br:8099/api/external/casted_videos_ladder');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER     => ['X-Api-Token: XXXXXXX'],
]);
$videos = json_decode(curl_exec($ch), true);
curl_close($ch);

foreach ($videos as $v) {
    $players = explode(',', $v['playerRelicId']);
    echo $v['title'] . ' - ' . $v['castedBy'] . PHP_EOL;
}

CASTER VIDEOS · RESPONSE PAYLOAD

Response Structure

JSON array where each item is one casted video.

HTTP 200 OK

Field	Type	Description
`id`	integer	Unique video identifier.
`title`	string	Video title.
`castedBy`	string	Name of the caster who narrated the match.
`publishedAt`	datetime	Publish date and time, ISO 8601 (e.g. `2026-09-07T00:00:00`).
`stage`	string	Season stage of the match (e.g. `"FINAL"`).
`videoUrlYoutube`	string	YouTube video URL. Empty string `""` when not available.
`videoUrlTwitch`	string	Twitch video URL. Empty string `""` when not available.
`seasonId`	integer	Season identifier (same value as `seasonid` in Ranking Ladder).
`playerRelicId`	string	Relic IDs of the players in the match, comma-separated (e.g. `"111,222,333,444"`).

i playerRelicId is a single string. Split it by , to get each player, then match against relicid from Ranking Ladder.

CASTER VIDEOS · JSON EXAMPLE

JSON Response Example

response.json

[
  {
    "id": 1,
    "title": "A Bad Day to Be An Aussie G2",
    "castedBy": "HelpingHans",
    "publishedAt": "2026-09-07T00:00:00",
    "stage": "FINAL",
    "videoUrlYoutube": "https://www.youtube.com/watch?v=dbIEhEpEKoA",
    "videoUrlTwitch": "",
    "seasonId": 1,
    "playerRelicId": "XXXXX,XXXXX,XXXXX,XXXXX"
  }
]