API access

Using the API

Authenticate with Authorization: Bearer kss_… or X-Api-Key. Base URL: https://api.mightpulse.com/v1.

Limits and freshness

Each key allows 60 requests per minute and 5,000 per day. A Discord account linked to an active Mighty patron gets double that: 120 per minute and 10,000 per day. Exceeding either limit returns 429.

Player and alliance responses may be up to 60 minutes old. Each included section is checked on its own. If a requested section is older than 60 minutes, the request waits up to 90 seconds for an update. Concurrent requests for the same player or alliance share that result. If the wait expires, the last stored copy is returned.

Player

GET /v1/players/{id}?include=base
GET /v1/players/{id}?include=base,heroes,ranks,gov_gear
GET /v1/players/{id}?id_type=uid

id is the in-game governor_id by default. Governor ID and internal uid overlap, so the two are not interchangeable.

id_type is optional. Default governor_id (aliases fid, gov, governor) looks up fid only. Pass id_type=uid to look up by internal uid. Unknown IDs return 404. Invalid id_type returns 400.

Wrapper fields: ok, uid, governor_id, id_type, include, fresh, cached_at, age_seconds, player. Extra sections appear only when listed in include.

player (include=base, default):

uid, governor_id, fid, nick_name, kid, power, town_center_level, vip,
x, y, kills, office, online, last_active_at, last_login, avatar_url,
language, shield_endtime, burn_endtime,
alliance: { aid, abbr, name, rank, rank_label, power, count, flag_url, leader_name }

The game no longer sends activity. online, last_active_at, and last_login are leftover values from before that change. They are stale and should not be used.

heroes — arena defence team, including equipped hero gear and exclusive/widget gear:

id, name, level, star, stars, star_label, quality, power, icon, position,
skill_levels: [{ id, level }],
exclusive_gear_level,
exclusive_gear: {
  id, name, level, slot,
  atk_ratio, hp_ratio, def_ratio, power_ratio,
  slg_skill_id, pve_skill_id,
  slg_attr: [{ id, value, label }]
},
gear: [{
  eid, sid, slot, name,
  enhancement_level, refine_level, gear_level,
  quality, quality_key, quality_label, red,
  troop, troop_label
}]

Hero gear is helmet / gloves / armor / boots. enhancement_level is the in-game upgrade (+N). refine_level is mastery forging. red is true at enhancement 101+. exclusive_gear is the hero's exclusive weapon (widget); null if none is on record. Catalog ratios and slg_attr come from the exclusive's wiki row for that hero.

ranks — kingdom standings:

power, power_rank, kills, kills_rank, town_center_level, town_center_rank,
migrant_score, migrant_rank, mystic_trial, mystic_rank,
leaderboards: [{ name, value, kingdom_rank }]

gov_gear — governor equipment. When gear is hidden, hidden is true, items is empty, and message explains that.

hidden, message,
items: [{ slot, name, equipid, quality, tier, star, strength_level, score, combat, icon,
          gems: [{ slot, id }] }]

Alliance

GET /v1/alliances/{kid}/{tag}?include=info,roster

Path parameters are kingdom ID and alliance tag (abbr). Tags are case-sensitive. The same tag can exist in more than one kingdom, so kid is required.

alliance (include=info):

aid, name, abbr, kid, power, count, leader_name, leader_uid, leader_governor_id, flag_url, power_rank

members (include=roster):

uid, governor_id, fid, nick_name, power, town_center_level, kills, alliance_rank, alliance_rank_label,
kid, avatar_url, last_active_at, online

Kingdom

GET /v1/kingdoms?page=1&size=24
GET /v1/kingdoms/{kid}
GET /v1/kingdoms/{kid}?include=boards&limit=100
GET /v1/kingdoms/{kid}/ranks?limit=100
GET /v1/kingdoms/{kid}/ranks?board=pet_power&limit=50

kingdom fields:

active_players is governors currently on the map (same value as located). active_7d and active_30d are still returned.

kid, name, banner_url, player_count, located, active_players, active_7d, active_30d, alliance_count,
age_days, opened_on, power, avg_power, power_rank, activity_rank, health,
power_gain_7d, tc_pushers_7d,
gov_power, alliance_power, alliance_kills, kills,
hero_power, hero_total, troop_power, building_power, research_power,
hero_no_equip, hero_equip, governor_gear_power, governor_charm_power,
pet_power, island_prosperity, migrant_score, mystic_trial, master_power,
board_totals: [{ type, key, label, total }]

