MLBB API Web v4.0.8
MLBB Card Install OpenMLBB Tutorial GitHub Stars
Home User MLBB Academy Addon

OpenMLBB SDK Docs

OpenMLBB MLBB Client

Structured SDK docs for MLBB endpoints using from OpenMLBB import OpenMLBB.

Every card documents the SDK call from OpenMLBB and mirrors API path/query/body requirements.

Jump to SDK endpoint

GET /openmlbb/mlbb/heroes GET /openmlbb/mlbb/heroes/rank GET /openmlbb/mlbb/heroes/positions GET /openmlbb/mlbb/heroes/{hero_identifier} GET /openmlbb/mlbb/heroes/{hero_identifier}/stats GET /openmlbb/mlbb/heroes/{hero_identifier}/skill-combos GET /openmlbb/mlbb/heroes/{hero_identifier}/trends GET /openmlbb/mlbb/heroes/{hero_identifier}/relations GET /openmlbb/mlbb/heroes/{hero_identifier}/counters GET /openmlbb/mlbb/heroes/{hero_identifier}/compatibility

GET List Heroes

/openmlbb/mlbb/heroes

Open Only This

API Path: /api/heroes

Retrieve a paginated list of all heroes with basic information. Supports query parameters for pagination (size, index), sorting (order), and localization (lang).

Query parameters:

  • size: Number of items per page (minimum: 1).
  • index: Page index (starting from 1).
  • order: Sort order for results. Allowed values: asc, desc.
  • lang: Language code for localized content (default: en).

The response includes hero records:

  • records: Array of hero entries, each containing:
      • data:
          • hero:
              • data:
                  • head: Hero head image URL.
                  • name: Hero name.
                  • smallmap: Hero smallmap image URL.
          • hero_id: Unique hero identifier.
          • relation:
              • assist:
                  • target_hero_id: Array of hero IDs assisted.
              • strong:
                  • target_hero_id: Array of hero IDs this hero is strong against.
              • weak:
                  • target_hero_id: Array of hero IDs this hero is weak against.

This endpoint is useful for:

  • Displaying hero collections.
  • Browsing hero details.
  • Analyzing hero relationships (assist, strong, weak).

Python Example

from OpenMLBB import OpenMLBB

client = OpenMLBB()
response = client.mlbb.heroes(size=20, index=1, order="desc", lang="en")
print(response)

Path and Query Parameters

Name In Type Required Default
size query integer no 20
index query integer no 1
order query string no desc
lang query string no en

GET Hero Rank Statistics

/openmlbb/mlbb/heroes/rank

Open Only This

API Path: /api/heroes/rank

Fetch rank statistics for heroes over a specified time window. Supports query parameters for filtering by past days, rank tier, sorting, pagination, and localization.

Query parameters:

  • days: Past day window. Allowed values: 1, 3, 7, 15, 30.
  • rank: Rank filter. Allowed values: all, epic, legend, mythic, honor, glory.
  • sort_field: Sort field. Allowed values: pick_rate, ban_rate, win_rate.
  • sort_order: Sort order for results. Allowed values: asc, desc.
  • size: Number of items per page (minimum: 1).
  • index: Page index (starting from 1).
  • lang: Language code for localized content (default: en).

The response includes hero rank statistics:

  • records: Array of hero entries, each containing:
      • data:
          • main_hero:
              • data:
                  • head: Hero head image URL.
                  • name: Hero name.
          • main_heroid: Unique hero identifier.
          • main_hero_channel:
              • id: Channel ID reference.
          • main_hero_appearance_rate: Hero pick rate (appearance frequency).
          • main_hero_ban_rate: Hero ban rate.
          • main_hero_win_rate: Hero win rate.
          • sub_hero: Array of related sub-heroes, each containing:
              • hero:
                  • data:
                      • head: Sub-hero head image URL.
              • heroid: Sub-hero ID.
              • hero_channel:
                  • id: Channel ID reference.
              • increase_win_rate: Impact of sub-hero on win rate.

This endpoint is useful for:

  • Analyzing hero performance trends across different ranks.
  • Tracking pick, ban, and win rates over time.
  • Understanding synergies and counters via sub-hero relationships.

Python Example

from OpenMLBB import OpenMLBB

