ai-teacher/specs/001-neuro-rag-learning/contracts/topics-api.md

Contract: Topics API

Base path: /api/v1/topics Auth: HTTP Basic (shared credential) required on all endpoints.

---

GET /api/v1/topics

List all predefined neurosurgery topics.

Response 200 OK:

[
  {
    "id": "cerebral-aneurysm",
    "name": "Cerebral Aneurysm Management",
    "description": "Diagnosis, grading, and surgical/endovascular treatment of cerebral aneurysms.",
    "category": "Vascular"
  },
  {
    "id": "glioblastoma",
    "name": "Glioblastoma (GBM)",
    "description": "Pathophysiology, surgical resection strategies, and adjuvant therapy for GBM.",
    "category": "Oncology"
  }
]

---

POST /api/v1/topics/{id}/summary

Generate an AI summary for the selected topic by cross-referencing all READY books.

Path param: id — topic slug (e.g., cerebral-aneurysm)

Response 200 OK:

{
  "topicId": "cerebral-aneurysm",
  "topicName": "Cerebral Aneurysm Management",
  "summary": "Cerebral aneurysms are focal dilations of intracranial arteries...",
  "sources": [
    {
      "bookTitle": "Principles of Neurosurgery",
      "page": 312
    },
    {
      "bookTitle": "Youmans and Winn Neurological Surgery",
      "page": 1048
    }
  ],
  "generatedAt": "2026-03-31T10:15:00Z"
}

Response 404 Not Found (unknown topic):

{ "error": "Topic not found." }

Response 503 Service Unavailable (no READY books):

{ "error": "No books are available as knowledge sources. Please upload and process at least one book." }

---

Notes

• Topics are read-only; they cannot be created or deleted via the API.
• The topic list is loaded from topics.json at application startup.
• Summary generation is synchronous for the POC (< 30 s per SC-002); no polling needed.