Documents API

上傳文件

POST /v1/documents

使用 multipart/form-data 上傳文件。

POST /v1/documents
Authorization: Bearer sk-your-api-key
Content-Type: multipart/form-data

Form Fields：

欄位	類型	必填	說明
file	file	✓	文件二進位內容
filename	string	✓	文件名稱（含副檔名）
chunk_strategy	string		切分策略，預設 recursive
chunk_size	number		每個段落最大字元數
chunk_overlap	number		相鄰段落重疊字元數
metadata	string (JSON)		自訂 metadata（JSON 字串）

回應：

{
  "success": true,
  "data": {
    "id": "doc-uuid",
    "filename": "manual.pdf",
    "status": "processing",
    "chunk_strategy": "recursive",
    "created_at": "2026-05-08T12:00:00Z"
  }
}

---

列出文件

GET /v1/documents

查詢參數：

參數	類型	說明
search	string	按文件名稱搜尋
status	string	篩選狀態：processing / ready / failed / inactive
page	number	頁碼，預設 1
page_size	number	每頁筆數，預設 20

---

取得文件詳情

GET /v1/documents/{id}

---

刪除文件

DELETE /v1/documents/{id}

刪除後無法復原，向量資料與原始檔案都會一起移除。

---

停用文件

PATCH /v1/documents/{id}/deactivate

文件從 RAG 索引中移除，但檔案保留。

---

啟用文件

PATCH /v1/documents/{id}/activate

重新將文件加入 RAG 索引（會重新排入 Embedding 佇列）。

---

更新切分設定

PATCH /v1/documents/{id}/chunking

{
  "chunk_strategy": "semantic",
  "chunk_size": 1000,
  "chunk_overlap": 100,
  "chunk_semantic_threshold": 0.75
}

可更新的欄位：

欄位	類型	說明
chunk_strategy	string	recursive / fixed / semantic / sentence / parent_child / llm
chunk_size	number	段落最大字元數
chunk_overlap	number	重疊字元數
chunk_semantic_threshold	number	Semantic 策略的切分門檻（0.0 – 1.0）

---

重新索引

POST /v1/documents/{id}/reindex

觸發重新切分和向量化，通常在更新切分設定後使用。

---

查看段落

GET /v1/documents/{id}/chunks

查詢參數：

參數	類型	說明
page	number	頁碼
page_size	number	每頁筆數

回應：

{
  "success": true,
  "data": {
    "chunks": [
      {
        "id": "chunk-uuid",
        "index": 0,
        "content": "第一章：產品概述...",
        "token_count": 128
      }
    ],
    "total": 42
  }
}

---

下載原始檔案

GET /v1/documents/{id}/download

回傳原始二進位檔案，Content-Type 為原始文件格式。

---

下載 Markdown 版本

GET /v1/documents/{id}/download/markdown

回傳文件解析後的 Markdown 文字，方便檢查文字擷取的結果。

---

所需權限

操作	所需權限
讀取文件列表和詳情	source.read
上傳、管理、刪除文件	source.write