104 lines
2.1 KiB
Markdown
104 lines
2.1 KiB
Markdown
# 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
|
|
```
|