# API Contracts: Enhanced Embedding with Image Parsing and Metadata

**Branch**: `002-image-aware-embedding` | **Date**: 2026-04-03  
**Base path**: `/api/v1`  
**Auth**: HTTP Basic (existing)

---

## New / Changed Endpoints

### 1. Re-embed a book (new)

Triggers a full re-embedding of an already-processed book, replacing all existing chunks and
figures with the new image-aware pipeline output. Safe to call on books previously embedded
by feature 001.

```
POST /api/v1/books/{id}/reembed
```

**Path parameters**

| Parameter | Type | Description |
|-----------|------|-------------|
| `id` | UUID | Book ID |

**Response** `202 Accepted`

```json
{ "bookId": "uuid", "status": "PROCESSING" }
```

**Error responses**

| Status | Condition |
|--------|-----------|
| 404 | Book not found |
| 409 | Book already in PROCESSING state |

---

### 2. Get figures for a book (new)

Returns the list of extracted figures for a book, including their type, caption, and image URL.
Used by the frontend to display a figure gallery or inline figures in chat responses.

```
GET /api/v1/books/{id}/figures
```

**Path parameters**

| Parameter | Type | Description |
|-----------|------|-------------|
| `id` | UUID | Book ID |

**Response** `200 OK`

```json
[
  {
    "figureId": "youmans-7ed-fig-12-4",
    "label": "Fig. 12-4",
    "caption": "Coronal cross-section of the cavernous sinus showing cranial nerve relationships",
    "figureType": "ANATOMICAL_DIAGRAM",
    "page": 184,
    "imageUrl": "/api/v1/figures/550e8400-e29b-41d4-a716-446655440000/youmans-7ed-fig-12-4.png",
    "sectionId": "youmans-7ed-ch12-s2-3",
    "sectionTitle": "Cavernous Sinus"
  }
]
```

**Error responses**

| Status | Condition |
|--------|-----------|
| 404 | Book not found |

---

### 3. Serve figure image (new)

Serves the extracted figure image file. Mounted as a static resource from the file store.

```
GET /api/v1/figures/{bookId}/{filename}
```

**Path parameters**

| Parameter | Type | Description |
|-----------|------|-------------|
| `bookId` | UUID | Book ID |
| `filename` | string | Image filename (e.g. `youmans-7ed-fig-12-4.png`) |

**Response** `200 OK` — binary PNG  
**Content-Type**: `image/png`

**Error responses**

| Status | Condition |
|--------|-----------|
| 404 | Image file not found |

---

### 4. Chat message response — extended source format (changed)

The existing `POST /api/v1/chat/sessions/{id}/messages` endpoint is unchanged in its request
format. The response `sources` field is extended to include figure references.

**Existing request** (unchanged):

```json
{ "content": "Describe the anatomy of the cavernous sinus" }
```

**Response** `200 OK` — extended `sources`:

```json
{
  "id": "uuid",
  "role": "ASSISTANT",
  "content": "The cavernous sinus is ... [Fig. 12-4, p.184] ...",
  "sources": [
    {
      "type": "TEXT",
      "bookTitle": "Youmans and Winn Neurological Surgery, 7th Ed.",
      "page": 184,
      "chunkText": "The cavernous sinus contains ..."
    },
    {
      "type": "FIGURE",
      "bookTitle": "Youmans and Winn Neurological Surgery, 7th Ed.",
      "page": 184,
      "figureId": "youmans-7ed-fig-12-4",
      "label": "Fig. 12-4",
      "caption": "Coronal cross-section of the cavernous sinus ...",
      "figureType": "ANATOMICAL_DIAGRAM",
      "imageUrl": "/api/v1/figures/550e8400-e29b-41d4-a716-446655440000/youmans-7ed-fig-12-4.png"
    }
  ],
  "createdAt": "2026-04-03T12:00:00Z"
}
```

**Changed fields in `sources` array**:

| Field | Old | New |
|-------|-----|-----|
| `type` | absent | `"TEXT"` or `"FIGURE"` |
| `figureId` | absent | figure ID string (FIGURE type only) |
| `label` | absent | caption label (FIGURE type only) |
| `caption` | absent | full caption (FIGURE type only) |
| `figureType` | absent | enum name (FIGURE type only) |
| `imageUrl` | absent | image URL (FIGURE type only) |

---

## Unchanged Endpoints

All endpoints from feature 001 remain at their existing paths with no breaking changes:

- `POST /api/v1/books/upload`
- `GET /api/v1/books`
- `DELETE /api/v1/books/{id}`
- `GET /api/v1/topics`
- `GET /api/v1/topics/{id}/summary`
- `POST /api/v1/chat/sessions`
- `GET /api/v1/chat/sessions/{id}/messages`
- `DELETE /api/v1/chat/sessions/{id}`