From a4314db2d7aa42d0b29cd1e04d6bdb93104c9fb4 Mon Sep 17 00:00:00 2001
From: John O'Keefe <jrokeefe@protonmail.com>
Date: Sun, 8 Feb 2026 13:33:12 -0500
Subject: [PATCH] docs(api): update existing documentation

- Update api-reference.md with current endpoint list

- Update bulk_update_books.md with improved documentation

- Update scanner/overview.md to reference scan_library.md
---
 docs/developer/api/api-reference.md           |  2 +-
 docs/developer/api/books/bulk_update_books.md | 61 +++++++++++++------
 docs/developer/api/scanner/overview.md        |  2 +-
 3 files changed, 45 insertions(+), 20 deletions(-)

diff --git a/docs/developer/api/api-reference.md b/docs/developer/api/api-reference.md
index ffbf74c..d353412 100644
--- a/docs/developer/api/api-reference.md
+++ b/docs/developer/api/api-reference.md
@@ -200,7 +200,7 @@ See [Sync Queue](queue/)
 See [Scanner Operations](scanner/)
 
 - [Scanner Overview](scanner/overview.md) - Supported formats, metadata extraction, and features
-- POST /api/scanner/scan - One-time library scan (ebooks, manga, comics)
+- POST /api/scanner/scan - Scan library (one-time) (ebooks, manga, comics)
 - POST /api/scanner/start - Start automated scanner
 - POST /api/scanner/stop - Stop automated scanner
 - GET /api/scanner/status/:jobId - Get scan job status
diff --git a/docs/developer/api/books/bulk_update_books.md b/docs/developer/api/books/bulk_update_books.md
index 1e65f6c..2997fd9 100644
--- a/docs/developer/api/books/bulk_update_books.md
+++ b/docs/developer/api/books/bulk_update_books.md
@@ -10,30 +10,47 @@ Update multiple media items at once.
 
 | Field | Type | Required | Description |
 |--------|------|-----------|-------------|
-| media_item_ids | array of UUID | Yes | Array of media item UUIDs to update |
+| updates | array of objects | Yes | Array of update operations (see below) |
+
+### Update Object
+
+| Field | Type | Required | Description |
+|--------|------|-----------|-------------|
+| book_id | string (UUID) | Yes | Media item UUID to update |
 | updates | object | Yes | Fields to update (see below) |
 
 ### Update Fields
 
 | Field | Type | Required | Description |
 |--------|------|-----------|-------------|
-| tags | array of strings | No | New tags (will replace existing) |
-| contributors | array of strings | No | New contributors (will replace existing) |
-| add_tags | array of strings | No | Tags to add to existing |
-| remove_tags | array of strings | No | Tags to remove from existing |
+| title | string | No | Updated title |
+| author | string | No | Updated author |
+| genre | string | No | Updated genre |
+| language | string | No | Updated language |
+| tags | array of strings | No | Updated tags (auto-normalized) |
+| contributors | array of strings | No | Updated contributors (auto-normalized) |
 
 ### Example Request
 
 ```json
 {
-  "media_item_ids": [
-    "550e8400-e29b-41d4-a716-446655440001",
-    "660e8400-e29b-41d4-a716-446655440002"
-  ],
-  "updates": {
-    "add_tags": ["science-fiction", "award-winner"],
-    "contributors": ["Publisher Name"]
-  }
+  "updates": [
+    {
+      "book_id": "550e8400-e29b-41d4-a716-446655440001",
+      "updates": {
+        "title": "Updated Title",
+        "genre": "Science Fiction",
+        "tags": ["science fiction", "non-fiction", "ACME CORP."]
+      }
+    },
+    {
+      "book_id": "660e8400-e29b-41d4-a716-446655440002",
+      "updates": {
+        "author": "Updated Author",
+        "contributors": ["O'Reilly Media", "Penguin Random House"]
+      }
+    }
+  ]
 }
 ```
 
@@ -41,11 +58,19 @@ Update multiple media items at once.
 
 ```json
 {
-  "message": "Books updated successfully",
-  "updated_count": 2,
-  "failed_count": 0,
-  "normalized_tags": ["Science-Fiction", "Award-Winner"],
-  "normalized_contributors": ["Publisher Name"]
+  "results": [
+    {
+      "book_id": "550e8400-e29b-41d4-a716-446655440001",
+      "success": true
+    },
+    {
+      "book_id": "660e8400-e29b-41d4-a716-446655440002",
+      "success": true
+    }
+  ],
+  "total": 2,
+  "success": 2,
+  "failed": 0
 }
 ```
 
diff --git a/docs/developer/api/scanner/overview.md b/docs/developer/api/scanner/overview.md
index 3f3c935..807756c 100644
--- a/docs/developer/api/scanner/overview.md
+++ b/docs/developer/api/scanner/overview.md
@@ -139,7 +139,7 @@ GET /api/scanner/status/550e8400-e29b-41d4-a716-446655440000
 
 ## Related Endpoints
 
-- [Scan Ebooks](scan_ebooks.md) - Manual one-time scan
+- [Scan Library](scan_library.md) - Manual one-time scan
 - [Start Scanner](start_scanner.md) - Automated periodic scanning
 - [Stop Scanner](stop_scanner.md) - Stop automated scanner
 - [Get Scan Status](get_scan_status.md) - Check scan progress