Achievements

Badges and achievements that unlock automatically based on event counts, streak lengths, or XP thresholds.

Achievements are badges that unlock automatically when users meet specific criteria. They can award bonus XP on unlock and support hidden achievements.

How it works

Admin defines achievements with criteria (event count, streak length, XP threshold, or property value)
Amba evaluates criteria in the background
When a user meets the criteria, the achievement unlocks and optional bonus XP is awarded
Hidden achievements only appear in the user's list after being unlocked

SDK usage

Get all achievements with progress

const achievements = await client.achievements.getAll();
// Returns achievements with unlock status and progress:
// [
//   { key: "first_workout", name: "First Workout", unlocked_at: "2025-01-10T...", progress: { current: 1, target: 1 } },
//   { key: "streak_master_7", name: "Streak Master", unlocked_at: null, progress: { current: 4, target: 7 } }
// ]

Get a specific achievement

const achievement = await client.achievements.get('streak_master_7');

Criteria types

Type	Description	Required fields
`event_count`	Track an event N times	`event_name`, `target_value`
`streak_length`	Maintain a streak for N days	`streak_definition_id`, `target_value`
`xp_threshold`	Reach N total XP	`target_value`
`property_value`	User property reaches N	`property_key`, `target_value`

Admin API reference

Method	Path	Description
`POST`	`/admin/achievements`	Create achievement
`GET`	`/admin/achievements`	List all achievements

Client API reference

Method	Path	Description
`GET`	`/client/achievements`	Get all achievements with user progress
`GET`	`/client/achievements/:id`	Get specific achievement with progress

MCP tools

Tool	Description
`amba_create_achievement`	Create an achievement with criteria and optional XP reward
`amba_list_achievements`	List all achievements for a project

Example: Fitness app achievements

Agent: "Create achievements for a fitness app"

amba_create_achievement({
  key: "first_workout",
  name: "First Workout",
  description: "Complete your first workout",
  xp_reward: 100,
  criteria: { type: "event_count", event_name: "workout_completed", target_value: 1 }
})

amba_create_achievement({
  key: "streak_master_7",
  name: "Streak Master",
  description: "Maintain a 7-day workout streak",
  xp_reward: 500,
  criteria: { type: "streak_length", streak_definition_id: "streak_xxx", target_value: 7 }
})

amba_create_achievement({
  key: "xp_legend",
  name: "XP Legend",
  description: "Earn 10,000 XP",
  xp_reward: 1000,
  is_hidden: true,
  criteria: { type: "xp_threshold", target_value: 10000 }
})

Database tables

Table	Purpose
`achievement_definitions`	Achievement definitions with criteria, XP reward, hidden flag
`user_achievements`	Unlock records with timestamp and progress

On this page