# 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`:
```json
{
  "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`:
```json
[
  { "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