Contests API
Time-boxed competitions with scoring, ranked leaderboards, and prize tiers. Contest CONFIGURATION (creation, publishing, prize setup, completion) is done in the Builder dashboard; this public surface covers entering and reading.
Auth
All endpoints require an
X-API-Key header. Production keys are prefixed bq_live_; sandbox keys bq_test_.Scopes
Participant key Reads (active list, public leaderboard, prizes) are PUBLIC. Entering and reading your own entry are conditional: a participant JWT is verified when present (and required for gated engagements); the token's identity overrides any body participant_id, so entries cannot be spoofed.
Base URL
https://api.bricqs.co/api/v1/gamifyEndpoint inventory
| Method | Endpoint | Auth | Purpose |
|---|---|---|---|
| GET | /gamify/contests/active | Public | Active contests, optionally filtered by engagement_id. |
| POST | /gamify/contests/{contest_id}/enter | Conditional | Enter the contest. Duplicate entries are rejected idempotently (one entry per participant). |
| GET | /gamify/contests/{contest_id}/me | Conditional | Your entry: score, rank, disqualification state. |
| GET | /gamify/contests/{contest_id}/leaderboard/public | Public | Ranked public leaderboard. |
| GET | /gamify/contests/{contest_id}/prizes | Public | Prize tiers for the contest. |
Semantics worth designing around
- Scoring is driven by emitted events during the contest window; the rules engine updates entry scores server-side.
- Completion and prize allocation run in a background lifecycle worker; on completion,
contest.completed.v1andcontest.prize_allocated.v1webhooks fire, andcontest.entry_submitted.v1fires on entry. - Anti-spoof: when a participant JWT is present its subject is authoritative for the entry identity, regardless of the request body.
Errors
| Status | Code | When it fires |
|---|---|---|
| 401 | AUTH_UNAUTHENTICATED | Entering a gated contest without a valid participant JWT. |
| 404 | not_found | Contest id unknown or not active. |
| 409 | already_exists | The participant already entered this contest. |
Related
← Back to Gamification API