知识库版本管理 API
知识库多版本生命周期接口:版本列出与读取、工作副本(working copy)创建与操作查询/取消、就绪检查与封存(seal)、发布(publish)与回滚(rollback)、版本删除(不可逆异步清理)及删除操作查询、版本采纳(adoption)及其查询/取消。骨架与产品语义见 知识库 API。
资源与基础路径
- Base URL:
https://<your-endpoint>/v1,路径前缀/knowledgebases/{knowledgeBaseId}。 - 层级:知识库
{knowledgeBaseId}→ 版本{versionId};旁路资源:采纳操作{adoptionId}、工作副本操作{operationId}、删除操作{operationId}。 - 生命周期:
DRAFT(工作副本)→READY(seal 后只读快照)→CURRENT/ROLLBACK(publish / rollback 的路由角色);删除后版本进入deletionState流转且不可逆。
认证与权限
认证与请求头约定见 通用约定。查询类端点需 knowledgebases.read,全部写操作需 knowledgebases.write。接受类写端点(创建工作副本、seal、delete、adoption 创建/取消、工作副本取消)另要求稳定的 Idempotency-Key 头:同一 key 与同一请求重放返回原操作,复用 key 提交不同输入返回 idempotency_key_reused(409)。
端点清单
| 方法 + 路径 | 用途 |
|---|---|
GET /knowledgebases/{knowledgeBaseId}/versions | 列出版本(status / role 过滤,cursor 分页)(见 版本管理) |
POST /knowledgebases/{knowledgeBaseId}/versions | 创建工作副本(异步,202 + 操作)(见 版本管理) |
GET /knowledgebases/{knowledgeBaseId}/versions/{versionId} | 获取版本(见 版本管理) |
DELETE /knowledgebases/{knowledgeBaseId}/versions/{versionId} | 请求不可逆删除(异步,202 + 删除操作)(见 版本管理) |
POST /knowledgebases/{knowledgeBaseId}/versions/{versionId}/publish | 发布 READY 版本为当前版本(见 版本管理) |
POST /knowledgebases/{knowledgeBaseId}/versions/{versionId}/rollback | 回滚到保留的回滚目标(见 版本管理) |
POST /knowledgebases/{knowledgeBaseId}/versions/{versionId}/seal | 就绪检查通过后封存 DRAFT 为 READY(见 版本管理) |
GET /knowledgebases/{knowledgeBaseId}/versions/{versionId}/readiness | 就绪摘要(sealable + 阻塞原因)(见 版本管理) |
GET /knowledgebases/{knowledgeBaseId}/version-adoptions | 列出采纳操作(见 版本管理) |
POST /knowledgebases/{knowledgeBaseId}/version-adoptions | 为未版本化库启动采纳(异步,202)(见 版本管理) |
GET /knowledgebases/{knowledgeBaseId}/version-adoptions/{adoptionId} | 获取采纳操作(见 版本管理) |
POST /knowledgebases/{knowledgeBaseId}/version-adoptions/{adoptionId}/cancel | 请求取消采纳(异步,202)(见 版本管理) |
GET /knowledgebases/{knowledgeBaseId}/version-delete-operations/{operationId} | 查询版本删除操作(见 版本管理) |
GET /knowledgebases/{knowledgeBaseId}/working-copy-operations | 列出工作副本操作(见 版本管理) |
GET /knowledgebases/{knowledgeBaseId}/working-copy-operations/{operationId} | 获取工作副本操作(见 版本管理) |
POST /knowledgebases/{knowledgeBaseId}/working-copy-operations/{operationId}/cancel | 请求取消工作副本操作(见 版本管理) |
请求与响应
通用约定:认证头 X-Appwrite-Project / X-Appwrite-Key(见 通用约定);异步端点返回 202 + Location 头指向对应操作查询端点,客户端轮询至终态;操作模型对调用方脱敏(不暴露 provider locator、物理表、bucket/file、manifest 或 checkpoint)。示例中 kb_product_docs、ver_001 等请替换为实际值。
GET /v1/knowledgebases/{knowledgeBaseId}/versions
列出指定知识库中对调用方可见的版本;只返回已提交的版本(物化中的工作副本不以半成品 DRAFT 出现)。
输入:
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
knowledgeBaseId | path | string | 是 | 目标知识库 ID。 | |
limit | query | integer | 否 | 默认 25 | 每页最大版本数。 |
cursor | query | string | 否 | 默认 "" | 版本 ID 分页游标。 |
status | query | string | 否 | 枚举:draft / ready | 按生命周期状态过滤。 |
role | query | string | 否 | 枚举:current / rollback / none | 按路由角色过滤。 |
输出:200,返回模型 KnowledgeBaseVersionList:total + versions[](模型 KnowledgeBaseVersion,字段见下)。
POST /v1/knowledgebases/{knowledgeBaseId}/versions
从一个 READY 且 deletionState=NONE 的版本创建完全物化的工作副本;复制与校验完成后新版本才以隔离 DRAFT 可见,parentVersionId 记录逻辑源版本。
输入:
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
knowledgeBaseId | path | string | 是 | 目标知识库 ID。 | |
sourceVersionId | body | string | 是 | 源版本 ID(READY 且未进入删除流程)。 | |
expectedSourceVersionRevision | body | integer | 是 | 预期源版本修订号。 | |
expectedBindingRevision | body | integer | 是 | 预期知识库绑定修订号。 | |
label | body | string | 是 | 工作副本标签,非空且唯一。 | |
description | body | string | 否 | 工作副本描述。 | |
retryOf | body | string | 否 | 被重试的失败/取消操作 ID。 |
输出:202,返回模型 KnowledgeBaseWorkingCopyOperation(status: queued / preflight / copying / validating / reconciling / cancelling / succeeded / failed / cancelled,含 operationRevision、progress、errorCode/errorSummary、result.versionId、retryOf);Location 头指向工作副本操作查询端点。
GET /v1/knowledgebases/{knowledgeBaseId}/versions/{versionId}
获取单个版本的状态、角色、逻辑父版本、修订号与处理进度摘要;跨库或不存在的版本统一按不可见处理。
输入:
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
knowledgeBaseId | path | string | 是 | 目标知识库 ID。 | |
versionId | path | string | 是 | 版本 ID。 |
输出:200,返回模型 KnowledgeBaseVersion。
| 字段 | 类型 | 说明 |
|---|---|---|
$id* | string | 版本 ID。 |
$createdAt* / $updatedAt* | string | 创建/更新时间(ISO 8601)。 |
parentVersionId | string | 直属逻辑父版本 ID;根版本为 null。 |
label* | string | 版本标签。 |
description | string | 版本描述。 |
status* | string | 生命周期状态:DRAFT / READY。 |
deletionState* | string | 删除状态:NONE / REQUESTED / RUNNING / RETRYABLE_FAILED / COMPLETED;仅 NONE 允许数据访问。 |
role* | string | 路由角色:CURRENT / ROLLBACK / NONE。 |
versionRevision* | integer | 版本元数据与生命周期修订号。 |
definitionRevision* | integer | 版本内容与配置修订号。 |
documentProcessingRevision* | integer | 文档处理配置修订号。 |
readiness | object | 只读就绪摘要(不含源内容与 provider locator)。 |
DELETE /v1/knowledgebases/{knowledgeBaseId}/versions/{versionId}
请求对一个非活跃版本做不可逆清理。仅 role=NONE、deletionState=NONE 且状态为 DRAFT/READY 的版本可删;接受后访问立即被撤销且不可撤回,物理清理由后台 Worker 有界分批异步执行。
输入:
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
knowledgeBaseId | path | string | 是 | 目标知识库 ID。 | |
versionId | path | string | 是 | 目标版本 ID。 | |
expectedVersionRevision | body | integer | 是 | 预期版本生命周期修订号。 |
输出:202,返回模型 KnowledgeBaseVersionDeleteOperation(status: queued / running / retryable_failed / completed);Location: /v1/knowledgebases/{knowledgeBaseId}/version-delete-operations/{operationId}。retryable_failed 时访问保持被撤销,需换新幂等键重新提交 DELETE 重排队同一操作。
POST /v1/knowledgebases/{knowledgeBaseId}/versions/{versionId}/publish
将未删除的 READY 版本发布为线上 CURRENT;同一事务内切换 currentVersionId 与 rollbackVersionId,先前的 CURRENT 成为唯一 ROLLBACK 目标。
输入:
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
knowledgeBaseId | path | string | 是 | 目标知识库 ID。 | |
versionId | path | string | 是 | 目标 READY 版本 ID。 | |
expectedBindingRevision | body | integer | 是 | 预期知识库绑定修订号。 | |
expectedVersionRevision | body | integer | 是 | 预期版本生命周期修订号。 |
输出:200,返回模型 KnowledgeBaseVersion(发布后的版本)。
POST /v1/knowledgebases/{knowledgeBaseId}/versions/{versionId}/rollback
将 Binding 保留的 ROLLBACK 角色指向的未删除 READY 版本恢复为线上 CURRENT;原子交换 currentVersionId 与 rollbackVersionId,不能指定任意历史版本作为回滚目标。
输入:与 publish 相同——knowledgeBaseId、versionId(path,必填),expectedBindingRevision、expectedVersionRevision(body,integer,必填)。
输出:200,返回模型 KnowledgeBaseVersion(回滚后的当前版本)。
POST /v1/knowledgebases/{knowledgeBaseId}/versions/{versionId}/seal
在全部就绪检查通过后将 DRAFT 版本设为 READY;活动任务、未就绪/待重建文档、stale/failed 的已启用索引能力与 Wiki 冲突都会拒绝转换。成功后的 READY 版本只读,不自动发布。
输入:
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
knowledgeBaseId | path | string | 是 | 目标知识库 ID。 | |
versionId | path | string | 是 | 目标 DRAFT 版本 ID。 | |
expectedDefinitionRevision | body | integer | 是 | 预期版本内容/配置修订号。 | |
expectedVersionRevision | body | integer | 是 | 预期版本生命周期修订号。 |
输出:200,返回模型 KnowledgeBaseVersion(封存后的 READY 版本)。
GET /v1/knowledgebases/{knowledgeBaseId}/versions/{versionId}/readiness
获取版本的只读就绪摘要:状态与修订号、文档/索引/活动任务计数、是否可封存及按数量聚合的阻塞原因。
输入:
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
knowledgeBaseId | path | string | 是 | 目标知识库 ID。 | |
versionId | path | string | 是 | 目标版本 ID。 |
输出:200,返回模型 KnowledgeBaseVersionReadiness。
| 字段 | 类型 | 说明 |
|---|---|---|
versionId* | string | 版本 ID。 |
status* | string | 生命周期状态:DRAFT / READY。 |
versionRevision* | integer | 当前版本生命周期修订号。 |
definitionRevision* | integer | 当前版本内容/配置修订号。 |
documentProcessingRevision* | integer | 当前文档处理修订号。 |
sealable* | boolean | 是否无就绪阻塞(可设为 READY)。 |
summary* | object | 就绪计数(不含文档内容与 provider 引用)。 |
blockers* | object | 稳定阻塞码与计数(如 active_tasks、documents_not_ready、documents_rebuild_required、capabilities_stale、capabilities_failed、wiki_conflicts)。 |
GET /v1/knowledgebases/{knowledgeBaseId}/version-adoptions
列出本知识库的采纳操作历史。
输入:
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
knowledgeBaseId | path | string | 是 | 目标知识库 ID。 | |
limit | query | integer | 否 | 默认 25 | 每页最大操作数。 |
cursor | query | string | 否 | 默认 "" | 操作 ID 分页游标。 |
status | query | string | 否 | 按操作状态过滤。 |
输出:200,返回采纳操作列表模型(total + adoptions[],元素为采纳操作模型,见下)。
POST /v1/knowledgebases/{knowledgeBaseId}/version-adoptions
为尚未启用版本的 Shared V2 知识库启动采纳:后台 Worker 完成 schema reconciliation、drain、标记、验证与激活,成功前不切换 currentVersionId。
输入:
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
knowledgeBaseId | path | string | 是 | 目标知识库 ID(须未启用版本化)。 | |
expectedBindingRevision | body | integer | 是 | 预期知识库绑定修订号。 | |
retryOf | body | string | 否 | 被重试的终态采纳操作 ID。 |
输出:202,返回采纳操作模型(KnowledgeBaseVersionAdoptionOperation 口径,字段与工作副本操作同构:$id、时间戳、kind、status、operationRevision、progress、errorCode/errorSummary、result、retryOf;status 枚举含 queued / preflight / storage_reconciling / draining / backfilling / marking / validating / activating / reconciling / cancelling / succeeded / failed / cancelled);Location 头指向采纳操作查询端点。模型名以 spec 为准。
GET /v1/knowledgebases/{knowledgeBaseId}/version-adoptions/{adoptionId}
获取单个采纳操作的当前状态与进度。
输入:
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
knowledgeBaseId | path | string | 是 | 目标知识库 ID。 | |
adoptionId | path | string | 是 | 采纳操作 ID。 |
输出:200,返回采纳操作模型(同上,模型名以 spec 为准)。
POST /v1/knowledgebases/{knowledgeBaseId}/version-adoptions/{adoptionId}/cancel
在采纳尚未进入不可取消阶段时请求取消;成功接受后由后台流程完成一致性收敛。
输入:
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
knowledgeBaseId | path | string | 是 | 目标知识库 ID。 | |
adoptionId | path | string | 是 | 采纳操作 ID。 | |
expectedOperationRevision | body | integer | 是 | 预期采纳操作修订号。 |
输出:202,返回采纳操作模型(进入 cancelling,最终收敛至 cancelled 或继续原流程;模型名以 spec 为准)。
GET /v1/knowledgebases/{knowledgeBaseId}/version-delete-operations/{operationId}
查询单个版本删除操作用于轮询;仅接受发起 DELETE 的同一知识库的 operationId(跨库按 version_not_found 处理)。
输入:
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
knowledgeBaseId | path | string | 是 | 目标知识库 ID(须与删除操作所属库一致)。 | |
operationId | path | string | 是 | 删除操作 ID。 |
输出:200,返回模型 KnowledgeBaseVersionDeleteOperation。
GET /v1/knowledgebases/{knowledgeBaseId}/working-copy-operations
列出本知识库的工作副本操作。
输入:
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
knowledgeBaseId | path | string | 是 | 目标知识库 ID。 | |
limit | query | integer | 否 | 默认 25 | 每页最大操作数。 |
cursor | query | string | 否 | 默认 "" | 操作 ID 分页游标。 |
status | query | string | 否 | 按操作状态过滤。 |
输出:200,返回模型 KnowledgeBaseWorkingCopyOperationList:total + operations[](模型 KnowledgeBaseWorkingCopyOperation)。
GET /v1/knowledgebases/{knowledgeBaseId}/working-copy-operations/{operationId}
获取单个工作副本操作的当前状态、进度与结果。
输入:
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
knowledgeBaseId | path | string | 是 | 目标知识库 ID。 | |
operationId | path | string | 是 | 工作副本操作 ID。 |
输出:200,返回模型 KnowledgeBaseWorkingCopyOperation。
POST /v1/knowledgebases/{knowledgeBaseId}/working-copy-operations/{operationId}/cancel
请求取消非终态的工作副本操作;取消为异步——响应通常为 cancelling,继续轮询至 cancelled。私有候选副本会被清理,不会生成可见 DRAFT。
输入:
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
knowledgeBaseId | path | string | 是 | 目标知识库 ID。 | |
operationId | path | string | 是 | 工作副本操作 ID。 | |
expectedOperationRevision | body | integer | 是 | 预期工作副本操作修订号。 |
输出:200,返回模型 KnowledgeBaseWorkingCopyOperation(status=cancelling)。
错误与边界
- 修订号预期不符被拒:
expectedBindingRevision/expectedVersionRevision/expectedDefinitionRevision/expectedOperationRevision漂移、生命周期/角色/删除状态不合规或并发 Binding 变化,返回version_concurrently_modified(409)——刷新后重读状态再决定是否重试。 - seal 前置:
sealVersion要求就绪检查全部通过(readiness.sealable=true),否则拒绝转换。 - publish 仅 READY:只有未删除的
READY版本可发布;发布/回滚不创建任何摄取、同步、索引或 Memory 任务。 - delete 不可逆异步:接受即撤销访问且不可撤回;物理清理异步执行,
retryable_failed需换新幂等键重新提交;完成后数据清除、版本记录保留为审计痕迹。 - adoption 仅未版本化库:已启用版本化的库不能再发起采纳;进入不可取消阶段后取消失败(revision 漂移同样失败)。
- 幂等键复用不同输入返回
idempotency_key_reused(409);工作副本标签重复返回version_label_already_exists;不支持版本化的存储模式返回version_storage_mode_not_supported。 - 列表与查询对跨库/不存在的资源统一按不可见处理(404
version_not_found),不泄露存在性。
与 Server SDK 的对应
| service.method | 端点 | |
|---|---|---|
KnowledgeBases.listVersions | GET /knowledgebases/{id}/versions | |
KnowledgeBases.createVersion | POST /knowledgebases/{id}/versions | |
KnowledgeBases.getVersion | GET .../versions/{versionId} | |
KnowledgeBases.deleteVersion | DELETE .../versions/{versionId} | |
KnowledgeBases.publishVersion | POST .../versions/{versionId}/publish | |
KnowledgeBases.rollbackVersion | POST .../versions/{versionId}/rollback | |
KnowledgeBases.sealVersion | POST .../versions/{versionId}/seal | |
KnowledgeBases.getVersionReadiness | GET .../versions/{versionId}/readiness | |
KnowledgeBases.listVersionAdoptions / createVersionAdoption | `GET | POST .../version-adoptions` |
KnowledgeBases.getVersionAdoption / cancelVersionAdoption | GET .../version-adoptions/{adoptionId}、POST .../{adoptionId}/cancel | |
KnowledgeBases.getVersionDeleteOperation | GET .../version-delete-operations/{operationId} | |
KnowledgeBases.listWorkingCopyOperations / getWorkingCopyOperation / cancelWorkingCopyOperation | GET .../working-copy-operations、`GET | POST .../working-copy-operations/{operationId}(/cancel)` |
事实源
- Server API spec:
agentbase-sdksv2.8.0specs/open-api3-latest-server.json(/knowledgebases/{id}/versions*、/knowledgebases/{id}/version-adoptions*、/knowledgebases/{id}/version-delete-operations*、/knowledgebases/{id}/working-copy-operations*端点与knowledgeBaseVersion*/ 操作模型)。 - appbase v2.8.0(peeled
ea835e462085decbbf49ab7fd6a0e99928be72a9):src/Appwrite/Migration/Version/V55.php(版本存储契约)与 Consolekb-[kb]/versions/页面集(采纳、工作副本、封存、发布/回滚、删除的交互语义)。