XP and Levels

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

1. Admin creates XP rules that map event names to XP amounts
2. When a user tracks a matching event, XP is awarded automatically
3. XP accumulates in the user's XP balance with total, level, and period tracking
4. 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.

Manual adjustments (support & promos)

Most XP flows through rules that fire automatically on events. For one-off corrections — a support credit, a promo top-up, reversing a mistaken award — adjust a user's XP directly with amba_xp_grant and amba_xp_deduct (REST: POST /admin/xp/grant, POST /admin/xp/deduct).

A manual adjustment is deliberately quieter than a rule-driven award: it updates the user's total and recomputes their level, but it does not emit level-up engagement events or re-evaluate achievement criteria — those belong to genuine user actions, not operator corrections. The ledger records each adjustment so it's distinguishable from rule-driven XP. deduct floors at zero — it returns INSUFFICIENT_XP rather than driving a balance negative. Amounts are positive integers.

Agent: "Credit Maria 200 XP for the bug she reported"
amba_xp_grant({ project_id: "proj_xxx", app_user_id: "user_xxx", amount: 200, reason: "bug_bounty" })

Agent: "Reverse the duplicate promo XP on Sam's account"
amba_xp_deduct({ project_id: "proj_xxx", app_user_id: "user_yyy", amount: 100, reason: "reversed_promo" })

To also award a badge use amba_achievements_grant; a manual XP grant never auto-unlocks achievements.

The level curve

A user's level is computed from their total_xp against the project's level curve. By default the curve is flat — xp_per_level of 1000, so level = floor(total_xp / 1000) + 1. You can make it non-flat by setting explicit level_thresholds: a strictly-increasing array of cumulative-XP boundaries.

Read and set the curve via the admin XP config endpoints:

GET   /admin/xp/config
PATCH /admin/xp/config

// Flat curve — 500 XP per level
PATCH /admin/xp/config
{ "xp_per_level": 500 }
 
// Non-flat curve — explicit cumulative thresholds (wins over xp_per_level)
PATCH /admin/xp/config
{ "level_thresholds": [100, 300, 700, 1500, 3000] }

level_thresholds: null clears the explicit curve and falls back to the flat xp_per_level. The PATCH response includes persisted — true once the curve is durably stored, false on a project that predates the feature (the effective default is returned but not saved).

Clients can read the effective curve so the app shows exact thresholds instead of reverse-engineering them:

GET /client/xp/config
→ { "data": { "xp_per_level": 1000, "thresholds": [100, 300, 700, …] } }

Setting a new curve does not retroactively recompute existing rows — levels rebase naturally on each user's next XP write (so changing the curve never re-fires level-up events for past XP).

Admin API reference

Client API reference

MCP tools

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