API reference

Base URL and response format

Every route is served under the /api prefix. Locally the base URL is http://localhost:8000/api. On a server it is your API's address followed by /api, the same value both frontends read from NEXT_PUBLIC_API_BASE_URL (Environment variables).

The API serves two audiences that never share a token. Students use the routes under /api/users/<area> and /api/shop, listed in the student sections below. The admin dashboard uses every other route, including /api/users itself and /api/users/<username>, which manage student accounts.

Request bodies are JSON, except the file upload. Every answer comes in the same envelope:

{
  "success": true,
  "data": { },
  "message": ""
}

data holds the result. message is a short sentence some writes fill in, translated to the request's language, and empty otherwise. The health check needs no token and shows the envelope:

curl http://localhost:8000/api/health

{"success":true,"data":{"status":"ok"},"message":""}

It answers 503 while the database cannot be reached or holds no tables, so a load balancer can use it as a readiness probe.

Errors

A failed request answers with the matching HTTP status and the same envelope, with success: false, data: null and, for validation, the problems per field, keyed by the field's name (a field inside a nested object by its dotted path):

curl -X POST http://localhost:8000/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email":"not-an-email","password":"x"}'

{
  "success": false,
  "data": null,
  "message": "Enter a valid email address (example@domain.com).",
  "errors": {
    "email": ["Enter a valid email address (example@domain.com)."]
  }
}

Successful writes answer 201 for POST and 200 for the other methods.

Pagination and sorting

Lists come in two shapes, one per audience. The student routes answer in the shape the student site reads; the admin routes answer in the shape the dashboard reads.

A page holds at most 100 rows: a larger page size is read as 100, and a missing or unreadable one falls back to the list's default. The same goes for page, which falls back to 1.

sort only accepts the columns each list allows. An unknown key falls back to the default order instead of failing, so an old bookmark still loads.

The public course list sorts by id, price, discount_percentage, rating, duration, level, language, created_at or updated_at, and filters by title, category_id, instructor_id and type (live or recorded).

Language

Send the reader's language in the Accept-Language header. The API speaks the languages listed in back-end/src/i18n/locales.ts, en and ar as shipped. It reads the first tag, so ar-SA is Arabic, and a request that names no supported language is answered in the default_locale setting's language. There is no language query parameter.

• Error messages and the message of a successful write are translated.
• Text stored in both languages, such as course titles and descriptions, comes back as { "en": "...", "ar": "..." } and the client picks one.
• A few student routes answer in the requested language only: the enrolment list, a course's content and the search.
• Checkout takes the language from its body (locale, one of the supported languages), so the receipt matches the page the student bought on.

Authentication

Students and admins sign in at different endpoints, against different tables, and receive tokens only their own routes accept.

• Both are JWTs signed with JWT_SECRET. Send them as Authorization: Bearer <token>.
• A token lasts for JWT_EXPIRATION, 7d by default (Environment variables). The admin sign-in reports the same value as expires_in.
• There is no refresh endpoint. When a token expires, the next request answers 401 and the client signs in again.
• Signing out (POST /api/users/auth/logout) only tells the client to drop its token. Nothing is revoked on the server, so a token stays valid until it expires.
• A student token is refused on admin routes and an admin token on student routes, although both use the same secret.
• A failed sign-in answers 401 with one message, whether the email has no account or the password is wrong, so the form cannot be used to find out who has an account.
• The sign-in, sign-up and password routes accept 10 attempts a minute from one address, counted per route. Past that they answer 429 with a Retry-After header. The count is kept in the API's memory, so it starts again on a restart and is counted separately by each instance.

1. 01

   Sign in as the seeded Super Admin

   TerminalCopy

   curl -X POST http://localhost:8000/api/auth/login \
     -H "Content-Type: application/json" \
     -d '{"email":"admin@learnio.com","password":"Admin@123"}'

   ResponseCopy

   {
     "success": true,
     "data": {
       "access_token": "eyJhbGciOiJIUzI1NiIs...",
       "token_type": "Bearer",
       "expires_in": "7d",
       "admin": {
         "id": 1,
         "email": "admin@learnio.com",
         "instructor_id": null,
         "roles": [{ "id": 1, "name": "Super Admin", "guard_name": "web" }],
         "permissions": ["admins.view", "admins.create", "..."]
       }
     },
     "message": "Signed in successfully."
   }
2. 02

   Call a protected route with the token

   TerminalCopy

   curl "http://localhost:8000/api/courses?page=1&page_count=5" \
     -H "Authorization: Bearer <access_token>"

   Expected result: The first five courses, in the admin list shape.
3. 03

   Sign in as the seeded student

   The sample data also holds a student, demo@learnio.com with the password Demo@123:

   TerminalCopy

   curl -X POST http://localhost:8000/api/users/auth/login \
     -H "Content-Type: application/json" \
     -d '{"email":"demo@learnio.com","password":"Demo@123"}'

   Then pass data.token the same way, for example to GET /api/users/enrollments.

Permissions

Every admin route checks the token first, then the permission it names. Permissions are named <module>.<action>, and an admin holds every permission of every role they have. Where a route names several, any one of them is enough. In the admin tables below, a permission name in the Who can call it column means an admin whose roles grant it.

