# 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**:
```json
[
  {
    "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**:
```json
{
  "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):
```json
{ "error": "Topic not found." }
```

**Response 503 Service Unavailable** (no READY books):
```json
{ "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.