Admin API

Admin endpoints manage tenant-wide gamification definitions (badges, tiers, leaderboards, streaks, rewards) and the participant catalogue. They sit under /api/v1/gamify/admin and use the same X-API-Key header as participant-facing endpoints. The only difference is the scope attached to the key.

Auth

All endpoints require an X-API-Key header. Production keys are prefixed bq_live_; sandbox keys bq_test_.

Scopes

Admin scope All admin endpoints require an API key with the admin or gamify:admin scope. The X-API-Key + Authorization Bearer model is unchanged; only the scope on the key differs from participant keys.

Base URLhttps://YOUR_API_DOMAIN/api/v1/gamify

Endpoint inventory

27 endpoints across six resources. Each resource follows the same List / Create / Get / Update / Delete shape. Per-resource pages carry the detailed field tables and error rows; this page is the catalogue and the home for cross-cutting admin behaviour.

Badges

Method	Endpoint	Purpose
GET	`/gamify/admin/badges`	List badge definitions.
POST	`/gamify/admin/badges`	Create a badge definition.
GET	`/gamify/admin/badges/{badge_id}`	Get one badge definition.
PATCH	`/gamify/admin/badges/{badge_id}`	Partial update of a badge definition.
DELETE	`/gamify/admin/badges/{badge_id}`	Soft-delete (sets `is_active=false`).

Definitions store the badge code, name, description, icon, category, rarity, and display ordering. Awarding badges to participants happens via fact evaluation or the dedicated award endpoint covered on the Badges reference. See full reference: Badges API →

Tiers

Method	Endpoint	Purpose
GET	`/gamify/admin/tiers`	List tier definitions (global only).
POST	`/gamify/admin/tiers`	Create a global tier definition.
GET	`/gamify/admin/tiers/{tier_id}`	Get one tier definition.
PATCH	`/gamify/admin/tiers/{tier_id}`	Update a tier definition.
DELETE	`/gamify/admin/tiers/{tier_id}`	Soft-delete the tier.

Tier definitions carry code, name, level, criteria, benefits, optional point multiplier, and presentation fields (icon, color, badge image). The Tiers reference also documents the participant-scoped read and manual-assign endpoints. See full reference: Tiers API →

Leaderboards

Method	Endpoint	Purpose
GET	`/gamify/admin/leaderboards`	List leaderboard definitions.
POST	`/gamify/admin/leaderboards`	Create a leaderboard definition.
GET	`/gamify/admin/leaderboards/{leaderboard_id}`	Get one leaderboard definition.
PATCH	`/gamify/admin/leaderboards/{leaderboard_id}`	Update a leaderboard definition.
DELETE	`/gamify/admin/leaderboards/{leaderboard_id}`	Soft-delete the leaderboard.

Definitions configure the metric, period (daily, weekly, monthly, all-time), scope, and ranking behaviour. Reading rankings is a participant-scoped operation covered on the dedicated page. See full reference: Leaderboards API →

Streaks

Method	Endpoint	Purpose
GET	`/gamify/admin/streaks`	List streak definitions.
POST	`/gamify/admin/streaks`	Create a streak definition.
GET	`/gamify/admin/streaks/{streak_id}`	Get one streak definition.
PATCH	`/gamify/admin/streaks/{streak_id}`	Update a streak definition.
DELETE	`/gamify/admin/streaks/{streak_id}`	Soft-delete the streak.

Streak definitions configure period (daily, weekly, monthly), optional grace period, and presentation. Read endpoints (current streak, history) are participant-scoped. See full reference: Streaks API →

Rewards

Method	Endpoint	Purpose
GET	`/gamify/admin/rewards`	List reward definitions.
POST	`/gamify/admin/rewards`	Create a reward definition. Code auto-generated as `gamify_<8 hex>`.
GET	`/gamify/admin/rewards/{reward_id}`	Get one reward definition.
PATCH	`/gamify/admin/rewards/{reward_id}`	Update a reward definition.
DELETE	`/gamify/admin/rewards/{reward_id}`	Soft-delete the reward.

Definitions carry type (coupon, voucher, physical, digital, points_multiplier), point cost, inventory caps, and claim limits. Code inventory and participant claim endpoints live on the dedicated page. See full reference: Rewards API →

Participants

Method	Endpoint	Purpose
GET	`/gamify/admin/participants`	List participants with search, filter, and sort.
DELETE	`/gamify/admin/participants/{participant_id}`	Hard-delete a participant, or anonymize via `?anonymize=true`.

Participant endpoints do not live on a per-resource Reference page. They are documented in full below.

GET/api/v1/gamify/admin/participants

Admin scope

List participants for the tenant with search, filter, sort, and pagination. Returns a flat aggregate per participant (points totals, current tier, activity counts) sourced from the user_state and ledger tables.

