Users API: Manage Accounts, Analytics, and Audit Logs

The Users API gives platform administrators full control over the user directory. Admins can create accounts for students, examiners, and other admins; search and filter the user list; update profile details; and permanently delete accounts. This page also documents the Analytics endpoint — which provides a platform-wide performance summary — and the Audit Log endpoint, which provides a tamper-evident record of all sensitive actions taken on the platform. All endpoints on this page require the admin role.

GET /api/users

Retrieve a list of all user accounts on the platform. Requires Admin role.

Query Parameters

role

string

Filter by user role. Accepted values: student, examiner, admin.

string

Search by name or email address (case-insensitive partial match).

status

string

Filter by account status. Accepted values: active, inactive.

Example Request

curl "https://your-domain.com/api/users?role=student&status=active&search=arjun" \
  -H "Authorization: Bearer <token>"

Example Response

[
  {
    "id": "usr_01J3P7RQZN",
    "name": "Arjun Sharma",
    "email": "arjun.sharma@university.edu",
    "role": "student",
    "status": "active",
    "roll_number": "CS2024001",
    "registration_number": "REG20240001"
  },
  {
    "id": "usr_01J4HQRZMB",
    "name": "Priya Menon",
    "email": "priya.menon@university.edu",
    "role": "student",
    "status": "active",
    "roll_number": "CS2024002",
    "registration_number": "REG20240002"
  }
]

POST /api/users

Create a new user account. Requires Admin role. The newly created user receives a welcome email containing their login credentials. This is the only way to create examiner and admin accounts — those roles cannot self-register.

Request Body

full_name

string

required

The user’s full name as it should appear across the platform.

string

required

A valid, unique email address. Used for login and all platform communications.

role

string

required

The role to assign to this user. Accepted values: student, examiner, admin.

roll_number

string

Required when role is student. The student’s institutional roll number. Must be unique.

registration_number

string

Required when role is student. The student’s official enrollment or registration number.

phone

string

Optional contact phone number.

employee_id

string

Optional employee identifier for examiner accounts. Useful for institutional record-keeping.

Example Request

curl -X POST https://your-domain.com/api/users \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "full_name": "Dr. Kavitha Nair",
    "email": "kavitha.nair@university.edu",
    "role": "examiner",
    "employee_id": "EMP-2024-087",
    "phone": "+91-9800001234"
  }'

Example Response

{
  "id": "usr_01J8RKVWPQ",
  "name": "Dr. Kavitha Nair",
  "email": "kavitha.nair@university.edu",
  "role": "examiner",
  "employee_id": "EMP-2024-087",
  "status": "active",
  "created_at": "2024-11-05T09:15:00Z",
  "welcome_email_sent": true
}

PATCH /api/users/:id

Update an existing user’s profile. Requires Admin role. Only send the fields you wish to change; all other fields retain their current values.

Path Parameters

string

required

The unique identifier of the user to update.

Request Body

Any subset of the fields accepted by POST /api/users. You may also update status (active or inactive) to enable or disable an account without deleting it.

Example Request

curl -X PATCH https://your-domain.com/api/users/usr_01J8RKVWPQ \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "phone": "+91-9800005678",
    "status": "inactive"
  }'

Example Response

{
  "id": "usr_01J8RKVWPQ",
  "name": "Dr. Kavitha Nair",
  "email": "kavitha.nair@university.edu",
  "role": "examiner",
  "status": "inactive",
  "phone": "+91-9800005678"
}

DELETE /api/users/:id

Permanently delete a user account. Requires Admin role.

Path Parameters

string

required

The unique identifier of the user to delete.

Example Request

curl -X DELETE https://your-domain.com/api/users/usr_01J8RKVWPQ \
  -H "Authorization: Bearer <token>"

Response

Returns 204 No Content on success with no response body.

Account deletion is irreversible. The user’s profile, login credentials, and all associated data are permanently removed. If you need to temporarily prevent a user from accessing the platform without losing their records, consider setting their status to inactive via PATCH /api/users/:id instead.

GET /api/analytics

Retrieve a platform-wide performance summary. Requires Admin role. This endpoint aggregates submission and exam data to surface key metrics including subject-wise averages, exam status distribution, AI integrity signals, and overall pass/completion rates.

Example Request

curl https://your-domain.com/api/analytics \
  -H "Authorization: Bearer <token>"

Example Response

