API Reference Overview

The Akako LMS provides a comprehensive RESTful API for managing all aspects of the learning management system. This API is built with Next.js 14 App Router and follows modern API design principles.

Authentication

All API endpoints require authentication using Clerk.js JWT tokens. Include the token in the Authorization header:

Authorization: Bearer <jwt_token>

Response Format

All API responses follow a consistent format:

Success Response

{
  "success": true,
  "data": {
    // Response data
  },
  "message": "Operation completed successfully"
}

Error Response

{
  "success": false,
  "error": "Error message",
  "code": "ERROR_CODE",
  "details": {
    // Additional error details
  }
}

HTTP Status Codes

• 200 - Success
• 201 - Created
• 400 - Bad Request
• 401 - Unauthorized
• 403 - Forbidden
• 404 - Not Found
• 409 - Conflict (duplicate resource)
• 422 - Unprocessable Entity (validation error)
• 500 - Internal Server Error

Rate Limiting

API endpoints are protected with rate limiting using Redis:

• General endpoints: 100 requests per minute per IP
• Authentication endpoints: 10 requests per minute per IP
• File upload endpoints: 20 requests per minute per user

Rate limit headers are included in responses:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1640995200

API Endpoints

Authentication

Method	Endpoint	Description	Auth Required
POST	/auth/sync	Sync user data from Clerk	No
GET	/auth/profile	Get current user profile	Yes
PUT	/auth/profile	Update user profile	Yes

User Management

Method	Endpoint	Description	Auth Required	Roles
GET	/users	List all users	Yes	Admin
GET	/users/[id]	Get user by ID	Yes	Admin
PUT	/users/[id]	Update user	Yes	Admin
POST	/users/[id]/roles	Assign role to user	Yes	Admin
DELETE	/users/[id]/roles	Remove role from user	Yes	Admin

Education System

Method	Endpoint	Description	Auth Required	Roles
GET	/education/levels	List education levels	No	-
GET	/education/levels/[id]/grades	Get grades for level	No	-
GET	/education/grades/[id]/subjects	Get subjects for grade	No	-
GET	/education/subjects/[id]/topics	Get topics for subject	No	-
POST	/admin/education/levels	Create education level	Yes	Admin
PUT	/admin/education/levels/[id]	Update education level	Yes	Admin
DELETE	/admin/education/levels/[id]	Delete education level	Yes	Admin

File Management

Method	Endpoint	Description	Auth Required	Roles
POST	/s3/document/upload	Upload document	Yes	Admin, Mentor
GET	/s3/document/stream	Stream document	Yes	Admin, Mentor, Learner
DELETE	/admin/education/topics/[id]/documents/[docId]	Delete document	Yes	Admin, Mentor

Video Management

Method	Endpoint	Description	Auth Required	Roles
PUT	/admin/education/topics/[id]/video	Upload/update video	Yes	Admin, Mentor
DELETE	/admin/education/topics/[id]/video	Delete video	Yes	Admin, Mentor

Enrollment System

Method	Endpoint	Description	Auth Required	Roles
POST	/enrollment/request	Request enrollment	Yes	Learner
GET	/admin/enrollment/pending	Get pending enrollments	Yes	Admin
PUT	/admin/enrollment/[id]/approve	Approve enrollment	Yes	Admin
PUT	/admin/enrollment/[id]/reject	Reject enrollment	Yes	Admin

Mentor Applications

Method	Endpoint	Description	Auth Required	Roles
POST	/mentor/apply	Submit mentor application	Yes	Learner
GET	/admin/mentor/pending	Get pending applications	Yes	Admin
PUT	/admin/mentor/[id]/approve	Approve mentor application	Yes	Admin
PUT	/admin/mentor/[id]/reject	Reject mentor application	Yes	Admin

Error Handling

Validation Errors

When request validation fails, the API returns detailed error information:

