Knowledge Base Version Management API
Knowledge base multi-version lifecycle endpoints: version listing and reading, working copy creation and operation query/cancellation, ready check and seal, publish and rollback, version deletion (irreversible asynchronous cleanup) with deletion operation query, and version adoption with its query/cancellation. For the usage workflow and product semantics, see Knowledge Base API.
Service and resource boundaries
The knowledge base version management API provides immutable snapshot sealing, canary validation, and second-level rollback capabilities for enterprise production knowledge bases: daily document editing is isolated in a DRAFT working copy, after passing the readiness ready check it is sealed (seal) as a read-only READY version, and then via publish / rollback the CURRENT version that production retrieval traffic points to is atomically switched, avoiding retrieval result jitter during document ingestion or chunk adjustments.
Resources and Base Paths
Base URL:
https://<your-endpoint>/v1, path prefix/knowledgebases/{knowledgeBaseId}.Hierarchy: knowledge base
{knowledgeBaseId}→ version{versionId}; side resources: adoption operation{adoptionId}, working copy operation{operationId}, deletion operation{operationId}.Lifecycle:
DRAFT(working copy) →READY(read-only snapshot after seal) →CURRENT/ROLLBACK(routing roles of publish / rollback); after deletion the version enters thedeletionStateflow and is irreversible.
Authentication and Permissions
For authentication and request header conventions, see General Conventions. Query endpoints require knowledgebases.read, and all write operations require knowledgebases.write. Accepted write endpoints (create working copy, seal, delete, adoption create/cancel, working copy cancel) additionally require a stable Idempotency-Key header: replaying the same key with the same request returns the original operation, while reusing a key with different input returns idempotency_key_reused (409).
Endpoint overview
This module contains 16 endpoints in total, covering: version listing and detail queries, asynchronously cloning a DRAFT working copy from an existing READY version, readiness probe (readiness) and version sealing (seal), production version publish (publish) and rollback (rollback), adoption of legacy non-versioned knowledge bases (version-adoptions), and asynchronous physical version deletion (version-delete-operations).
Endpoint List
| Method + path | Purpose |
|---|---|
GET /knowledgebases/{knowledgeBaseId}/versions | List versions (status / role filters, cursor pagination) (see version management) |
POST /knowledgebases/{knowledgeBaseId}/versions | Create working copy (asynchronous, 202 + operation) (see version management) |
GET /knowledgebases/{knowledgeBaseId}/versions/{versionId} | Get version (see version management) |
DELETE /knowledgebases/{knowledgeBaseId}/versions/{versionId} | Request irreversible deletion (asynchronous, 202 + deletion operation) (see version management) |
POST /knowledgebases/{knowledgeBaseId}/versions/{versionId}/publish | Publish READY version as current version (see version management) |
POST /knowledgebases/{knowledgeBaseId}/versions/{versionId}/rollback | Roll back to the retained rollback target (see version management) |
POST /knowledgebases/{knowledgeBaseId}/versions/{versionId}/seal | Seal DRAFT as READY after the ready check passes (see version management) |
GET /knowledgebases/{knowledgeBaseId}/versions/{versionId}/readiness | Readiness summary (sealable + blocking reasons) (see version management) |
GET /knowledgebases/{knowledgeBaseId}/version-adoptions | List adoption operations (see version management) |
POST /knowledgebases/{knowledgeBaseId}/version-adoptions | Start adoption for an unversioned knowledge base (asynchronous, 202) (see version management) |
GET /knowledgebases/{knowledgeBaseId}/version-adoptions/{adoptionId} | Get adoption operation (see version management) |
POST /knowledgebases/{knowledgeBaseId}/version-adoptions/{adoptionId}/cancel | Request adoption cancellation (asynchronous, 202) (see version management) |
GET /knowledgebases/{knowledgeBaseId}/version-delete-operations/{operationId} | Query version deletion operation (see version management) |
GET /knowledgebases/{knowledgeBaseId}/working-copy-operations | List working copy operations (see version management) |
GET /knowledgebases/{knowledgeBaseId}/working-copy-operations/{operationId} | Get working copy operation (see version management) |
POST /knowledgebases/{knowledgeBaseId}/working-copy-operations/{operationId}/cancel | Request cancellation of working copy operation (see version management) |
Endpoint details
All write operations that change version topology enforce dual concurrency validation combining the Idempotency-Key header with the expected revision number (expectedSourceVersionRevision / expectedBindingRevision): this both guarantees that a network-timeout retransmission safely returns the same asynchronous operation, and prevents conflicting publishes issued from stale metadata.
Requests and Responses
General conventions: authentication headers X-Appwrite-Project / X-Appwrite-Key (see General Conventions); asynchronous endpoints return 202 + a Location header pointing to the corresponding operation query endpoint, and clients poll until a terminal state; the operation model is opaque to callers (no provider locator, physical tables, bucket/file, manifest, or checkpoint exposed). In the examples, replace kb_product_docs, ver_001, etc., with actual values.
GET /v1/knowledgebases/{knowledgeBaseId}/versions
List versions of the specified knowledge base visible to the caller; only committed versions are returned (working copies being materialized do not appear as half-finished DRAFTs).
Input:
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
knowledgeBaseId | path | string | Yes | Target knowledge base ID. | |
limit | query | integer | no | default 25 | Maximum number of versions per page. |
cursor | query | string | no | default "" | Version ID pagination cursor. |
status | query | string | no | enum: draft / ready | Filter by lifecycle status. |
role | query | string | no | enum: current / rollback / none | Filter by routing role. |
Output: 200, return model KnowledgeBaseVersionList: total + versions[] (model KnowledgeBaseVersion, fields below).
POST /v1/knowledgebases/{knowledgeBaseId}/versions
Create a fully materialized working copy from a version that is READY and deletionState=NONE; the new version only becomes visible with an isolated DRAFT after copying and validation complete, and parentVersionId records the logical source version.
Input:
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
knowledgeBaseId | path | string | Yes | Target knowledge base ID. | |
sourceVersionId | body | string | yes | Source version ID (READY and not in the deletion flow). | |
expectedSourceVersionRevision | body | integer | yes | Expected source version revision number. | |
expectedBindingRevision | body | integer | yes | Expected knowledge base binding revision number. | |
label | body | string | yes | Working copy label, non-empty and unique. | |
description | body | string | no | Working copy description. | |
retryOf | body | string | no | ID of the failed/cancelled operation being retried. |
Output: 202, return model KnowledgeBaseWorkingCopyOperation (status: queued / preflight / copying / validating / reconciling / cancelling / succeeded / failed / cancelled, including operationRevision, progress, errorCode/errorSummary, result.versionId, retryOf); the Location header points to the working copy operation query endpoint.
Call example:
curl -X POST "https://appbuild-sit.oceanbase.com/v1/knowledgebases/kb_enterprise_support/versions" \
-H "X-Appwrite-Project: enterprise-ai-hub-210" \
-H "X-Appwrite-Key: <APPBASE_API_KEY>" \
-H "Idempotency-Key: wc-create-v20261022-01" \
-H "Content-Type: application/json" \
-d '{
"sourceVersionId": "ver_initial_ready_01",
"expectedSourceVersionRevision": 1,
"expectedBindingRevision": 2,
"label": "v2026.10.22-rc1",
"description": "新增 OceanBase V4.3 排障手册与多模态架构图切片"
}'Response example (202 Accepted):
{
"$id": "wcop_99201a",
"$createdAt": "2026-10-22T06:10:00.000+00:00",
"$updatedAt": "2026-10-22T06:10:00.000+00:00",
"knowledgeBaseId": "kb_enterprise_support",
"kind": "create_working_copy",
"status": "queued",
"operationRevision": 1,
"progress": 0,
"result": {
"versionId": "ver_draft_20261022"
}
}GET /v1/knowledgebases/{knowledgeBaseId}/versions/{versionId}
Get a single version's status, role, logical parent version, revision numbers, and processing progress summary; versions from other knowledge bases or nonexistent versions are uniformly treated as invisible.
Input:
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
knowledgeBaseId | path | string | Yes | Target knowledge base ID. | |
versionId | path | string | yes | Version ID. |
Output: 200, return model KnowledgeBaseVersion.
| Field | Type | Description |
|---|---|---|
$id* | string | Version ID. |
$createdAt* / $updatedAt* | string | Creation/update time (ISO 8601). |
parentVersionId | string | Direct logical parent version ID; null for the root version. |
label* | string | Version label. |
description | string | Version description. |
status* | string | Lifecycle status: DRAFT / READY. |
deletionState* | string | Deletion status: NONE / REQUESTED / RUNNING / RETRYABLE_FAILED / COMPLETED; data access is only allowed for NONE. |
role* | string | Routing role: CURRENT / ROLLBACK / NONE. |
versionRevision* | integer | Version metadata and lifecycle revision number. |
definitionRevision* | integer | Version content and configuration revision number. |
documentProcessingRevision* | integer | Document processing configuration revision number. |
readiness | object | Read-only readiness summary (excludes source content and provider locator). |
DELETE /v1/knowledgebases/{knowledgeBaseId}/versions/{versionId}
Request irreversible cleanup of an inactive version. Only versions that are role=NONE, deletionState=NONE, and in status DRAFT/READY can be deleted; once accepted, access is revoked immediately and cannot be withdrawn, and physical cleanup is performed asynchronously by a background Worker in bounded batches.
Input:
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
knowledgeBaseId | path | string | Yes | Target knowledge base ID. | |
versionId | path | string | Yes | Target version ID. | |
expectedVersionRevision | body | integer | Yes | Expected version lifecycle revision number. |
Output: 202, returning model KnowledgeBaseVersionDeleteOperation (status: queued / running / retryable_failed / completed); Location: /v1/knowledgebases/{knowledgeBaseId}/version-delete-operations/{operationId}. When retryable_failed, access remains revoked; a new idempotency key must be used to resubmit the DELETE to re-enqueue the same operation.
POST /v1/knowledgebases/{knowledgeBaseId}/versions/{versionId}/publish
Publishes a non-deleted READY version as the live CURRENT; switches currentVersionId and rollbackVersionId within the same transaction, making the previous CURRENT the sole ROLLBACK target.
Input:
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
knowledgeBaseId | path | string | Yes | Target knowledge base ID. | |
versionId | path | string | Yes | Target READY version ID. | |
expectedBindingRevision | body | integer | yes | Expected knowledge base binding revision number. | |
expectedVersionRevision | body | integer | Yes | Expected version lifecycle revision number. |
Output: 200, returning model KnowledgeBaseVersion (the published version).
Call example:
curl -X POST "https://appbuild-sit.oceanbase.com/v1/knowledgebases/kb_enterprise_support/versions/ver_draft_20261022/publish" \
-H "X-Appwrite-Project: enterprise-ai-hub-210" \
-H "X-Appwrite-Key: <APPBASE_API_KEY>" \
-H "Idempotency-Key: ver-publish-20261022-01" \
-H "Content-Type: application/json" \
-d '{
"expectedBindingRevision": 3,
"expectedVersionRevision": 2
}'POST /v1/knowledgebases/{knowledgeBaseId}/versions/{versionId}/rollback
Restores the non-deleted ROLLBACK version pointed to by the Binding-retained READY role as the live CURRENT; atomically swaps currentVersionId and rollbackVersionId; an arbitrary historical version cannot be specified as the rollback target.
Input: same as publish — knowledgeBaseId and versionId (path, required), expectedBindingRevision and expectedVersionRevision (body, integer, required).
Output: 200, returning model KnowledgeBaseVersion (the current version after rollback).
Call example:
curl -X POST "https://appbuild-sit.oceanbase.com/v1/knowledgebases/kb_enterprise_support/versions/ver_initial_ready_01/rollback" \
-H "X-Appwrite-Project: enterprise-ai-hub-210" \
-H "X-Appwrite-Key: <APPBASE_API_KEY>" \
-H "Idempotency-Key: ver-rollback-20261022-01" \
-H "Content-Type: application/json" \
-d '{
"expectedBindingRevision": 4,
"expectedVersionRevision": 2
}'POST /v1/knowledgebases/{knowledgeBaseId}/versions/{versionId}/seal
Sets a DRAFT version to READY after all readiness checks pass; active tasks, non-ready/pending-rebuild documents, stale/failed enabled index capabilities, and Wiki conflicts all cause the transition to be rejected. After success, the READY version is read-only and is not published automatically.
Input:
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
knowledgeBaseId | path | string | Yes | Target knowledge base ID. | |
versionId | path | string | Yes | Target DRAFT version ID. | |
expectedDefinitionRevision | body | integer | Yes | Expected version content/configuration revision number. | |
expectedVersionRevision | body | integer | Yes | Expected version lifecycle revision number. |
Output: 200, returning model KnowledgeBaseVersion (the sealed READY version).
Call example:
curl -X POST "https://appbuild-sit.oceanbase.com/v1/knowledgebases/kb_enterprise_support/versions/ver_draft_20261022/seal" \
-H "X-Appwrite-Project: enterprise-ai-hub-210" \
-H "X-Appwrite-Key: <APPBASE_API_KEY>" \
-H "Idempotency-Key: ver-seal-20261022-01" \
-H "Content-Type: application/json" \
-d '{
"expectedDefinitionRevision": 5,
"expectedVersionRevision": 1
}'GET /v1/knowledgebases/{knowledgeBaseId}/versions/{versionId}/readiness
Retrieves a read-only readiness summary of a version: status and revision numbers, document/index/active task counts, sealability, and blocking reasons aggregated by count.
Input:
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
knowledgeBaseId | path | string | Yes | Target knowledge base ID. | |
versionId | path | string | Yes | Target version ID. |
Output: 200, return model KnowledgeBaseVersionReadiness.
| Field | Type | Description |
|---|---|---|
versionId* | string | Version ID. |
status* | string | Lifecycle status: DRAFT / READY. |
versionRevision* | integer | Current version lifecycle revision number. |
definitionRevision* | integer | Current version content/configuration revision number. |
documentProcessingRevision* | integer | Current document processing revision number. |
sealable* | boolean | Whether there are no readiness blockers (can be set to READY). |
summary* | object | Readiness counts (excluding document content and provider references). |
blockers* | object | Stable blocking codes and counts (e.g. active_tasks, documents_not_ready, documents_rebuild_required, capabilities_stale, capabilities_failed, wiki_conflicts). |
Call example:
curl -X GET "https://appbuild-sit.oceanbase.com/v1/knowledgebases/kb_enterprise_support/versions/ver_draft_20261022/readiness" \
-H "X-Appwrite-Project: enterprise-ai-hub-210" \
-H "X-Appwrite-Key: <APPBASE_API_KEY>"Response example (200 OK):
{
"versionId": "ver_draft_20261022",
"status": "DRAFT",
"versionRevision": 1,
"definitionRevision": 5,
"documentProcessingRevision": 4,
"sealable": true,
"summary": {
"documentsTotal": 12,
"documentsReady": 12,
"activeTasks": 0
},
"blockers": {
"active_tasks": 0,
"documents_not_ready": 0,
"documents_rebuild_required": 0,
"capabilities_stale": 0,
"capabilities_failed": 0,
"wiki_conflicts": 0
}
}GET /v1/knowledgebases/{knowledgeBaseId}/version-adoptions
Lists the adoption operation history of this knowledge base.
Input:
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
knowledgeBaseId | path | string | Yes | Target knowledge base ID. | |
limit | query | integer | No | Default 25 | Maximum number of operations per page. |
cursor | query | string | No | Default "" | Pagination cursor by operation ID. |
status | query | string | No | Filter by operation status. |
Output: 200, returning the adoption operation list model (total + adoptions[], elements are adoption operation models, see below).
POST /v1/knowledgebases/{knowledgeBaseId}/version-adoptions
Starts adoption for a Shared V2 knowledge base with versioning not yet enabled: a background Worker completes schema reconciliation, drain, marking, validation, and activation, without switching currentVersionId until success.
Input:
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
knowledgeBaseId | path | string | Yes | Target knowledge base ID (must not have versioning enabled). | |
expectedBindingRevision | body | integer | yes | Expected knowledge base binding revision number. | |
retryOf | body | string | No | ID of the terminal adoption operation being retried. |
Output: 202, returning the adoption operation model (KnowledgeBaseVersionAdoptionOperation structure; fields are isomorphic to working-copy operations: $id, timestamps, kind, status, operationRevision, progress, errorCode/errorSummary, result, retryOf; the status enum includes queued / preflight / storage_reconciling / draining / backfilling / marking / validating / activating / reconciling / cancelling / succeeded / failed / cancelled); the Location header points to the adoption operation query endpoint. Model names follow the spec.
Call example:
curl -X POST "https://appbuild-sit.oceanbase.com/v1/knowledgebases/kb_enterprise_support/version-adoptions" \
-H "X-Appwrite-Project: enterprise-ai-hub-210" \
-H "X-Appwrite-Key: <APPBASE_API_KEY>" \
-H "Idempotency-Key: adopt-kb-20261022-01" \
-H "Content-Type: application/json" \
-d '{
"expectedBindingRevision": 1
}'GET /v1/knowledgebases/{knowledgeBaseId}/version-adoptions/{adoptionId}
Retrieves the current status and progress of a single adoption operation.
Input:
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
knowledgeBaseId | path | string | Yes | Target knowledge base ID. | |
adoptionId | path | string | Yes | Adoption operation ID. |
Output: 200, returning the adoption operation model (as above; model names follow the spec).
POST /v1/knowledgebases/{knowledgeBaseId}/version-adoptions/{adoptionId}/cancel
Requests cancellation while adoption has not yet entered the non-cancellable phase; after successful acceptance, a background process completes consistency convergence.
Input:
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
knowledgeBaseId | path | string | Yes | Target knowledge base ID. | |
adoptionId | path | string | Yes | Adoption operation ID. | |
expectedOperationRevision | body | integer | Yes | Expected adoption operation revision number. |
Output: 202, returning the adoption operation model (entering cancelling, eventually converging to cancelled or continuing the original flow; model names follow the spec).
GET /v1/knowledgebases/{knowledgeBaseId}/version-delete-operations/{operationId}
Queries a single version deletion operation for polling; only accepts an operationId from the same knowledge base that initiated the DELETE (cross-library is handled as version_not_found).
Input:
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
knowledgeBaseId | path | string | Yes | Target knowledge base ID (must match the knowledge base the deletion operation belongs to). | |
operationId | path | string | Yes | Deletion operation ID. |
Output: 200, return model KnowledgeBaseVersionDeleteOperation.
GET /v1/knowledgebases/{knowledgeBaseId}/working-copy-operations
Lists the working-copy operations of this knowledge base.
Input:
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
knowledgeBaseId | path | string | Yes | Target knowledge base ID. | |
limit | query | integer | No | Default 25 | Maximum number of operations per page. |
cursor | query | string | No | Default "" | Pagination cursor by operation ID. |
status | query | string | No | Filter by operation status. |
Output: 200, returning model KnowledgeBaseWorkingCopyOperationList: total + operations[] (model KnowledgeBaseWorkingCopyOperation).
GET /v1/knowledgebases/{knowledgeBaseId}/working-copy-operations/{operationId}
Retrieves the current status, progress, and result of a single working-copy operation.
Input:
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
knowledgeBaseId | path | string | Yes | Target knowledge base ID. | |
operationId | path | string | Yes | Working-copy operation ID. |
Output: 200, return model KnowledgeBaseWorkingCopyOperation.
POST /v1/knowledgebases/{knowledgeBaseId}/working-copy-operations/{operationId}/cancel
Requests cancellation of a non-terminal working-copy operation; cancellation is asynchronous — the response is usually cancelling, and polling continues until cancelled. Private candidate copies are cleaned up and no visible DRAFT is generated.
Input:
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
knowledgeBaseId | path | string | Yes | Target knowledge base ID. | |
operationId | path | string | Yes | Working-copy operation ID. | |
expectedOperationRevision | body | integer | Yes | Expected working-copy operation revision number. |
Output: 200, returning model KnowledgeBaseWorkingCopyOperation (status=cancelling).
Errors and boundaries
Revision mismatch rejected:
expectedBindingRevision/expectedVersionRevision/expectedDefinitionRevision/expectedOperationRevisiondrift, lifecycle/role/deletion status non-compliance, or concurrent Binding changes returnversion_concurrently_modified(409) — refresh and re-read the status before deciding whether to retry.seal Prerequisites:
sealVersionrequires all readiness checks to pass (readiness.sealable=true); otherwise the transition is rejected.publish is READY-only: only non-deleted
READYversions can be published; publish/rollback does not create any ingestion, sync, index, or Memory tasks.delete is irreversible and asynchronous: once accepted, access is revoked and cannot be undone; physical cleanup is asynchronous,
retryable_failedrequires resubmission with a new idempotency key; after completion, data is purged and the version record is retained as an audit trail.adoption only for non-versioned libraries: libraries with versioning enabled cannot start adoption; cancellation fails once the non-cancellable phase has been entered (revision drift likewise fails).
Reusing an idempotency key with different input returns
idempotency_key_reused(409); duplicate working-copy labels returnversion_label_already_exists; storage modes not supporting versioning returnversion_storage_mode_not_supported.List and query operations uniformly treat cross-library/nonexistent resources as invisible (404
version_not_found), without leaking existence.
Correspondence with the Server SDK
| service.method | Endpoint |
|---|---|
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) |