版本管理

当前开放接口统一使用 v1 版本。

当前版本

• 网关基础地址：https://runtime-api.invalid/v1/openapi/
• 所有对外 OpenAPI 路径均以：/v1/openapi/ 开头
• 当前文档示例默认全部基于 v1

v1 兼容性规则

以下变更视为 兼容变更（不影响现有 v1 调用）：

• 新增接口
• 新增可选请求参数
• 新增响应字段
• 优化错误文案（不改变状态码与语义）

以下变更视为 非兼容变更（原则上不应在 v1 中直接破坏已有调用）：

• 删除或重命名接口
• 删除或重命名已有请求/响应字段
• 修改已有字段类型或含义
• 修改鉴权方式（例如请求头规则变化）
• 修改错误状态码语义（例如把原 401 改成 403）

调用方建议

• 调用路径固定使用 https://runtime-api.invalid/v1/openapi/
• 请求头统一使用 Authorization: Bearer sk_*，工作空间由网关根据 API Key 自动识别
• 对响应做“向后兼容解析”：允许出现新增字段，避免使用严格全字段匹配

说明

当前阶段仅维护 v1 文档规则。若后续新增版本（如 v2），会在文档中单独增加迁移说明与发布时间。