Data API/Game Data

Data API · Types

GET /api/reference

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

{
  schemaVersion: 1
  contentHash: string // SHA-256 of JSON.stringify({schemaVersion, items, values, tables})
  items: Array<ItemDefinition & { presentation: ItemPresentation }> // raster imageUrl
  values: Record<string, {
    value: string | number
    format: "number" | "text" | "duration" | "markdown"
  }>
  tables: Record<string, {
    columns: string[]
    rows: Array<Array<string | number>>
  }>
}

ItemDefinition includes the misc/itemData fields below: identity, base worth (cost, 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.

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

interface ItemPresentation {
  boostTier: { tier: number; category: string | null } | null
  lootSources: Array<{
    source: string
    itemId: number | null // source container, or Lunar Shard for rare loot
    label: string
    percent: number // 0..100, before display rounding
  }>
  loot: Array<{
    itemId: number
    probability: number // 0..1 per draw; empty list for non-containers
    odds: string // e.g. "1 in 12"
  }>
  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"
}

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.

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

The response supplies an ETag and Cache-Control: public, max-age=300. If-None-Match supports 304 Not Modified. 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.

misc/itemData

Returns static data for all game items.

Request

{ "type": "misc/itemData" }

Response

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

misc/gameState

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 activeGiveaways array.

Request

{ "type": "misc/gameState" }

Response

{
  globalActionBoosts: Array<{
    type: "baseGlobalActionBoost" | "flexibleGlobalActionBoost"
    user: User
    action: "fish" | "hunt" | "explore" | "mine" | "work"
    multiplier: number
    duration: number    // ms
    endTime: number     // Unix ms
  }>
  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<{
    id: number
    ownerBcId: number
    message: string
    endDate: string     // ISO 8601
    numWinners: number
    entrantBcIds: number[]
    flatInventory: Inventory
  }>
}

misc/userBallsOwned

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

Request

{ "type": "misc/userBallsOwned" }

Response — number (non-negative integer)

stats/questSeasons

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

Request

{ "type": "stats/questSeasons" }

Response

interface QuestSeasonsResponse {
  endedSeasons: Array<{
    id: number
    name: string
    emoji: string
    endedAt: number   // Unix ms
  }>
}

misc/bossFactionStats

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

Request

{ "type": "misc/bossFactionStats" }

Response

interface BossFactionStatsResponse {
  factionPresenceMemberCount: number
  factionMultiplier: number
} | null

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