Challenges API

Read challenge definitions, enroll participants, and track objective progress. Challenge CONFIGURATION (creating challenges, objectives, milestones) is done in the Builder dashboard; this public surface is the participant-facing read/act side.

Auth

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

Scopes

Participant key Definition reads (by-engagement, by-ids, leaderboard, feed) are PUBLIC: no credential required; tenant context resolves from the engagement. Enroll and progress are conditional: anonymous works for open engagements, and gated engagements require a participant JWT.

Base URLhttps://api.bricqs.co/api/v1/gamify

Endpoint inventory

Method	Endpoint	Auth	Purpose
GET	`/gamify/challenges/by-engagement/{engagement_id}`	Public	First active challenge for an engagement, with objectives and milestones.
GET	`/gamify/challenges/by-engagement/{engagement_id}/all`	Public	All challenges linked to an engagement.
POST	`/gamify/challenges/by-ids`	Public	Batch-fetch challenge definitions by id: body `{ "ids": [...] }`.
POST	`/gamify/challenges/{challenge_id}/enroll`	Conditional	Enroll the participant. Gated engagements require a participant JWT.
GET	`/gamify/challenges/{challenge_id}/progress`	Conditional	Objective-level progress for the participant.
GET	`/gamify/challenges/{challenge_id}/leaderboard`	Public	Challenge leaderboard. `limit` default 100, max 500; `offset`; optional `participant_id` for my-rank context.
GET	`/gamify/challenges/{challenge_id}/feed`	Public	Recent challenge activity feed entries.

How progress advances

Clients never write progress directly. Emit events (POST /gamify/events) and the objective evaluators advance progress server-side; read it back here or via the unified state read. Completion fires challenge.objective_completed.v1 and challenge.completed.v1 webhooks.

# 1. What challenges does this engagement have?
GET /api/v1/gamify/challenges/by-engagement/ENGAGEMENT_UUID/all

# 2. Enroll (participant JWT for gated engagements)
POST /api/v1/gamify/challenges/YOUR_CHALLENGE_ID/enroll
Authorization: Bearer <participant-jwt>

# 3. Act: emit qualifying events (see Events API)

# 4. Read progress
GET /api/v1/gamify/challenges/YOUR_CHALLENGE_ID/progress?participant_id=user_42

Errors

Status	Code	When it fires
401	AUTH_UNAUTHENTICATED	Enroll/progress on a gated engagement without a valid participant JWT.
404	not_found	Challenge id unknown, inactive, or not linked to the engagement.

React SDK

useChallenge / useChallenges →

Hook signatures, props, auto-refresh behaviour.

← Back to Gamification API