Skip to content

LMS API overview

Audience: backend, frontend, qa
Status: specced
Owns: backend
Depends on: LMS overview, Lifecycle, Data model, Architecture handover

OpenAPI is the HTTP source of truth for LMS client APIs. Design SoT is ecosystem-root lms-openapi.yaml; this docs site publishes openapi/lms.yaml. Frontend must not reverse-engineer screens for endpoints.

Envelope matches Orchestrator / CAP (§19): list endpoints return { success, data: [ ... ], meta? } — data is the array itself, not { items: [...] }. Pagination (when present) is only in meta.pagination.

Item Convention
Design SoT lms-openapi.yaml (ecosystem root)
Prisma Implemented in elimi-ecosystem/apps/lms/prisma/; design seed lms-schema.prisma
Published copy openapi/lms.yaml in elimi-documentation
Interactive Scalar — LMS REST
Orchestrator auth / address / storage openapi/orchestrator.yaml
gRPC recs lms.v1.RecommendationsService in @yourorg/proto
Gateway prefix /v1/lms
Local http://localhost:4200/v1
  • Login / JWT / Address lists / Storage upload / Notifications → Orchestrator
  • Payment processing → OL InitiatePayment (self-pay). Cohort invoices are OL REST. LMS checkout may return settlement: organization_cohort.
  • CAP recommendations → gRPC, not public OpenAPI
Group Use Notes
Me GET /me, GET/PATCH /me/profile Personas, onboarding gates, capabilities; person name + photo + learner onboarding person blocks
Onboarding start / mine / get / save / submit per persona Multi-persona allowed
Catalogue published courses + outline Public browse (security: []). Optional Bearer. Resolved thumbnail on list/detail/outline.
Authoring courses, modules, items, sequencing, publish SCORM via OL packageAssetId
Level offerings catalogue, staff compose/publish, fan-out enroll + checkout Public published GETs; enroll/checkout authenticated. Thumbnail from first member course with one.
Instructors invites, co-instructors Platform invite only
Enrollments enroll, checkout, admin grants Entitlement sources include organization_seat
Player progress, launch, SCORM CMI + player HTML lms.sequencing.locked. See SCORM player.
Assessments native quiz attempts SCORM quizzes stay inside the package
Certificates LMS-owned Independent of CAP
Staff invites, roles, directory person fields, enrollment lookup, platform settings Staff ⊇ instructor. GET /staff returns name, email, photo. GET/PATCH /admin/settings is the Settings screen.
Learners directory, export, invite, LMS-local suspend, admin enroll, OL org proxy learner.manage; planned org-scoped list/detail (ORG-44)
Seat allocations LMS projection of sponsored seats CSV or rows; canonical paid cohort is OL (ORG-43/45)
Admin payments checkout ledger + receipt snapshot payments.read (staff admin). Course self-pay + level enrollments; no fan-out double count; grants omitted. Receipt is JSON only.
Admin dashboard year-filtered KPIs and charts analytics.read (staff admin). Query year is a UTC calendar year (default current). Cohort dates: learners LearnerProfile.createdAt, courses publishedAt, certified LmsCertificate.issuedAt, active enrollments Enrollment.createdAt + ACTIVE, revenue checkout.completedAt, rankings createdAt. Gender uses the same learner set as totalLearners. Top courses/levels rank by enrollment volume (default top 5).
Admin settings Contact + terms / privacy / refund settings.read / settings.write (staff admin). Each legal section is typed text or a PDF documentAssetId (upload via OL storage first).

Do not open launchUrl in a browser or iframe. That URL is JSON session metadata (GET /player/scorm/{sessionId}).

Field / route Client use
POST /enrollments/{id}/items/{id}/launch Start. Returns sessionId, launchUrl (JSON), playerUrl, contentBaseUrl
playerUrl Iframe this from the client origin. LMS HTML shell (GET …/player?ct=). Sets window.API (SCORM 1.2) and iframes scoHref?ct=
GET /player/scorm/{sessionId} Resume metadata + last cmi. Same Bearer as launch
GET /player/scorm/{sessionId}/content/{path} Extracted package files (used by the shell). Path-jailed
POST /player/scorm/{sessionId}/cmi Owned by the shell. Do not POST …/items/{id}/progress for SCORM

Player HTML, package files, and CMI accept Bearer or a short-lived content token (ct query, lms_scorm_ct cookie, X-Elimi-Scorm-Token, or Referer ct). ct is bound to the enrollment learner. HTTPS sets SameSite=None; Secure; Partitioned. Set LMS_PUBLIC_BASE_URL to the OpenAPI server the client calls (…/v1/lms on the gateway) and LMS_SCORM_CONTENT_TOKEN_SECRET in production.

Interactive spec: Scalar — LMS REST (getScormPlayer, getScormContent).

  1. lms_users + user.created + GET /me + onboarding
  2. Staff/instructor invites
  3. Authoring + publish + catalogue
  4. Entitlements + checkout (payment.completed)
  5. Player + sequencing + native assessments + SCORM runtime
  6. Completion policy + LMS certificate + lms.course.completed
  7. gRPC RecommendCourses (replace CAP mock)
  8. Admin learners + OL organization proxy + seat allocations (organization_seat)
  9. Admin payments ledger + year-filtered dashboard (GET /admin/payments*, GET /admin/dashboard)