跳至主要内容
版本:PrivStation 4.0.0
Markdown 原文

取得單一知識版本的檔案列表

此 API 用於查詢指定 Fileset 中所包含的所有檔案,以及每個檔案在此 Fileset 內的 commit 狀態(Fileset File State)與實際採用的解析品質(used_quality)。

curl -X 'GET' \
'http://127.0.0.1:8000/v1/filesets/{fileset_id}/files?limit=20&order=desc' \
-H 'accept: application/json' \
-H "Authorization: Bearer $PRIVAI_API_KEY"

Request Headers​

KeyValue
Request MethodGET
acceptapplication/json
AuthorizationBearer $PRIVAI_API_KEY

Path Parameters​

FieldTypeNoteRequired
fileset_idstringuuidtrue

Query Parameters​

FieldTypeNoteRequired
limitint1 - 10000,預設為 10000false
orderstring依檔案的 created_at 排序,asc 或 desc,預設為 descfalse
afterstringuuid,分頁游標(檔案 ID),取得此檔案之後的資料。不可與 before 同時使用false
beforestringuuid,分頁游標(檔案 ID),取得此檔案之前的資料。不可與 after 同時使用false
files_statestring依檔案在此 Fileset 內的狀態篩選,可用值:draft、queued、processing、completed、failedfalse
⚠️

篩選參數名稱為 files_state(複數 files)。

Response Body​

{
"object": "list",
"first_id": "18b8b0f0-83c1-41a0-ba58-40774c8dfb99",
"last_id": "18b8b0f0-83c1-41a0-ba58-40774c8dfb99",
"has_more": false,
"data": [
{
"object": "fileset.file",
"id": "18b8b0f0-83c1-41a0-ba58-40774c8dfb99",
"filename": "2024清明.pdf",
"filetype": "application/pdf",
"bytes": 200273,
"metadata": {
"parsed_results": {
"HQ": {
"parsing_state": "completed",
"character_count": 2639,
"page_count": 5,
"failed_page_numbers": []
},
"LQ": {
"parsing_state": "draft"
}
},
"fail_detail": []
},
"state": "completed",
"used_quality": "HQ",
"purpose": "user_data",
"created_at": "2025-12-02T03:15:01.975741Z",
"expires_at": null
}
]
}

Field Explanation

FieldDetail
object固定為 list
data[]Fileset File 物件列表,欄位見下表
first_id本頁第一個檔案的 ID,無資料時為 null
last_id本頁最後一個檔案的 ID,無資料時為 null
has_more此知識版本是否還有更多的檔案

Fileset File 物件(data[])
包含「檔案物件」的所有欄位,差異如下:

FieldDetail
object固定為 fileset.file
state該檔案在此 Fileset 內的 commit 狀態(Fileset File State):draft、queued、processing、completed、failed
used_quality此檔案在該 Fileset commit 時實際採用的解析品質,可能為 null、HQ、LQ、STD

狀態定義詳見「File Parse State、Fileset File State 與 Fileset State 的差異」章節。

常見錯誤代碼​

Error CodeHTTP Status情境
FILESET_001404指定的 Fileset 不存在
VAL_001422同時帶入 after 與 before
VAL_002404after/before 指定的檔案 ID 不存在
—422files_state 不是允許的值

身份驗證錯誤(AUTH_001~AUTH_003)詳見「錯誤代碼說明-身份驗證類」章節;知識版本相關錯誤碼完整說明請參考 錯誤代碼說明-知識版本管理類。