🚀 Horace LMS API Documentation

Welcome to the comprehensive API documentation for Horace Learning Management System. This guide provides detailed information about all available endpoints, request/response formats, and authentication requirements.

---

📚 Table of Contents

• Authentication
• User Management
  • User Sign-up
  • Reset Password
  • Edit User
  • Upload Photo
  • Delete User
  • Change Role
• Course Management
  • Create Course
  • Edit Course
  • Add Module
  • Edit Module
  • Upload Assets
  • Add Lesson
  • Get Organization Courses
  • Get My Drafts
  • Course Registration
  • Get My Courses
  • Get Course by ID
  • Get Courses by Author
• Error Codes
• Rate Limiting

---

🔐 Authentication

All API requests require proper authentication. Include your API key in the request headers:

Create an account here

Authorization: Bearer YOUR_API_KEY

---

👥 User Management

User Sign-up

Register a new user for your organization.

⚠️ Important: Email must be unique for each user. Use the type field to assign roles.

Endpoint

POST /api/v1/user/add

User Roles

Role	Description	Access Level
USER	Standard user	Basic access
INSTRUCTOR	Course creator	Full course management
ADMIN	Administrator	Full system access

Request Body

{
  "firstname": "string",
  "lastname": "string",
  "country": "string",
  "password": "string",
  "organizationId": "string",
  "bio": "string",
  "address": "string",
  "city": "string",
  "state": "string",
  "zip": "string",
  "phone": "string",
  "email": "string",
  "type": "INSTRUCTOR|ADMIN|USER"
}

Example Request

curl -X 'POST' \
  'http://localhost:5071/api/v1/user/add' \
  -H 'accept: */*' \
  -H 'Content-Type: application/json' \
  -d '{
    "firstname": "fela",
    "lastname": "kuti",
    "country": "Nigeria",
    "password": "Password1$",
    "organizationId": "684e58d4df81cc6605736c85",
    "bio": "This is the lord'\''s doing",
    "address": "12 Mill ridge drive",
    "city": "cypress",
    "state": "TX",
    "zip": "77429",
    "phone": "11111111",
    "email": "babaphemy@mail.com",
    "type": "INSTRUCTOR"
  }'

---

Reset Password

Password reset is a two-step process:

1. Generate Token - Sends reset token to user's email
2. Reset Password - Uses token to set new password

Step 1: Generate Token

Endpoint

POST /api/v1/user/dotoken

Request Body

{
  "organizationId": "string",
  "email": "string"
}

Example Request

curl -X 'POST' \
  'http://localhost:5071/api/v1/user/dotoken' \
  -H 'accept: */*' \
  -H 'Content-Type: application/json' \
  -d '{
    "organizationId": "6812345611grxa",
    "email": "lasisonboard@gmail.com"
  }'

Step 2: Reset Password

Endpoint

POST /api/v1/user/reset/password

Request Body

{
  "organizationId": "string",
  "email": "string",
  "password": "string",
  "token": "string"
}

Response

Returns status: SUCCESS or FAILED

Example Request

curl -X 'POST' \
  'http://localhost:5071/api/v1/user/reset/password' \
  -H 'accept: */*' \
  -H 'Content-Type: application/json' \
  -d '{
    "organizationId": "6812345611grxa",
    "email": "lasisonboard@gmail.com",
    "password": "Password1$",
    "token": "667865"
  }'

---

Edit User

Modify basic information about a selected user.

Endpoint

PUT /api/v1/user/edit

Request Body

{
  "id": "string",
  "organizationId": "string",
  "firstname": "string",
  "lastname": "string",
  "country": "string",
  "bio": "string",
  "address": "string",
  "city": "string",
  "state": "string",
  "zip": "string",
  "phone": "string",
  "email": "string",
  "type": "string"
}

Example Request

curl -X 'PUT' \
  'http://localhost:5071/api/v1/user/edit' \
  -H 'accept: */*' \
  -H 'Content-Type: application/json' \
  -d '{
    "id": "684f8dadd1deea23f92582b4",
    "organizationId": "684e58d4df81cc6605736c85",
    "firstname": "fela",
    "lastname": "kuti",
    "country": "USA",
    "bio": "Love is in the air",
    "address": "11 Zone 2",
    "city": "Lagos",
    "state": "Lagos",
    "zip": "Ojo",
    "phone": "1111111111",
    "email": "lasisonboard@gmail.com",
    "type": "INSTRUCTOR"
  }'

