Public API
Read-only, CORS-enabled, free to use. Build Discord bots, overlays, spreadsheets, or any tool on top of shared builds.
Base URL
https://gms-upgrade-tracker.vercel.appAll responses are JSON. No authentication required. Rate limits are generous (Vercel serverless defaults). Players must save their build on the website before it can be accessed via API.
Builds
/api/share?id={IGN}Fetch a shared build by character name. Returns full gear, stats, class, server type, and Nexon region.
Parameters
region(string, default: na)Optional Nexon region for build lookup: na or euResponse
{ id, selectedClass, serverType, nexonRegion, characterStats, gear }/api/build/{IGN}/summaryGet a summary of a build including power score, gear overview, and set effects.
Parameters
region(string, default: na)Optional Nexon region for build lookup: na or euResponse
{ buildId, class, serverType, nexonRegion, powerScore, gear }/api/build/{IGN}/recommendGet upgrade recommendations ranked by meso efficiency. Supports query params for limit, mesoRate, sfDiscount, feverTime, cubeSale.
Parameters
limit(int, default: 5)Number of recommendations (1-20)mesoRate(int, default: 300000)Meso market rate (meso per NX)sfDiscount(bool, default: false)Star Force 30% discount eventfeverTime(bool, default: false)Spell Trace Fever Time eventcubeSale(bool, default: false)Cube 25% off eventbossPDR(number, default: 3.8)Boss-defense multiplier (3.8 = 380% PDR)region(string, default: na)Optional Nexon region for build lookup: na or euResponse
{ recommendations: [{ description, upgradeType, expectedMesoCost, expectedDamageGainPercent, ... }], powerScore }/api/build/{IGN}/rankGet a player's leaderboard rank (overall and class-specific).
Parameters
region(string, default: na)Optional Nexon region for build lookup: na or euResponse
{ buildId, nexonRegion, overall, class }/api/build/{IGN}/hexaGet the calibrated HEXA Matrix estimate — hexa score, gear-only score, completion %, and per-tier estimated FD. Completion is null in estimated-assumption mode.
Parameters
region(string, default: na)Optional Nexon region for build lookup: na or euResponse
{ estimated: true, estimateProvenance, hexaScore, gearOnlyScore, scoreGap, completionPercent, hexaAssumptionMode, breakdown: { actualFD, maxFD, perTier } }Calculators
/api/calc/starforceCalculate ordinary, true-Superior, weapon-style Sweetwater Katara, or paired Zero Star Force expected cost and booms. Level-only requests preserve the ordinary cost-only API. Item-aware requests may use a named preset as autofill or provide an arbitrary item's explicit profile, cap, and clean stats. Level 160 Sweetwater targets can reconstruct an exact Transposition residual from a certified source name plus its source-star history; custom sources require all source facts and clean stats. A true-Superior source caps the destination at 15 stars. Zero uses the actual weapon type level for stats, caps tap cost at level 150, and returns Alpha/Lazuli and Beta/Lapis separately. Type 8/9 consumes finite entered essence stock exactly; Heroic requires at least 75% completion coverage under the selected protection policy. Fixed Genesis/Destiny profiles return certified snapshots with costAvailable=false. Level 138-249 ordinary and Type 5-9 Zero weapon stat projection is available through 30 stars; level-250 ordinary weapons remain separate.
Parameters
itemLevel(int)Item level (required)from(int, default: 0)Current starto(int, default: 17)Target starreplacementCost(int, default: 0)Cost per boom replacement (meso); for Zero, the exact repurchased unenhanced Lazuli/Lapis pair cost before any Type 8/9 essence.itemName(string)Optional item identity. An exact named preset autofills mechanical metadata; any other name is treated as an arbitrary item.slot(string)Required with itemName; exact equipment slot. Category and WSE identity are always derived from this slot or a recognized preset.class(string)Required with itemName; exact class name used to resolve Job Stats and ATT/MATT.serverType(string)Required with itemName: heroic or interactive. Heroic needs no scroll parameters.starforceItemKind(string)Required for arbitrary items: ordinary, superior, fixed, zero, destiny, or special. A recognized preset owns this value.mechanicsPresetName(string | null)Canonical preset/mechanics identity when name is a custom display label. Use null for an explicitly custom item; omit only for legacy exact-name migration.starforceStatProfile(string)Use weapon-secondary for an ordinary Dual Blade Katara, or nonweapon-secondary for an ordinary armor-category shield. Sweetwater Katara and Terminus Defender autofill their respective profiles.zeroWeaponIdentity(string)Required for Zero unless inferred from a Genesis/Destiny or Type 1-9 item name: type-1 through type-9, genesis, or destiny-stage1.zeroEssenceCost(int, default: 0)Zero Type 8/9 Interactive only: price of one additional AbsoLab or Arcane Umbra Essence. Required when the exact finite-stock path expects to buy essences after owned stock is exhausted. Heroic must omit it or pass 0.zeroEssencesOwned(int)Required for Zero Type 8/9: exact owned essence count. Interactive prices only purchases beyond this stock; Heroic uses it for the 75% completion-coverage gate.zeroLuckyScrollState(string)Required for player-enhanced Zero weapons: none, root-abyss, absolab, or arcane-umbra. This is the set scroll currently applied before Star Force begins.zeroLuckyScrollsOwned(int)Required when an applied Lucky Item Scroll state is selected: exact count of raw replacement scroll items owned. A no-boom run consumes none; after any number of booms the engine models one eventual successful application at the final target.zeroLuckyScrollCost(int)Interactive price/opportunity value for one additional raw Lucky Item Scroll. Required when the exact path can exhaust owned scrolls; distinct from zeroEssenceCost. Heroic must omit it or pass 0 and uses joint owned-resource coverage.starforceCap(int)Required for arbitrary items. Use 0 for the published level/profile cap or provide the item-specific cap.baseStr / baseDex / baseInt / baseLuk / baseAtt / baseMatt / baseHp / baseMp(int)Complete clean, non-flame stat block. Supply all eight or none; arbitrary weapons and ordinary 16+ stat projections require all eight.starforceJobStatVariant(string)Required for Xenon armor: thief (DEX/LUK) or pirate (STR/DEX).transposed(bool, default: false)Set true only for a Level 160 Sweetwater destination with exact source history. Transposition keeps a permanent source C(S) - destination C(S-1) residual; it is included in a 0-to-current snapshot and cancels from a current-to-target delta.transposeSourceName(string)Required when transposed=true. Certified autofill names include Fafnir Rapid Edge, Papulatus Mark, Dominator Pendant, Daybreak Pendant, Superior Gollux Pendant, and Reaper's Pendant. Other names are custom sources.transposeSourceStars(int)Required when transposed=true: the source item's exact Star Force count at the moment of Transposition (before the destination displayed one fewer star).transposeSourceItemLevel / transposeSourceSlot / transposeSourceItemKind / transposeSourceCap(mixed, default: certified source autofill)Required for a custom source: level 140-150, compatible equipment slot, ordinary or superior Star Force system, and item cap (0 = profile/level cap). For a certified source these may be omitted; any supplied value must exactly match its canonical profile.transposeSourceStatProfile(string)Custom Katara sources require weapon-secondary. Fafnir Rapid Edge autofills it. Do not use it for shields or non-Katara secondaries.transposeSourceBaseStr / transposeSourceBaseDex / transposeSourceBaseInt / transposeSourceBaseLuk / transposeSourceBaseAtt / transposeSourceBaseMatt / transposeSourceBaseHp / transposeSourceBaseMp(int)All eight exact clean, non-flame source stats are required for a custom source and must be omitted for a certified source.transposeSourceJobStatVariant(string)Required only for a custom Xenon armor source: thief or pirate.totalSlots(int, default: slot default)Arbitrary-item upgrade-slot count. Recognized presets autofill and validate this value.scrollType(string)Interactive only; required with successfulScrolls and failedSlots. Use none for a clean item. On a transposed target these fields are the exact transferred source scroll state now stored on the Sweetwater item.successfulScrolls(int)Interactive only; exact successful scroll count.failedSlots(int)Interactive only; exact failed-slot count.scrollATT / scrollStat / scrollSecStat / scrollTertStat(int)Interactive variable-roll scrolls only; all four captured totals are required, including explicit zeros.spares(int)True Superior only; owned replacement copies consumed before paid replacements. Finite-spare expectation is solved exactly.strategy(string, default: optimal)Ordinary only; protection strategy: none, optimal, or max.starCatch(bool, default: true)Apply Star Catching to ordinary or true Superior taps.discount(bool, default: false)Ordinary only; apply the 30% Star Force discount event.lessBooms(bool, default: false)Ordinary only; apply the 30% lower boom-rate event.mvp(string, default: none)Ordinary only; MVP discount rank: none, silver, gold, or diamond.Response
{ costAvailable, costEngine: ordinary | superior | zero-paired | zero-paired-fixed, expectedCost, expectedBooms, expectedRecoveryResources: { replacementWeaponPairs, essence, luckyScroll: { applicationProbability, expectedRawScrolls, expectedOwnedScrollsConsumed, expectedPurchasedScrolls, ownedCoveragePercent } }, statGainAvailable, statGain, transposition: { inheritedResidual, sourceStars, destinationBaselineStars, includedInStatGain }, pairedStatGain: { alpha, beta }, aggregateFdAvailable, plan }/api/calc/cubeCalculate mean (default) or P50 cube counts for potential targets. Modes: tierup, wse, armor, glove, hat. Violet and Equality are explicitly opt-in, unverified cross-server references because current GMS probabilities are unpublished.
Parameters
mode(string, default: -)tierup | wse | armor | glove | hatcubeType(string, default: glowing)glowing | bright | solid | violet | equalityallowUnverifiedReference(bool, default: false)Required true for Violet or Equality. Explicitly acknowledges that this is a cross-server reference, not a published current-GMS probability.costMode(string, default: mean)mean (long-run expectation) | median (P50)attackType(string, default: att)att | matt (wse mode only)weaponProfile(string, default: ordinary)ordinary | destiny (wse mode only; destiny requires slot=weapon and uses the upgraded 35/40/45 Boss pool)itemLevel(int, default: 200)Required-level band for Potential values. GMS 13/10 lines begin at level 151.primaryStat(string, default: str)str | dex | int | luk (armor/glove/hat)currentTier(string, default: -)rare | epic | unique (tierup mode)targetTier(string, default: legendary)epic | unique | legendary (tierup mode)slot(string, default: cape)Equipment slot for violet armor ratesResponse
{ mode, cubeType, costMode, countMeaning, calculationStatus?, calculationProvenance?, combos: [{ id, label, expectedCubes, calculationStatus?, calculationProvenance? }] }/api/calc/flameCalculate expected flames to reach a target score.
Response
{ itemLevel, currentScore, targetScore, advantaged, flameType, expectedFlames }/api/calc/powerscoreCalculate converted stat from raw character stats. Critical Rate is expected-hit weighted and capped at 100%; omitting it uses a visibly labeled 100% assumption. Heroic requests require characterLevel for the GMS passive FD band.
Parameters
buildId(string)Optional shared build IGN to load stats from instead of manual stat paramsregion(string, default: na)Optional Nexon region when using buildId: na or eubossPDR(number, default: 3.0)Boss-defense multiplier (3.0 = 300% PDR; maximum 10)critRatePercent(number, default: 100 (assumed))Status-window Critical Rate, 0-100. Supply it to replace the assumption.characterLevel(int)Required for Heroic: selects 15/20/25/35/45% passive FD by level band.Response
{ totalScore, tier, bossPDRMultiplier, breakdownAvailable, breakdown, marginalValues, assumptions }Leaderboard
/api/leaderboardGet the top players ranked by converted stat. Filter by server type, class, and Nexon region.
Parameters
type(string, default: interactive)Server type: interactive or heroicregion(string, default: all)Optional region filter: all, na, or euclass(string)Filter by class (e.g. Hero, Demon Slayer)limit(int, default: 100)Number of entries (1-2000)Response
{ entries: [{ rank, name, displayName, selectedClass, nexonRegion, sharePath, score }], serverType, region }