All endpoints live under /api, take and return JSON, and use the same error shape:
{ "error": { "code": "validation", "message": "price: Too small: expected number to be >=0" } }
| Status | Codes you will see |
|---|---|
| 400 | bad_json |
| 401 | unauthorized, invalid_credentials |
| 403 | forbidden, not_enrolled, locked, no_profile |
| 404 | not_found (also for records outside an instructor's scope) |
| 409 | conflict (slug, code or email used), in_use, has_students, already_passed, no_attempts_left, not_eligible, owned, bad_transition, last_admin, self |
| 422 | validation, coupon_invalid, payment_disabled, payment_required, unavailable |
| 429 | rate_limited |
| 502/503 | payment_unavailable, ai_failed, ai_off |
Money is always an integer in baisa (1 OMR = 1000). Dates are ISO 8601.
Authentication
Two separate sessions, both httpOnly cookies signed with AUTH_SECRET:
- Students:
POST /api/account/loginor/registersetsmaarifa_student(30 days). - Dashboard:
POST /api/auth/loginsetsmaarifa_staff(12 hours). Every request re-reads the account, so switching an account off or changing its role applies at once.
PATCH endpoints change only the fields you send: {"status":"ARCHIVED"} on a course keeps everything else.
Public
| Method | Path | |
|---|---|---|
| GET | /api/academy |
Academy details, payment options, categories with counts, headline numbers |
| GET | /api/courses |
Published courses. Query: q, category (comma list), level, price=free|paid, lang, rating (3, 3.5, 4, 4.5), duration=short,medium,long, sort=popular|rating|newest|price-asc|price-desc, page, perPage |
| GET | /api/courses/{slug} |
Course page: syllabus with lesson titles and preview flags, instructor, FAQ, reviews, rating breakdown; viewer tells a signed-in student if they are enrolled or saved it |
| GET | /api/courses/{slug}/reviews |
Approved reviews |
| GET | /api/instructors, /api/instructors/{slug} |
Profiles with experience, skills and courses |
| GET | /api/blog, /api/blog/{slug} |
Published articles |
| GET | /api/certificates/{code} |
Certificate verification |
| POST | /api/cart/quote |
{courseIds, couponCode?} → lines with issues, coupon result, subtotal, discount, tax, total, payment options |
| GET | /api/learn/{slug}/lessons/{lessonId} |
A lesson: preview lessons for anyone, every lesson for enrolled students, otherwise 403 locked |
| GET | /api/payments/thawani/return |
Thawani's return URL; verifies the session with Thawani, then redirects to the student's orders |
Student
| Method | Path | |
|---|---|---|
| POST | /api/account/register |
{name, email, password (8+), phone?} |
| POST | /api/account/login, /api/account/logout |
|
| GET, PATCH | /api/account/me |
Profile, saved and enrolled course ids, unread messages; PATCH {name?, phone?, headline?} |
| PUT | /api/account/password |
{current, next} |
| GET, POST, DELETE | /api/account/wishlist |
Saved courses; body {courseId} |
| GET | /api/account/courses |
My enrolments with progress, resume lesson and certificate code |
| GET | /api/account/certificates |
My certificates |
| GET | /api/account/orders |
My orders |
| GET, POST | /api/account/messages |
My conversations; POST {courseSlug, subject, body} (enrolled courses only) |
| GET, POST | /api/account/messages/{id} |
A conversation (marks it read); POST {body} |
| POST | /api/courses/{slug}/enrol |
Enrol in a free course |
| POST | /api/courses/{slug}/reviews |
{rating 1-5, body}, enrolled students only; waits for moderation |
| POST | /api/orders |
{courseIds, couponCode?, paymentMethod: CARD|BANK, locale} → {code, status}, plus payUrl for cards. A zero total is paid and enrolled at once |
| GET | /api/learn/{slug} |
Outline with done flags, quiz states, progress, resume lesson, live sessions with links, certificate state |
| POST | /api/learn/{slug}/lessons/{lessonId}/complete |
{done: true|false} → {progress} |
| PUT | /api/learn/{slug}/lessons/{lessonId}/note |
{body} (empty deletes) |
| GET | /api/learn/{slug}/quizzes/{quizId} |
Questions without right answers, my attempts, attempts left |
| POST | /api/learn/{slug}/quizzes/{quizId}/attempts |
{answers: [optionIndex or -1, ...]} → score, passed, attempts left, review with right answers and explanations |
| POST | /api/learn/{slug}/certificate |
Issues the certificate, or 409 not_eligible with what is missing |
Dashboard
Permissions in brackets (see Admin & instructor dashboard). Instructors only reach their own courses and everything attached to them.
| Method | Path | |
|---|---|---|
| POST | /api/auth/login, /api/auth/logout |
|
| GET | /api/auth/me |
Account and permissions |
| GET | /api/dashboard/stats |
Overview numbers and charts |
| GET | /api/dashboard/earnings |
Sales and instructor share [earnings] |
| GET, POST | /api/dashboard/courses |
List (status, q) and create [courses]; publishing needs [publish] |
| GET, PATCH, DELETE | /api/dashboard/courses/{id} |
Editor data, update, delete (only without learners or orders) |
| POST | /api/dashboard/courses/{id}/sections |
{titleAr, titleEn, sort?} |
| PATCH, DELETE | /api/dashboard/sections/{id} |
|
| POST | /api/dashboard/courses/{id}/lessons |
{sectionId, titleAr, titleEn, kind, videoUrl, bodyAr, bodyEn, minutes, preview} |
| GET, PATCH, DELETE | /api/dashboard/lessons/{id} |
Progress of enrolled learners is recomputed after adding or removing lessons |
| GET, POST | /api/dashboard/quizzes |
[quizzes] |
| GET, PATCH, DELETE | /api/dashboard/quizzes/{id} |
Quiz with questions and right answers |
| POST | /api/dashboard/quizzes/{id}/questions |
{kind: MCQ|TF, promptAr, promptEn, options:[{ar,en}], correct, explanationAr?, explanationEn?} |
| PATCH, DELETE | /api/dashboard/questions/{id} |
|
| GET, POST | /api/dashboard/sessions |
Live sessions (from, to) [schedule] |
| PATCH, DELETE | /api/dashboard/sessions/{id} |
|
| GET | /api/dashboard/messages |
Threads (status, unread) [messages] |
| GET, POST, PATCH | /api/dashboard/messages/{id} |
Read, reply {body}, close/reopen {status} |
| GET | /api/dashboard/students, /api/dashboard/students/{id} |
[students] |
| GET, POST | /api/dashboard/enrolments |
List; POST {studentId, courseId} (admins) |
| DELETE | /api/dashboard/enrolments/{id} |
Admins; paid enrolments are refunded instead |
| GET | /api/dashboard/reviews |
(status, rating) [reviews] |
| PATCH, DELETE | /api/dashboard/reviews/{id} |
{status?, featured?, reply?}; featuring and deleting are for admins |
| GET, POST | /api/dashboard/posts |
[blog] |
| GET, PATCH, DELETE | /api/dashboard/posts/{id} |
|
| GET, POST | /api/dashboard/categories |
GET for any account; changes [categories] |
| PATCH, DELETE | /api/dashboard/categories/{id} |
|
| GET, POST | /api/dashboard/instructors |
[instructors] |
| PATCH, DELETE | /api/dashboard/instructors/{id} |
|
| GET | /api/dashboard/orders |
(status, method, q) [orders] |
| GET, PATCH | /api/dashboard/orders/{id} |
PATCH {status: PAID|CANCELLED|REFUNDED} following the order flow |
| GET, POST | /api/dashboard/coupons |
[coupons] |
| PATCH, DELETE | /api/dashboard/coupons/{id} |
|
| GET, POST | /api/dashboard/admins |
Accounts [admins] |
| PATCH, DELETE | /api/dashboard/admins/{id} |
Keeps at least one active admin |
| GET, PUT | /api/dashboard/roles |
{INSTRUCTOR: [...]} [roles] |
| GET, PATCH | /api/dashboard/settings |
[settings] |
| POST | /api/dashboard/uploads |
multipart file: JPEG, PNG, WebP, AVIF or GIF up to 5 MB → {url} |
| POST | /api/dashboard/ai/describe |
{courseId, notes?} → draft texts [ai] |
| POST | /api/dashboard/ai/quiz |
{lessonId, count} → draft questions [ai] |
| POST | /api/dashboard/ai/ask |
{messages: [{role, content}]} → {answer} [ai] |
Order flow
PENDING → PAID (Thawani confirmation for cards; an admin for bank transfers) or CANCELLED/FAILED. PAID → REFUNDED (enrolments of the order removed). Free orders are created PAID.
Testing the API
python scripts/e2e_api.py runs the main flows against a running server with a fresh demo database: catalogue and filters, sign-up, free enrolment, lesson access, progress, quiz scoring and attempt limits, certificates and verification, checkout with coupons, bank transfer confirmation and refund, role checks for instructors, validation errors and PATCH partial updates.