# API 串接 & API 列表

#### API 串接

每一個 API 請求都必須包含有效的 API 金鑰。請在 Authorization 標頭中加入以下格式的金鑰

```python
Authorization: Bearer <your-api-key>
```

PrivAI 支援兩種類型的 API Key：

- **Master Key**：具有管理者權限，可跨租戶檢視與管理資料，也可呼叫 API Key 管理相關 API。  

- **租戶 Key / Tenant Key**：提供給單一客戶或單一租戶使用，只能存取該 API Key 所屬租戶的資料。

**備註：**

- 原本由系統環境變數設定的 `SECRET_KEY` 機制仍保留，並在此架構下作為 **Master Key** 使用。  

- **Tenant Key** 的呼叫方式與既有 API 完全相同，僅需將原本的金鑰替換為客戶專屬 API Key。  

- 當 API Key 已過期、被停用或格式不正確時，系統將拒絕請求並回傳對應錯誤碼。

#### API Key 類型與權限說明

PrivAI 使用 API Key 作為身份驗證與資料範圍控制的基礎。不同類型的 API Key 對應不同的權限與資料可見範圍。

**Key 類型說明**

| **類型** | **說明** |
| --- | --- |
| Master Key | 系統管理用金鑰，可檢視所有租戶資料，並管理租戶Key |
| Tenant Key | 單一租戶專屬金鑰，只能存取自身租戶資料 |

**權限差異**

| **功能** | **Master Key** | **租戶 Key** |
| --- | --- | --- |
| 呼叫既有 PrivAI API | 支援 | 支援 |
| 檢視所有租戶資料 | 支援 | 不支援 |
| 建立 API Key | 支援 | 不支援 |
| 查詢 API Key 列表 | 支援 | 不支援 |
| 更新 / 停用 / 啟用 API Key | 支援 | 不支援 |
| 存取其他租戶資料 | 支援 | 不支援 |

**使用說明**

- **使用 Master Key 呼叫既有 PrivAI API 時，系統將以管理者視角回傳跨租戶資料。**

- **使用 客戶 API Key 呼叫既有 PrivAI API 時，系統會自動套用該租戶的資料範圍限制（tenant scope）。**

- **客戶 API Key 無需額外理解租戶概念，也不需改變既有 API 呼叫方式。**

#### 伺服器主機

測試 PrivAI 伺服器是否正常運作

```bash
curl -X 'GET' \
  'http://127.0.0.1:8000/v1/models' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer <your-api-key>'

```

**Request Headers**

| **Key** | **Value** |
| --- | --- |
| Request Method | GET |
| accept | application/json |
| Authorization | Bearer &lt;your-api-key> |

**Response Body**

```javascript
{
  "object": "list",
  "data": [
    {
      "id": "ace-1-3b-reasoning",
      "object": "model",
      "created": 1677610602,
      "owned_by": "APMIC"
    }
    ...
  ]
}

```

#### API 列表

PrivAI 所有的 API 端點。

#### 模型管理模組

| **請求方法** | **端點** | **描述** |
| --- | --- | --- |
| GET | /v1/models | 取得所有模型 |

#### API Key 管理模組

| **請求方法** | **端點** | **描述** |
| --- | --- | --- |
| GET | /v1/api-keys | 取得所有 API Key 列表 |
| POST | /v1/api-keys | 建立 API Key |
| PUT | /v1/api-keys/{id} | 更新 / 停用 / 啟用 API Key |

#### 檔案管理模組

| **請求方法** | **端點** | **描述** |
| --- | --- | --- |
| GET | /v1/files | 取得所有檔案列表 |
| POST | /v1/files | 上傳檔案 |
| POST | /v1/files/{file_id}/parse | 單一檔案轉換 |
| GET | /v1/files/{file_id} | 取得單一檔案資料 |
| GET | /v1/files/{file_id}/content | 下載檔案 |
| DELETE | /v1/files/{file_id} | 刪除單一檔案 |

#### 知識版本管理模組

| **請求方法** | **端點** | **描述** |
| --- | --- | --- |
| GET | /v1/filesets | 取得所有知識版本列表 |
| POST | /v1/filesets | 新增知識版本 |
| GET | /v1/filesets/{fileset_id} | 取得單一知識版本資料 |
| GET | /v1/filesets/{fileset_id}/files | 取得單一知識版本的檔案列表 |
| PUT | /v1/filesets/{fileset_id} | 更新知識版本 |
| DELETE | /v1/filesets/{fileset_id} | 刪除知識版本 |
| POST | /v1/filesets/{fileset_id}/commit | commit 知識版本 |
| DELETE | /v1/filesets/{fileset_id}/commit | 取消 commit 知識版本 |
| POST | /v1/filesets/{fileset_id}/duplicate | 複製知識版本 |
| POST | /v1/chat/references/{fileset_id}&{query} | 資料參考搜尋 (在指定的知識版本中，搜尋相關的參考資料) |

#### 提示詞管理模組

| **請求方法** | **端點** | **描述** |
| --- | --- | --- |
| GET | /v1/prompts | 取得所有提示詞列表 |
| POST | /v1/prompts | 新增提示詞 |
| GET | /v1/prompts/{prompt_id} | 取得單一提示詞資訊 |
| DELETE | /v1/prompts/{prompt_id} | 刪除提示詞 |
| POST | /v1/prompts/{prompt_id}/optimize/auto | 提示詞自動優化 |
| POST | /v1/prompts/{prompt_id}/optimize/instruct | 提示詞手動優化 |

#### 對話模組

| **請求方法** | **端點** | **描述** |
| --- | --- | --- |
| POST | /v1/chat/completions | 與 LLM 互動 |

#### 其他工具

| **請求方法** | **端點** | **描述** |
| --- | --- | --- |
| POST | /v1/qa/generate | 問答集生成 |
