XP and Levels

Auto-award XP based on engagement events with configurable rules, daily caps, and cooldowns.

XP (experience points) automatically accrue when users track events. Define rules that map events to XP amounts, and Amba handles the rest.

How it works

Admin creates XP rules that map event names to XP amounts
When a user tracks a matching event, XP is awarded automatically
XP accumulates in the user's XP balance with total, level, and period tracking
Every XP award is logged for a full audit trail

SDK usage

Get current XP

const xp = await Amba.xp.getBalance();
// XpBalance:
// {
//   user_id: "usr_…",
//   total_xp: 1500,
//   current_level: 5,
//   xp_into_level: 200,       // XP earned at the current level
//   xp_to_next_level: 800,    // XP still needed to advance
//   xp_this_period: 200,      // XP earned in the current rolling window
//   updated_at: "2026-01-14T10:30:00Z"
// }

Use xp_this_period to drive weekly/monthly leaderboards or "earn 500 XP this week" challenges — the window is defined by the project's XP rules and rolls over server-side, so the client just reads the current value.

Get XP history

const history = await Amba.xp.getHistory(20);
// Returns the last N XP ledger entries with amounts and reasons.

Admin API reference

Method	Path	Description
`POST`	`/admin/xp`	Create XP rule
`GET`	`/admin/xp`	List XP rules

Client API reference

Method	Path	Description
`GET`	`/client/xp`	Get user's XP, level, and period XP
`GET`	`/client/xp/history`	Get XP ledger entries (paginated)
`GET`	`/client/xp/rules`	Get active XP rules

MCP tools

Tool	Description
`amba_xp_rules_create`	Create an XP rule with event trigger, amount, daily cap, and cooldown
`amba_xp_rules_list`	List all XP rules for a project
`amba_users_get_xp`	Get a specific user's XP and level

Example: Set up XP rules

Agent: "Set up XP for a fitness app"

amba_xp_rules_create({ name: "Workout Completed", event_name: "workout_completed", xp_amount: 50, max_per_day: 3 })
amba_xp_rules_create({ name: "Daily Login", event_name: "app_open", xp_amount: 10, max_per_day: 1 })
amba_xp_rules_create({ name: "Shared Progress", event_name: "share_completed", xp_amount: 25, cooldown_seconds: 3600 })

Rule options

Field	Type	Description
`name`	string	Display name for the rule
`event_name`	string	Event that triggers the XP award
`xp_amount`	number	XP to award per trigger
`max_per_day`	number	Max triggers per user per day (null = unlimited)
`cooldown_seconds`	number	Min seconds between awards for same user (default 0)

On this page