API: Exam

Base URL: http://localhost:8001. Prefix: /api/exam.

Auth: Bearer JWT.
Gate: MEDICAL_ASSISTANT_ENABLED plus LEARNING_ROLES.

First list call runs ensure_seed_tests (EN+RU seeds, idempotent by title).

---

GET /api/exam

List tests.

Query

Parameter	Description
language	en | ru
category	Category
difficulty	Difficulty

Response 200

{
  "items": [
    {
      "id": "…",
      "title": "…",
      "description": "…",
      "category": "cardiology",
      "difficulty": "intermediate",
      "questions": [
        {"question": "…", "options": ["A", "B", "C", "D"]}
      ],
      "created_at": "…"
    }
  ]
}

correct_index and explanation are hidden until submit.

---

GET /api/exam/{test_id}

One test. 404 if missing.

---

POST /api/exam/generate

Request

{
  "category": "cardiology",
  "difficulty": "intermediate",
  "num_questions": 5,
  "language": "en",
  "persist": true
}

Field	Constraints
category	required
difficulty	default intermediate
num_questions	1–20, default 5
language	default en
persist	default true

Response 200 — persisted test or raw payload.

---

POST /api/exam/{test_id}/submit

Request

{
  "answers": [0, 2, 1, 3, 0],
  "time_spent": 600
}

answers — option indexes in question order (min 1 item).

Response 200

{
  "score": 80.0,
  "correct": 4,
  "total": 5,
  "details": [
    {
      "index": 0,
      "correct": true,
      "selected": 0,
      "correct_index": 0,
      "explanation": "…"
    }
  ]
}

Progress: module=exam, score = percent, extra_data.test_id / correct.

---

curl example

curl -s -X POST http://localhost:8001/api/exam/$TEST_ID/submit \
  -H "Authorization: Bearer $JWT" \
  -H "Content-Type: application/json" \
  -d '{"answers":[0,1,2],"time_spent":120}'