取得單一知識版本的檔案列表
此 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
| Key | Value |
|---|---|
| Request Method | GET |
| accept | application/json |
| Authorization | Bearer $PRIVAI_API_KEY |
Path Parameters
| Field | Type | Note | Required |
|---|---|---|---|
| fileset_id | string | uuid | true |
Query Parameters
| Field | Type | Note | Required |
|---|---|---|---|
| limit | int | 1 - 10000,預設為 10000 | false |
| order | string | 依檔案的 created_at 排序,asc 或 desc,預設為 desc | false |
| after | string | uuid,分頁游標(檔案 ID),取得此檔案之後的資料。不可與 before 同時使用 | false |
| before | string | uuid,分頁游標(檔案 ID),取得此檔案之前的資料。不可與 after 同時使用 | false |
| files_state | string | 依檔案在此 Fileset 內的狀態篩選,可用值:draft、queued、processing、completed、failed | false |
⚠️
篩選參數名稱為 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
| Field | Detail |
|---|---|
| object | 固定為 list |
| data[] | Fileset File 物件列表,欄位見下表 |
| first_id | 本頁第一個檔案的 ID,無資料時為 null |
| last_id | 本頁最後一個檔案的 ID,無資料時為 null |
| has_more | 此知識版本是否還有更多的檔案 |
Fileset File 物件(data[])
包含「檔案物件」的所有欄位,差異如下:
| Field | Detail |
|---|---|
| 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 Code | HTTP Status | 情境 |
|---|---|---|
| FILESET_001 | 404 | 指定的 Fileset 不存在 |
| VAL_001 | 422 | 同時帶入 after 與 before |
| VAL_002 | 404 | after/before 指定的檔案 ID 不存在 |
| — | 422 | files_state 不是允許的值 |
身份驗證錯誤(AUTH_001~AUTH_003)詳見「錯誤代碼說明-身份驗證類」章節;知識版本相關錯誤碼完整說明請參考 錯誤代碼說明-知識版本管理類。