Chests

Chests are reward containers a player can own and open to receive randomized prizes. RapidMule rolls the prize pool on the server when a chest is opened, optionally scaling the reward by the player's level. These endpoints let you open a chest, list a player's chests, preview a chest's possible contents, and read a player's open history.

Open Chest

Opens one chest the player owns and returns the prizes that were rolled and granted.

Endpoint

POST /v1/chest/open

Request Body

Parameter	Type	Required	Description
playerId	string	Yes	Unique identifier for the player
chestDeliverableUId	string	Yes	UID of the chest deliverable to open

Example Request

{
  "playerId": "{{playerID}}",
  "chestDeliverableUId": "{{chestID}}"
}

Response

{
"code": 200,
"data": {
  "chestLabel": "Loot Chest",
  "scalingMode": "Custom",
  "playerLevel": 5,
  "drawCount": 1,
  "prizes": [
    {
      "label": "Football Jersey",
      "amount": 1.0000,
      "imageName": "https://rapidmulestorage.blob.core.windows.net/images/d73830ad-d553-4871-bf3c-98839cd8c29e_jersey.png",
      "type": 1
    }
  ]
}
}

Response Fields

Field	Type	Description
chestLabel	string	Display name of the opened chest
scalingMode	string	How rewards scale: None, PlayerLevel, or Custom
playerLevel	number	The player's level at the time of opening
drawCount	number	How many prizes were drawn
prizes	array	The prizes granted
prizes[].label	string	Prize deliverable name
prizes[].amount	number	Amount granted
prizes[].imageName	string	URL to the prize image
prizes[].type	number	Deliverable type of the prize

Request Example

curl -X POST https://api.rapidmule.com/v1/chest/open \
  -H "AuthKey: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "playerId": "{{playerID}}",
    "chestDeliverableUId": "{{chestID}}"
  }'

List Chests

Returns the chests a player currently owns. When the player owns no chests, data is an empty array.

Endpoint

POST /v1/chest/list

Request Body

Parameter	Type	Required	Description
playerId	string	Yes	Unique identifier for the player

Response

{
"code": 200,
"data": [
  {
    "chestDeliverableUid": "5bab9d902c8e4316b9d9fa0ddd91863d",
    "label": "Loot Chest",
    "imageName": null,
    "balance": 33.0000,
    "scalingMode": "Custom",
    "isActive": true
  }
]
}

Response Fields

Field	Type	Description
chestDeliverableUid	string	UID of the chest deliverable
label	string	Display name of the chest
imageName	string	URL to the chest image (may be null)
balance	number	How many of this chest the player owns
scalingMode	string	Reward scaling mode: None, PlayerLevel, or Custom
isActive	boolean	Whether the chest is currently active

Request Example

curl -X POST https://api.rapidmule.com/v1/chest/list \
  -H "AuthKey: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"playerId": "{{playerID}}"}'

Preview Chest

Returns a chest's possible contents with their drop weights — without opening it or requiring the player to own one. Points and powerup contents are excluded from previews.

Endpoint

POST /v1/chest/preview

Request Body

Parameter	Type	Required	Description
chestDeliverableUId	string	Yes	UID of the chest deliverable to preview
playerId	string	No	Optional player context for level-scaled previews

Response

{
"code": 200,
"data": {
  "chestLabel": "Loot Chest",
  "scalingMode": "Custom",
  "drawCountMin": 1,
  "drawCountMax": 1,
  "contents": [
    {
      "rewardLabel": "Football Jersey",
      "rewardImageName": "https://rapidmulestorage.blob.core.windows.net/images/d73830ad-d553-4871-bf3c-98839cd8c29e_jersey.png",
      "type": 1,
      "amountMin": 1.0000,
      "amountMax": 1.0000,
      "probability": 50,
      "weightPct": 100.0,
      "limited": false,
      "remainingStock": -1
    }
  ]

Response Fields

Field	Type	Description
chestLabel	string	Display name of the chest
scalingMode	string	Reward scaling mode: None, PlayerLevel, or Custom
drawCountMin	number	Minimum number of prizes drawn per open
drawCountMax	number	Maximum number of prizes drawn per open
contents	array	Possible rewards in the pool
contents[].rewardLabel	string	Reward deliverable name
contents[].rewardImageName	string	URL to the reward image
contents[].type	number	Deliverable type of the reward
contents[].amountMin	number	Minimum amount that can be awarded
contents[].amountMax	number	Maximum amount that can be awarded
contents[].probability	number	Raw draw weight of this reward
contents[].weightPct	number	Draw weight as a percentage of the pool
contents[].limited	boolean	Whether the reward has limited stock
contents[].remainingStock	number	Remaining stock (-1 when unlimited)

Request Example

curl -X POST https://api.rapidmule.com/v1/chest/preview \
  -H "AuthKey: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"chestDeliverableUId": "{{chestID}}", "playerId": "{{playerID}}"}'

Chest History

Returns a player's chest-open history (most recent first). When there is no history, data is an empty array.

Endpoint

POST /v1/chest/history

Request Body

Parameter	Type	Required	Description
playerId	string	Yes	Unique identifier for the player
top	integer	No	Maximum number of records to return. Defaults to 100

Response

{
"code": 200,
"data": [
  {
    "openedAt": 1783499458480,
    "chestLabel": "Loot Chest",
    "rewardLabel": "Points Booster",
    "rewardImageName": null,
    "type": 6,
    "amount": 1.0000
  },
  {
    "openedAt": 1783499458476,
    "chestLabel": "Loot Chest",
    "rewardLabel": "Football Jersey",
    "rewardImageName": "https://rapidmulestorage.blob.core.windows.net/images/d73830ad-d553-4871-bf3c-98839cd8c29e_jersey.png",
    "type": 1,
    "amount": 1.0000
  }
]

Response Fields

Field	Type	Description
openedAt	long	Unix timestamp (ms) when the chest was opened
chestLabel	string	Name of the chest that was opened
rewardLabel	string	Name of the reward received
rewardImageName	string	URL to the reward image (may be null)
type	number	Deliverable type of the reward
amount	number	Amount of the reward received

Request Example

curl -X POST https://api.rapidmule.com/v1/chest/history \
  -H "AuthKey: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"playerId": "{{playerID}}", "top": 10}'

Use Cases

• Chest Opening UX: Drive an open-and-reveal animation from the open response
• Odds Disclosure: Show drop rates with preview before a player spends
• Inventory Display: List owned chests with list
• Reward History: Show what a player has won over time with history

Error Codes

Code	Description	Resolution
1002	Missing required field	Provide playerId / chestDeliverableUId
4001	Invalid AuthKey	Verify API key
9010	Chest not found, inactive, or outside its active window	Check the chest deliverable
9011	Player does not own this chest	The player has no balance of this chest
9012	Limited prize pool exhausted	No stock remains in the chest pool
9013	No reward tier for the player's level	Configure a tier for the player's level
9020	Player not found	Verify playerId exists

Related Endpoints

• Deliverables - Chests and their rewards are deliverables
• Player Detail - Check a player's inventory and levels