client = OpenMLBB()
response = client.mlbb.heroes_rank(days="1", rank="all", sort_field="win_rate", sort_order="desc", size=20, index=1, lang="en")
print(response)

Path and Query Parameters

Name In Type Required Default
days query string no 1
rank query string no all
sort_field query string no win_rate
sort_order query string no desc
size query integer no 20
index query integer no 1
lang query string no en

GET Hero Position Filters

/openmlbb/mlbb/heroes/positions

Open Only This

API Path: /api/heroes/positions

Filter heroes by their position on the map using role and lane criteria. Supports multiple query parameters for roles and lanes, along with pagination, sorting, and localization.

Query parameters:

  • role: Role filter (multi allowed). Values: tank, fighter, assassin, mage, marksman, support.

Example: role=tank&role=fighter

  • lane: Lane filter (multi allowed). Values: exp, mid, roam, jungle, gold.

Example: lane=exp&lane=mid

  • size: Number of items per page (minimum: 1).
  • index: Page index (starting from 1).
  • order: Sort order for results. Allowed values: asc, desc.
  • lang: Language code for localized content (default: en).

The response includes hero position data:

  • records: Array of hero entries, each containing:
      • data:
          • hero:
              • data:
                  • name: Hero name.
                  • smallmap: Hero smallmap image URL.
                  • roadsort: Array of lane metadata objects:
                      • _id: Unique identifier.
                      • caption: Lane caption (localized).
                      • configId: Configuration ID.
                      • createdAt: Creation timestamp.
                      • createdUser: Creator username.
                      • data:
                          • _object: Object reference ID.
                          • road_sort_icon: Lane icon URL.
                          • road_sort_id: Lane ID.
                          • road_sort_title: Lane title (e.g., Roam).
                      • updatedAt: Last update timestamp.
                      • updatedUser: Last updater username.
                  • sortid: Array of role metadata objects:
                      • _id: Unique identifier.
                      • caption: Role caption (localized).
                      • configId: Configuration ID.
                      • createdAt: Creation timestamp.
                      • createdUser: Creator username.
                      • data:
                          • _object: Object reference ID.
                          • sort_icon: Role icon URL.
                          • sort_id: Role ID.
                          • sort_title: Role title (e.g., Support).
                      • updatedAt: Last update timestamp.
                      • updatedUser: Last updater username.
          • hero_id: Unique hero identifier.
          • relation:
              • assist:
                  • target_hero_id: Array of hero IDs assisted.
              • strong:
                  • target_hero_id: Array of hero IDs this hero is strong against.
              • weak:
                  • target_hero_id: Array of hero IDs this hero is weak against.
      • id: Record identifier.

This endpoint is useful for:

  • Building filtered hero lists.
  • Analyzing hero roles and lane assignments.
  • Understanding hero relationships (assist, strong, weak).

Python Example

from OpenMLBB import OpenMLBB

client = OpenMLBB()
response = client.mlbb.heroes_positions(role=['tank', 'fighter', 'assassin', 'mage', 'marksman', 'support'], lane=['exp', 'mid', 'roam', 'jungle', 'gold'], size=20, index=1, order="desc", lang="en")
print(response)

Path and Query Parameters

Name In Type Required Default
role query array no tank, fighter, assassin, mage, marksman, support
lane query array no exp, mid, roam, jungle, gold
size query integer no 20
index query integer no 1
order query string no desc
lang query string no en

GET Hero Detail

/openmlbb/mlbb/heroes/{hero_identifier}

Open Only This

API Path: /api/heroes/{hero_identifier}

Get detailed information for a specific hero by ID or name. Supports query parameters for pagination and localization.

Path parameters:

  • hero_identifier: Hero identifier as numeric hero ID or hero name. Accepts values like 30, Yi Sun-shin, or yisunshin.

Query parameters:

  • size: Number of items per page (minimum: 1).
  • index: Page index (starting from 1).
  • lang: Language code for localized content (default: en).

