Participants API
Retrieve participant state, record screen visits for gate evaluation, and query the activity feed.
Authentication: Session-based. Pass
session_id and engagement_id as query parameters or in the request body. No API key required.Endpoints
| Method | Endpoint | Description |
|---|---|---|
| GET | /runtime/participant/state | Get participant state |
| POST | /runtime/participant/screen-visit | Track a screen visit |
| GET | /public/activity-log | Get activity feed |
Get Participant State
Returns the participant's accumulated state for an engagement, including completed activities, visited screens, and collected data.
curl -X GET "https://YOUR_API_DOMAIN/api/v1/runtime/participant/state?session_id=sess_abc123&engagement_id=550e8400-e29b-41d4-a716-446655440000"Response
{
"session_id": "sess_abc123",
"engagement_id": "550e8400-e29b-41d4-a716-446655440000",
"completed_activities": ["quiz_1", "spin_wheel_1"],
"visited_screens": ["screen-welcome", "screen-quiz"],
"user_state": {
"email": "user@example.com",
"first_name": "Alex"
},
"first_seen_at": "2026-04-10T14:00:00Z",
"last_seen_at": "2026-04-10T14:35:00Z"
}Track Screen Visit
Records that a participant visited a screen. Used for gate evaluation (e.g., "visited screen X" conditions) and analytics.
curl -X POST https://YOUR_API_DOMAIN/api/v1/runtime/participant/screen-visit \
-H "Content-Type: application/json" \
-d '{
"session_id": "sess_abc123",
"engagement_id": "550e8400-e29b-41d4-a716-446655440000",
"screen_id": "screen-rewards"
}'Response
{
"recorded": true,
"screen_id": "screen-rewards",
"visit_count": 1
}Activity Feed
Returns a chronological feed of the participant's activities, including completions, points earned, and badges awarded.
curl -X GET "https://YOUR_API_DOMAIN/api/v1/public/activity-log?session_id=sess_abc123&engagement_id=550e8400-e29b-41d4-a716-446655440000&limit=10"Response
{
"activities": [
{
"type": "activity_completed",
"activity_type": "quiz",
"activity_id": "quiz_1",
"timestamp": "2026-04-10T14:30:00Z",
"details": {
"score": 80,
"points_earned": 100
}
},
{
"type": "badge_earned",
"badge_code": "first_quiz",
"badge_name": "Quiz Master",
"timestamp": "2026-04-10T14:30:01Z"
},
{
"type": "reward_claimed",
"reward_name": "20% Off Coupon",
"reward_type": "coupon",
"timestamp": "2026-04-10T14:30:02Z"
}
],
"has_more": false
}