Library reference
Library reference
Classes
| Class | Description |
|---|---|
| ClanApi | GET /api/clan/*: a clan's profile and members |
| EventsApi | events the key's scopes allow, kept for 30 days; own limit of 6 requests a minute on top of the key's |
| KpdApi | player hacker reports; needs the kpd scope on the key |
| Krunker | the three krunker apis behind one object: - the documented developer api on the root (krunker.player, krunker.market, ...), needs apiKey - krunker.game.*, what the game itself reads without any auth - krunker.as(token).*, what the game reads with the player's own frvr token |
| KrunkerArgumentError | a call was made with an argument the api would reject, nothing was sent |
| KrunkerBadRequestError | 400, the api rejected a parameter the local checks did not catch |
| KrunkerClient | the http layer under every tier: one base url, one rate limit tracker, typed errors, one retry on a 5xx or a network error |
| KrunkerConfigError | no api key configured |
| KrunkerDeveloperApi | the documented developer api; one key is one rate limit window, so keep one instance per key |
| KrunkerError | the base of every error krapio throws |
| KrunkerForbiddenError | the api key is invalid or revoked; on a token endpoint the player lacks the role (moderator, kpd reviewer) |
| KrunkerGameApi | what the game reads without any auth: no key, no documented limits, shapes from live replies; reads only |
| KrunkerHttpError | a reply with a non 2xx status; the subclasses cover the common ones |
| KrunkerNetworkError | the request never got an http reply |
| KrunkerNotFoundError | 404, no such player, clan, map, mod or match |
| KrunkerRateLimitError | 429, or a request refused locally because the window is known to be empty |
| KrunkerServerError | a 5xx; retried once before it is thrown |
| KrunkerTokenApi | reads that need the player's frvr access token (FRVR.auth.getFreshAccessToken() in the game). the token is only ever sent as a bearer header, never stored or logged; every write of the game api is left out on purpose |
| KrunkerTokenError | a player token that is malformed or already expired, nothing was sent |
| KrunkerUnauthorizedError | a token endpoint without a valid token: missing, expired or rejected |
| LeaderboardApi | GET /api/leaderboard/*: the ranked leaderboard per region |
| MapApi | GET /api/map/* and /api/maps/*: map details, featured maps and map leaderboards |
| MarketApi | GET /api/market/*: listings, owners and price history per skin |
| MatchApi | GET /api/match/*: one ranked match with its participants |
| ModsApi | GET /api/mods/*: the mod list and single mods |
| PlayerApi | GET /api/player/*: profile, inventory, listings, ranked matches and posts of a player |
| PublicClansApi | GET /clans/*: clan profiles, loot config, motd and the recruitment board |
| PublicGameApi | the static game data the page loads at start plus the community map and mod records |
| PublicItemsApi | the item page of the social market, by skin index |
| PublicLeaderboardsApi | GET /leaderboards/*: player, clan, raid and KrunkCup boards |
| PublicLegacyApi | api.krunker.io, the old rest api; only the paths the page calls without a token |
| PublicMarketApi | the market reads that answer without a token; listings, inventory and history need one (token wrapper) |
| PublicMatchmakerApi | matchmaker.krunker.io, plain json without an envelope; the game polls the list every 60 s |
| PublicPlayersApi | GET /players/*: the social profile, search, sales, followers and feed |
| PublicShopApi | the shop's catalogue data; the wild offer and every purchase need the player's token |
| PublicSocialApi | the social feed; a player's own posts are players.feed |
| PublicTurfApi | GET /territorial-wars/*: Turf Wars status, clans, players and leaderboards |
| RateLimitTracker | mirrors the X-RateLimit-* headers so a call can be refused before it costs a request |
| SkinsApi | GET /api/skins/*: the skin definitions |
| TokenCreatorApi | what a creator sees of their own maps and studios, plus the clan applications of the player |
| TokenMarketApi | the market behind a login: listings, the player's inventory, sales and history, the black market |
| TokenPlayerApi | the token's own account: /player, /account, /email, /discord, /guest |
| TokenRankedApi | api.krunker.io behind a token: the ranked system's own api, plain {data} without an error field on success |
| TokenSession | the token bound resources plus the token's claims; made by Krunker.as(token) |
| TokenShopApi | per player shop state and the player's own custom skins (the editor's /skins) |
| TokenStaffApi | role gated reads: moderators and kpd reviewers; a normal token gets 403 "insufficient permissions" |
| TokenTradesApi | player to player trades; creating, accepting and cancelling are writes and stay out |
Type Aliases
| Type Alias | Description |
|---|---|
| ApiErrorBody | body of every error reply |
| ApiEvent | one event of GET /api/events or of a webhook delivery |
| BlackMarket | GET /market/black-market, the skin indices on offer |
| BlackMarketRank | GET /market/black-market/rank, null without a ranked history |
| BrowserQuery | category tab (index) and page (pos) of the legacy map and mod browsers, 0 based |
| ClanLeaderboardRow | one row of GET /leaderboards/player_clan |
| ClanLeaderboardSort | sort of the clan leaderboard |
| ClanLootConfig | GET /clans/:id/loot-config |
| ClanMember | one row of a clan's member list |
| ClanMembers | GET /api/clan/:name/members, 10 per page |
| ClanMotd | GET /clans/:id/motd |
| ClanProfile | GET /api/clan/:name |
| ClanPublicMember | one member in a public clan profile, short keys as the game sends them |
| ClanPublicProfile | GET /clans/by-name/:name and /clans/:id/profile |
| ClientOptions | options shared by every tier; apiKey only matters for the developer api |
| CommunityLeaderboardQuery | page, board type and order of a community map leaderboard |
| CommunityMap | GET /maps/by-name/:name, the community map record (the official Burg is a different thing, see OfficialMap) |
| CommunityMapLeaderboard | GET /maps/by-name/:name/leaderboard |
| CreatorEvents | GET /creators/events, the menu's event and survey box |
| CreatorPoll | a running survey of GET /creators/events |
| CustomSkin | a custom skin of the token's player (the skin editor) |
| CustomSkinsPage | GET /skins, the player's custom skins paged |
| CustomSkinsQuery | page, page size and filters of the player's custom skins |
| DailySpinProgress | GET api.krunker.io/daily-spin/progress |
| DayMapQuery | turf day and map filter; today and every map when omitted |
| DiscordStatus | GET /discord/status, the optional fields only while linked |
| DropCampaign | a running drop campaign |
| EmailPreferences | GET /email/preferences |
| Envelope | the reply envelope of gapi.svc.krunker.io, a non-null error comes with a 4xx or 5xx |
| EventsPage | GET /api/events |
| EventsQuery | filters of GET /api/events; keep them the same between calls when paging with after |
| EventTarget | what an event is about, e.g. type "map" and the map id |
| EventType | the types documented so far; a key only sees the types of the event scopes it holds |
| FeaturedMap | one featured map |
| FeaturedMaps | GET /api/maps/featured |
| FeedPost | one post of the social feed, short keys as the game sends them |
| FeedTab | tab of GET /social/feed; only global has been seen |
| FetchLike | only the call signature, so a wrapper or a mock needs none of fetch's statics |
| GameApiOptions | options of the game tier: everything of ClientOptions but the key, no endpoint here takes one |
| GameList | GET /game-list, every public lobby |
| GameListEntry | [game id, region key, players, max players, options, seconds left] |
| GameOptions | the options object inside a game list entry |
| GuestProfile | GET /guest/profile, zeros without a guest token |
| InventoryItem | one entry of GET /api/player/:name/inventory |
| InventoryItemMetadata | undocumented: kounter stats and float data of one owned skin, every field optional; shape from the community wrapper |
| InventoryStack | one inventory stack: skin index, count, instance id, state |
| ItemInstance | one row of GET /items/:id/instances: the holder's name, the serial and the wear where the skin has one |
| ItemListing | one live listing on an item page, the same row the token tier's market/listings feed gives |
| ItemOwner | one of an item's top owners, short keys as the game sends them |
| ItemPrices | GET api.krunker.io/webhooks/general/items/prices: index = skin index, null = no price |
| ItemSale | one day of sales of an item: kr, count, date; GET /items/:id/sales and /market/items/:id/sales-statistics |
| ItemSalesInfo | GET /market/items/:id/sales: the ask range, circulation and the top owners' player ids, despite the path no sales |
| ItemView | GET /items/:id/view, the item page of the social market: the whole order book of the skin, not a page of it |
| KpdCall | one row of GET /api/kpd/latest-calls |
| KpdCallContext | 0 public, 1 ranked, 2 comp, 3 custom |
| KpdCallRating | 0 pending, 1 banned, 2 rejected |
| KpdCallStatus | 1 not responded, 2 responded, 3 reviewed |
| KpdDemosQuery | offset and search of the kpd demo queue |
| KrunkCupPlayerRow | rows of /leaderboards/krunkcup/players and .../teams/:id/contributors |
| KrunkCupTeam | one row of GET /leaderboards/krunkcup/teams |
| KrunkerOptions | options of Krunker: ClientOptions without baseUrl, every tier picks its own host |
| LeaderboardEntry | one row of the ranked leaderboard |
| LeaderboardOrder | 0 = ascending (lower is better), 1 = descending |
| LeaderboardType | which built in board a map has: score or time |
| LegacyMapList | GET api.krunker.io/webhooks/general/maps/list |
| LegacyMapRow | one row of the legacy map browser |
| LegacyModList | GET api.krunker.io/webhooks/general/mods/list |
| LegacyModRow | one row of the legacy mod browser |
| LiveListing | one active listing on the live market |
| Logger | optional sinks, nothing is logged without one |
| LootDistributionMode | how a clan splits its turf earnings |
| Lottery | GET /lottery/:id, every past draw with its prizes |
| MapConfig | GET /maps/:id, the whole map file (120 KB for Burg), only the keys the client reads are named |
| MapEventData | data of map.featured and map.unfeatured |
| MapInfo | GET /api/map/:name |
| MapLeaderboard | GET /api/map/:name/leaderboard, 25 per page |
| MapLeaderboardEntry | one row of a map leaderboard |
| MapLeaderboardPlayer | GET /api/map/:name/leaderboard/player/:player, one player's entry |
| MapLeaderboardQuery | which of a map's boards to read and in which order |
| MarketHistory | GET /market/history |
| MarketHistoryEntry | one completed buy or sell of the player |
| MarketHistoryQuery | sort, cursor and limit of GET /market/history |
| MarketHistorySort | sort of the player's market history |
| MarketListing | one active listing of a skin on the market |
| MarketListings | GET /market/listings |
| MarketListingsQuery | filters, sort and cursor of GET /market/listings |
| MarketListingsSort | sort of the live market listings |
| MarketListRequest | the body the game posts to /market/list; krapio never sends it |
| MarketListResult | the reply to POST /market/list: the kr left, the stack left of that skin, the new listing's market id |
| MarketOwner | one owner in a skin's top owners |
| MarketPurchaseRequest | the body the game posts to /market/purchase |
| MarketPurchaseResult | the reply to POST /market/purchase: the kr left, the bought instance, the listing's market id and skin index |
| MarketSkin | GET /api/market/skin/:skinindex |
| MarketSkinQuery | page of listings and days of price history for a market skin |
| MarketStatRow | one row of GET /market/stats: skin index, in circulation, on sale, and the ask range while something is listed |
| MarketStats | GET /market/stats, paged by cursor |
| MarketStatsQuery | filters, sort and cursor of GET /market/stats |
| MarketStatsSort | sort of GET /market/stats; "rarity" is what the market tab sends, an unknown value is answered with the default order |
| MarketUnlistRequest | the body the game posts to /market/unlist |
| MarketUnlistResult | the reply to POST /market/unlist |
| MatchDetails | GET /api/match/:id |
| MatchesQuery | page and season of a player's ranked matches |
| MatchHistoryEntry | one player's line in a match of a social profile's match_history |
| MatchHistoryGame | one match in a social profile's match_history |
| MatchParticipant | one player of a ranked match |
| MatchResult | 1 = win, 0 = loss, -1 = draw |
| MePlayer | GET /player/me, data is the packed account blob the game decodes itself |
| Mod | GET /api/mods/:name |
| ModInfo | GET /mods/by-name/:name |
| Mods | GET /api/mods, 10 per page |
| MyApplications | GET /clans/my-applications, null without any |
| OfficialMap | GET /maps, index = id = preview image number at assets.krunker.io/img/maps/map_.png |
| OpenListing | GET /market/sales, one of the player's own open listings |
| Page | the page query every paged developer endpoint takes, 1 based |
| PingList | region key (as in a game entry) -> lobby host:port to ping |
| PlayerFollow | one row of GET /players/:name/followers and /following |
| PlayerLeaderboardQuery | sort and season of a player leaderboard |
| PlayerLeaderboardRow | one row of a player leaderboard |
| PlayerLeaderboardType | the player boards GET /leaderboards/:type knows |
| PlayerListing | one of a player's active market listings |
| PlayerListings | GET /api/player/:name/listings, 10 per page |
| PlayerMatch | one ranked match from a player's point of view |
| PlayerMatches | GET /api/player/:name/matches, 10 per page |
| PlayerPost | one social post of a player |
| PlayerPosts | GET /api/player/:name/posts, 10 per page |
| PlayerProfile | GET /api/player/:name |
| PlayerRanked | a player's ranked stats in one region this season |
| PlayerSale | one day of market sales: funds earned, count sold, date |
| PlayerSearchResult | one hit of GET /players/search |
| PlayerSocialProfile | GET /players/:name, the legacy flat profile the social popup renders |
| PlayerStats | the packed stats blob of a social profile, the developer api's profile has the same numbers under full names |
| PricePoint | one day of a skin's price history |
| QueryValue | a query string value; undefined leaves the parameter out |
| RaidLeaderboardRow | GET /leaderboards/raids/:mapId, 100 rows; map 31 is a raid map, 0 is not ("invalid raid map ID") |
| RaidSort | sort of a raid leaderboard |
| RaidStats | a player's raid stats on one map |
| RankedConnection | GET api.krunker.io/ranked/me/connection |
| RankedLeaderboard | GET /api/leaderboard/:region, 10 per page |
| RankedMatchHistory | GET api.krunker.io/match-history/me/..., paged |
| RankedMatchHistoryQuery | limit, offset, mode, ranked flag and region of the ranked match history |
| RankedProfile | GET api.krunker.io/player-profile/me/season/:season[/region/:region], the only place with a season accuracy total |
| RankedProfileEntry | a player's ranked card in the season rankings |
| RankedQuery | page and season of the ranked leaderboard |
| RankedShop | GET /ranked/shop, the skins bought with ranked currency |
| RateLimitState | what the tracker knows: the key's window and the routes with a window of their own |
| RateLimitWindow | one rate limit window as the last reply described it |
| RecruitmentBoard | GET /clans/recruitment, paged |
| RecruitmentPost | a clan's post on the recruitment board |
| RecruitmentQuery | page, limit, region and language of the recruitment board |
| RegionId | a ranked region id, one of Region or a number the api knows |
| RequestOptions | what a resource passes to KrunkerClient.get for one request |
| SeasonRankings | GET api.krunker.io/leaderboards/rankings/season/:season[/region/:region] |
| SeasonRankingsQuery | limit, offset and region of the season rankings |
| ShopDisplay | GET /shop/displays, a tree of displays with the products they show |
| ShopPrice | one price of a shop product, real money or recurring |
| ShopProduct | one product in a shop display |
| SkinDefinition | extra config properties of a skin (creator, glow, frames, ...) get merged into the root, so the index signature is real |
| Skins | GET /api/skins, paged skin definitions |
| SkinsQuery | page, page size and season filter of the skin definitions |
| SocialNews | GET /social/news |
| SocialPost | GET /social/post/:id |
| SoftError | a reply that carries its refusal inside data (wild offer: "Wild offer is not available") |
| SpinPool | one item pool of a spin wheel |
| SpinWheel | GET /spins/wheels, the spin shop's wheels with their pools |
| Stream | one live stream in the menu's stream box |
| Title | one player title of GET /titles |
| TokenApiOptions | options of the token tier: everything of ClientOptions but the key, the token replaces it |
| TokenClaims | the claims of a frvr access token (RS256, about 24 h); nothing here is verified, krunker does that |
| TopStreams | GET api.krunker.io/streams/top |
| Trade | one trade, short keys as the game sends them |
| TradeCancelResult | the reply to POST /trades/:id/cancel |
| TradeCreateRequest | the body the game posts to /trades/create |
| TradeCurrency | one currency amount in a trade |
| TradeFundsResult | the reply to POST /trades/create and POST /trades/:id/accept: the kr left |
| TradeHistory | GET /trades/history |
| TradeHistoryQuery | offset, limit and whether open trades are included |
| TradeInventories | GET /trades/inventory/:playerId, both sides |
| TradeItem | one item in a trade, by skin index |
| TradePlayer | GET /trades/player-search, one player by exact name |
| TurfClan | GET /territorial-wars/clan/:id |
| TurfClanEarning | one day's reward of a clan on one map |
| TurfClanMap | a clan's standing on one turf map for one day |
| TurfContribution | one day and map of a player's turf contributions |
| TurfPayouts | GET /territorial-wars/clan/:id/payouts |
| TurfPlayer | GET /territorial-wars/player/:id |
| TurfPlayerEarning | one payout to a player |
| TurfPlayerRow | one row of GET /territorial-wars/clan/:id/players |
| TurfStatus | one turf map with its current owner |
| TurfStatusEntry | one of the top 5 clans of a turf map |
| TurfTopClan | one row of the top performing clans board |
| TurfTopGrossingClan | one row of the top grossing clans board |
| TurfTopPlayer | one row of the top performing players board |
| Usernames | GET /account/usernames |
| VerifyWebhookOptions | knobs of verifyWebhook, for tests and for clocks that drift |
| VotedItem | undocumented: a map or mod the player voted on, shape from the community wrapper |
| Wallet | GET /player/wallet, kr plus every studio currency |
| WalletCurrency | one currency in the wallet, kr or a studio currency |
| WebhookEvent | one webhook delivery; test and verify sends carry id 0, the real id is in the Krunker-Event-Id header |
| WebhookSignature | the parsed Krunker-Signature header |
| WildOffer | GET /shop/wild-offer, a SoftError when there is none |
| Wristband | GET /krunkcup/wristband |
Variables
| Variable | Description |
|---|---|
| DEFAULT_BASE_URL | gapi.svc.krunker.io, the host of the developer api and of most game endpoints |
| GAPI_URL | gapi.svc.krunker.io, the game api and the developer api |
| GLOBAL_LIMIT | the per key limit every endpoint shares; a reply showing a smaller limit is an endpoint's own window |
| LEGACY_API_URL | api.krunker.io, the old rest api and the ranked api |
| MATCHMAKER_URL | matchmaker.krunker.io, the lobby list |
| MAX_EVENT_TARGETS | target ids one events call may filter by |
| MAX_EVENTS_PER_PAGE | the largest page the events endpoint serves |
| MAX_HISTORY_DAYS | days of price history GET /api/market/skin/:skinindex can return |
| MAX_SKINS_PER_PAGE | the largest page GET /api/skins serves |
| RAID_MAPS | map ids known to have a raid board; not enforced, so a new raid map keeps working |
| Region | ranked region ids as the leaderboard endpoint takes them |
| TURF_EPOCH_UTC | turf days count whole utc days from here (season 10 epoch, from the game code) |
| TURF_MAPS | 0 Burg, 2 Sandstorm, 3 Subzero |
| WEBHOOK_HEADERS | the headers of every delivery |
| WEBHOOK_TOLERANCE_S | requests whose timestamp is further off than this are rejected, as the docs ask |
Functions
| Function | Description |
|---|---|
| decodeToken | reads the claims without verifying the signature; throws KrunkerTokenError for anything that is not a live jwt |
| isNotFound | type guard for KrunkerNotFoundError |
| isRateLimited | type guard for KrunkerRateLimitError |
| isTransient | retrying makes sense for these, the request itself was fine |
| parseWebhookSignature | the Krunker-Signature header split up, null when it is not of the documented form |
| signWebhook | the Krunker-Signature value for a body, for tests and for signing your own test deliveries |
| turfDay | the turf day of a date: whole utc days since TURF_EPOCH_UTC |
| verifyWebhook | true when the delivery was signed with the endpoint's secret and is not older than the tolerance. the body has to be the raw request body, re-serialized json gives a different signature. answer 401 when this is false, the signature check sends deliberately bad signatures and expects that |