API Examples src/api

Short illustrative examples. Use /openapi.json for the exact machine-readable contract.

Create participant

POST /v1/participants
{
  "phone_number": "+254700000000",
  "primary_language": "sw",
  "age_group": "60_69",
  "digital_literacy_level": "somewhat",
  "prior_web_use": false,
  "font_size_preference": "large",
  "self_efficacy_score": 55,
  "consent_recorded": true
}

Start session

POST /v1/sessions
{
  "template_id": "00000000-0000-0000-0000-000000000001",
  "device_type": "desktop",
  "signal_capture_mode": "full",
  "schema_version": 1,
  "il_score": 50,
  "language_code": "sw"
}

Submit event

POST /v1/sessions/{session_id}/events
{
  "client_event_id": "01HX...",
  "step_id": "personal-details",
  "step_type": "form_field",
  "event_timestamp": "2026-06-12T09:15:30Z",
  "detection_confidence": 0.82,
  "step_completed": false,
  "time_on_step_seconds": 42,
  "wrong_clicks": 2,
  "backtracking_count": 1,
  "field_clear_count": 0,
  "invalid_actions": 0,
  "frustration_decay": 20,
  "persistence_score": 65,
  "long_idle_count": 0,
  "internet_strength": "wifi",
  "connectivity_status": "stable",
  "language_mismatch": false,
  "device_flat": false,
  "usage_context": "alone",
  "help_request_count": 0,
  "explicit_help": false,
  "overlay_dismissed": false,
  "enrichment_data": {
    "_device_type": "desktop"
  }
}

Request help

POST /v1/sessions/{session_id}/help
{
  "step_id": "personal-details",
  "request_type": "button_press",
  "typed_message": "What should I enter here?"
}

Export view

GET /v1/dashboard/exports/readiness?format=csv
Authorization: Bearer <researcher-token>