Learning APIs

Why This Exists

This document defines API responsibilities for the Learning Domain. It does not define final OpenAPI specifications.

Owner

The owner is the Chief Product Officer and Enterprise Architect.

Business Value

API boundaries make Learning usable by the Academy interface, Digital Professionals, adjacent domains, analytics, notifications, and future workflow automation.

API Groups

API group	Responsibilities	Example endpoints
Course Catalog API	Browse and manage courses, modules, lessons, quizzes, and exercises.	GET /learning/courses, POST /learning/courses, GET /learning/courses/{courseId}
Learning Path API	Create and retrieve guided learning paths.	GET /learning/paths, POST /learning/paths, GET /learning/paths/{pathId}
Enrollment API	Enrol users in courses or paths.	POST /learning/enrollments, GET /learning/users/{userId}/enrollments
Lesson API	Retrieve lesson content and record lesson activity.	GET /learning/lessons/{lessonId}, POST /learning/lessons/{lessonId}/start, POST /learning/lessons/{lessonId}/complete
Quiz API	Retrieve quizzes and submit attempts.	GET /learning/quizzes/{quizId}, POST /learning/quizzes/{quizId}/attempts
Practical Exercise API	Retrieve exercises and submit applied work.	GET /learning/exercises/{exerciseId}, POST /learning/exercises/{exerciseId}/submissions
Certificate API	Retrieve and issue certificates through policy-controlled commands.	GET /learning/certificates, POST /learning/certificates/evaluate
User Progress API	Retrieve progress summaries and detailed progress records.	GET /learning/users/{userId}/progress, GET /learning/progress/{progressId}
Procurement Maturity Assessment API	Create and submit assessments.	POST /learning/maturity-assessments, POST /learning/maturity-assessments/{assessmentId}/submit
Learning Recommendation API	Create, present, accept, dismiss, and complete recommendations.	GET /learning/recommendations, POST /learning/recommendations/{recommendationId}/accept
AI Tutor API	Start, continue, and complete tutor sessions with Intelligence support.	POST /learning/tutor-sessions, POST /learning/tutor-sessions/{sessionId}/messages
Organization Learning Profile API	Retrieve organization education state.	GET /learning/organizations/{organizationId}/profile

API Design Rules

• Commands that mutate learning records must go through Learning APIs.
• Cross-domain triggers should pass references and reasons, not copied business facts.
• AI tutor endpoints must record confidence, references, and guardrail outcomes.
• Certificate issuance must be policy-controlled.
• Final endpoint names and schemas will be defined in later OpenAPI work.

Example Command Flow

sequenceDiagram
    participant UI as Academy UI
    participant LearningAPI as Learning API
    participant Learning as Learning Domain
    participant Intelligence as Intelligence Domain

    UI->>LearningAPI: POST /learning/tutor-sessions
    LearningAPI->>Learning: Start tutor session command
    Learning->>Intelligence: Request tutor reasoning
    Intelligence-->>Learning: Explanation and confidence
    Learning-->>LearningAPI: Tutor session record
    LearningAPI-->>UI: Tutor response with learning context