Contests API
Enter time-limited contests, view public leaderboards, check prize tiers, and retrieve your own contest entries.
Authentication: Session-based for participant endpoints. Pass
session_id or participant_id as query parameters.Endpoints
| Method | Endpoint | Description |
|---|---|---|
| GET | /contests/active | List active contests |
| POST | /contests/{id}/enter | Enter a contest |
| GET | /contests/{id}/leaderboard/public | Public leaderboard |
| GET | /contests/{id}/prizes | Prize tier information |
| GET | /contests/{id}/me | My contest entry |
List Active Contests
Returns all currently active contests for the tenant.
curl -X GET "https://YOUR_API_DOMAIN/api/v1/contests/active"Response
{
"contests": [
{
"id": "contest_001",
"name": "Spring Quiz Championship",
"description": "Score the highest across all quizzes this month",
"status": "active",
"starts_at": "2026-04-01T00:00:00Z",
"ends_at": "2026-04-30T23:59:59Z",
"scoring_method": "cumulative",
"entry_count": 342
}
]
}Enter Contest
Enters a participant in a contest. Returns the existing entry if already entered (idempotent).
curl -X POST https://YOUR_API_DOMAIN/api/v1/contests/{contestId}/enter \
-H "Content-Type: application/json" \
-d '{
"participant_id": "user_123",
"display_name": "Alex M."
}'Response
{
"entry_id": "entry_456",
"contest_id": "contest_001",
"participant_id": "user_123",
"entered_at": "2026-04-10T14:30:00Z",
"score": 0,
"rank": null
}Public Leaderboard
Returns the top entries in a contest, sorted by score with tie-breaking by earliest submission.
curl -X GET "https://YOUR_API_DOMAIN/api/v1/contests/{contestId}/leaderboard/public?limit=10"Response
{
"entries": [
{
"rank": 1,
"display_name": "Jordan K.",
"score": 2450,
"last_scored_at": "2026-04-10T12:00:00Z"
},
{
"rank": 2,
"display_name": "Alex M.",
"score": 2100,
"last_scored_at": "2026-04-10T14:30:00Z"
}
],
"total_entries": 342,
"updated_at": "2026-04-10T14:35:00Z"
}Prize Tiers
Returns the prize structure for a contest, including rank ranges and reward details.
curl -X GET "https://YOUR_API_DOMAIN/api/v1/contests/{contestId}/prizes"Response
{
"prizes": [
{
"rank_from": 1,
"rank_to": 1,
"label": "Grand Prize",
"reward_name": "$100 Gift Card",
"reward_type": "voucher"
},
{
"rank_from": 2,
"rank_to": 5,
"label": "Runner Up",
"reward_name": "20% Off Coupon",
"reward_type": "coupon"
},
{
"rank_from": 6,
"rank_to": 20,
"label": "Top 20",
"reward_name": "500 Bonus Points",
"reward_type": "points_multiplier"
}
]
}My Entry
Returns the current participant's contest entry, score, and rank.
curl -X GET "https://YOUR_API_DOMAIN/api/v1/contests/{contestId}/me?participant_id=user_123"Response
{
"entry_id": "entry_456",
"participant_id": "user_123",
"display_name": "Alex M.",
"score": 2100,
"rank": 2,
"entered_at": "2026-04-10T14:30:00Z",
"score_events": 5,
"status": "active"
}