Docs
Contents

Version management

Overview and use cases

Starting with 2.8.0, knowledge bases support multi-version: create a working copy from the READY version (asynchronous copy into an isolated DRAFT) → after readiness checks pass, Seal it into a read-only READY → Publish to switch it to the currently active version, and Rollback restores the retained rollback target; libraries without versioning enabled must first adopt via Adoption. All write paths carry an expected revision number for concurrency protection, and operational changes are asynchronous (idempotency key + polling). For product semantics and Console entry points, see Version Management (Product Manual).

Usage workflow

  1. List and read: listVersions(knowledgeBaseId, limit, cursor, status, role) (limit, cursor, status, and role all optional) paginates versions (status filters draft / ready, role filters current / rollback / none); getVersion reads a single version; the list does not include working copies still being materialized.

  2. Create a working copy: createVersion({ knowledgeBaseId, sourceVersionId, expectedSourceVersionRevision, expectedBindingRevision, label, description, retryOf }) (description and retryOf both optional) returns KnowledgeBaseWorkingCopyOperation—the DRAFT is invisible until validation succeeds; poll with listWorkingCopyOperations / getWorkingCopyOperation, and request cancellation with cancelWorkingCopyOperation.

  3. Readiness check and seal: getVersionReadiness returns sealable and blocking reasons; sealVersion (carrying expectedDefinitionRevision + expectedVersionRevision + idempotency key) sets the DRAFT to READY and does not publish automatically.

  4. Publish and rollback: publishVersion / rollbackVersion (both carrying expectedBindingRevision + expectedVersionRevision) atomically switch currentVersionId / rollbackVersionId and return KnowledgeBaseVersion.

  5. Delete: deleteVersion({ knowledgeBaseId, versionId, expectedVersionRevision }) initiates irreversible asynchronous cleanup and returns KnowledgeBaseVersionDeleteOperation; poll getVersionDeleteOperation until completed. Versions with the CURRENT / ROLLBACK role cannot be deleted.

  6. Adoption: createVersionAdoption({ knowledgeBaseId, expectedBindingRevision, retryOf }) (retryOf optional) starts adoption for an unversioned library (returns 202 + operation); query with listVersionAdoptions / getVersionAdoption, and cancelVersionAdoption (carrying expectedOperationRevision) can only cancel before version marking begins.

Key parameters and returns

Errors and boundaries

Examples by language

Main chain: create working copy → poll operation → seal → publish. Revision numbers such as expectedBindingRevision on each card are taken from the most recently read library and version objects.

// 1) create a working copy (revision numbers of the source version and library are taken from the most recent read)
const op = await kb.createVersion({
    knowledgeBaseId: base.$id,
    sourceVersionId: readyVersion.$id,
    expectedSourceVersionRevision: readyVersion.versionRevision,
    expectedBindingRevision: base.bindingRevision,
    label: 'v2-改写稿',
});
// 2) poll the operation until a terminal state succeeded / failed / cancelled (visible only after DRAFT validation succeeds)
let st = await kb.getWorkingCopyOperation({ knowledgeBaseId: base.$id, operationId: op.$id });
// Cancel: await kb.cancelWorkingCopyOperation({ knowledgeBaseId: base.$id, operationId: op.$id, expectedOperationRevision: st.operationRevision });
const draft = await kb.getVersion({ knowledgeBaseId: base.$id, versionId: st.result.versionId });
// 3) after the readiness check passes, seal as READY (idempotency keys are loaded per platform convention)
const readiness = await kb.getVersionReadiness({ knowledgeBaseId: base.$id, versionId: draft.$id });
if (readiness.sealable) {
    await kb.sealVersion({
        knowledgeBaseId: base.$id,
        versionId: draft.$id,
        expectedDefinitionRevision: readiness.definitionRevision,
        expectedVersionRevision: readiness.versionRevision,
    });
}
// 4) publish switches the currently active version (the old current version automatically becomes the rollback target)
await kb.publishVersion({
    knowledgeBaseId: base.$id,
    versionId: draft.$id,
    expectedBindingRevision: base.bindingRevision,
    expectedVersionRevision: draft.versionRevision,
});