取得所有檔案列表
此 API 用於取得目前已上傳至 Storage 中的所有檔案清單。每個檔案都包含其唯一 ID、檔名、檔案類型、上傳時間等基本資訊,可用於後續建立 Fileset、檢查上傳狀態或執行維運管理。
curl -X 'GET' \
'http://127.0.0.1:8000/v1/files?limit=20&order=desc' \
-H 'accept: application/json' \
-H "Authorization: Bearer $PRIVAI_API_KEY"
-
檔案列表回傳的是 File 物件基本資訊與解析資訊。
-
檔案是否已解析完成,請查看
metadata.parsed_results內各解析品質的parsing_state。 -
分頁方式詳見「分頁策略 & 文件解析模式優化策略 (PDF)」章節。
Request Headers
| Key | Value |
|---|---|
| Request Method | GET |
| accept | application/json |
| Authorization | Bearer $PRIVAI_API_KEY |
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 |
| purpose | string | (與 OpenAI 相容而保留),指定時只回傳 purpose 相符的檔案 | false |
Response Body
{
"object": "list",
"first_id": "b0d1bdbc-4f94-40b0-9358-68c579c99e8c",
"last_id": "ce7f0171-8993-4e5d-961d-fad6b93400c3",
"has_more": false,
"data": [
{
"object": "file",
"id": "b0d1bdbc-4f94-40b0-9358-68c579c99e8c",
"filename": "company_policy.pdf",
"filetype": "application/pdf",
"bytes": 1463728,
"metadata": {
"parsed_results": {
"HQ": {
"parsing_state": "completed",
"character_count": 6789,
"page_count": 8,
"failed_page_numbers": []
},
"LQ": {
"parsing_state": "draft"
}
},
"fail_detail": []
},
"purpose": "user_data",
"created_at": "2025-01-01T00:00:14.173Z"
},
{
"object": "file",
"id": "ce7f0171-8993-4e5d-961d-fad6b93400c3",
"filename": "faq.docx",
"filetype": "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
"bytes": 58232,
"metadata": {
"parsed_results": {
"STD": {
"parsing_state": "draft"
}
},
"fail_detail": []
},
"purpose": "user_data",
"created_at": "2024-12-31T08:00:00.000Z"
}
]
}
Field Explanation
| Field | Detail |
|---|---|
| object | 固定為 list |
| data[] | 請參考「檔案物件」章節列表 |
| first_id | 本頁第一個檔案的 ID(無資料時不回傳) |
| last_id | 本頁最後一個檔案的 ID(無資料時不回傳) |
| has_more | 是否還有更多檔案 |
備註:此 API 會省略值為 null 的欄位,因此回應中不會出現 expires_at。
常見錯誤代碼
| Error Code | HTTP Status | 情境 |
|---|---|---|
| VAL_001 | 422 | 同時帶入 after 與 before |
| VAL_002 | 404 | after/before 指定的檔案 ID 不存在 |
身份驗證錯誤(AUTH_001~AUTH_003)詳見「錯誤代碼說明-身份驗證類」章節;參數驗證錯誤請參考 錯誤代碼說明-傳遞參數驗證類。