Skip to main content
This section documents the SMS REST API. Endpoints use predictable URLs, JSON (or form-encoded) bodies, and standard HTTP status codes. The reference is generated from the codebase with drf-spectacular (OpenAPI 3).

​
Authentication

Most endpoints require authentication. Two methods are supported:
  1. Log in via system or school auth:
    • System: POST /api/v1/system/auth/login/ (on public domain).
    • School: POST /api/v1/school/auth/login/ (on tenant domain).
  2. Send the access token on every request:
Authorization: Bearer <your-access-token>
  1. When the access token expires, call the refresh endpoint with the refresh token to get a new access token.

​
API key (for integrations)

Send the key in a header: 
X-API-KEY: <your-api-key>
API keys are managed under the system API (platform administrators). Use for chatbot, scripts, or server-to-server calls.

​
Multi-tenancy and base URL

The host (and optionally headers) determine which schema your request uses:
Base URL / contextUse case
Public domain (e.g. https://app.sms.local)System API: schools, platform users, roles, system auth. No tenant.
Tenant domain (e.g. https://school1.sms.local)School API: auth, users, admissions, sessions, exams, marks, reports, settings, notices, RBAC, audit, chatbot. All data is in that school’s schema.
  • System routes: /api/v1/system/ — platform administration only.
  • School routes: /api/v1/school/ — all tenant-scoped resources. Use the correct tenant domain (or X-Schema-Name for superadmin) so the middleware sets the right schema.
  • Chatbot routes: /api/v1/chatbot/ — webhooks, results, reports, notices, welcome messages. Tenant is set by domain or phone lookup.
A school JWT is valid only for that tenant. Calling a school endpoint on a different tenant’s domain will not return the other school’s data; the request runs in the domain’s tenant or fails.

​
Using the reference

  • System — Schools (clients), platform users, roles, system auth, API keys.
  • School — Auth, users, admissions, sessions, academic classes, exam sessions, exams, marks, report cards, comments, settings, session setup, promotions, notices, staff, roles, permissions, audit logs.
  • Chatbot — Welcome messages, students lookup, results, report generation, academic sessions, notices.
Request/response schemas and parameters are in the Endpoints section (generated from OpenAPI). To regenerate the OpenAPI file: python manage.py spectacular --file docs/api-reference/openapi.json.