The response includes hero details:

  • records: Array of hero entries, each containing:
      • _id: Unique record identifier.
      • caption: Caption or localized label.
      • configId: Configuration ID.
      • createdAt: Creation timestamp.
      • createdUser: Creator username.
      • data:
          • head: Hero portrait image URL.
          • head_big: Larger hero portrait image URL.
          • hero:
              • data:
                  • heroid: Hero ID.
                  • name: Hero name.
                  • story: Hero lore or background story.
                  • painting: Hero splash art image URL.
                  • speciality: Array of hero specialties (e.g., Support, Crowd Control).
                  • abilityshow: Array of ability stats.
                  • difficulty: Difficulty rating.
                  • heroskilllist: Array of skill sets, each containing:
                      • skilllist: Array of skills:
                          • skillid: Skill ID.
                          • skillname: Skill name.
                          • skilldesc: Skill description.
                          • skillicon: Skill icon URL.
                          • skillcd&cost: Cooldown and mana cost.
                          • skilltag: Array of tags:
                              • tagid: Tag ID.
                              • tagname: Tag name (e.g., Burst, CC).
                              • tagrgb: Tag color.
                          • skillvideo: Skill video URL (if available).
                  • roadsort: Lane assignment metadata:
                      • road_sort_id: Lane ID.
                      • road_sort_title: Lane title (e.g., Mid Lane).
                      • road_sort_icon: Lane icon URL.
                  • sortid: Role assignment metadata:
                      • sort_id: Role ID.
                      • sort_title: Role title (e.g., Mage).
                      • sort_icon: Role icon URL.
                  • smallmap: Hero smallmap image URL.
                  • squarehead: Square portrait image URL.
                  • squareheadbig: Larger square portrait image URL.
          • hero_id: Unique hero identifier.
          • relation:
              • assist:
                  • desc: Description of assist synergy.
                  • target_hero_id: Array of hero IDs assisted.
                  • target_hero: Array of assisted hero metadata (images).
              • strong:
                  • desc: Description of heroes countered.
                  • target_hero_id: Array of hero IDs countered.
                  • target_hero: Array of countered hero metadata (images).
              • weak:
                  • desc: Description of heroes that counter this hero.
                  • target_hero_id: Array of hero IDs that counter.
                  • target_hero: Array of counter hero metadata (images).
          • url: Official lore or profile URL.

This endpoint is useful for:

  • Displaying comprehensive hero profiles.
  • Analyzing hero abilities and skill tags.
  • Understanding hero synergies and counters.
  • Linking lane and role assignments to gameplay analysis.

Python Example

from OpenMLBB import OpenMLBB

client = OpenMLBB()
response = client.mlbb.hero_detail("miya", size=20, index=1, lang="en")
print(response)

Path and Query Parameters

Name In Type Required Default
hero_identifier path string yes -
size query integer no 20
index query integer no 1
lang query string no en

GET Hero Detail Statistics

/openmlbb/mlbb/heroes/{hero_identifier}/stats

Open Only This

API Path: /api/heroes/{hero_identifier}/stats

Get detailed statistics for a specific hero by ID or name. Supports query parameters for rank tier, pagination, and localization.

Path parameters:

  • hero_identifier: Hero identifier as numeric hero ID or hero name. Accepts values like 30, Yi Sun-shin, or yisunshin.

Query parameters:

  • rank: Rank filter. Allowed values: all, epic, legend, mythic, honor, glory.
  • size: Number of items per page (minimum: 1).
  • index: Page index (starting from 1).
  • lang: Language code for localized content (default: en).