---

Upload Photo (DP)

🚧 Coming Soon - Documentation for profile picture upload endpoint.

---

Delete User

🚧 Coming Soon - Documentation for user deletion endpoint.

---

Change Role

🚧 Coming Soon - Documentation for role management endpoint.

---

📖 Course Management

🔒 Permission Required: All course management endpoints require INSTRUCTOR role or higher.

Create Course

Creates a new course in the system.

Endpoint

POST /api/v1/course/add

Request Body

{
  "user": "string",
  "courseName": "string",
  "brief": "string",
  "overview": "string",
  "thumbnail": "string",
  "category": "string",
  "currency": "string",
  "draft": boolean,
  "cost": number
}

Parameters

• user - ID of the course author (required)
• draft - Set to true to save as draft, false to publish

Example Request

curl -X 'POST' \
  '{basepath}/api/v1/course/add' \
  -H 'accept: */*' \
  -H 'Content-Type: application/json' \
  -d '{
    "user": "684e665d59f9a83e5140d977",
    "courseName": "Game Theory",
    "brief": "This is a great course on how to improve your game.",
    "overview": "<p>This course provides a decent introduction to game development.</p>",
    "thumbnail": "",
    "category": "web",
    "currency": "NGN",
    "draft": true,
    "cost": 40000
  }'

---

Edit Course

Update an existing course.

Endpoint

POST /api/v1/course/add

💡 Note: Include the id field to edit existing course. Without id, a new course will be created.

Request Body

{
  "id": "string",
  "user": "string",
  "courseName": "string",
  "brief": "string",
  "overview": "string",
  "thumbnail": "string",
  "category": "string",
  "currency": "string",
  "draft": boolean,
  "cost": number
}

Example Request

curl -X 'POST' \
  '{basepath}/api/v1/course/add' \
  -H 'accept: */*' \
  -H 'Content-Type: application/json' \
  -d '{
    "id": "684f2a07b73d5f7a3bdebd5a",
    "user": "684e665d59f9a83e5140d977",
    "courseName": "FIFA and Corruption",
    "brief": "This is a great documentary",
    "overview": "Welcome to this documentary on the blatant corruption at FIFA",
    "thumbnail": "https://essluploads.s3.amazonaws.com/logo/horace-logo.png",
    "category": "web",
    "currency": "NGN",
    "draft": false,
    "cost": 40000
  }'

---

Add Module to Course

Add a new module to an existing course.

Endpoint

POST /api/v1/course/module

Request Body

{
  "module": "string",
  "description": "string",
  "orderIndex": number,
  "cid": "string"
}

Parameters

• orderIndex - Controls the arrangement/order of modules
• cid - Course ID where the module will be attached

Example Request

curl -X 'POST' \
  '{basepath}/api/v1/course/module' \
  -H 'accept: */*' \
  -H 'Content-Type: application/json' \
  -d '{
    "module": "History of FIFA",
    "description": "Who or what is FIFA? what do you need to know about FIFA",
    "orderIndex": 2,
    "cid": "684f2a07b73d5f7a3bdebd5a"
  }'

---

Edit Module

Edit an existing module by including the module ID.

Endpoint

POST /api/v1/course/module

💡 Note: Include id (module ID) to edit. cid is the course ID, id is the module ID.

Request Body

{
  "id": "string",
  "module": "string",
  "description": "string",
  "orderIndex": number,
  "cid": "string"
}

---

Upload Asset

Universal upload endpoint for all file types including videos, images, and documents.

🎥 Video Processing: Videos are automatically encoded, optimized, compressed, and cached on CDN.

File/Photo Upload

Endpoint

PUT https://horacelms.com/info/s3/upload

Example Request

curl -X 'PUT' \
  'https://horacelms.com/info/s3/upload' \
  -H 'accept: application/json' \
  -H 'Content-Type: multipart/form-data' \
  -F 'image=@2.1.svg;type=image/svg+xml'

