Assessment Construction Engine

Shift from querying individual database rows to generating complete, psychometrically balanced examination papers in a single API call.

L1 · 1 creditPOST /v1/assessments/generatePOST /v1/assessments/sessions

2.5.0Overview

Building a real exam or mock test requires more than picking random questions. Real examination bodies (JAMB, WAEC) curate papers with calibrated difficulty distributions, multi-topic syllabus balancing, and cheat-resistant distractor ordering.

The ALOC Assessment Construction Engine handles this entire psychometric assembly server-side. You specify the syllabus preset or difficulty split, and ALOC returns the complete, balanced assessment paper.

2.5.1Official Examination Presets

Use standard presets to immediately generate official examination structures without manual question counting:

Preset Code	Question Count	Psychometric Split (E / M / H)	Target Exam Body
jamb_standard_40	40 Questions	30% Easy · 50% Med · 20% Hard	JAMB / UTME
waec_standard_50	50 Questions	25% Easy · 55% Med · 20% Hard	WAEC / WASSCE
micro_test_10	10 Questions	30% Easy · 50% Med · 20% Hard	Quick Diagnostic

2.5.2Direct Paper Generation

# Generate standard assessment paper

curl -X POST https://dev.aloc.com.ng/api/v1/assessments/generate \
  -H "X-API-Key: aloc_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "subject": "mathematics",
    "examType": "jamb",
    "preset": "jamb_standard_40",
    "shuffleOptions": true,
    "seed": "lagos_state_mock_batch_1"
  }'

# Response (200 OK)

{
  "data": {
    "id": "7f8b91a2-58cc-4372-a567-0e02b2c3d479",
    "subject": "mathematics",
    "examType": "jamb",
    "preset": "jamb_standard_40",
    "seed": "lagos_state_mock_batch_1",
    "totalQuestions": 40,
    "difficultyBreakdown": {
      "easy": 12,
      "medium": 20,
      "hard": 8
    },
    "topicsCovered": [
      "algebra",
      "calculus",
      "trigonometry",
      "geometry"
    ],
    "questions": [
      {
        "id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
        "questionHtml": "<p>Evaluate \\(\\log_2 32 + \\log_3 81\\)</p>",
        "options": {
          "a": "8",
          "b": "9",
          "c": "10",
          "d": "12"
        },
        "difficultyLevel": "medium"
      }
    ]
  }
}

2.5.3Seed Reproducibility & Cohort Consistency

Passing a deterministic string to seed guarantees that every candidate or test-taker receives the exact same set of questions and difficulty calibration.

2.5.4Secure Live CBT & Candidate Sessions

For live test environments, computer-based testing (CBT) engines, and exam apps, you can provision scoped, time-bound session tokens. This ensures each student receives a dedicated, reproducible question set with an automatic 2-hour lifecycle:

Step 1: Create Candidate Session

Call POST /v1/assessments/sessions when the student starts an exam. ALOC creates a dedicated assessment instance locked to your parameters with a 2-hour TTL.

# Request: Provision Candidate Session

curl -X POST https://dev.aloc.com.ng/api/v1/assessments/sessions \
  -H "X-API-Key: aloc_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "subject": "mathematics",
    "examType": "jamb",
    "preset": "jamb_standard_40",
    "seed": "student_candidate_98214"
  }'

# Response (201 Created)

{
  "data": {
    "sessionId": "sess_01j7b8q9x0e8d9a7c6f5e4d3c2",
    "totalQuestions": 40,
    "preset": "jamb_standard_40",
    "seed": "student_candidate_98214",
    "expiresAt": "2026-08-30T23:15:00+01:00"
  }
}

Step 2: Retrieve Session Questions

Fetch the questions allocated to that candidate's active sitting using their sessionId.

# Request: Stream Questions via Session ID

curl https://dev.aloc.com.ng/api/v1/assessments/sessions/sess_01j7b8q9x0e8d9a7c6f5e4d3c2/questions \
  -H "X-API-Key: aloc_live_YOUR_KEY"

# Response (200 OK)

{
  "data": [
    {
      "id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
      "subject": "mathematics",
      "examType": "jamb",
      "year": 2019,
      "questionNumber": 1,
      "questionHtml": "<p>Evaluate \\(\\log_2 32 + \\log_3 81\\)</p>",
      "options": {
        "a": "8",
        "b": "9",
        "c": "10",
        "d": "12"
      },
      "difficultyLevel": "medium"
    }
  ]
}