The response includes hero statistics:

  • records: Array of hero entries, each containing:
      • _id: Unique record identifier.
      • _createdAt: Creation timestamp.
      • _updatedAt: Last update timestamp.
      • data:
          • main_hero:
              • data:
                  • head: Hero portrait image URL.
                  • name: Hero name.
          • main_heroid: Hero ID.
          • main_hero_channel:
              • id: Channel ID reference.
          • main_hero_appearance_rate: Hero pick rate (appearance frequency).
          • main_hero_ban_rate: Hero ban rate.
          • main_hero_win_rate: Hero win rate.
          • sub_hero: Array of synergy heroes, each containing:
              • heroid: Sub-hero ID.
              • hero_win_rate: Sub-hero win rate.
              • hero_appearance_rate: Sub-hero pick rate.
              • increase_win_rate: Impact of sub-hero on win rate.
              • hero_channel:
                  • id: Channel ID reference.
              • hero:
                  • data:
                      • head: Sub-hero portrait image URL.
              • min_win_rate6: Win rate in matches ≤ 6 minutes, (min_win_rate6*100%).
              • min_win_rate6_8: Win rate in matches 6-8 minutes, (min_win_rate6_8*100%).
              • min_win_rate8_10: Win rate in matches 8-10 minutes, (min_win_rate8_10*100%).
              • min_win_rate10_12: Win rate in matches 10-12 minutes, (min_win_rate10_12*100%).
              • min_win_rate12_14: Win rate in matches 12-14 minutes, (min_win_rate12_14*100%).
              • min_win_rate14_16: Win rate in matches 14-16 minutes, (min_win_rate14_16*100%).
              • min_win_rate16_18: Win rate in matches 16-18 minutes, (min_win_rate16_18*100%).
              • min_win_rate18_20: Win rate in matches 18-20 minutes, (min_win_rate18_20*100%).
              • min_win_rate20: Win rate in matches ≥ 20 minutes, (min_win_rate20*100%).
          • sub_hero_last: Array of negative synergy heroes, each containing:
              • heroid: Sub-hero ID.
              • hero_win_rate: Sub-hero win rate.
              • hero_appearance_rate: Sub-hero pick rate.
              • increase_win_rate: Negative impact on win rate.
              • min_win_rate6 through min_win_rate20: Win rate breakdown across match durations.

This endpoint is useful for:

  • Analyzing hero performance trends across different ranks.
  • Tracking pick, ban, and win rates.
  • Understanding synergy with other heroes.
  • Identifying counters and negative synergies across match durations.

Python Example

from OpenMLBB import OpenMLBB

client = OpenMLBB()
response = client.mlbb.hero_stats("miya", rank="all", size=20, index=1, lang="en")
print(response)

Path and Query Parameters

Name In Type Required Default
hero_identifier path string yes -
rank query string no all
size query integer no 20
index query integer no 1
lang query string no en

GET Hero Skill Combos

/openmlbb/mlbb/heroes/{hero_identifier}/skill-combos

Open Only This

API Path: /api/heroes/{hero_identifier}/skill-combos

Get the most effective skill combos for a specific hero by ID or name. Supports query parameters for pagination and localization.

Path parameters:

  • hero_identifier: Hero identifier as numeric hero ID or hero name. Accepts values like 30, Yi Sun-shin, or yisunshin.

Query parameters:

  • size: Number of items per page (minimum: 1).
  • index: Page index (starting from 1).
  • lang: Language code for localized content (default: en).

The response includes hero skill combo details:

  • records: Array of combo entries, each containing:
      • _id: Unique record identifier.
      • caption: Caption or localized label (e.g., laning, teamfight).
      • configId: Configuration ID.
      • createdAt: Creation timestamp.
      • createdUser: Creator username.
      • data:
          • hero_id: Hero ID.
          • title: Combo title (e.g., 'TEAMFIGHT COMBOS').
          • desc: Descriptive instructions on how to execute the combo (e.g., laning phase or teamfight scenarios).
          • skill_id: Array of skills in recommended sequence, each containing:
              • skillid: Skill ID.
              • skillicon: Skill icon URL.
              • _id, _createdAt, _updatedAt: Metadata fields.
      • updatedAt: Last update timestamp.
      • updatedUser: Last updater username.

This endpoint is useful for:

  • Guiding players on optimal skill usage patterns.
  • Teaching effective combos for laning and teamfight scenarios.
  • Helping maximize hero performance in different situations.

Python Example

from OpenMLBB import OpenMLBB

client = OpenMLBB()
response = client.mlbb.hero_skill_combos("miya", size=20, index=1, lang="en")
print(response)

Path and Query Parameters

Name In Type Required Default
hero_identifier path string yes -
size query integer no 20
index query integer no 1
lang query string no en

GET Hero Performance Trends

/openmlbb/mlbb/heroes/{hero_identifier}/trends

Open Only This

API Path: /api/heroes/{hero_identifier}/trends

Get rate trends for a specific hero by ID or name over a specified time window. Supports query parameters for rank tier, past days window, pagination, and localization.

Path parameters:

  • hero_identifier: Hero identifier as numeric hero ID or hero name. Accepts values like 30, Yi Sun-shin, or yisunshin.

