> ## Documentation Index
> Fetch the complete documentation index at: https://ihub.learnille.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Master API Endpoint Map

> Migrated from the previous Learnille internal documentation hub

## Overview

This document provides a comprehensive reference map of all REST API endpoints provided by the NestJS backend server (`server/src`). All endpoints require Bearer JWT authentication via `JwtAuthGuard` unless explicitly marked public (`@Public()`).

***

## 🔐 1. Authentication & User Management (`/auth`, `/users`)

| Method | Endpoint | Access Level | Description |
| :- | :- | :- | :- |
| `POST` | `/auth/register` | Public | Register new user (Student, Instructor, Consultant). |
| `POST` | `/auth/login` | Public | Authenticate user credentials and issue JWT pair. |
| `POST` | `/auth/refresh` | Public | Refresh expired access token using refresh token. |
| `POST` | `/auth/logout` | Authenticated | Revoke active refresh token. |
| `POST` | `/auth/forgot-password` | Public | Request password reset code via email. |
| `POST` | `/auth/reset-password` | Public | Reset password using verified code. |
| `GET` | `/users/me` | Authenticated | Retrieve current user profile details. |
| `PATCH` | `/users/me` | Authenticated | Update user profile, avatar, and notification settings. |

***

## 📚 2. Course Engine (`/course`, `/category`)

| Method | Endpoint | Access Level | Description |
| :- | :- | :- | :- |
| `GET` | `/course` | Public | List published courses with pagination and category filters. |
| `GET` | `/course/slug/:slug` | Public | Get full course details by unique slug. |
| `POST` | `/course` | Instructor / Admin | Create a new draft course. |
| `PATCH` | `/course/:id` | Instructor / Admin | Update course metadata, pricing, and level. |
| `POST` | `/course/:id/sections` | Instructor / Admin | Add section to course curriculum. |
| `POST` | `/course/sections/:id/subsections` | Instructor / Admin | Add subsection to course section. |
| `POST` | `/course/subsections/:id/items` | Instructor / Admin | Add video/quiz/document item to subsection. |
| `POST` | `/course/progress` | Owning student | Mark an enrolled active lesson complete. |
| `POST` | `/course/progress/video` | Owning student | Save progress for an enrolled active video. |
| `GET` | `/category` | Public | List top-level categories and subcategories. |

***

## 🗓 3. Consultation Booking & Sessions (`/consultation`, `/sessions`, `/orders`)

| Method | Endpoint | Access Level | Description |
| :- | :- | :- | :- |
| `GET` | `/consultation` | Public | List active consultations with filter criteria. |
| `GET` | `/consultation/slug/:slug` | Public | Retrieve consultation profile by slug. |
| `POST` | `/consultation` | Consultant | Create new one-off or recurring consultation offer. |
| `POST` | `/consultation/:id/availability` | Consultant | Set weekly availability slots and buffer times. |
| `GET` | `/consultation/:id/availability` | Public | Query available booking time slots for dates. |
| `POST` | `/orders` | Authenticated purchaser | Purchase or rebook a consultation through direct/cart checkout; creates a new booking on fulfillment. |
| `GET` | `/enrollment/check/:productType/:productId` | Authenticated | Read enrollment and `canPurchase`; existing consultation enrollment does not prevent rebooking. |
| `POST` | `/sessions/:id/request-reschedule` | Owning consultant | Prompt the booked student to reschedule an eligible missed session; no date/status change. |
| `POST` | `/sessions/:id/reschedule` | Booked student | Select a replacement time; apply after fee payment where required. |
| `POST` | `/sessions/:id/approve-reschedule` | Owning consultant / Admin | Change a rescheduled session to scheduled. |
| `POST` | `/sessions/:id/join` | Session participant | Record attendance for the current session time. |
| `POST` | `/sessions/:id/complete` | Owning consultant / Admin | Enqueue finalization; attendance determines completion and release scheduling. |
| `GET` | `/calendar` | Authenticated | Consultation and space events for the student or consultant view; each event includes `googleCalendarUrl`. |
| `GET` | `/calendar/events/:type/:id.ics` | Session participant / host | Download one consultation or space session as an `.ics` file. |
| `GET` | `/calendar/feed` | Authenticated | Whether the user has an active calendar subscription link. |
| `POST` | `/calendar/feed` | Authenticated | Create a private calendar feed URL (shown once) and revoke any previous one. |
| `DELETE` | `/calendar/feed` | Authenticated | Turn the calendar feed off. |
| `GET` | `/calendar/feed/:token.ics` | Public (token in URL) | The calendar feed fetched by Google, Apple or Outlook. Not IP rate limited; cached per token for 5 minutes. |

