# 新增知識版本

![](https://privstation-docs.apmic.ai/img/notion/1afbd270f2ad.png)

此 API 用於建立一個新的 **Fileset**，作為後續知識組織與查詢的單位。  
開發者可以指定該 Fileset 的名稱、Metadata 以及要包含的檔案 ID 清單（`file_ids`）。新建立的 Fileset 狀態為 `draft`，需再透過「Commit 知識版本」API 建立為可查詢的知識版本。完整流程詳見「Fileset 知識版本建立流程」章節。

```bash
curl -X 'POST' \
  'http://127.0.0.1:8000/v1/filesets' \
  -H 'accept: application/json' \
  -H "Authorization: Bearer $PRIVAI_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "file_ids": [
      "3fa85f64-5717-4562-b3fc-2c963f66afa6"
    ],
    "metadata": {
      "tag": ["policy", "operation"]
    },
    "name": "Company Policy Files v1.0"
  }'
```

#### Request Headers

| Key | Value |
| --- | --- |
| Request Method | POST |
| accept | application/json |
| Authorization | `Bearer $PRIVAI_API_KEY` |
| Content-Type | application/json |

#### Request Payload

```json
{
  "file_ids": [
    "3fa85f64-5717-4562-b3fc-2c963f66afa6"
  ],
  "metadata": {
    "tag": ["policy", "operation"]
  },
  "name": "Company Policy Files v1.0"
}
```

**Field Explanation**

| Field | Type | Detail | Required |
| --- | --- | --- | --- |
| file_ids | array | File ID（uuid）列表。此欄位必須帶入，可為空陣列或 null（建立不含檔案的 Fileset，但 commit 前至少需加入一個檔案）。任一 ID 不存在時回傳 `FILE_009` | true |
| metadata | object | 使用者自訂的描述資訊 | false |
| name | string | Fileset 的名稱，若沒指定系統會自動產生，格式為 `fileset_YYYYMMDD_hh:mm` | false |
| id | string | uuid，指定 Fileset ID；若沒有指定則由系統自動產生。指定的 ID 已存在時回傳 `FILESET_002` | false |

#### Response Body

```json
{
  "object": "fileset",
  "id": "a1ecdb5d-e2a5-4aec-8925-b0648a5c0e21",
  "name": "Company Policy Files v1.0",
  "metadata": {
    "tag": ["policy", "operation"],
    "embedding_model": null,
    "parsing_mode": null
  },
  "state": "draft",
  "created_at": "2025-01-01T00:00:00.000Z",
  "committed_at": null,
  "updated_at": "2025-01-01T00:00:00.000Z",
  "file_counts": {
    "draft": 1,
    "queued": 0,
    "processing": 0,
    "completed": 0,
    "failed": 0,
    "total": 1
  }
}
```

**Field Explanation**  
回傳「[知識版本物件](https://privstation-docs.apmic.ai/latest/privai-400/知識版本物件.md)」章節列表內容。HTTP Status 為 200。尚未 commit 的 Fileset，`metadata.embedding_model` 與 `metadata.parsing_mode` 為 null。

#### 常見錯誤代碼

| Error Code | HTTP Status | 情境 |
| --- | --- | --- |
| FILESET_002 | 409 | 以 `id` 指定的 Fileset ID 已存在 |
| FILE_009 | 404 | `file_ids` 中有不存在的檔案，回應中的 `file_ids` 列出找不到的 ID |
| — | 422 | 缺少 `file_ids`、ID 不是合法 uuid，或帶入未定義的欄位 |

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