API: Cases

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

Auth: Bearer JWT.
Gate: MEDICAL_ASSISTANT_ENABLED plus LEARNING_ROLES.

The first list call runs ensure_seed_cases — inserts EN+RU seed cases (idempotent by title).

---

GET /api/cases

List cases.

Query

Parameter	Description
language	en | ru — seed language filter
specialty	Specialty filter
difficulty	Difficulty filter

Response 200

{
  "items": [
    {
      "id": "…",
      "title": "…",
      "description": "…",
      "specialty": "cardiology",
      "difficulty": "intermediate",
      "steps": [
        {"step": 1, "question": "…", "options": ["A", "B"]}
      ],
      "created_at": "…"
    }
  ]
}

Correct answers and explanations are hidden on list/GET.

---

GET /api/cases/{case_id}

One case by UUID (public_id). 404 if missing.

Body matches an items element above (no correct_answer / explanation).

---

POST /api/cases/generate

Generate a case (LLM / generator).

Request

{
  "specialty": "cardiology",
  "difficulty": "intermediate",
  "language": "en",
  "topic": "ACS",
  "persist": true
}

Field	Default	Description
specialty	—	required
difficulty	intermediate	level
language	en	language
topic	null	optional
persist	true	save to DB

Response 200 — serialized case (if persist) or raw generator payload.

---

POST /api/cases/{case_id}/submit

Submit a step answer.

Request

{
  "step_index": 0,
  "answer": "Obtain ECG",
  "time_spent": 45
}

Field	Description
step_index	≥ 0
answer	1–1000 characters
time_spent	seconds, optional

Response 200

{
  "correct": true,
  "correct_answer": "Obtain ECG",
  "explanation": "…",
  "score": 1.0,
  "step": 1
}

Writes progress module=cases with score 0 or 100.

---

curl example

curl -s "http://localhost:8001/api/cases?language=en" \
  -H "Authorization: Bearer $JWT"