{
  "system_wide_performance": [
    { "subject": "Mathematics", "average_pct": 72.4, "attempts": 310 },
    { "subject": "Physics", "average_pct": 65.1, "attempts": 280 },
    { "subject": "Computer Science", "average_pct": 79.8, "attempts": 420 }
  ],
  "exam_status_breakdown": {
    "live": 2,
    "upcoming": 5,
    "active": 1,
    "completed": 38
  },
  "published_results": 34,
  "overall_average": 72.1,
  "overall_pass_rate": 84.3,
  "completion_rate": 97.6,
  "ai_integrity_signal": 0.98
}

system_wide_performance

array

Per-subject breakdown. Each entry contains subject (string), average_pct (float — mean score percentage), and attempts (integer — total submissions for that subject).

exam_status_breakdown

object

Count of exams currently in each status: live, upcoming, active, and completed.

overall_average

float

Mean score percentage across all graded submissions platform-wide.

overall_pass_rate

float

Percentage of graded submissions where the student met or exceeded the passing threshold.

completion_rate

float

Percentage of assigned exam sessions that were submitted (as opposed to abandoned).

ai_integrity_signal

float

Composite AI proctoring signal (0.0–1.0). Values close to 1.0 indicate low detected anomaly rates across all monitored sessions.

GET /api/audit-logs

Retrieve the tamper-evident audit log of sensitive actions performed on the platform. Every significant state change — publishing an exam, creating an admin account, force-submitting a session — is recorded here with a timestamp, actor, and IP address. Requires Admin role.

Query Parameters

action

string

Filter by action type (e.g., exam.publish, admin.create_user, submission.force_submit, user.delete).

user_id

string

Filter to show only actions performed by the specified user.

from

string

ISO 8601 datetime. Return only log entries at or after this time (e.g., "2024-12-01T00:00:00Z").

string

ISO 8601 datetime. Return only log entries at or before this time (e.g., "2024-12-31T23:59:59Z").

Example Request

curl "https://your-domain.com/api/audit-logs?action=exam.publish&from=2024-12-01T00:00:00Z" \
  -H "Authorization: Bearer <token>"

Example Response

[
  {
    "timestamp": "2024-12-02T08:00:45Z",
    "user": {
      "id": "usr_01J2K9XMAB",
      "name": "Jane Doe",
      "role": "examiner"
    },
    "action": "exam.publish",
    "entity": {
      "type": "exam",
      "id": "exam_01J5CKWPNR",
      "title": "Final Examination — Computer Science"
    },
    "ip": "203.0.113.47"
  },
  {
    "timestamp": "2024-12-10T11:03:47Z",
    "user": {
      "id": "usr_00J1ADMINXZ",
      "name": "Platform Admin",
      "role": "admin"
    },
    "action": "submission.force_submit",
    "entity": {
      "type": "submission",
      "id": "sub_01J7NQVRMZ"
    },
    "ip": "198.51.100.12"
  }
]

Use the from and to parameters together to scope audit log exports to a specific exam date range. This is particularly useful when generating compliance reports or investigating incidents tied to a particular exam window.

Configuration

API Reference

Users API: Manage Accounts, Analytics, and Audit Logs

GET /api/users

Query Parameters

Example Request

Example Response

POST /api/users

Request Body

Example Request

Example Response

PATCH /api/users/:id

Path Parameters

Request Body

Example Request

Example Response

DELETE /api/users/:id

Path Parameters

Example Request

Response

GET /api/analytics

Example Request

Example Response

GET /api/audit-logs

Query Parameters

Example Request

Example Response

Build docs developers (and LLMs) love

Configuration

API Reference

Documentation Index

​GET /api/users

​Query Parameters

​Example Request

​Example Response

​POST /api/users

​Request Body

​Example Request

​Example Response

​PATCH /api/users/:id

​Path Parameters

​Request Body

​Example Request

​Example Response

​DELETE /api/users/:id

​Path Parameters

​Example Request

​Response

​GET /api/analytics

​Example Request

​Example Response

​GET /api/audit-logs

​Query Parameters

​Example Request

​Example Response

Build docs developers (and LLMs) love

GET /api/users

Query Parameters

Example Request

Example Response

POST /api/users

Request Body

Example Request

Example Response

PATCH /api/users/:id

Path Parameters

Request Body

Example Request

Example Response

DELETE /api/users/:id

Path Parameters

Example Request

Response

GET /api/analytics

Example Request

Example Response

GET /api/audit-logs

Query Parameters

Example Request

Example Response