Query parameters:

  • rank: Rank filter. Allowed values: all, epic, legend, mythic, honor, glory.
  • past-days: Rate window in days. Allowed values: 7, 15, 30.
  • size: Number of items per page (minimum: 1).
  • index: Page index (starting from 1).
  • lang: Language code for localized content (default: en).

The response includes hero rate trend data:

  • records: Array of hero entries, each containing:
      • _id: Unique record identifier.
      • _createdAt: Creation timestamp.
      • _updatedAt: Last update timestamp.
      • data:
          • main_heroid: Hero ID.
          • bigrank: Rank tier identifier.
          • camp_type: Camp type indicator.
          • match_type: Match type indicator.
          • win_rate: Array of daily statistics, each containing:
              • date: Date of record.
              • app_rate: Appearance rate (pick frequency).
              • ban_rate: Ban rate.
              • win_rate: Win rate.

This endpoint is useful for:

  • Tracking hero performance trends over time.
  • Monitoring hero popularity and ban frequency.
  • Comparing win rates across different ranks and time periods.

Python Example

from OpenMLBB import OpenMLBB

client = OpenMLBB()
response = client.mlbb.hero_trends("miya", rank="all", size=20, index=1, lang="en")
print(response)

Path and Query Parameters

Name In Type Required Default
hero_identifier path string yes -
rank query string no all
past-days query string no 7
size query integer no 20
index query integer no 1
lang query string no en

GET Hero Relations

/openmlbb/mlbb/heroes/{hero_identifier}/relations

Open Only This

API Path: /api/heroes/{hero_identifier}/relations

Get information about the relations of a specific hero by ID or name. Supports query parameters for pagination and localization.

Path parameters:

  • hero_identifier: Hero identifier as numeric hero ID or hero name. Accepts values like 30, Yi Sun-shin, or yisunshin.

Query parameters:

  • size: Number of items per page (minimum: 1).
  • index: Page index (starting from 1).
  • lang: Language code for localized content (default: en).

The response includes hero relation data:

  • records: Array of hero entries, each containing:
      • data:
          • hero:
              • data:
                  • name: Hero name.
          • hero_id: Unique hero identifier.
          • relation:
              • assist:
                  • target_hero_id: Array of hero IDs that synergize well.
              • strong:
                  • target_hero_id: Array of hero IDs that are countered.
              • weak:
                  • target_hero_id: Array of hero IDs that counter this hero.

This endpoint is useful for:

  • Understanding hero synergies (assist).
  • Identifying heroes that are countered (strong).
  • Recognizing heroes that counter the selected hero (weak).
  • Building balanced team compositions.

Python Example

from OpenMLBB import OpenMLBB

client = OpenMLBB()
response = client.mlbb.hero_relations("miya", size=20, index=1, lang="en")
print(response)

Path and Query Parameters

Name In Type Required Default
hero_identifier path string yes -
size query integer no 20
index query integer no 1
lang query string no en

GET Hero Counters

/openmlbb/mlbb/heroes/{hero_identifier}/counters

Open Only This

API Path: /api/heroes/{hero_identifier}/counters

Get information about heroes that counter a specific hero by ID or name. Supports query parameters for rank tier, pagination, and localization.

Path parameters:

  • hero_identifier: Hero identifier as numeric hero ID or hero name. Accepts values like 30, Yi Sun-shin, or yisunshin.

Query parameters:

  • days: Time window for counter data. Allowed values: 1, 3, 7, 15, 30.
  • rank: Rank filter. Allowed values: all, epic, legend, mythic, honor, glory.
  • size: Number of items per page (minimum: 1).
  • index: Page index (starting from 1).
  • lang: Language code for localized content (default: en).

