> ## Documentation Index
> Fetch the complete documentation index at: https://docs.brightalk.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# 版本控制

> 使用 Brightalk-Version 標頭選擇日期版本的 API 契約。

<Note>
  **私人測試版。** 新組織預設已啟用。組織管理員仍須在 Brightalk 設定中建立具權限範圍的 API 金鑰，請求才能通過驗證。可用範圍與限制以本文件和 OpenAPI 契約為準。
</Note>

Brightalk 使用日期版本的契約，讓伺服器能選擇整合所依循的 API 行為。

## 使用不含版本的 URL

所有請求都使用正式環境 base URL `https://api.brightalk.ai`。版本號不屬於路徑的一部分；例如，使用 `POST /calls` 建立通話。

## 傳送 Brightalk-Version

客戶端應在每個請求明確傳送支援的日期版本：

```http theme={null}
Brightalk-Version: 2026-07-16
```

每個回應都會在 `Brightalk-Version` 標頭回傳實際套用的版本。請將標頭值放在設定中，讓契約升級都能先完成審查與測試。

## 理解省略標頭與預設值

私人測試版期間，每個已啟用的組織都有固定的預設版本。若請求省略 `Brightalk-Version`，Brightalk 會使用該固定預設值，並仍在回應標頭傳回實際版本。省略標頭不代表任意選用最新版本。

## 處理不支援的版本

未知或已停用的值會傳回 `400 unsupported_version`。選用且可供機器讀取的 `details` 會列出支援版本：

```json theme={null}
{
  "error": {
    "code": "unsupported_version",
    "message": "The requested API version is not supported.",
    "request_id": "req_demo_001",
    "details": {
      "supported_versions": ["2026-07-16"]
    }
  }
}
```

會破壞相容性的回應或行為變更必須使用另一個日期版本。同一版本內可能新增回應欄位，因此客戶端應忽略未知的回應欄位。