API Overview

OptiLearn exposes 100+ REST endpoints across courses, learners, assessments, notifications, parents, peer review, captions, recording, analytics, and integrations. The API follows a single response envelope and shared error vocabulary.

Base URL

https://learn.opticrm.app/api

Authentication

All API routes (except public ones like certificate verification, NextAuth, and the Jibri webhook) require an authenticated session. OptiLearn uses the same JWT cookie as OptiCRM:

Cookie: __Secure-authjs.session-token=<jwt>

Requests without a valid session return 401 Unauthorized. Mobile clients use bearer tokens via /api/v1/* (separate doc, mobile auth).

Response Format

All responses use a consistent envelope:

Success

{
  "data": { ... },
  "error": null,
  "meta": {
    "total": 42,
    "page": 1,
    "perPage": 12,
    "totalPages": 4
  }
}

meta is only present for paginated endpoints.

Error

{
  "data": null,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid input",
    "details": { ... }
  }
}

Error Codes

Endpoint Categories

Courses & Content

• GET /api/courses — List courses with filters
• POST /api/courses — Create a course
• GET /api/courses/[id] — Get course detail
• PATCH /api/courses/[id] — Update course
• DELETE /api/courses/[id] — Archive course
• POST /api/courses/[id]/publish — Change publish status
• POST /api/courses/[id]/duplicate — Duplicate a course
• GET/POST /api/courses/[id]/modules — List/create modules
• POST /api/courses/[id]/lessons — Create a lesson
• GET/POST /api/courses/[id]/announcements — Announcements (class-targetable)
• GET/POST /api/courses/[id]/discussions — Course forum
• PATCH/DELETE /api/modules/[id] — Update/delete module
• GET/PATCH/DELETE /api/lessons/[id] — Lesson CRUD

Lesson Engagement (per-lesson)

• GET/POST /api/lessons/[id]/notes — Student notes
• GET/PATCH/DELETE /api/lessons/[id]/notes/[noteId]
• GET/POST /api/lessons/[id]/bookmarks
• GET/PATCH/DELETE /api/lessons/[id]/bookmarks/[bookmarkId]
• GET/POST /api/lessons/[id]/captions — WebVTT caption tracks
• PATCH/DELETE /api/lessons/[id]/captions/[captionId]
• GET /api/lessons/[id]/captions/[captionId]/transcript — parsed cues
• GET/POST /api/lessons/[id]/discussions
• GET/POST /api/lessons/[id]/blocks/[blockId]/answer — interactive block answers
• POST /api/lessons/[id]/events — learner events
• POST /api/lessons/[id]/interactions
• POST /api/lessons/[id]/pdf-progress
• POST /api/lessons/[id]/progress / progress-v2

See Notes & Bookmarks API and Captions API.

Aggregate "My" Endpoints

• GET /api/me/notes — every note the student has taken (paginated)
• GET /api/me/bookmarks — every bookmark
• GET /api/me/peer-reviews — peer-review queue

Enrollment & Progress

• POST /api/courses/[id]/enroll — Self-enroll
• GET/POST /api/courses/[id]/enrollments — List / bulk enroll
• GET/DELETE /api/courses/[id]/enrollments/[studentId] — Detail / unenroll
• POST /api/lessons/[id]/progress — Update lesson progress

Assessment & Peer Review

• GET/PUT /api/quiz/[id] — Get / upsert quiz
• POST /api/quiz/[id]/attempt — Submit quiz attempt
• GET /api/quiz/[id]/attempts — List attempts
• GET/PUT /api/assignments/[id] — Get / upsert assignment
• POST /api/assignments/[id]/submit — Submit assignment
• POST /api/assignments/[id]/grade — Grade a submission
• GET /api/assignments/[id]/submissions — List submissions
• GET /api/assignments/[id]/peer-reviews — Instructor moderation view
• GET/PATCH /api/peer-reviews/[id] — Reviewer detail / draft
• POST /api/peer-reviews/[id]/submit — Final submit
• POST /api/peer-reviews/[id]/flag — Flag inappropriate work

See Peer Reviews API.

Live Sessions & Recording

• GET/POST /api/live-sessions
• POST /api/live-sessions/[id]/start
• POST /api/live-sessions/[id]/end
• POST /api/live-sessions/[id]/join
• POST /api/live-sessions/[id]/register
• POST /api/live-sessions/[id]/attendance
• GET /api/live-sessions/[id]/ics
• POST /api/live-sessions/[id]/recording/start — Jibri start (host only)
• POST /api/live-sessions/[id]/recording/stop — Jibri stop
• POST /api/webhooks/jitsi-recording — public Jibri callback (HMAC)

See Recording API.

Notifications

• GET /api/notifications — list IN_APP rows
• PATCH /api/notifications/read — mark read ({ ids } or { all: true })
• GET /api/notifications/unread-count — bell badge poll
• GET /api/notifications/preferences — preference rows + digest times
• PATCH /api/notifications/preferences — upsert one row
• DELETE /api/notifications/preferences — reset to defaults
• PATCH /api/notifications/preferences/digest-times — daily/weekly delivery time
• POST /api/notifications/push-token — register web push token

See Notifications API.

Parent Portal

• GET /api/parent/children — children linked to the calling parent
• GET /api/parent/children/[childId]/overview — read-only dashboard

See Parent API.

Student-Facing

• GET /api/catalogue — Browse published courses
• GET /api/my-courses — My enrolled courses
• GET /api/learn/[courseId] — Course nav data
• GET /api/learn/[courseId]/[lessonId] — Lesson content

Gamification

• GET /api/gamification/leaderboard — Rankings (period: all/month/week)
• GET /api/gamification/badges — Badge list with earned status
• GET /api/gamification/streak — Current streak + recent points
• POST /api/reviews — Submit a course review

Certificates

• GET /api/certificates — List my certificates
• GET /api/certificates/verify?code= — Public verification endpoint

Learning Paths

• GET/POST /api/learning-paths
• GET/PATCH /api/learning-paths/[id]
• POST /api/learning-paths/[id]/courses
• POST /api/learning-paths/[id]/enroll

Compliance & SCORM

• GET/POST /api/compliance/training
• GET /api/compliance/records
• POST /api/compliance/waive
• GET /api/scorm/[id]/launch
• POST /api/scorm/[id]/track
• GET/POST /api/xapi/statements

Analytics

• POST /api/analytics/reports/run — Execute a ReportDefinition
• POST /api/analytics/reports/export — Run + serialize as CSV/XLSX/PDF
• GET /api/analytics/entities — Entity registry
• GET/POST /api/analytics/reports — Saved reports
• GET/PATCH/DELETE /api/analytics/reports/[id]
• GET/POST /api/analytics/reports/[id]/schedules
• PATCH/DELETE /api/analytics/reports/schedules/[id]
• GET/POST /api/analytics/reports/[id]/alerts
• PATCH/DELETE /api/analytics/reports/alerts/[id]
• GET /api/cron/report-schedules — Hourly cron entry
• GET /api/cron/analytics-snapshot — Hourly snapshot + cache invalidation
• GET /api/cron/assignment-reminders — Hourly assignment reminder cron
• GET /api/analytics/dashboard/revenue — Bespoke revenue rollup
• GET /api/analytics/courses/[id] — Course meta + lesson engagement (legacy)
• POST /api/sync/opticrm — Push completions to OptiCRM

See the Analytics Engine developer reference.

Files

• POST /api/upload — Get presigned upload URL
• GET/POST /api/files

Settings & Misc

• GET/PATCH /api/settings — LMS settings (incl. fee gating toggle)
• GET/POST /api/categories
• GET /api/audit-log

Pagination

Paginated endpoints accept:

• ?page=1 — Page number (1-indexed)
• ?perPage=12 (or ?limit=) — Items per page (max 100)

Response includes meta with total, page, perPage, totalPages.

Rate Limiting

Hot endpoints carry per-user limits. Examples:

• /analytics/reports/run — 30 / minute
• /analytics/reports/export — 10 / minute
• General write endpoints — 30 / minute
• General read endpoints — 100 / minute

Exceeding the limit returns 429 Too Many Requests.

Public Endpoints

These don't require authentication:

• /api/auth/* — NextAuth endpoints
• /api/certificates/verify?code= — Certificate verification
• /api/webhooks/* — External webhooks (Razorpay, Jibri recording — both signature-verified)
• /api/xapi/statements — xAPI LRS (uses Basic auth)

All other endpoints require a valid session.