Powerups

Powerups are player-owned boosts — for example a temporary points multiplier — that a player can activate and deactivate. These endpoints let you list a player's powerups and toggle their active state.

List Powerups

Returns the powerups a player owns. When the player owns none, data is an empty array.

Endpoint

POST /v1/powerup/list

Request Body

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

Response

{
"code": 200,
"data": [
  {
    "uid": "FD2ABC92-FFCA-4FB9-8AE5-F8FA648017CC",
    "prizeLabel": "Points Booster",
    "prizeImageName": "https://rapidmulestorage.blob.core.windows.net/images/072c8a3e-7950-41cc-88bb-37a7769b3e29_fire.png",
    "multiplier": 1.5,
    "isActive": true,
    "isActivated": true,
    "isValid": true,
    "initialUseCount": 5,
    "remainingUseCount": 5,
    "powerupMaxUseCount": 5,
    "powerupTimeoutSeconds": 2592000,
    "neverExpires": false,
    "activatedAt": 1783504573,
    "createdAt": 1783504573,
    "expiresAt": 1786096573,
    "remainingSeconds": 2555594,

Response Fields

Field	Type	Description
uid	string	Unique identifier of the powerup instance
prizeLabel	string	Display name of the powerup
prizeImageName	string	URL to the powerup image
multiplier	number	The multiplier applied when active
isActive	boolean	Whether the powerup is currently usable
isActivated	boolean	Whether the powerup is currently activated
isValid	boolean	Whether the powerup is still valid (owned, not expired, uses remaining)
initialUseCount	number	Total uses the powerup was granted with
remainingUseCount	number	Uses remaining
powerupMaxUseCount	number	Maximum uses configured for the powerup
powerupTimeoutSeconds	number	Lifetime of the powerup in seconds once granted
neverExpires	boolean	Whether the powerup never expires
activatedAt	long	Unix timestamp (seconds) the powerup was activated, or null
createdAt	long	Unix timestamp (seconds) the powerup was granted
expiresAt	long	Unix timestamp (seconds) the powerup expires
remainingSeconds	long	Seconds remaining before expiry
targetPrizes	array	Deliverables the powerup applies to (empty = all)
targetPrizes[].targetPrizeUid	string	UID of the targeted deliverable
targetPrizes[].targetPrizeLabel	string	Name of the targeted deliverable
targetPrizes[].targetPrizeImageName	string	URL to the targeted deliverable image
targetPrizes[].deliveryMethod	number	How the targeted deliverable is delivered

Request Example

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

Activate Powerup

Activates a powerup the player owns.

Endpoint

POST /v1/powerup/activate

Request Body

Parameter	Type	Required	Description
playerId	string	Yes	Unique identifier for the player
powerupUId	string	Yes	UID of the powerup instance to activate

Response

{
  "code": 200,
  "data": "Powerup activated"
}

Request Example

curl -X POST https://api.rapidmule.com/v1/powerup/activate \
  -H "AuthKey: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"playerId": "{{playerID}}", "powerupUId": "{{powerupID}}"}'

Deactivate Powerup

Deactivates a currently active powerup.

Endpoint

POST /v1/powerup/deactivate

Request Body

Parameter	Type	Required	Description
playerId	string	Yes	Unique identifier for the player
powerupUId	string	Yes	UID of the powerup instance to deactivate

Response

{
  "code": 200,
  "data": "Powerup deactivated"
}

Request Example

curl -X POST https://api.rapidmule.com/v1/powerup/deactivate \
  -H "AuthKey: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"playerId": "{{playerID}}", "powerupUId": "{{powerupID}}"}'

Use Cases

• Powerup Inventory: Show a player their owned boosts with list
• Boost Toggle: Let players turn a multiplier on before a session with activate
• Cleanup: Turn a boost off with deactivate when it is no longer needed

Error Codes

Code	Description	Resolution
1002	Missing required field	Provide playerId / powerupUId
4001	Invalid AuthKey	Verify API key
9020	Player not found	Verify playerId exists
9021	Powerup not found, not owned, or already active	Check the powerup before activating
9023	Powerup not found, not owned, or not active	Check the powerup before deactivating

Related Endpoints

• Deliverables - Powerups are configured as deliverables
• Player Detail - Review a player's owned items