{
  "success": false,
  "error": "Validation failed",
  "code": "VALIDATION_ERROR",
  "details": {
    "field": "email",
    "message": "Invalid email format",
    "value": "invalid-email"
  }
}

Role-based Access Errors

When a user lacks required permissions:

{
  "success": false,
  "error": "Insufficient permissions",
  "code": "FORBIDDEN",
  "details": {
    "required": ["ADMIN"],
    "user_roles": ["LEARNER"]
  }
}

Duplicate Resource Errors

When attempting to create duplicate resources:

{
  "success": false,
  "error": "Resource already exists",
  "code": "CONFLICT",
  "details": {
    "resource": "education_level",
    "field": "name",
    "value": "Primary School"
  }
}

Pagination

List endpoints support pagination using query parameters:

GET /api/users?page=1&limit=20&sort=createdAt&order=desc

Response includes pagination metadata:

{
  "success": true,
  "data": [...],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 150,
    "pages": 8,
    "hasNext": true,
    "hasPrev": false
  }
}

Filtering and Search

Many endpoints support filtering and search:

GET /api/users?search=john&role=LEARNER&status=ACTIVE

Available Filters

• Search: Text search across relevant fields
• Role: Filter by user roles
• Status: Filter by user status
• Date Range: Filter by creation/update dates
• Boolean Fields: Filter by boolean properties

File Upload

Document Upload

Documents are uploaded using multipart form data:

POST /api/s3/document/upload
Content-Type: multipart/form-data

file: <binary_data>
topicId: "topic_id_here"
metadata: {"name": "document.pdf", "description": "Study material"}

Video Upload

Videos are uploaded directly to topics:

PUT /api/admin/education/topics/[id]/video
Content-Type: multipart/form-data

video: <binary_data>

Webhooks

The system supports webhooks for real-time notifications:

Clerk Webhooks

POST /api/webhooks/clerk
Content-Type: application/json
X-Svix-Signature: <signature>

{
  "type": "user.created",
  "data": {
    "id": "user_123",
    "email_addresses": [...],
    "first_name": "John",
    "last_name": "Doe"
  }
}

SDK and Client Libraries

JavaScript/TypeScript

import { AkakoAPI } from '@akako/lms-sdk';

const api = new AkakoAPI({
  baseURL: 'https://akako.example.com/api',
  token: 'your_jwt_token'
});

// Get education levels
const levels = await api.education.getLevels();

// Create new level
const newLevel = await api.education.createLevel({
  name: 'High School',
  description: 'Secondary education'
});

Python

from akako_lms import AkakoAPI

api = AkakoAPI(
    base_url='https://akako.example.com/api',
    token='your_jwt_token'
)

# Get education levels
levels = api.education.get_levels()

# Create new level
new_level = api.education.create_level(
    name='High School',
    description='Secondary education'
)

Testing

Postman Collection

A complete Postman collection is available for testing all API endpoints:

Download Postman Collection

API Testing Script

# Test authentication
curl -X POST https://akako.example.com/api/auth/sync \
  -H "Content-Type: application/json" \
  -d '{"userId": "user_123", "email": "test@example.com"}'

# Test education levels
curl -X GET https://akako.example.com/api/education/levels \
  -H "Authorization: Bearer your_jwt_token"

Rate Limiting and Quotas

Free Tier

• 1,000 API calls per month
• 10 file uploads per month
• Basic support

Pro Tier

• 10,000 API calls per month
• 100 file uploads per month
• Priority support
• Advanced analytics

Enterprise Tier

• Unlimited API calls
• Unlimited file uploads
• Dedicated support
• Custom integrations

Support

For API support and questions:

• Documentation: docs.akako.com
• GitHub Issues: github.com/quivlabs/lms/issues
• Email Support: hello@quivlabs.com
• Discord Community: discord.gg/akako

Next Steps

• Authentication API: Detailed authentication endpoints
• Education API: Complete education system endpoints
• User Management API: User and role management endpoints
• File Management API: File upload and management endpoints