# 取得單一檔案資料

此 API 用於查詢單一檔案的詳細資訊。  
你可以透過檔案的 `file_id` 取得該檔案的原始檔名、格式、上傳時間、檔案大小等資訊。  
此功能常用於查詢單一檔案的基本資訊，以及確認該檔案在不同解析品質下的文件解析結果與處理狀態。在建立 Fileset 前，也可先透過此 API 檢查檔案是否已完成所需的解析流程。

```bash
curl -X 'GET' \
  'http://127.0.0.1:8000/v1/files/{file_id}' \
  -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 |
| --- | --- | --- | --- |
| file_id | string | uuid | true |

#### Response Body

```json
{
  "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": [],
    "source": "internal_policy",
    "language": "zh-Hant"
  },
  "purpose": "user_data",
  "created_at": "2025-01-01T00:00:14.173Z"
}
```

**Field Explanation**  
回傳「[檔案物件](https://privstation-docs.apmic.ai/latest/privai-400/檔案物件.md)」章節列表內容。  
備註：

- 此 API 會省略值為 null 的欄位，因此回應中不會出現 `expires_at`；`parsing_state` 為 `draft` 的解析品質也只會回傳 `parsing_state`。

- 此 API 回傳的是 File 物件本身的資訊，不包含 Fileset File State 與 `used_quality`。若需查詢檔案在特定 Fileset 中的 commit 狀態，請改用「取得單一知識版本的檔案列表」API。

#### 常見錯誤代碼

| Error Code | HTTP Status | 情境 |
| --- | --- | --- |
| FILE_002 | 404 | 指定的檔案不存在 |

身份驗證錯誤（`AUTH_001`～`AUTH_003`）詳見「錯誤代碼說明-身份驗證類」章節；檔案相關錯誤碼完整說明請參考 [錯誤代碼說明-檔案管理類](https://privstation-docs.apmic.ai/latest/privai-400/錯誤代碼說明-檔案管理類.md)。
