Admin API

Create, update, and delete gamification definitions (badges, tiers, leaderboards, streaks, rewards). These endpoints require an API key with admin or gamify:admin scope.

Authentication: Requires an admin-scoped X-API-Key header. Base URL: https://YOUR_API_DOMAIN/api/v1/gamify

Resource	Endpoints	Operations
Badges	`/gamify/admin/badges`	List, Create, Get, Update, Delete
Tiers	`/gamify/admin/tiers`	List, Create, Get, Update, Delete
Leaderboards	`/gamify/admin/leaderboards`	List, Create, Get, Update, Delete
Streaks	`/gamify/admin/streaks`	List, Create, Get, Update, Delete
Rewards	`/gamify/admin/rewards`	List, Create, Get, Update, Delete
Participants	`/gamify/admin/participants`	List (search/filter/sort), Delete/Anonymize

Standard CRUD Pattern

All admin resources follow the same CRUD pattern:

# List with pagination and filters
GET  /api/v1/gamify/admin/badges?page=1&page_size=50&is_active=true

# Create
POST /api/v1/gamify/admin/badges
{
  "code": "streak_master",
  "name": "Streak Master",
  "description": "Maintain a 30-day streak",
  "icon_url": "https://cdn.example.com/badges/streak.png",
  "category": "achievement",
  "rarity": "epic",
  "display_order": 10
}

# Get by ID
GET  /api/v1/gamify/admin/badges/{badge_id}

# Update (partial)
PATCH /api/v1/gamify/admin/badges/{badge_id}
{ "name": "Updated Name", "rarity": "legendary" }

# Delete (soft-delete)
DELETE /api/v1/gamify/admin/badges/{badge_id}

Tier Definition Example

POST /api/v1/gamify/admin/tiers

{
  "code": "platinum",
  "name": "Platinum",
  "level": 4,
  "color": "#E5E4E2",
  "criteria_config": { "min_points": 10000 },
  "award_type": "automatic",
  "benefits": ["priority_support", "2x_points"],
  "display_order": 4
}

Streak Definition Example

POST /api/v1/gamify/admin/streaks

{
  "code": "daily_login",
  "name": "Daily Login Streak",
  "description": "Log in every day to build your streak",
  "period": "daily",
  "grace_period_hours": 24,
  "display_order": 1
}

Reward Definition Example

POST /api/v1/gamify/admin/rewards

{
  "name": "Premium Gift Card",
  "type": "voucher",
  "description": "Redeemable for premium items",
  "points_cost": 1000,
  "max_claims_per_user": 1,
  "total_inventory": 100,
  "is_active": true
}

Participant Management

# List participants with search, filter, and sort
GET /api/v1/gamify/admin/participants?search=jane&sort_by=total_points&sort_order=desc

{
  "items": [
    {
      "participant_id": "user_123",
      "display_name": "Jane Doe",
      "total_points": 5000,
      "available_points": 1500,
      "current_tier": "gold",
      "total_events": 156,
      "is_active": true
    }
  ],
  "total": 1, "page": 1, "page_size": 50
}

# Anonymize a participant (soft-delete, clears PII)
DELETE /api/v1/gamify/admin/participants/user_123?anonymize=true

# Hard delete a participant and all their data
DELETE /api/v1/gamify/admin/participants/user_123

← Back to Gamification API