ai-teacher/specs/004-rag-retrieval-quality/contracts/topics-api.md

API Contract: Topics — Summary Persistence

Base path: /api/v1/topics

---

Existing endpoint (unchanged behaviour, extended response)

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

Generates a new summary for the topic, persists it, and returns it.

Path param: id — topic id (e.g. intracranial-aneurysms)

Response 200 OK:

{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "summaryNumber": 3,
  "topicId": "intracranial-aneurysms",
  "topicName": "Intracranial Aneurysms",
  "summary": "## Key Points\n...",
  "sources": [
    { "bookId": "uuid", "bookTitle": "Youmans & Winn", "page": 142 }
  ],
  "generatedAt": "2026-04-07T10:23:00Z"
}

Error responses:

• 404 Not Found — topic id does not exist
• 503 Service Unavailable — no books ready (existing NoKnowledgeSourceException)

---

New endpoints

GET /api/v1/topics/{id}/summaries

Returns the list of saved summaries for a topic (no full text — list metadata only).

Path param: id — topic id

Response 200 OK:

[
  { "id": "uuid-1", "summaryNumber": 1, "generatedAt": "2026-04-06T08:00:00Z" },
  { "id": "uuid-2", "summaryNumber": 2, "generatedAt": "2026-04-06T09:15:00Z" }
]

Ordered ascending by summaryNumber. Empty array if no summaries saved yet.

Error responses:

• 404 Not Found — topic id does not exist

---

GET /api/v1/topics/{id}/summaries/{summaryId}

Fetches the full content of a specific saved summary.

Path params: id — topic id, summaryId — summary UUID

Response 200 OK: same shape as POST /summary response above.

Error responses:

• 404 Not Found — topic or summary not found