From 7bc6bc77e489721107e97e2be5f6c2615aa257ee Mon Sep 17 00:00:00 2001
From: John O'Keefe <jrokeefe@protonmail.com>
Date: Mon, 9 Feb 2026 14:29:14 -0500
Subject: [PATCH] docs: Document media item creation prerequisites

- Add POST /api/media-items prerequisite documentation
- Document 400 error for libraries without folders
- Update API reference with validation rules
- Include usage example showing proper setup order

Related: Media item validation changes
---
 .../api/media-items/create_media_item.md      | 31 ++++++++++++++++++-
 1 file changed, 30 insertions(+), 1 deletion(-)

diff --git a/docs/developer/api/media-items/create_media_item.md b/docs/developer/api/media-items/create_media_item.md
index a162ebd..08bbb46 100644
--- a/docs/developer/api/media-items/create_media_item.md
+++ b/docs/developer/api/media-items/create_media_item.md
@@ -6,6 +6,16 @@ Create a new media item (Admin only).
 **Auth**: Required (Admin only)
 **Content-Type**: `application/json`
 
+## Prerequisites
+
+**Before creating media items**, the library must have at least one folder configured:
+
+1. Create a library: `POST /api/libraries`
+2. Add folder(s) to the library: `POST /api/libraries/{library_id}/folders`
+3. Then create media items: `POST /api/media-items`
+
+See [Library API documentation](../libraries/) for more details.
+
 ## Request Body
 
 | Field | Type | Required | Description |
@@ -84,11 +94,30 @@ Tags and contributors are automatically normalized:
 
 | Code | Description |
 |------|-------------|
-| 400 | Invalid request data |
+| 400 | Invalid request data OR library has no folders |
 | 401 | Invalid or expired token |
 | 403 | User is not an admin |
 | 404 | Library not found |
 
+### 400 - Library Has No Folders
+
+When attempting to create a media item in a library that has no folders configured:
+
+```json
+{
+  "error": "Cannot add media items to a library with no folders. Please add at least one folder to the library first."
+}
+```
+
+**Solution**: Add a folder to the library first:
+
+```bash
+POST /api/libraries/{library_id}/folders
+{
+  "folder_path": "/path/to/library/folder"
+}
+```
+
 ## Try It Out
 
 <!-- API Explorer will be inserted here in Phase 3 -->