Challenges

Time-limited goals with XP and achievement rewards to drive short-term engagement.

Challenges are time-limited goals that users can join and complete for rewards. They create short-term engagement bursts.

How it works

Admin creates a challenge with start/end dates, goal type, and rewards
Users discover active challenges and opt in (join)
Progress is tracked automatically based on the goal type
When a user meets the goal, they receive XP and/or an achievement

SDK usage

Get active challenges

const challenges = await client.challenges.getActive();
// Returns challenges with user's progress:
// [
//   {
//     name: "7-Day Fitness Sprint",
//     goal_type: "event_count",
//     goal_value: 7,
//     user_progress: 3,
//     user_status: "active",
//     is_joined: true
//   }
// ]

Join a challenge

await client.challenges.join('challenge_xxx');

Get my challenges

const mine = await client.challenges.getMine();
// Returns active + completed + failed challenges

Goal types

Type	Description	How progress is tracked
`event_count`	Track an event N times	Counts matching events between start and end
`xp_earned`	Earn N XP	Sums XP earned between start and end
`streak_maintained`	Keep streak for N days	Checks streak continuity within the period

Admin API reference

Method	Path	Description
`POST`	`/admin/challenges`	Create challenge
`GET`	`/admin/challenges`	List challenges (filter by status)

Client API reference

Method	Path	Description
`GET`	`/client/challenges`	Get active challenges with progress
`POST`	`/client/challenges/:id/join`	Join a challenge
`GET`	`/client/challenges/mine`	Get user's joined challenges

MCP tools

Tool	Description
`amba_create_challenge`	Create a challenge with goal, dates, and rewards
`amba_list_challenges`	List challenges filtered by status

Example

Agent: "Create a weekend XP challenge"

amba_create_challenge({
  project_id: "proj_xxx",
  name: "Weekend XP Blitz",
  description: "Earn 500 XP this weekend for a bonus reward!",
  start_at: "2025-01-18T00:00:00Z",
  end_at: "2025-01-20T00:00:00Z",
  goal_type: "xp_earned",
  goal_value: 500,
  reward_xp: 200,
  reward_achievement_id: "achievement_weekend_warrior"
})

Database tables

Table	Purpose
`challenge_definitions`	Challenge config with dates, goal, and rewards
`user_challenges`	Per-user join records with progress and status

On this page