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`

Manual grant & revoke (support & moderation)

Achievements normally unlock through automatic criteria evaluation. For support, promos, or corrections you can also award or claw one back for a specific user with amba_achievements_grant and amba_achievements_revoke (REST: POST /admin/achievements/:id/grant, POST /admin/achievements/:id/revoke).

A manual grant is idempotent — re-granting an already-unlocked achievement keeps the original unlock time. It does not auto-award the achievement's xp_reward (that's reserved for a genuine criteria-driven unlock); award XP separately with amba_xp_grant if you want it. Revoke removes the user's unlock entirely, returning a not-found error if they didn't hold it.

Agent: "Manually unlock the launch-day badge for our beta testers"
amba_achievements_grant({ project_id: "proj_xxx", achievement_id: "ach_xxx", app_user_id: "user_xxx" })

Agent: "That badge was awarded by mistake — take it back"
amba_achievements_revoke({ project_id: "proj_xxx", achievement_id: "ach_xxx", app_user_id: "user_xxx" })

Admin API reference

Method	Path	Description
`POST`	`/admin/achievements`	Create achievement
`GET`	`/admin/achievements`	List all achievements
`POST`	`/admin/achievements/:id/grant`	Manually unlock for a user (support)
`POST`	`/admin/achievements/:id/revoke`	Claw back a user's unlock

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_achievements_create`	Create an achievement with criteria and optional XP reward
`amba_achievements_list`	List all achievements for a project
`amba_achievements_grant`	Manually unlock an achievement for a user (support / promo)
`amba_achievements_revoke`	Claw back a user's unlock (inverse of grant)

Example: Fitness app achievements

Agent: "Create achievements for a fitness app"

amba_achievements_create({
  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_achievements_create({
  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_achievements_create({
  key: "xp_legend",
  name: "XP Legend",
  description: "Earn 10,000 XP",
  xp_reward: 1000,
  is_hidden: true,
  criteria: { type: "xp_threshold", target_value: 10000 }
})

On this page