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. 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 }

heroes — arena defence team:

id, name, level, star, power, icon, position

ranks — kingdom standings:

power, power_rank, kills, kills_rank, town_center_level, town_center_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:

kid, name, banner_url, player_count, located, 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.

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"

401 missing or invalid key. 404 unknown player, alliance, kingdom, or board. 429 rate limit exceeded.