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）代表现有的调用行为可能会有所不同。每次变更时，更新日志皆会注明该版本号。