Video Upload

Endpoint

POST https://horacelms.com/info/s3/video

Example Request

curl -X 'POST' \
  'https://horacelms.com/info/s3/video' \
  -H 'accept: application/json' \
  -H 'Content-Type: multipart/form-data' \
  -F 'video=@horace-enc.mp4;type=video/mp4'

---

Add Lesson to Module

Add lessons to course modules. Supports multiple content types.

Endpoint

POST /api/v1/course/module/lesson

Lesson Types

Type	Description
video	Video content
document	Document files
html	HTML content
pdf	PDF documents
quiz	Interactive quizzes
text	Text-based lessons

Request Body

{
  "title": "string",
  "content": "string",
  "type": "video|document|html|pdf|quiz|text",
  "video": "string",
  "orderIndex": number,
  "tid": "string"
}

Parameters

• video - Only used when type is "video". Path to uploaded video file
• tid - Module ID where the lesson will be attached
• orderIndex - Controls lesson order within the module

Example Request - Text Lesson

curl -X 'POST' \
  '{basepath}/api/v1/course/module/lesson' \
  -H 'accept: */*' \
  -H 'Content-Type: application/json' \
  -d '{
    "title": "FIFA and Corruption",
    "content": "FIFA is ridden with corruption despite all the good things they have done for the big beautiful sport",
    "type": "text",
    "orderIndex": 2,
    "tid": "684f542d28f7ad4a06794fb8"
  }'

---

All Organization's Courses

Get all courses for an organization, including courses by all users in the organization.

🔒 Permission Required: Admin or Instructor role

Endpoint

GET /api/v1/course/org-courses?page={page}&size={size}&orgId={orgId}

Query Parameters

• page - Page number (0-based)
• size - Number of items per page
• orgId - Organization ID

Example Request

curl -X 'GET' \
  '{basepath}/api/v1/course/org-courses?page=0&size=10&orgId={orgId}' \
  -H 'accept: */*'

---

My Drafts

Fetch all draft courses created by a user.

📝 Draft Courses: Unpublished courses that users cannot register for yet.

Endpoint

GET /api/v1/course/mydrafts/{userId}

Example Request

curl -X 'GET' \
  '{basepath}/api/v1/course/mydrafts/{userId}' \
  -H 'accept: */*'

---

Course Registration

Register a student/learner for a selected course.

🚧 Coming Soon - Documentation for course registration endpoint.

---

My Registered Courses

Get all courses a user has registered for.

🚧 Coming Soon - Documentation for user's registered courses endpoint.

---

Course by ID

Fetch detailed information for a single course.

Endpoint

GET /api/v1/course/lms/{courseId}

Example Request

curl -X 'GET' \
  '{basepath}/api/v1/course/lms/684f2a07b73d5f7a3bdebd5a' \
  -H 'accept: */*'

---

Courses by Author

Get all courses created by a specific author.

Endpoint

GET /api/v1/course/byauthor/{authorId}

Example Request

curl -X 'GET' \
  '{basepath}/api/v1/course/byauthor/684e665d59f9a83e5140d977' \
  -H 'accept: */*'

---

⚠️ Error Codes

Code	Description	Solution
400	Bad Request	Check request format and required fields
401	Unauthorized	Verify authentication credentials
403	Forbidden	Check user permissions and role
404	Not Found	Verify resource exists
429	Too Many Requests	Implement rate limiting in your application
500	Internal Server Error	Contact support if issue persists

---

🚦 Rate Limiting

API requests are limited to prevent abuse:

• Standard Users: 100 requests per minute
• Premium Users: 1000 requests per minute
• Enterprise: Custom limits available

Include these headers in responses:

• X-RateLimit-Limit - Request limit per minute
• X-RateLimit-Remaining - Remaining requests
• X-RateLimit-Reset - Time when limit resets

---

📞 Support

Need help? Reach out to our support team:

• Email: office@horacelearning.com
• Documentation: https://docs.horacelms.com
• Home Page: https://status.horacelms.com

---

Last updated: June 2025