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

These code blocks are separate steps. Initialize client and kb, then read the target knowledge base base and source READY version ready (readyVersion in Node.js). For REST, APPBASE_ENDPOINT includes /v1; replace placeholders and revisions, and confirm project and credentials belong to that environment. Creation and sealing use different stable idempotency keys; SDK client headers persist on later requests.

  1. Create a working copy.

client.addHeader('Idempotency-Key', '<CREATE_KEY>');
const op = await kb.createVersion({ knowledgeBaseId: base.$id,
  sourceVersionId: readyVersion.$id, expectedSourceVersionRevision: readyVersion.versionRevision,
  expectedBindingRevision: base.bindingRevision, label: 'draft-v2' });
console.log(op.$id);
  1. Query this operation. Only on succeeded, obtain versionId / version_id from result.versionId. Stop on failed or cancelled; query again later for other states.

const st = await kb.getWorkingCopyOperation({ knowledgeBaseId: base.$id, operationId: op.$id });
if (st.status !== 'succeeded') throw new Error(`Working copy is ${st.status}; check again or inspect the failure`);
const result = st.result as { versionId?: unknown };
if (typeof result?.versionId !== 'string' || !result.versionId) throw new Error('Operation did not return a version ID');
const versionId = result.versionId;
console.log(versionId);
  1. Check version readiness and seal only when sealable is true. For REST, query the version /readiness first and replace the example revision numbers with the response.

const readiness = await kb.getVersionReadiness({ knowledgeBaseId: base.$id, versionId });
if (!readiness.sealable) throw new Error('Version is not ready to seal');
client.addHeader('Idempotency-Key', '<SEAL_KEY>');
const sealed = await kb.sealVersion({ knowledgeBaseId: base.$id, versionId,
  expectedDefinitionRevision: readiness.definitionRevision,
  expectedVersionRevision: readiness.versionRevision });
console.log(sealed.$id, sealed.versionRevision);
  1. Publish only after sealing succeeds and you intend to switch. For REST, read the latest binding and sealed version revisions and replace the example numbers.

const latest = await kb.get({ knowledgeBaseId: base.$id });
const published = await kb.publishVersion({ knowledgeBaseId: base.$id, versionId: sealed.$id,
  expectedBindingRevision: latest.bindingRevision, expectedVersionRevision: sealed.versionRevision });
console.log(published.$id);