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 user_xp record with total, level, and period tracking
Every XP award is logged in the xp_ledger for full audit trail

SDK usage

Get current XP

const xp = await client.xp.getMyXp();
// Returns:
// {
//   total_xp: 1500,
//   level: 5,
//   xp_this_period: 200,
//   last_xp_at: "2025-01-14T10:30:00Z"
// }

Get XP history

const history = await client.xp.getHistory({ limit: 20 });
// Returns array of XP ledger entries with amounts and reasons

Get active XP rules

const rules = await client.xp.getRules();
// Returns: [{ name: "Workout", event_name: "workout_completed", xp_amount: 50 }, ...]

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_create_xp_rule`	Create an XP rule with event trigger, amount, daily cap, and cooldown
`amba_list_xp_rules`	List all XP rules for a project
`amba_get_user_xp`	Get a specific user's XP and level

Example: Set up XP rules

Agent: "Set up XP for a fitness app"

amba_create_xp_rule({ name: "Workout Completed", event_name: "workout_completed", xp_amount: 50, max_per_day: 3 })
amba_create_xp_rule({ name: "Daily Login", event_name: "app_open", xp_amount: 10, max_per_day: 1 })
amba_create_xp_rule({ 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)

Database tables

Table	Purpose
`xp_rules`	Rule definitions with event triggers and limits
`user_xp`	Per-user XP state (total, level, period XP)
`xp_ledger`	Full audit trail of XP awards

On this page