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

取得所有檔案列表

此 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​

KeyValue
Request MethodGET
acceptapplication/json
AuthorizationBearer $PRIVAI_API_KEY

Query Parameters​

FieldTypeNoteRequired
limitint1 - 10000,預設為 10000false
orderstring依 created_at 排序,asc 或 desc,預設為 descfalse
afterstringuuid,分頁游標(檔案 ID),取得此檔案之後的資料。不可與 before 同時使用false
beforestringuuid,分頁游標(檔案 ID),取得此檔案之前的資料。不可與 after 同時使用false
purposestring(與 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

FieldDetail
object固定為 list
data[]請參考「檔案物件」章節列表
first_id本頁第一個檔案的 ID(無資料時不回傳)
last_id本頁最後一個檔案的 ID(無資料時不回傳)
has_more是否還有更多檔案

備註:此 API 會省略值為 null 的欄位,因此回應中不會出現 expires_at。

常見錯誤代碼​

Error CodeHTTP Status情境
VAL_001422同時帶入 after 與 before
VAL_002404after/before 指定的檔案 ID 不存在

身份驗證錯誤(AUTH_001~AUTH_003)詳見「錯誤代碼說明-身份驗證類」章節;參數驗證錯誤請參考 錯誤代碼說明-傳遞參數驗證類。