75 lines
1.7 KiB
Markdown
75 lines
1.7 KiB
Markdown
# 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.
|