The purchase/rescheduling/session rows above were reviewed on 2026-09-23. See the
[rescheduling and rebooking lifecycle](https://ihub.learnille.com/engineering/architecture/consultation-rescheduling-and-rebooking.md)
and [QA checklist](https://ihub.learnille.com/engineering/testing-and-qa/consultation-rescheduling-and-rebooking.md). Detailed
HTTP contracts remain in the separate API documentation; other sections of this map
retain their existing review status.

***

## 💳 4. Wallet & Withdrawal System (`/wallet`, `/withdrawals`)

| Method | Endpoint | Access Level | Description |
| :- | :- | :- | :- |
| `GET` | `/wallet/balance` | Authenticated | Get provider wallet balance (available, pending hold). |
| `GET` | `/wallet/revenue-chart` | Authenticated | Retrieve earnings history broken down by period. |
| `GET` | `/withdrawals/methods` | Authenticated | List configured payout bank accounts / recipient IDs. |
| `POST` | `/withdrawals/methods` | Authenticated | Add new withdrawal method (OTP verification required). |
| `POST` | `/withdrawals/request` | Authenticated | Initiate withdrawal request from available balance. |
| `POST` | `/withdrawals/:id/verify` | Authenticated | Verify pending withdrawal using approval OTP. |
| `PATCH` | `/withdrawals/:id/approve` | Admin Only | Administrative approval and execution of bank payout. |
| `POST` | `/payment/paystack-webhook` | Public (Paystack signature) | Paystack charges, transfers, refunds and disputes. |
| `POST` | `/payment/flutterwave-webhook` | Public (Flutterwave signature) | Flutterwave v3/v4 charges, transfers, refunds and chargebacks. |
| `POST` | `/payment/webhook/:gateway` | Public (provider signature) | Older single entry point; runs the same handlers as the two routes above. To be removed. |
| `GET` | `/payment/failed-webhooks` | Admin Only | Webhooks that failed processing and their recovery status. |
| `POST` | `/payment/failed-webhooks/:id/retry` | Admin Only | Retry a failed webhook. |
| `POST` | `/payment/failed-webhooks/:id/resolve` | Admin Only | Mark a failed webhook as resolved by hand. |

Webhook events, signatures and their effects are documented in the API docs under *Flows → Payment Webhooks*.

***

## 🔍 5. Quality Validation Queue (`/validation`, `/admin`)

| Method | Endpoint | Access Level | Description |
| :- | :- | :- | :- |
| `GET` | `/validation/queue` | Admin Only | Fetch list of courses and consultations pending review. |
| `POST` | `/validation/course/:id/submit` | Instructor | Submit course for admin validation. |
| `POST` | `/product/:id/approve` | Admin Only | Approve course/consultation for public marketplace. |
| `POST` | `/product/:id/reject` | Admin Only | Reject product submission with feedback notes. |

***

## ⚡ 6. Real-Time & Analytics Endpoints (`/instant`, `/analytics`)

| Method | Endpoint | Access Level | Description |
| :- | :- | :- | :- |
| `GET` | `/instant/session-room` | Authenticated | Obtain InstantDB room token and presence credentials. |
| `POST` | `/analytics/beacon` | Authenticated | Ingest student active time, video heartbeats, and engagement. |
| `GET` | `/analytics/platform-overview` | Admin Only | View system-wide metrics (GMV, active users, course counts). |

## Course certificates (`/certificate`)

All routes require the learner's JWT and are scoped to that learner.

| Method | Endpoint | Description |
| - | - | - |
| POST | `/certificate/course/:courseId/issue` | Idempotently issue/retrieve a completion certificate; no body, HTTP 200. |
| GET | `/certificate` | Paginated own certificates; optional `courseId`, `page`, `limit`. |
| GET | `/certificate/:id` | Immutable certificate metadata. |
| GET | `/certificate/:id/download` | Private PDF attachment bytes; no JSON envelope. |

See [certificate architecture](https://ihub.learnille.com/engineering/architecture/course-certificates.md) and the
[frontend integration guide](https://docs.learnille.com/flows/certificates).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.