research_power is also returned as science_power. governor_gear_power is also lord_equip. governor_charm_power is also lord_gem.

Leaderboards are available with include=boards or GET /v1/kingdoms/{kid}/ranks. limit is 1–100 (default 100). board is a slug or numeric type:

alliance_power, alliance_kills, personal_power, kills, town_center, rebel_conquest,
single_hero, hero_total, troop_power, building_power, research_power,
hero_no_equip, hero_equip, gov_gear, gov_charm, pet_power,
island_prosperity, migrant_score, mystic_trial,
coliseum, forest_of_life, crystal_cave, knowledge_nexus, molten_fort, radiant_spire,
master_power

Alliance boards include aid, abbr, name, and score. Player boards include uid, governor_id, nick_name, and score.

Events Mighty

GET /v1/kingdoms/{kid}/events

Same calendar as the kingdom page. A Mighty key is required. Any other key receives 403 mighty_required.

Each kingdom is fetched once and kept until 00:00 UTC.

{
  "ok": true,
  "kid": 1,
  "date": "2026-10-05",
  "count": 11,
  "categories": [
    {
      "name": "Events",
      "events": [
        {
          "name": "Hero Rally",
          "category": "Events",
          "when": "28 Sep 00:00 – 11 Oct 24:00",
          "begin_ts": 1759017600,
          "end_ts": 1760227199
        }
      ]
    }
  ]
}

when is the date line shown on the site. begin_ts and end_ts are Unix seconds.

KvK Mighty

GET /v1/kingdoms/{kid}/kvk

GET /v1/kingdoms/{kid}/kvk/scores

GET /v1/kvk/matchups

Mighty only. Any other key receives 403 mighty_required. This is the same matchup card and live prep board as the kingdom page.

The matchup is this kingdom and its opponent. previous_season is the last stored season for that kingdom, or null. /v1/kvk/matchups is every pair in the current season, listed once. Scores are the two kingdom totals and prep days I–V, with In Progress, Available Soon, or Ended. KvK scores are refreshed every 5 minutes. A kingdom with no published score returns 404 scores_unavailable.

{
  "ok": true,
  "season": 22,
  "stage": "armament",
  "bye": false,
  "kingdom": { "kid": 1, "name": null },
  "opponent": { "kid": 39, "name": null },
  "previous_season": 21
}

{
  "ok": true,
  "season": 22,
  "stage": "armament",
  "kingdom": 1,
  "opponent": 39,
  "score": 166483680,
  "opponent_score": 60111200,
  "days": [
    {
      "day": 1,
      "name": "I",
      "status": "In Progress",
      "kingdom_score": 166483680,
      "opponent_score": 60111200,
      "begin_ts": 1791158400,
      "end_ts": 1791244800
    }
  ]
}

Example

curl -sS "https://api.mightpulse.com/v1/players/{governor_id}?include=base,heroes,ranks,gov_gear" \
  -H "Authorization: Bearer kss_YOUR_KEY"
curl -sS "https://api.mightpulse.com/v1/players/{uid}?id_type=uid&include=base" \
  -H "Authorization: Bearer kss_YOUR_KEY"
curl -sS "https://api.mightpulse.com/v1/kingdoms/1" \
  -H "Authorization: Bearer kss_YOUR_KEY"
curl -sS "https://api.mightpulse.com/v1/kingdoms/1/ranks?board=pet_power&limit=20" \
  -H "Authorization: Bearer kss_YOUR_KEY"
curl -sS "https://api.mightpulse.com/v1/kingdoms/1/events" \
  -H "Authorization: Bearer kss_YOUR_KEY"
curl -sS "https://api.mightpulse.com/v1/kingdoms/1/kvk" \
  -H "Authorization: Bearer kss_YOUR_KEY"
curl -sS "https://api.mightpulse.com/v1/kingdoms/1/kvk/scores" \
  -H "Authorization: Bearer kss_YOUR_KEY"
curl -sS "https://api.mightpulse.com/v1/kvk/matchups" \
  -H "Authorization: Bearer kss_YOUR_KEY"

401 missing or invalid key. 403 mighty_required on events and KvK without a Mighty key. 404 unknown player, alliance, kingdom, board, or matchup, or scores_unavailable when live scores are not published yet. 429 rate limit exceeded.