For: Full Stack · Backend API

API reference

The REST API used by the website, the student area and the dashboard (111 endpoints), with authentication and errors.

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/login or /register sets maarifa_student (30 days).
  • Dashboard: POST /api/auth/login sets maarifa_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.