Running the seeder again creates the roles that are missing and leaves existing roles' permissions as they are, so changes made in the dashboard survive. Super Admin is the exception: it receives any permission it does not hold yet.

Every read permission ends in .view and nothing else does: the seeded Viewer role is built from that rule. The roles the sample data creates:

An admin account linked to an instructor carries an instructor_id in its sign-in answer, and is held to its own courses on top of its permissions: lists show only those courses and their students, and a write outside them answers 403.

When an admin's roles change, the dashboard is told over the /auth socket (event permissions-updated) so it can refresh GET /api/auth/me. That socket accepts admin tokens only.

Public catalogue

No token needed. These are the routes the student site's public pages call.

The capital I in /api/users/Instructors is the path the student site calls; matching is not case sensitive.

Student sign-up and sign-in

The student site uses the routes under /api/users/auth. Registration signs the student in straight away and mails a confirmation link; an unconfirmed account can still browse and buy.

resend and forgot-password answer the same way whether or not the address has an account, so they cannot be used to find out who is registered. Sign-in, registration, resend, forgot-password and reset-password are rate limited (Authentication).

A second set of student routes under /api/students/auth works on the same accounts, answering token and user too. The student site does not use it; prefer /api/users/auth.

Student profile, courses and progress

Every route here needs a student token. Courses and lessons are addressed by their code, not their numeric id.

The review routes take the course's numeric id, and each student has one review per course. Only a student enrolled on the course can write one; a cancelled enrolment answers 403.

• A review is published straight away, or pending until a moderator approves it when the reviews_require_approval setting is true. Editing a review a moderator hid sends it back to pending.
• A review a moderator deleted comes back with status: removed and can no longer be edited or withdrawn (403).
• Every write recomputes the course's rating and review count, and those of its instructor.
• A new review, and an edit that waits for approval, notifies the staff who hold reviews.view.

Quizzes, assignments and calendar

The calendar's live class routes are described with Live classes.

Student messages and notifications

New notifications are also pushed over Socket.IO, on the /notifications namespace at the API's address without /api. Pass the token as auth.token in the handshake and listen for notification:created. Admins use the same socket with their own token.

Checkout and payments

When the checkout answers with redirect_url, send the buyer there and treat the order as pending: the seat is granted when the processor's webhook confirms the payment, not on the return. Each webhook checks the processor's signature and answers 401 when it does not match. Events are applied once, however often the processor retries.

A free course (price 0) goes through the same route and never reaches a processor, so it works with no payment keys at all. The order is written as paid with gateway: "free" and redirect_url: null, the seat is granted at once, and the student receives the enrolment email without a receipt. Free orders count as enrolments, not sales: they are left out of the average order value.

Setting up the processors and their webhook subscriptions: Payments.

Admin sign-in and staff accounts

An email address belongs to one admin, including a deleted one: creating an admin, or changing an email to one already used, answers 409.

Roles

Students

Student accounts are addressed by username. Deleting one is a soft delete that can be restored.

Instructors

An instructor account messages its students through these routes, which answer 403 for an admin not linked to an instructor:

Categories

The reads are open to anyone and listed with the Public catalogue. Writes need a permission:

Courses

Curriculum: sections, lessons and resources

Quizzes and assignments

Enrolments and orders

An order's status is pending, paid, failed or refunded. Its gateway names the processor that took the payment, demo for the built-in simulator, or free for a course that cost nothing.

Reviews

Students write their own reviews through the student routes, and the course page reads the published ones from the Public catalogue. Every moderation change recomputes the course's and the instructor's rating.

Blog

Settings

Platform settings are stored as key and value pairs and addressed by key.

The seeder creates these six, and each is read by the API or the student dashboard:

A change takes effect on the next request or email, with no restart. Running the seeder again adds a missing setting but never overwrites a value already saved.

Media uploads

Send multipart/form-data with the file in file, up to 150 MB, and optionally path (the folder, uploads by default), for (an image size preset) and type (video to skip image processing). Images are resized into several versions; video (mp4, webm, mov, m4v) is stored as it is. It needs the bucket settings in Media storage.

The route needs an admin or a student token, checked before the file is read. path must be one of the folders listed in back-end/src/modules/helpers/upload/upload-folders.constants.ts; any other answers 400. An admin may upload to uploads, admins/profile, admins/profiles, users/profiles, blog, categories, courses, instructors, messages and ai-chat. A student may upload only to messages, for the images they attach to a conversation. A new screen that uploads to a folder of its own needs that folder added to the list.

curl -X POST http://localhost:8000/api/helpers/upload \
  -H "Authorization: Bearer <access_token>" \
  -F "file=@cover.jpg" -F "path=courses"

Notifications, search and statistics

An admin only ever reads and changes their own notifications: the routes take the admin from the token. The API writes one for each of these events, to every admin holding the permission the linked screen needs:

An admin account linked to an instructor hears only about that instructor's own courses, and not about new sign-ups. Each one is also pushed over the /notifications socket as it is saved.

Live classes

Certificates

AI assistant

Assistant chat history

MCP server

Demo mode routes

Custom payment gateways