API Design

The SyncAD API follows REST conventions with a unified structure across all platform modules.

Base URLs

Environment	URL
Development	https://dev-api.metaonus.in
Production	https://api.metaonus.in

Path Structure

/{platform}/{module}/{action}

Examples:
POST /parent/student/list
POST /teacher/attendance/mark
POST /driver/bus-tracking/trips/123/start
POST /school-admin/student/create

Prefix	Platform	Auth
/parent/*	Parents App	JWT (PARENT role)
/teacher/*	Teachers App	JWT (TEACHER role)
/driver/*	Drivers App	JWT (DRIVER role)
/school-admin/*	School Admin UI	JWT (SCHOOL_ADMIN role)
/super-admin/*	Super Admin UI	JWT (SUPER_ADMIN role)

Request Format

POST /parent/student/list
Authorization: Bearer <jwt>
Content-Type: application/json

{
  "data": {
    "academicYearId": "uuid"
  }
}

Response Format

Success

{
  "data": {
    "students": [...],
    "total": 42
  },
  "message": "Students fetched successfully"
}

Error

{
  "statusCode": 400,
  "message": "Invalid academic year ID",
  "error": "Bad Request"
}

Paginated List

{
  "data": {
    "items": [...],
    "total": 120,
    "page": 1,
    "limit": 20,
    "totalPages": 6
  }
}

HTTP Status Codes

Code	Meaning
200	Success
201	Created
204	No Content (successful delete)
400	Bad Request — invalid input
401	Unauthorized — missing or invalid JWT
403	Forbidden — valid JWT but insufficient permissions
404	Not Found
409	Conflict — duplicate resource
422	Unprocessable Entity — validation error
500	Internal Server Error

Authentication

All endpoints (except /auth/*) require:

Authorization: Bearer eyJhbGciOiJIUzI1NiIs...

JWT payload contains sub (userId), role, and schoolId.

Pagination

List endpoints support pagination via request body:

{
  "data": {
    "page": 1,
    "limit": 20,
    "filters": {
      "classId": "uuid",
      "search": "john"
    },
    "sort": {
      "field": "firstName",
      "order": "asc"
    }
  }
}

Versioning

API is versioned via URL path prefix (current: v1 implicit). Breaking changes are introduced with a new prefix: /v2/parent/*.

Rate Limiting

Tier	Limit
Auth endpoints	10 req/min per IP
Read endpoints	100 req/min per user
Write endpoints	30 req/min per user

Common Enums

// Attendance Status
'PRESENT' | 'ABSENT' | 'LATE' | 'LEAVE' | 'HOLIDAY'

// Leave Status
'PENDING' | 'APPROVED' | 'REJECTED' | 'CANCELLED'

// Fee Entry Type
'DR' | 'CR'  // Debit / Credit (double-entry personal accounts)

// Trip Status
'SCHEDULED' | 'STARTED' | 'PAUSED' | 'ENDED'

// Boarding Status
'boaded' | 'alighted' | 'absent' | 'no_show'

Error Codes

Code	Description
SCHOOL_NOT_FOUND	schoolId in JWT does not match any school
STUDENT_NOT_FOUND	Student ID does not exist in school DB
DUPLICATE_ENTRY	Resource already exists (e.g., duplicate admission No)
EVALUATION_MODE_READONLY	Teacher attempted write in evaluation mode
OTP_EXPIRED	OTP TTL (5 min) exceeded
OTP_INVALID	Wrong OTP entered
REFRESH_TOKEN_EXPIRED	Refresh token older than 7 days
PERMISSION_DENIED	Role lacks required module permission