Creating Achievements

This guide explains how to create achievements, define criteria, and configure rewards through the Admin API.

Overview

Achievement creation involves:

Defining achievement metadata (name, description, badge)
Setting up criteria (what users need to do)
Configuring rewards (optional)
Activating the achievement

All achievement configuration is done through the Admin API.

Endpoint

POST /v1/achievements?tenant_id=${tenant_id}

Basic Achievement

Example: First Win Achievement

{
  "name": "First Victory",
  "description": "Win your first match",
  "badge_url": "https://example.com/badges/first-victory.png",
  "criteria": {
    "type": "event_count",
    "event_type": "match.completed",
    "conditions": {
      "attrs.victory": { "eq": true }
    },
    "threshold": 1
  },
  "reward_config_id": null,
  "active": true
}

Response:

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "tenant_id": "your_tenant",
  "name": "First Victory",
  "description": "Win your first match",
  "badge_url": "https://example.com/badges/first-victory.png",
  "criteria": {
    "type": "event_count",
    "event_type": "match.completed",
    "conditions": {
      "attrs.victory": { "eq": true }
    },
    "threshold": 1
  },
  "reward_config_id": null,
  "active": true,
  "created_at": "2026-01-28T10:00:00Z",
  "updated_at": "2026-01-28T10:00:00Z"
}

Criteria Types

Event Count

Unlock after completing a certain number of events.

{
  "criteria": {
    "type": "event_count",
    "event_type": "match.completed",
    "conditions": {
      "attrs.victory": { "eq": true }
    },
    "threshold": 100
  }
}

Cumulative Metric

Unlock after reaching a total value.

{
  "criteria": {
    "type": "cumulative",
    "metric": "xp",
    "threshold": 10000
  }
}

Streak Milestone

Unlock after maintaining a streak.

{
  "criteria": {
    "type": "streak_milestone",
    "streak_id": "daily-login",
    "threshold": 7
  }
}

Leaderboard Rank

Unlock after achieving a specific leaderboard rank.

{
  "criteria": {
    "type": "leaderboard_rank",
    "leaderboard_id": "weekly-xp",
    "threshold": 10
  }
}

Combined Criteria

Unlock after meeting multiple conditions.

{
  "criteria": {
    "type": "combined",
    "operator": "and",
    "conditions": [
      {
        "type": "event_count",
        "event_type": "match.completed",
        "threshold": 50
      },
      {
        "type": "cumulative",
        "metric": "xp",
        "threshold": 5000
      }
    ]
  }
}

Configuring Rewards

Achievements can grant rewards when completed.

Attaching Reward Configuration

{
  "name": "Century Club",
  "description": "Win 100 matches",
  "badge_url": "https://example.com/badges/century-club.png",
  "criteria": {
    "type": "event_count",
    "event_type": "match.completed",
    "conditions": {
      "attrs.victory": { "eq": true }
    },
    "threshold": 100
  },
  "reward_config_id": "century-club-rewards",
  "active": true
}

The reward configuration defines what rewards are granted. See Reward Configuration for details.

Achievement Examples

Example: Win Streak Achievement

{
  "name": "Hot Streak",
  "description": "Win 5 matches in a row",
  "badge_url": "https://example.com/badges/hot-streak.png",
  "criteria": {
    "type": "streak",
    "event_type": "match.completed",
    "conditions": {
      "attrs.victory": { "eq": true }
    },
    "threshold": 5,
    "reset_on_failure": true
  },
  "reward_config_id": "hot-streak-rewards",
  "active": true
}

Example: XP Milestone Achievement

{
  "name": "XP Master",
  "description": "Earn 50,000 total XP",
  "badge_url": "https://example.com/badges/xp-master.png",
  "criteria": {
    "type": "cumulative",
    "metric": "xp",
    "threshold": 50000
  },
  "reward_config_id": "xp-master-rewards",
  "active": true
}

Example: Top Performer Achievement

{
  "name": "Top 10 Weekly",
  "description": "Finish in the top 10 of a weekly leaderboard",
  "badge_url": "https://example.com/badges/top-10.png",
  "criteria": {
    "type": "leaderboard_rank",
    "leaderboard_id": "weekly-xp",
    "threshold": 10
  },
  "reward_config_id": "top-10-rewards",
  "active": true
}

Updating Achievements

To update an existing achievement:

PUT /v1/achievements/{achievement_id}?tenant_id=${tenant_id}

Only include fields you want to update:

{
  "description": "Updated description",
  "active": false
}

Best Practices

Clear Criteria: Make achievement requirements clear and achievable
Progressive Difficulty: Start with easy achievements, increase difficulty
Meaningful Rewards: Grant rewards that feel valuable
Visual Design: Use attractive badge images
Progress Visibility: Show users their progress toward achievements
Variety: Create achievements for different play styles and activities

Next Steps

Querying Results - Learn how to retrieve achievement data
Achievements Overview - Understand the achievements system

Creating Achievements

On this page