The response includes hero counter data:

  • records: Array of hero entries, each containing:
      • _id: Unique record identifier.
      • _createdAt: Creation timestamp.
      • _updatedAt: Last update timestamp.
      • data:
          • main_hero:
              • data:
                  • head: Main hero portrait image URL.
                  • name: Main hero name.
          • main_heroid: Main hero ID.
          • main_hero_channel:
              • id: Channel ID reference.
          • main_hero_appearance_rate: Pick rate of the main hero.
          • main_hero_ban_rate: Ban rate of the main hero.
          • main_hero_win_rate: Win rate of the main hero.
          • sub_hero: Array of counter heroes, each containing:
              • heroid: Counter hero ID.
              • hero_win_rate: Counter hero win rate.
              • hero_appearance_rate: Counter hero pick rate.
              • increase_win_rate: Impact of counter hero on win rate.
              • hero_channel:
                  • id: Channel ID reference.
              • hero:
                  • data:
                      • head: Counter hero portrait image URL.
              • min_win_rate6 through min_win_rate20: Win rate breakdown across match durations.
          • sub_hero_last: Array of negative synergy heroes, each containing:
              • heroid: Sub-hero ID.
              • hero_win_rate: Sub-hero win rate.
              • hero_appearance_rate: Sub-hero pick rate.
              • increase_win_rate: Negative impact on win rate.
              • min_win_rate6 through min_win_rate20: Win rate breakdown across match durations.

This endpoint is useful for:

  • Identifying which heroes are effective counters.
  • Analyzing matchup dynamics.
  • Understanding performance trends across different ranks and match durations.

Python Example

from OpenMLBB import OpenMLBB

client = OpenMLBB()
response = client.mlbb.hero_counters("miya", days="1", rank="all", size=20, index=1, lang="en")
print(response)

Path and Query Parameters

Name In Type Required Default
hero_identifier path string yes -
days query string no 1
rank query string no all
size query integer no 20
index query integer no 1
lang query string no en

GET Hero Compatibility

/openmlbb/mlbb/heroes/{hero_identifier}/compatibility

Open Only This

API Path: /api/heroes/{hero_identifier}/compatibility

Get compatibility information for a specific hero by ID or name. Supports query parameters for rank tier, pagination, and localization.

Path parameters:

  • hero_identifier: Hero identifier as numeric hero ID or hero name. Accepts values like 30, Yi Sun-shin, or yisunshin.

Query parameters:

  • days: Time window for compatibility data. Allowed values: 1, 3, 7, 15, 30.
  • rank: Rank filter. Allowed values: all, epic, legend, mythic, honor, glory.
  • size: Number of items per page (minimum: 1).
  • index: Page index (starting from 1).
  • lang: Language code for localized content (default: en).

The response includes hero compatibility data:

  • records: Array of hero entries, each containing:
      • _id: Unique record identifier.
      • _createdAt: Creation timestamp.
      • _updatedAt: Last update timestamp.
      • data:
          • main_hero:
              • data:
                  • head: Main hero portrait image URL.
                  • name: Main hero name.
          • main_heroid: Main hero ID.
          • main_hero_channel:
              • id: Channel ID reference.
          • main_hero_appearance_rate: Pick rate of the main hero.
          • main_hero_ban_rate: Ban rate of the main hero.
          • main_hero_win_rate: Win rate of the main hero.
          • sub_hero: Array of compatible heroes, each containing:
              • heroid: Compatible hero ID.
              • hero_win_rate: Compatible hero win rate.
              • hero_appearance_rate: Compatible hero pick rate.
              • increase_win_rate: Positive synergy impact on win rate.
              • hero_channel:
                  • id: Channel ID reference.
              • hero:
                  • data:
                      • head: Compatible hero portrait image URL.
              • min_win_rate6 through min_win_rate20: Win rate breakdown across match durations.
          • sub_hero_last: Array of negative synergy heroes, each containing:
              • heroid: Sub-hero ID.
              • hero_win_rate: Sub-hero win rate.
              • hero_appearance_rate: Sub-hero pick rate.
              • increase_win_rate: Negative impact on win rate.
              • min_win_rate6 through min_win_rate20: Win rate breakdown across match durations.

This endpoint is useful for:

  • Identifying which heroes pair well with the selected hero.
  • Analyzing synergy and team composition effectiveness.
  • Recognizing combinations that reduce performance.
  • Understanding matchup dynamics across ranks and match durations.

Python Example

from OpenMLBB import OpenMLBB

client = OpenMLBB()
response = client.mlbb.hero_compatibility("miya", days="1", rank="all", size=20, index=1, lang="en")
print(response)

Path and Query Parameters

Name In Type Required Default
hero_identifier path string yes -
days query string no 1
rank query string no all
size query integer no 20
index query integer no 1
lang query string no en