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:

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

{ "error": "Only PDF files are accepted." }

Response 413 Payload Too Large:

{ "error": "File exceeds maximum size of 100 MB." }

GET /api/v1/books

List all uploaded books with their current processing status.

Response 200 OK:

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

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

{ "error": "Book not found." }

Response 409 Conflict (book currently processing):

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

2.1 KiB Raw Blame History