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
List and read:
listVersions(knowledgeBaseId, limit, cursor, status, role)(limit,cursor,status, androleall optional) paginates versions (statusfiltersdraft/ready,rolefilterscurrent/rollback/none);getVersionreads a single version; the list does not include working copies still being materialized.Create a working copy:
createVersion({ knowledgeBaseId, sourceVersionId, expectedSourceVersionRevision, expectedBindingRevision, label, description, retryOf })(descriptionandretryOfboth optional) returnsKnowledgeBaseWorkingCopyOperation—the DRAFT is invisible until validation succeeds; poll withlistWorkingCopyOperations/getWorkingCopyOperation, and request cancellation withcancelWorkingCopyOperation.Readiness check and seal:
getVersionReadinessreturnssealableand blocking reasons;sealVersion(carryingexpectedDefinitionRevision+expectedVersionRevision+ idempotency key) sets the DRAFT to READY and does not publish automatically.Publish and rollback:
publishVersion/rollbackVersion(both carryingexpectedBindingRevision+expectedVersionRevision) atomically switchcurrentVersionId/rollbackVersionIdand returnKnowledgeBaseVersion.Delete:
deleteVersion({ knowledgeBaseId, versionId, expectedVersionRevision })initiates irreversible asynchronous cleanup and returnsKnowledgeBaseVersionDeleteOperation; pollgetVersionDeleteOperationuntilcompleted. Versions with theCURRENT/ROLLBACKrole cannot be deleted.Adoption:
createVersionAdoption({ knowledgeBaseId, expectedBindingRevision, retryOf })(retryOfoptional) starts adoption for an unversioned library (returns 202 + operation); query withlistVersionAdoptions/getVersionAdoption, andcancelVersionAdoption(carryingexpectedOperationRevision) can only cancel before version marking begins.
Key parameters and returns
createVersionrequiressourceVersionId(READY anddeletionState=NONE),expectedSourceVersionRevision,expectedBindingRevision, and a non-emptylabel; optionaldescriptionandretryOf(pointing to the original failed/canceled operation). Replaying with the same idempotency key returns the original operation; reusing the key with different input fails.Return models: version read
KnowledgeBaseVersion(status:DRAFT/READY;role:CURRENT/ROLLBACK/NONE;deletionState; three revision numbersversionRevision/definitionRevision/documentProcessingRevision) and listKnowledgeBaseVersionList; operationsKnowledgeBaseWorkingCopyOperation(status:queued → preflight → copying → validating → reconciling → succeeded | failed | cancelled),KnowledgeBaseVersionDeleteOperation(queued/running/retryable_failed/completed); the adoption operation model name follows the spec (KnowledgeBaseVersionAdoptionOperationterminology); readinessKnowledgeBaseVersionReadiness(sealable+summary+blockers).Idempotency keys: asynchronous or irreversible calls such as working copy creation, seal, delete, and adoption create/cancel require a stable
Idempotency-Key(Server SDK method surfaces for each language are loaded per platform convention; REST passes the header directly).publishVersion/rollbackVersiondo not create any ingestion, sync, or index tasks; after publishing, the old current version automatically becomes the sole rollback target.
Errors and boundaries
A mismatch of the expected revision number (
expectedBindingRevision/expectedVersionRevision/expectedDefinitionRevision/expectedOperationRevisiondrift) or concurrent state change returnsversion_concurrently_modified(409): refresh to read the latest state and then decide whether to retry.sealVersionrequires all readiness checks to pass: active tasks, not-ready/pending-rebuild documents, stale/failed enabled index capabilities, and Wiki conflicts all reject the transition.publishVersiononly accepts READY, non-deleted versions;rollbackVersioncan only roll back to theROLLBACKtarget retained by Binding, and cannot specify an arbitrary historical version.deleteVersionis irreversible: after acceptance, access is revoked immediately and cannot be undone;retryable_failedrequires resubmitting DELETE with a new idempotency key to requeue. Onlyrole=NONEanddeletionState=NONEDRAFT/READY versions can be deleted.Adoption only applies to unversioned Shared V2 knowledge bases; once the non-cancelable phase begins,
cancelVersionAdoptionfails.Reusing an idempotency key with different input returns
idempotency_key_reused(409); a duplicatelabelreturnsversion_label_already_exists.
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.
- Node.js (Server)
- Java
- Python
- Go
- REST (curl)
// 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,
});// Method names identical to Node (camelCase); parameters are positional; returns strongly typed models
var op = kb.createVersion(base.getId(), ready.getId(),
ready.getVersionRevision(), base.getBindingRevision(), "v2-改写稿", null, null);
// 2) Poll the operation until the final state succeeded / failed / cancelled
var st = kb.getWorkingCopyOperation(base.getId(), op.getId());
var draft = kb.getVersion(base.getId(),
((java.util.Map<?, ?>) st.getResult()).get("versionId").toString()); // result is a wide type
var readiness = kb.getVersionReadiness(base.getId(), draft.getId());
if (readiness.getSealable()) {
kb.sealVersion(base.getId(), draft.getId(),
readiness.getDefinitionRevision(), readiness.getVersionRevision());
}
// 4) publish switches the currently active version
kb.publishVersion(base.getId(), draft.getId(),
base.getBindingRevision(), draft.getVersionRevision());# Method names are snake_case; keyword arguments match REST fields
op = kb.create_version(
knowledge_base_id=base['$id'],
source_version_id=ready['$id'],
expected_source_version_revision=ready['versionRevision'],
expected_binding_revision=base['bindingRevision'],
label='v2-改写稿')
# 2) Poll the operation until the final state succeeded / failed / cancelled
st = kb.get_working_copy_operation(knowledge_base_id=base['$id'], operation_id=op['$id'])
draft = kb.get_version(knowledge_base_id=base['$id'], version_id=st['result']['versionId'])
# 3) after the readiness check passes, seal as READY
readiness = kb.get_version_readiness(knowledge_base_id=base['$id'], version_id=draft['$id'])
if readiness['sealable']:
kb.seal_version(knowledge_base_id=base['$id'], version_id=draft['$id'],
expected_definition_revision=readiness['definitionRevision'],
expected_version_revision=readiness['versionRevision'])
# 4) publish switches the currently active version
kb.publish_version(knowledge_base_id=base['$id'], version_id=draft['$id'],
expected_binding_revision=base['bindingRevision'],
expected_version_revision=draft['versionRevision'])// Method names in PascalCase; optional parameters via WithCreateVersion* options
op, err := kb.CreateVersion(base.Id, ready.Id,
ready.VersionRevision, base.BindingRevision, "v2-改写稿")
// 2) Poll the operation until the final state succeeded / failed / cancelled
st, err := kb.GetWorkingCopyOperation(base.Id, op.Id)
draft, err := kb.GetVersion(base.Id, st.Result.(map[string]interface{})["versionId"].(string))
// 3) after the readiness check passes, seal as READY
readiness, err := kb.GetVersionReadiness(base.Id, draft.Id)
if readiness.Sealable {
_, err = kb.SealVersion(base.Id, draft.Id,
readiness.DefinitionRevision, readiness.VersionRevision)
}
// 4) publish switches the currently active version
_, err = kb.PublishVersion(base.Id, draft.Id,
base.BindingRevision, draft.VersionRevision)# 1) Create a working copy: stable Idempotency-Key, 202 returns the operation
curl -sS -X POST "$APPBASE_ENDPOINT/knowledgebases/$KB_ID/versions" \
-H 'Content-Type: application/json' -H "Idempotency-Key: wc-20260920-01" \
-H "X-Appwrite-Project: $APPBASE_PROJECT_ID" -H "X-Appwrite-Key: $APPBASE_API_KEY" \
-d '{"sourceVersionId":"<SOURCE_VERSION_ID>","expectedSourceVersionRevision":7,"expectedBindingRevision":3,"label":"v2-改写稿"}'
# 2) Poll the operation: GET .../working-copy-operations/{operationId}; cancel: POST .../working-copy-operations/{operationId}/cancel (body expectedOperationRevision)
# After successful validation, read DRAFT: GET .../versions/{versionId}
# 3) readiness check: GET .../versions/{versionId}/readiness; sealing requires an idempotency key
curl -sS -X POST "$APPBASE_ENDPOINT/knowledgebases/$KB_ID/versions/$VERSION_ID/seal" \
-H 'Content-Type: application/json' -H "Idempotency-Key: seal-20260920-01" \
-H "X-Appwrite-Project: $APPBASE_PROJECT_ID" -H "X-Appwrite-Key: $APPBASE_API_KEY" \
-d '{"expectedDefinitionRevision":5,"expectedVersionRevision":1}'
# 4) publish switches the currently active version
curl -sS -X POST "$APPBASE_ENDPOINT/knowledgebases/$KB_ID/versions/$VERSION_ID/publish" \
-H 'Content-Type: application/json' \
-H "X-Appwrite-Project: $APPBASE_PROJECT_ID" -H "X-Appwrite-Key: $APPBASE_API_KEY" \
-d '{"expectedBindingRevision":3,"expectedVersionRevision":2}'