Public API (v1)
For schools, learning platforms and content creators. Scoped keys, OAuth for organisations, child data always pseudonymous.
| Endpoint | Usage | Authentication |
|---|---|---|
POST/v1/orgs/{id}/learners | Create a learner (pseudonym, grade, languages) | API key |
GET/v1/learners/{id}/progress | Mastery per skill, confusions, fluency, last activity | API key |
POST/v1/learners/{id}/assignments | Assign a track/unit (temporarily overrides adaptation) | API key |
POST/v1/wordlists | Custom word list → cards (goes through review) | API key |
GET/v1/children/{id}/report.pdf | PDF report for parent / therapist | Parent JWT |
POST/v1/webhooks | Events: unit.completed, mastery.reached, inactivity.7d, subscription.changed | API key |
POST/v1/speech/assess | Score pronunciation of a known word (partners) | API key |
GET/v1/content/packs?language=ar | List published units | Public |
GET/v1/content/units/{id} | Full unit with cards inline | Public |
GET/v1/children/{id}/stats/weekly | Weekly stats for the parent dashboard | Parent JWT |
POST/v1/children/{id}/sync | Push attempts / pull mastery (offline-first) | Parent JWT |
GET/health | Service health | Public |
curl https://api.alifly.app/v1/learners/lrn_8f2/progress \
-H "Authorization: Bearer sk_live_..."
{
"learner": "lrn_8f2",
"language": "ar",
"tracks": {
"letters": { "mastery": 0.78, "current_unit": "JHK" },
"sounds": { "mastery": 0.61 },
"vowels": { "locked": true }
},
"confusions": [["ح","خ",0.31],["ت","ث",0.18]],
"fluency_ms": 1300
}Authentication
Scoped API keys (read / write / assess) for organisations. OAuth 2.0 for school platforms. Send the key in the Authorization: Bearer header.
Limits
600 req/min per key · HMAC-signed webhooks · full access log · data export and deletion on request (GDPR).
POST/v1/orgs/{id}/learners
Create a learner (pseudonym, grade, languages)
Request
{ "pseudonym": "Y. B.", "childId": "ch_…" }Response
{ "id": "lrn_8f2", "pseudonym": "Y. B.", "consentByParentAt": null }GET/v1/learners/{id}/progress
Mastery per skill, confusions, fluency, last activity
Response
{
"learner": "lrn_8f2",
"language": "ar",
"tracks": {
"letters": { "mastery": 0.78, "current_unit": "JHK" },
"sounds": { "mastery": 0.61 },
"vowels": { "locked": true }
},
"confusions": [["ح","خ",0.31],["ت","ث",0.18]],
"fluency_ms": 1300
}POST/v1/learners/{id}/assignments
Assign a track/unit (temporarily overrides adaptation)
Request
{ "track": "T1", "unitId": "ar-T1-u2" }Response
{ "id": "asg_…", "track": "T1", "unitId": "ar-T1-u2", "createdAt": "2026-09-13T10:00:00Z" }POST/v1/wordlists
Custom word list → cards (goes through review)
Request
{ "language": "ar", "learnerId": "lrn_8f2", "words": ["بَيْت", "قَمَر"] }Response
{ "id": "wl_…", "status": "review", "words": 2 }GET/v1/children/{id}/report.pdf
PDF report for parent / therapist
Response
application/pdf
POST/v1/webhooks
Events: unit.completed, mastery.reached, inactivity.7d, subscription.changed
Request
{ "url": "https://school.example/hooks/alifly", "events": ["unit.completed", "mastery.reached"] }Response
{ "id": "wh_…", "secret": "whsec_…" }POST/v1/speech/assess
Score pronunciation of a known word (partners)
Request
{ "target": "بَيْت", "language": "ar", "audioBase64": "…", "mimeType": "audio/m4a" }Response
{ "transcript": "بيت", "score": 0.92, "match": "correct" }GET/v1/content/packs?language=ar
List published units
Response
[{ "id": "ar-T1-u1", "track": "T1", "level": 1, "title": { "ar": "ب ت ث" }, "version": 3 }]GET/v1/content/units/{id}
Full unit with cards inline
GET/v1/children/{id}/stats/weekly
Weekly stats for the parent dashboard
Response
{ "minutes": 38, "cards": 142, "accuracy": 0.81, "streak": 5, "perTrack": [...], "confusions": [...], "fluency": [...], "firstGain": "ح/خ" }POST/v1/children/{id}/sync
Push attempts / pull mastery (offline-first)
GET/health
Service health
Response
{ "ok": true }