API Overview

Author: Ariel Vernaza

README.md

@@ -336,20 +336,136 @@ To include Transformer and Image in the **API image** (larger image): `podman bu
 
 ## API Overview
 
-*(To be filled after implementation; summary here.)*
+The API is REST-style. All IDs are UUIDs. Base URL when running locally: `http://localhost:8000`. Interactive docs: **http://localhost:8000/docs**.
+
+### Endpoints summary
 
 | Method | Endpoint | Purpose |
 |--------|----------|---------|
 | POST   | `/libraries` | Create library |
-| GET    | `/libraries` | List libraries |
-| GET    | `/libraries/{id}` | Get library |
-| PUT    | `/libraries/{id}` | Update library |
-| DELETE | `/libraries/{id}` | Delete library |
-| POST   | `/libraries/{id}/documents` | Create document |
-| GET    | `/libraries/{id}/documents` | List documents |
-| ...    | ... | (similar for documents and chunks) |
-| POST   | `/libraries/{id}/index` | Build/rebuild index |
-| POST   | `/libraries/{id}/search` | kNN search by embedding |
+| GET    | `/libraries` | List all libraries |
+| GET    | `/libraries/{library_id}` | Get library |
+| PUT    | `/libraries/{library_id}` | Update library |
+| DELETE | `/libraries/{library_id}` | Delete library (and index, documents, chunks) |
+| POST   | `/libraries/{library_id}/documents` | Create document |
+| GET    | `/libraries/{library_id}/documents` | List documents in library |
+| GET    | `/libraries/{library_id}/documents/{document_id}` | Get document |
+| PUT    | `/libraries/{library_id}/documents/{document_id}` | Update document |
+| DELETE | `/libraries/{library_id}/documents/{document_id}` | Delete document (and its chunks) |
+| POST   | `/libraries/{library_id}/documents/{document_id}/chunks` | Create chunk |
+| GET    | `/libraries/{library_id}/documents/{document_id}/chunks` | List chunks in document |
+| GET    | `/libraries/{library_id}/documents/{document_id}/chunks/{chunk_id}` | Get chunk |
+| PUT    | `/libraries/{library_id}/documents/{document_id}/chunks/{chunk_id}` | Update chunk |
+| DELETE | `/libraries/{library_id}/documents/{document_id}/chunks/{chunk_id}` | Delete chunk |
+| POST   | `/libraries/{library_id}/index` | Build or rebuild vector index |
+| POST   | `/libraries/{library_id}/search` | k-NN search by embedding |
+
+### Status codes
+
+| Code | Meaning |
+|------|---------|
+| 200  | OK (get, list, update, search) |
+| 201  | Created (post library, document, chunk) |
+| 204  | No content (delete, build index) |
+| 404  | Not found (library, document, or chunk missing) |
+| 409  | Conflict (search called but index not built yet) |
+| 422  | Validation error (e.g. empty name, invalid body) |
+
+### Request / response examples
+
+**Create library** — `POST /libraries`
+
+```json
+// Request
+{ "name": "My Library" }
+
+// Response 201
+{
+  "id": "550e8400-e29b-41d4-a716-446655440000",
+  "name": "My Library",
+  "created_at": "2025-01-29T12:00:00Z",
+  "document_ids": []
+}
+```
+
+**Create document** — `POST /libraries/{library_id}/documents`
+
+```json
+// Request
+{ "name": "Doc 1" }
+
+// Response 201
+{
+  "id": "6ba7b810-9dad-11d1-80b4-00c04fd430c8",
+  "name": "Doc 1",
+  "created_at": "2025-01-29T12:00:00Z",
+  "chunk_ids": [],
+  "library_id": "550e8400-e29b-41d4-a716-446655440000"
+}
+```
+
+**Create chunk** — `POST /libraries/{library_id}/documents/{document_id}/chunks`
+
+```json
+// Request
+{
+  "text": "A short paragraph of content.",
+  "embedding": [0.1, -0.2, 0.3, ...],
+  "name": "chunk-1"
+}
+
+// Response 201
+{
+  "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
+  "text": "A short paragraph of content.",
+  "embedding": [0.1, -0.2, 0.3, ...],
+  "created_at": "2025-01-29T12:00:00Z",
+  "name": "chunk-1",
+  "document_id": "6ba7b810-9dad-11d1-80b4-00c04fd430c8"
+}
+```
+
+- `embedding` must have the same dimension for all chunks in the library (e.g. 384 for many Sentence Transformers). Omit `name` if not needed.
+
+**Build index** — `POST /libraries/{library_id}/index`
+
+```json
+// Request (body optional; default algorithm is brute_force)
+{ "algorithm": "brute_force" }
+// or: "kd_tree" | "ivf"
+
+// Response 204 No Content
+```
+
+- Must be called before search. Rebuilding replaces the previous index.
+
+**Search** — `POST /libraries/{library_id}/search`
+
+```json
+// Request
+{
+  "embedding": [0.1, -0.2, 0.3, ...],
+  "k": 10
+}
+
+// Response 200
+{
+  "results": [
+    { "chunk_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7", "distance": 0.0 },
+    { "chunk_id": "...", "distance": 0.42 }
+  ]
+}
+```
+
+- `k` between 1 and 1000. Results sorted by L2 distance ascending. If the index has not been built, response is **409 Conflict** with `{"detail": "Index not built for library ..."}`.
+
+**Error response (404, 409, 422)** — body shape:
+
+```json
+{ "detail": "Library 550e8400-e29b-41d4-a716-446655440000 not found" }
+```
+
+- For 422, `detail` may be a list of validation errors (FastAPI default).
 
 ---