Query parameters

Field	Type	Description
search	Optional[str]	Free-text match against display name and participant_id.
is_active	Optional[bool]	Filter by active status.
tier	Optional[str]	Filter by current tier code (e.g. gold).
sort_by	Optional[str]	Sort column. Allowed: created_at, total_points, last_event_at, user_id, display_name. Default: `"created_at"`
sort_order	Optional[str]	Sort direction. Allowed: asc, desc. Default: `"desc"`
page	int	1-indexed page number. Minimum 1. Default: `1`
page_size	int	Items per page. Range 1 to 100. Default: `50`

GET /api/v1/gamify/admin/participants?search=jane&tier=gold&sort_by=total_points&sort_order=desc&page=1&page_size=50
X-API-Key: bq_live_xxxxx   # admin or gamify:admin scope

Response fields

Field	Type	Description
items	list[Participant]	Array of aggregated participant records.
items[].participant_id	str	Your participant identifier.
items[].display_name	Optional[str]	Display name where one has been captured.
items[].total_points	int	Lifetime points earned. Never decremented (used for tier and leaderboard ranking).
items[].available_points	int	Spendable balance. Decremented on redemption.
items[].current_tier	str	Current tier code (e.g. silver). Empty string when no tier is held.
items[].total_events	int	Count of facts emitted by or about this participant.
items[].first_seen_at	Optional[datetime]	First fact timestamp.
items[].last_seen_at	Optional[datetime]	Most recent fact timestamp.
items[].is_active	bool	False after anonymization or explicit deactivation.
items[].created_at	datetime	Row creation timestamp.
total	int	Total matching participants for the supplied filters.
page	int	Echo of the requested page.
page_size	int	Echo of the requested page_size.

{
  "items": [
    {
      "participant_id": "user_123",
      "display_name": "Jane Doe",
      "total_points": 12500,
      "available_points": 4200,
      "current_tier": "gold",
      "total_events": 156,
      "first_seen_at": "2026-01-04T08:11:00Z",
      "last_seen_at": "2026-05-23T14:02:11Z",
      "is_active": true,
      "created_at": "2026-01-04T08:11:00Z"
    }
  ],
  "total": 1,
  "page": 1,
  "page_size": 50
}

Errors

Status	Code	When it fires
401	unauthorized	X-API-Key header missing, invalid, expired, or revoked.
403	forbidden	API key is missing the admin or gamify:admin scope.

DELETE/api/v1/gamify/admin/participants/{participant_id}

Admin scope

Remove a participant. Default behaviour is a hard delete that removes every progression and event row for the participant. Pass ?anonymize=true to nullify PII and deactivate the participant instead, preserving aggregate history.

Path parameters

Field	Type	Description
participant_idrequired	str	Your participant identifier.

Query parameters

Field	Type	Description
anonymize	bool	When true, nullifies PII fields and sets is_active=false. When false (default), hard-deletes the participant and all related rows (claims, badges, tiers, streaks, milestones, leaderboard entries, challenge progress, ledger, facts, user_state). Default: `false`

# Hard delete
DELETE /api/v1/gamify/admin/participants/user_123
X-API-Key: bq_live_xxxxx   # admin or gamify:admin scope

# Anonymize (GDPR right-to-erasure with audit history preserved)
DELETE /api/v1/gamify/admin/participants/user_123?anonymize=true
X-API-Key: bq_live_xxxxx

Response fields

Field	Type	Description
message	str	Either "Participant deleted" (hard delete) or "Participant anonymized" (when ?anonymize=true).

// Hard delete
{ "message": "Participant deleted" }

// Anonymize
{ "message": "Participant anonymized" }

Errors

Status	Code	When it fires
401	unauthorized	X-API-Key header missing, invalid, expired, or revoked.
403	forbidden	API key is missing the admin or gamify:admin scope.
404	Participant not found	No participant exists for the supplied participant_id in this tenant.

About admin keys

Admin endpoints use the same API key transport as every other Gamification API call: the X-API-Key header with a bq_live_ or bq_test_ prefix. What promotes a key to admin is the presence of the admin or gamify:admin scope on the key record. Keys without either scope receive a 403 with detail API key requires ‘admin’ or ‘gamify:admin’ scope.

Mint admin keys from the Bricqs dashboard under Settings → API Keys. Treat them like production database credentials: store them in a secret manager, never embed them in client code, and rotate them on a schedule. The full participant-key + admin-key model is documented on the Authentication page.

Convention: every admin endpoint lives under /api/v1/gamify/admin/<resource>. If a path lacks the /admin segment it is participant-scoped and a participant-only key is sufficient.

React SDK

Headless SDK overview →

Hook signatures, props, auto-refresh behaviour.

← Back to Gamification API