From 67c8c60cebac58fb892f8e1408afb3474d75cc1d Mon Sep 17 00:00:00 2001
From: Warren <warren@momentry.ddns.net>
Date: Wed, 25 Mar 2026 15:51:30 +0800
Subject: [PATCH] docs: add search endpoint documentation with chunk details

---
 docs/API_TRAINING_MARCOM.md | 63 +++++++++++++++++++++++++++++++++++--
 1 file changed, 61 insertions(+), 2 deletions(-)

diff --git a/docs/API_TRAINING_MARCOM.md b/docs/API_TRAINING_MARCOM.md
index 6459a6a..c9c44e8 100644
--- a/docs/API_TRAINING_MARCOM.md
+++ b/docs/API_TRAINING_MARCOM.md
@@ -73,7 +73,66 @@ curl -s -H "X-API-Key: muser_68600856036340bcafc01930eb4bd839_1774418104_97221b6
 #### GET /api/v1/videos/:uuid
 取得單一影片詳情
 
-### 3.2 任務相關
+### 3.2 搜尋與分段查詢
+
+#### POST /api/v1/search
+向量搜尋，查詢分段詳情
+
+**請求範例**:
+```json
+{
+  "query": "關鍵字",
+  "limit": 10
+}
+```
+
+**回應範例**:
+```json
+{
+  "results": [
+    {
+      "uuid": "5dea6618a606e7c7",
+      "chunk_id": "time_00001",
+      "chunk_type": "time",
+      "start_time": 0.0,
+      "end_time": 10.0,
+      "text": "分段內容文字",
+      "score": 0.95
+    }
+  ]
+}
+```
+
+#### POST /api/v1/n8n/search
+n8n 專用搜尋（包含縮圖網址）
+
+**請求範例**:
+```json
+{
+  "query": "關鍵字",
+  "limit": 10
+}
+```
+
+**回應範例**:
+```json
+{
+  "hits": [
+    {
+      "uuid": "5dea6618a606e7c7",
+      "chunk_id": "time_00001",
+      "chunk_type": "time",
+      "start_time": 0.0,
+      "end_time": 10.0,
+      "text": "分段內容文字",
+      "score": 0.95,
+      "thumbnail_url": "https://..."
+    }
+  ]
+}
+```
+
+### 3.3 任務相關
 
 #### GET /api/v1/jobs/:uuid
 查詢處理任務狀態
@@ -146,7 +205,7 @@ curl -s -H "X-API-Key: ..." \
 
 **注意**: 此操作會刪除影片及其所有分段、處理結果、縮圖等關聯資料，**無法復原**。
 
-### 3.4 健康檢查
+### 3.5 健康檢查
 
 #### GET /health
 服務健康狀態（**無需認證**）