# 取得所有檔案列表

此 API 用於取得目前已上傳至 Storage 中的所有檔案清單。每個檔案都包含其唯一 ID、檔名、檔案類型、上傳時間等基本資訊，可用於後續建立 Fileset、檢查上傳狀態或執行維運管理。

```bash
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

```json
{
  "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[] | 請參考「[檔案物件](https://privstation-docs.apmic.ai/latest/privai-400/檔案物件.md)」章節列表 |
| 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`）詳見「錯誤代碼說明-身份驗證類」章節；參數驗證錯誤請參考 [錯誤代碼說明-傳遞參數驗證類](https://privstation-docs.apmic.ai/latest/privai-400/錯誤代碼說明-傳遞參數驗證類.md)。
