Editing Data API/Game Data

<small>[[Data API|Data API]] · [[Data API/Types|Types]]</small>

== <code><nowiki>GET /api/reference</nowiki></code> ==

Public, read-only reference definitions from the running server. This is a plain <code><nowiki>GET</nowiki></code>, independent of <code><nowiki>POST /api/data</nowiki></code>, with no API key or player context.

<pre>{
  schemaVersion: 1
  contentHash: string // SHA-256 of JSON.stringify(all fields except contentHash)
  items: Array&lt;ItemDefinition &amp; { presentation: ItemPresentation }&gt; // raster imageUrl
  specials?: SpecialDefinition[] // present on servers supporting Special references
  icons: Record&lt;string, string&gt; // emoji/token -&gt; raster image URL
  values: Record&lt;string, {
    value: string | number
    format: "number" | "text" | "duration" | "markdown"
  }&gt;
  tables: Record&lt;string, {
    columns: string[]
    rows: Array&lt;Array&lt;string | number&gt;&gt;
  }&gt;
}</pre>

<code><nowiki>ItemDefinition</nowiki></code> includes the <code><nowiki>misc/itemData</nowiki></code> fields below: identity, base worth (<code><nowiki>cost</nowiki></code>, BC), attributes/restrictions, recipe, reverse crafting uses, loot pools, and optional crop, food, weapon, cooldown and boost properties. All durations are milliseconds before display formatting. These are base definitions, not player inventory, player-adjusted outcomes, or market prices.

<code><nowiki>specials</nowiki></code> contains public type definitions from the same catalog and descriptions used by the Special modal. It never includes owned instances, player IDs or expiry dates. Types are stable keys; optional attributes describe variants rather than an individual player's copy.

<pre>interface SpecialDefinition {
  type: string
  name: string
  emoji: string
  imageUrl: string // current game artwork, or Noto Emoji PNG
  description: string
  multiUse: boolean
  globalBoost: boolean
  selfOnlyDescription: string | null
  cooldown: number | null // milliseconds; null means no type-wide timed cooldown
  variants: Record&lt;string, string[]&gt; // supported action/species/skin/aura values
  storeOffers: Array&lt;{
    key: string
    spCost: number
    attributes: Record&lt;string, string | boolean&gt;
  }&gt;
}</pre>

An empty <code><nowiki>specials</nowiki></code> collection explicitly means no current Specials. An omitted field denotes an older server version and must not be interpreted as a removal. Store offers describe the public catalog, not a particular profile's purchase eligibility. A null cooldown does not imply unrestricted use: active-effect caps, target eligibility and profile rules still apply.

<code><nowiki>presentation</nowiki></code> adds the player-independent derived information used by the Item modal. Raw item fields remain available. The game computes tiers, probabilities, odds and usage thresholds with its shared gameplay/display helpers; consumers should format these values rather than reimplement the calculations.

<pre>interface ItemPresentation {
  boostTier: { tier: number; category: string | null } | null
  lootSources: Array&lt;{
    source: string
    itemId: number | null // source container, or Lunar Shard for rare loot
    label: string
    percent: number // 0..100, before display rounding
    emoji: string | null // action symbol; containers use their item artwork
  }&gt;
  loot: Array&lt;{
    itemId: number
    probability: number // 0..1 per draw; empty list for non-containers
    odds: string // e.g. "1 in 12"
  }&gt;
  uses: {
    upgrades: ItemUsage[]
    purchases: ItemUsage[]
    research: ItemUsage[]
  }
}
interface ItemUsage {
  label: string
  category: "tools" | "farm" | "pets" | "relay"
  emoji: string
  threshold: number | null
  thresholdKind: "bay" | "count" | "tier" | "level" | "none"
}</pre>

Boost tiers are distinct from pet-food tiers. Usage thresholds identify the minimum bay number, purchase count, upgrade tier or level; research has no numeric threshold. Loot probabilities describe a draw within that pool, not the chance that an action triggers a rare drop or the number of draws when a container opens.

<code><nowiki>icons</nowiki></code> resolves usage and loot-source symbols, plus supplementary infobox symbols, to image URLs. Standard emoji use pinned Noto Emoji PNGs at 128px; custom game emoji retain their game artwork. Consumers can mirror these assets rather than depending on system emoji fonts or calculating image URLs themselves.

