Badges API
Award badges to participants and query earned status. Badge awards are idempotent — awarding the same badge twice returns already_earned: true instead of an error.
Authentication: All endpoints require an
X-API-Key header. Base URL: https://YOUR_API_DOMAIN/api/v1/gamify| Method | Endpoint | Description |
|---|---|---|
| POST | /gamify/badges/award | Award a badge (idempotent). |
| GET | /gamify/participants/{pid}/badges | List all badges with earned/unearned status. |
Award a Badge
POST /api/v1/gamify/badges/award
{
"participant_id": "user_123",
"badge_code": "power_user",
"metadata": { "trigger": "10th_login" }
}
// Response
{
"participant_id": "user_123",
"badge_code": "power_user",
"badge_name": "Power User",
"icon": "https://cdn.example.com/badges/power.png",
"rarity": "rare",
"earned_at": "2026-02-14T10:00:00Z",
"already_earned": false
}
// Award same badge again → idempotent
{
"already_earned": true,
"badge_code": "power_user",
"earned_at": "2026-02-14T10:00:00Z",
...
}List Badges
Query all badges for a participant with optional filters for earned status and specific badge codes.
// All badges (earned and unearned)
GET /api/v1/gamify/participants/user_123/badges
// Only earned badges
GET /api/v1/gamify/participants/user_123/badges?earned_only=true
// Specific badges by code
GET /api/v1/gamify/participants/user_123/badges?badge_codes=power_user,first_steps
// Response
{
"participant_id": "user_123",
"badges": [
{
"code": "power_user",
"name": "Power User",
"description": "Log in 10 times",
"icon": "https://...",
"rarity": "rare",
"earned": true,
"earned_at": "2026-02-14T10:00:00Z"
}
],
"total": 8,
"earned_count": 3
}