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> // same processed definitions as misc/itemData; 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.

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.