Challenges API
Retrieve active challenges, enroll participants, track progress across objectives and milestones, and view challenge leaderboards.
Authentication: Public endpoints. Pass
session_id and engagement_id as query parameters. No API key required.Endpoints
| Method | Endpoint | Description |
|---|---|---|
| GET | /public/challenges | Get active challenges for an engagement |
| POST | /public/challenges/{id}/enroll | Enroll participant in a challenge |
| GET | /public/challenges/{id}/progress | Get challenge progress for a session |
| GET | /public/challenges/{id}/leaderboard | Get challenge leaderboard rankings |
Get Challenges
Returns active challenges for an engagement, including objectives, milestones, and the participant's enrollment status.
curl -X GET "https://YOUR_API_DOMAIN/api/v1/public/challenges?engagement_id=550e8400-e29b-41d4-a716-446655440000&session_id=sess_abc123"Response
{
"challenges": [
{
"id": "ch_001",
"name": "Weekly Wellness Challenge",
"description": "Complete 5 activities this week",
"status": "active",
"starts_at": "2026-04-07T00:00:00Z",
"ends_at": "2026-04-14T00:00:00Z",
"enrolled": true,
"objectives": [
{
"id": "obj_1",
"name": "Complete a quiz",
"evaluator": "activity_count",
"target": 1,
"current": 1,
"completed": true
},
{
"id": "obj_2",
"name": "Log 3 workouts",
"evaluator": "activity_count",
"target": 3,
"current": 2,
"completed": false
}
],
"milestones": [
{
"name": "Getting Started",
"threshold": 1,
"reached": true
}
]
}
]
}Enroll in Challenge
Enrolls a participant in a challenge. Returns 409 Conflict if already enrolled.
curl -X POST https://YOUR_API_DOMAIN/api/v1/public/challenges/{challengeId}/enroll \
-H "Content-Type: application/json" \
-d '{
"session_id": "sess_abc123",
"engagement_id": "550e8400-e29b-41d4-a716-446655440000"
}'Response
{
"enrolled": true,
"challenge_id": "ch_001",
"enrolled_at": "2026-04-10T14:30:00Z"
}Get Progress
Returns the participant's progress for a specific challenge, including objective completion and milestones reached.
curl -X GET "https://YOUR_API_DOMAIN/api/v1/public/challenges/{challengeId}/progress?session_id=sess_abc123&engagement_id=550e8400-e29b-41d4-a716-446655440000"Response
{
"challenge_id": "ch_001",
"overall_progress": 0.6,
"score": 200,
"objectives": [
{
"id": "obj_1",
"current": 1,
"target": 1,
"completed": true
},
{
"id": "obj_2",
"current": 2,
"target": 3,
"completed": false
}
],
"milestones_reached": ["Getting Started"]
}Get Leaderboard
Returns the challenge leaderboard sorted by score.
curl -X GET "https://YOUR_API_DOMAIN/api/v1/public/challenges/{challengeId}/leaderboard?limit=10"Response
{
"entries": [
{
"rank": 1,
"participant_id": "p_456",
"display_name": "Alex M.",
"score": 950,
"objectives_completed": 5
},
{
"rank": 2,
"participant_id": "p_789",
"display_name": "Jordan K.",
"score": 820,
"objectives_completed": 4
}
],
"total_participants": 142
}