ai-teacher/specs/002-image-aware-embedding/contracts/api.md

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

{ "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

[
  {
    "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):

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

Response 200 OK — extended sources:

{
  "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}