Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.nippy.la/llms.txt

Use this file to discover all available pages before exploring further.

​
Examples of what you can ask your agent

  • “Create a welcome roulette: 70% keep participating, 20% 10% discount, 10% Bluetooth headphones”
  • “What active roulettes do I have right now?”
  • “Add a physical prize: 50 Nippy backpacks to use in roulettes”
  • “Show me the full configuration of the May roulette”
  • “What prize items do I have available with stock?”
With Roulettes you build gamification campaigns without touching the console. Tell your agent what prizes you want, with what probability, and it configures everything. Before anything is created, you get a preview to review — nothing is saved until you confirm.
Always call list_roulette_items before proposing a roulette, to know which physical items are available with stock.

​
Read tools

​
roulettes_list_roulette_items

Lists the physical prize items available for this business. Call this first before proposing any roulette. No parameters. Response: each item includes _id, name, available_stock, and whether it’s enabled_in_rewards. Only items with available_stock > 0 and enabled_in_rewards = true should be used as physical prizes in a roulette. 
{
  "name": "roulettes_list_roulette_items",
  "arguments": {}
}

​
roulettes_get_roulette

Gets the full configuration of a roulette by its _id.
​
roulette_id
string
required
Roulette ID to query.
Response: full document including gifts (with probabilities, typeOfGift, item_id), typeOfRoulette, timers, terms, isActive, and counters (totalSpins). 
{
  "name": "roulettes_get_roulette",
  "arguments": {
    "roulette_id": "664f1a2b3c4d5e6f7a8b9c0d"
  }
}

​
roulettes_list_roulettes

Lists the existing roulettes for this business. No parameters. Response includes: _id, name, isActive, typeOfRoulette, counters (totalSpins), createdAt. 
{
  "name": "roulettes_list_roulettes",
  "arguments": {}
}

​
Write tools — Items

​
roulettes_propose_item

Generates a preview of a physical prize item. Does not write to the database. The country is inherited automatically from the business.
​
name
string
required
Item name.
​
available_stock
integer
required
Available stock quantity for prizes.
​
description
string
default:"''"
Item description.
​
currency
string
default:"'MXN'"
Currency (ISO 4217 code).
​
track_stock
boolean
default:"true"
Whether to track inventory for this item.
​
enabled_in_rewards
boolean
default:"true"
Whether the item is enabled for use as a prize in roulettes.
{
  "name": "roulettes_propose_item",
  "arguments": {
    "name": "Bluetooth Headphones",
    "available_stock": 50,
    "description": "Nippy-branded wireless headphones",
    "currency": "MXN",
    "track_stock": true,
    "enabled_in_rewards": true
  }
}

​
roulettes_create_item

Creates a new physical prize item. Same parameters as propose_item.
Only call this tool after showing the user the propose_item preview and receiving explicit confirmation.
Response: {"_id": "...", "name": "Bluetooth Headphones", "status": "created"}

​
Write tools — Roulettes

​
roulettes_propose_roulette

Generates a preview of a roulette configuration. Does not write to the database.
​
name
string
required
Roulette name.
​
gifts
array
required
List of prize objects. Each gift must contain:
  • value (string, required): name shown on the wheel
  • message (string, required): message shown when won
  • probability (float, required): relative weight (e.g. 80 = 80% relative weight among all gifts)
  • typeOfGift (object, required): {"name": "...", "_id": "..."} — prize type. The agent automatically looks up the available type catalog.
  • emoji (string, optional): decorative emoji
  • quantity (int, optional): available units. Required for physical prizes
  • item_id (string, optional): _id from list_roulette_items — only for physical prizes. Do not confuse with typeOfGift._id
  • guaranteedForFirstTimers (bool, optional)
  • winInterval (int, optional)
  • fallback (string, optional)
​
time_to_win
integer
required
Win animation time (seconds).
​
time_to_lose
integer
required
Lose animation time (seconds).
​
text_to_win
string
required
Text shown when the user wins.
​
text_to_lose
string
required
Text shown when the user loses.
​
terms_and_conditions
string
required
Roulette terms and conditions.
​
roulette_type_id
integer
required
Numeric ID of the roulette type. Check nippy://roulettes/schema/gifts for valid options.
​
roulette_type_name
string
required
Roulette type name (e.g. "standard", "premium").
​
is_active
boolean
default:"false"
Whether the roulette is activated immediately. Recommended: false until the user confirms.
​
time_unit
string
default:"'hours'"
Time unit for expiration: "hours", "days". Only applies if roulette_type_id supports it.
​
time_to_expire
integer
default:"24"
Time until the roulette expires, in time_unit units.
​
max_wins
integer
default:"1"
Maximum number of prizes a user can win in this roulette.
{
  "name": "roulettes_propose_roulette",
  "arguments": {
    "name": "Welcome Roulette May 2026",
    "gifts": [
      {
        "value": "Bluetooth Headphones",
        "message": "You won Nippy Bluetooth Headphones!",
        "probability": 10,
        "typeOfGift": {
          "name": "Fisico",
          "_id": "634f356e33e5c76785516a2d"
        },
        "emoji": "🎧",
        "quantity": 50,
        "item_id": "664f1a2b3c4d5e6f7a8b9c0d"
      },
      {
        "value": "10% discount",
        "message": "You got 10% off your next purchase!",
        "probability": 30,
        "typeOfGift": {
          "name": "Porcentaje",
          "_id": "6342f530705c91dcbe8aba8b"
        },
        "emoji": "💰"
      },
      {
        "value": "Keep trying",
        "message": "You didn't win this time. Try again!",
        "probability": 60,
        "typeOfGift": {
          "name": "Perder",
          "_id": "634f356e33e5c76785516a2c"
        },
        "emoji": "😔"
      }
    ],
    "time_to_win": 5,
    "time_to_lose": 3,
    "text_to_win": "Congratulations!",
    "text_to_lose": "Keep trying",
    "terms_and_conditions": "Promotion valid from May 1 to May 31, 2026. Restrictions apply.",
    "roulette_type_id": 1,
    "roulette_type_name": "standard",
    "is_active": false,
    "time_to_expire": 24,
    "max_wins": 1
  }
}

​
roulettes_create_roulette

Creates a new roulette for this business. Same parameters as propose_roulette.
Only call this tool after showing the user the propose_roulette preview and receiving explicit confirmation.
Response: {"_id": "...", "name": "Welcome Roulette May 2026", "status": "created"}
Schema references for the agent:
URINameDescription
nippy://roulettes/schema/giftsroulettes_gift_typestypeOfGift value catalog and typeOfRoulette options
nippy://roulettes/schema/fieldsroulettes_field_referenceRoulette and item document fields
typeOfGift catalog IDs:
Type_id
Porcentaje (Percentage)6342f530705c91dcbe8aba8b
Perder (Lose)634f356e33e5c76785516a2c
Points68b86722b5a6eee84f241985

​
Important notes

  • typeOfGift._id values must come from the official catalog — do not invent IDs.
  • The item_id for a physical prize goes in the gift’s item_id field, not in typeOfGift._id.
  • Always include at least one “Perder” (Lose) slot.
  • The country for items and roulettes is inherited automatically from the business.
  • Keep is_active: false until the user explicitly asks to activate the roulette.