API access

Using the API

Send the key as Authorization: Bearer kss_… or X-Api-Key. Base path is https://api.kingshotstats.com/v1.

Limits and freshness

60 requests / minute and 5,000 / day per key. Player and alliance payloads are reused for up to 60 minutes. If that copy is older than 60 minutes, this request waits (up to 90 seconds) for an updated copy, then returns it. Other requests for the same player or alliance during that wait share the same result. If the wait runs out, you get the last stored copy; a later request will see the update. Kingdom cards are served from the same stats as the site.

Player

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

Always returns wrapper fields: ok, uid, include, fresh, cached_at, age_seconds, and player (the base profile). Extra sections are added only when listed in include.

player (include=base, default):

uid, 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, array of:

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. If the player hides gear, 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/{aid}?include=info,roster

alliance (include=info):

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

members (include=roster) — array of:

uid, 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}

Card stats: kid, name, banner_url, player_count, located, active_7d, active_30d, alliance_count, gov_power, alliance_power, hero_total, pet_power, power_gain_7d, tc_pushers_7d, age_days, opened_on, power, avg_power, power_rank, activity_rank, health.

Example

curl -sS "https://api.kingshotstats.com/v1/players/123456?include=base,heroes,ranks,gov_gear" \
  -H "Authorization: Bearer kss_YOUR_KEY"

Unknown ids return 404. Missing or bad keys return 401. Over quota returns 429.

Use Regenerate on a key to mint a new token. You will be warned first: the previous token is revoked immediately and anything still using it will get 401.