API 參考
版本控制與棄用
了解 Kanorio 如何進行 API 版本控制、定義重大變更，以及在移除功能前如何公告棄用資訊。
所有三種 API 皆透過 URL 進行版本控制，例如 /api/v1。相容性變更會持續發布，無須建立新版本。重大變更則遵循本頁所述流程。目前 API 處於 beta 階段：資料結構仍可能調整，且每次變更皆會先於 更新日誌 中公告。
相容性變更
這類變更隨時會發布，請確保您的用戶端程式具備容錯能力：
- 新增端點、操作、MCP 工具與 Webhook 事件。
- 新增選填的請求欄位與查詢參數。
- 新增回應欄位。請忽略您未知的欄位。
- 新增錯誤代碼。請依照 HTTP 狀態碼處理未知代碼，詳見 錯誤處理。
- 新增權限，以及更寬鬆的驗證規則（接受更多數值）。
重大變更
這類變更絕不會在未經通知的情況下發布：
- 移除或重新命名端點、操作、工具或欄位。
- 變更欄位的類型或意義，或將選填欄位改為必填。
- 變更錯誤代碼或其 HTTP 狀態碼。
- 收緊驗證規則，或變更操作所需的權限。
針對穩定的操作，重大變更會經歷棄用流程，並透過新的 URL 版本保留舊版本至少六個月。在當前階段，重大變更會在發布當日列於更新日誌中。
如何接收棄用通知
當操作被棄用時，所有管道會同步通知您：
| 位置 | 您會看到的內容 |
|---|---|
| 回應標頭 | Deprecation 標頭包含棄用日期，Sunset 標頭包含移除日期，並附帶 Link 標頭指向此政策及替代方案 |
| OpenAPI | 在操作中標註 deprecated: true、x-kanorio-sunset 及 x-kanorio-replaced-by |
| MCP | 工具描述開頭會標示為 [Deprecated, removed after …; use …] |
| API 參考文件 | 顯示棄用標籤，並標註移除日期及替代方案 |
| CLI | 在 stderr 顯示警告訊息 |
| 電子郵件 | 在移除前，會發送提醒予過去 30 天內曾呼叫該操作的 Token 持有者 |
Deprecation: @1788134400 Sunset: Sat, 01 May 2027 00:00:00 GMT Link: <https://kanorio.com/en/developers/basics/versioning>; rel="deprecation"
操作僅會在超過停用日期（sunset date）後才會被移除。
發布階段
每個操作與產品皆有其發布階段。詳見 發布階段。
SDK、Elements 與 MCP 版本
@kanorio/sdk與@kanorio/elements遵循語意化版本控制（Semantic Versioning）。經常變更的規則（如機器人防護、爬蟲封鎖清單與重新導向）由 API 提供，因此已部署的前端無須升級即可自動獲取更新。- MCP 伺服器會在
serverInfo及其登錄項目中發布語意化版本。主要版本更新（Major version）代表現有的呼叫行為可能會有所不同。每次變更時，更新日誌皆會註明該版本號。