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

# 版本管理

> 日期式 API 版本:密钥在创建时钉住版本,破坏性变更以新日期发布,老集成原样继续工作。

开放 API 使用**日期版本** —— `2026-08-22` 是当前(也是创始)版本。当 API 需要破坏性变更(字段改名、响应结构调整)时,变更以**一个新日期**发布;所有旧版本的行为原封不动。纯新增的变化——新端点、新的可选字段——对所有版本同时生效,不产生新日期。

<Note>
  你永远不必追着 API 跑。今天写好的集成会一直收到今天的结构,直到**你**决定升级——这正是这套模型的全部意义。
</Note>

## 密钥钉住版本

每把 API 密钥都钉在**它被创建时的最新版本**上。不带版本头的请求,永远按密钥钉住的版本应答。控制台的 [API 密钥](/zh/developers/api-keys)页面在「API 版本」列展示每把钥匙钉住的版本。

## 按请求覆盖

发送 `Orriven-Version` 头,可以让单个请求按另一个版本应答——这是在正式切换前试用新版本的方式:

```bash theme={null}
curl -H "Authorization: Bearer $KEY" \
     -H "Orriven-Version: 2026-08-22" \
     "$BASE/v1/events"
```

未知的日期返回 `400` 并列出现存版本。版本不能捏造——只有已发布的日期有效。

## 每个响应都自报版本

无论版本由什么决定——你的请求头还是密钥的钉住值——响应都会回显它:

```
Orriven-Version: 2026-08-22
```

建议在集成里记录这个响应头:升级期间翻旧日志时,你能确切知道每条响应当时是哪个版本的结构。

## 升级姿势

<Steps>
  <Step title="读变更日志">
    每个新版本的条目(见下)都从调用方视角写清楚到底改了什么。
  </Step>

  <Step title="用请求头试跑">
    让预发环境的集成带上 `Orriven-Version` 指向新日期——密钥的钉住值不受影响,生产流量继续用旧结构。
  </Step>

  <Step title="挪动钉住值">
    生成一把新密钥(自动钉在最新版本),把集成切换过去,再吊销旧密钥——与任何凭证轮换一样零停机。
  </Step>
</Steps>

## 变更日志

| 版本           | 变更                     |
| ------------ | ---------------------- |
| `2026-08-22` | 创始版本——即本 tab 所记录的 API。 |

## 相关页面

<CardGroup cols={2}>
  <Card title="API 密钥" icon="key" href="/zh/developers/api-keys">
    密钥钉住的版本在哪里看。
  </Card>

  <Card title="端点参考" icon="book" href="/zh/developers/api-reference">
    当前版本的结构,逐端点列明。
  </Card>
</CardGroup>