Value keys are qualified manual paths, with <code><nowiki>/</nowiki></code> replaced by <code><nowiki>.</nowiki></code>, plus the placeholder name; for example <code><nowiki>farm.cropsDieTime</nowiki></code> and <code><nowiki>items.market.unlockRequirement</nowiki></code>. Markdown values are generated by the game and must be escaped/converted before embedding into another markup language. Tables currently include <code><nowiki>crops</nowiki></code>, <code><nowiki>fertilizers</nowiki></code>, <code><nowiki>poker</nowiki></code>, <code><nowiki>shop</nowiki></code>, <code><nowiki>perks</nowiki></code> and <code><nowiki>ranks</nowiki></code>.

The response supplies an <code><nowiki>ETag</nowiki></code> and <code><nowiki>Cache-Control: public, max-age=300</nowiki></code>. <code><nowiki>If-None-Match</nowiki></code> supports <code><nowiki>304 Not Modified</nowiki></code>. The hash describes content, not a release number or publication time. Consumers must accept changed hashes in both directions, since a production rollback may restore an earlier snapshot.

== <code><nowiki>misc/itemData</nowiki></code> ==

Returns static data for all game items.

<strong>Request</strong>

<pre>{ "type": "misc/itemData" }</pre>

<strong>Response</strong>

<pre>Array&lt;{
  id: number
  imageUrl: string
  recipe: Array&lt;[idName: string, amount: number]&gt;
  // plus all other item fields (name, emoji, idName, etc.)
}&gt;</pre>

== <code><nowiki>misc/gameState</nowiki></code> ==

Returns the current live game state including active bosses, the ball pit, global action boosts, and giveaways. Giveaways are included only for Main profiles; profiles without direct-transfer access receive an empty <code><nowiki>activeGiveaways</nowiki></code> array.

<strong>Request</strong>

<pre>{ "type": "misc/gameState" }</pre>

<strong>Response</strong>

<pre>{
  globalActionBoosts: Array&lt;{
    type: "baseGlobalActionBoost" | "flexibleGlobalActionBoost"
    user: User
    action: "fish" | "hunt" | "explore" | "mine" | "work"
    multiplier: number
    duration: number    // ms
    endTime: number     // Unix ms
  }&gt;
  lastGlobalActionCooldownResetTime: number  // Unix ms
  activeBossStatus: {
    lastUpdated: number
    data: {
      bossId: string
      startTime: number
      initialHealth: number
      weaknessItemIds: number[]
      numAttackingUsers: number
      damageDealt: number
      nextWeakpointRevealAt: number | null
    }
  } | null
  ballPitStatus: {
    type: "black" | "purple" | "blue" | "orange" | "yellow" | "green"
    balls: number
  }
  activeGiveaways: Array&lt;{
    id: number
    ownerBcId: number
    message: string
    endDate: string     // ISO 8601
    numWinners: number
    entrantBcIds: number[]
    flatInventory: Inventory
  }&gt;
}</pre>

== <code><nowiki>misc/userBallsOwned</nowiki></code> ==

Returns the number of balls the <strong>authenticated user</strong> (identified by the API key) currently has in the ball pit. No <code><nowiki>id</nowiki></code> parameter is accepted; the result is always for the key holder.

<strong>Request</strong>

<pre>{ "type": "misc/userBallsOwned" }</pre>

<strong>Response</strong> — <code><nowiki>number</nowiki></code> (non-negative integer)

== <code><nowiki>stats/questSeasons</nowiki></code> ==

Returns archived quest seasons. The live ongoing season is excluded.

<strong>Request</strong>

<pre>{ "type": "stats/questSeasons" }</pre>

<strong>Response</strong>

<pre>interface QuestSeasonsResponse {
  endedSeasons: Array&lt;{
    id: number
    name: string
    emoji: string
    endedAt: number   // Unix ms
  }&gt;
}</pre>

== <code><nowiki>misc/bossFactionStats</nowiki></code> ==

Returns active faction combat contribution stats for the current boss fight. Returns <code><nowiki>null</nowiki></code> if no boss is active or the user is not in a faction.

<strong>Request</strong>

<pre>{ "type": "misc/bossFactionStats" }</pre>

<strong>Response</strong>

<pre>interface BossFactionStatsResponse {
  factionPresenceMemberCount: number
  factionMultiplier: number
} | null</pre>

<small>Generated from the Bconomy source documentation. Edits made on the wiki are overwritten on the next publish; ask the developers to change the source.</small>

[[Category:Data API]]