plan

specs/001-neuro-rag-learning/contracts/books-api.md

@@ -0,0 +1,103 @@
+# Contract: Books API
+
+**Base path**: `/api/v1/books`
+**Auth**: HTTP Basic (shared credential) required on all endpoints.
+
+---
+
+## POST /api/v1/books
+
+Upload a new book for embedding.
+
+**Request**: `multipart/form-data`
+
+| Field | Type | Required | Notes |
+|-------|------|----------|-------|
+| file | File | Yes | PDF only; max 100 MB |
+
+**Response 202 Accepted**:
+```json
+{
+  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
+  "title": "Principles of Neurosurgery",
+  "fileName": "principles-of-neurosurgery.pdf",
+  "status": "PENDING",
+  "uploadedAt": "2026-03-31T10:00:00Z"
+}
+```
+
+**Response 400 Bad Request** (unsupported format):
+```json
+{ "error": "Only PDF files are accepted." }
+```
+
+**Response 413 Payload Too Large**:
+```json
+{ "error": "File exceeds maximum size of 100 MB." }
+```
+
+---
+
+## GET /api/v1/books
+
+List all uploaded books with their current processing status.
+
+**Response 200 OK**:
+```json
+[
+  {
+    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
+    "title": "Principles of Neurosurgery",
+    "fileName": "principles-of-neurosurgery.pdf",
+    "fileSizeBytes": 45234567,
+    "pageCount": 842,
+    "status": "READY",
+    "uploadedAt": "2026-03-31T10:00:00Z",
+    "processedAt": "2026-03-31T10:07:23Z"
+  }
+]
+```
+
+---
+
+## GET /api/v1/books/{id}
+
+Get status and metadata for a single book.
+
+**Path param**: `id` — UUID
+
+**Response 200 OK**: Same shape as a single item in the list above, plus optional `errorMessage` field when `status = FAILED`.
+
+**Response 404 Not Found**:
+```json
+{ "error": "Book not found." }
+```
+
+---
+
+## DELETE /api/v1/books/{id}
+
+Delete a book and all its embedding chunks.
+
+**Response 204 No Content**: Book deleted.
+
+**Response 404 Not Found**:
+```json
+{ "error": "Book not found." }
+```
+
+**Response 409 Conflict** (book currently processing):
+```json
+{ "error": "Cannot delete a book that is currently being processed." }
+```
+
+---
+
+## Status Lifecycle
+
+```
+PENDING   → returned immediately after upload
+PROCESSING → set when embedding pipeline starts
+READY      → set when all chunks are embedded
+FAILED     → set on any unrecoverable error; errorMessage populated
+```