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. Before retrying, confirm that the source version matches and cleanup of the original operation has completed.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 / cancelling / succeeded / failed / cancelled),KnowledgeBaseVersionDeleteOperation(queued/running/retryable_failed/completed); the adoption operation model name follows the spec (KnowledgeBaseVersionAdoptionOperationterminology); readinessKnowledgeBaseVersionReadiness(sealable+summary+blockers).Working copies can be cancelled only in
queued,preflight,copying, orvalidating. An accepted request enterscancelling; poll the terminal state and wait for cleanup.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
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.
- Node.js(Server)
- Java
- Python
- Go
- REST(curl)
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);Query this operation. Only on
succeeded, obtainversionId/version_idfromresult.versionId. Stop onfailedorcancelled; 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);Check version readiness and seal only when
sealableis true. For REST, query the version/readinessfirst 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);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);Create a working copy.
client.addHeader("Idempotency-Key", "<CREATE_KEY>");
var op = kb.createVersion(base.getId(), ready.getId(), ready.getVersionRevision(),
base.getBindingRevision(), "draft-v2", null, null);
System.out.println(op.getId());Query this operation. Only on
succeeded, obtainversionId/version_idfromresult.versionId. Stop onfailedorcancelled; query again later for other states.
var st = kb.getWorkingCopyOperation(base.getId(), op.getId());
if (!"succeeded".equals(st.getStatus().getValue()))
throw new IllegalStateException("Working copy is " + st.getStatus());
if (!(st.getResult() instanceof java.util.Map<?, ?>))
throw new IllegalStateException("Operation did not return a result");
var result = (java.util.Map<?, ?>) st.getResult();
var value = result.get("versionId");
if (!(value instanceof String) || ((String) value).isEmpty())
throw new IllegalStateException("Operation did not return a version ID");
var versionId = (String) value;
System.out.println(versionId);Check version readiness and seal only when
sealableis true. For REST, query the version/readinessfirst and replace the example revision numbers with the response.
var readiness = kb.getVersionReadiness(base.getId(), versionId);
if (!readiness.getSealable()) throw new IllegalStateException("Version is not ready to seal");
client.addHeader("Idempotency-Key", "<SEAL_KEY>");
var sealed = kb.sealVersion(base.getId(), versionId,
readiness.getDefinitionRevision(), readiness.getVersionRevision());
System.out.println(sealed.getId() + " " + sealed.getVersionRevision());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.
var latest = kb.get(base.getId(), null);
var published = kb.publishVersion(base.getId(), sealed.getId(),
latest.getBindingRevision(), sealed.getVersionRevision());
System.out.println(published.getId());Create a working copy.
client.add_header('Idempotency-Key', '<CREATE_KEY>')
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='draft-v2')
print(op.id)Query this operation. Only on
succeeded, obtainversionId/version_idfromresult.versionId. Stop onfailedorcancelled; query again later for other states.
st = kb.get_working_copy_operation(knowledge_base_id=base.id, operation_id=op.id)
if st.status.value != 'succeeded':
raise RuntimeError(f'Working copy is {st.status.value}; check again or inspect the failure')
if not isinstance(st.result, dict) or not isinstance(st.result.get('versionId'), str) or not st.result['versionId']:
raise RuntimeError('Operation did not return a version ID')
version_id = st.result['versionId']
print(version_id)Check version readiness and seal only when
sealableis true. For REST, query the version/readinessfirst and replace the example revision numbers with the response.
readiness = kb.get_version_readiness(knowledge_base_id=base.id, version_id=version_id)
if not readiness.sealable:
raise RuntimeError('Version is not ready to seal')
client.add_header('Idempotency-Key', '<SEAL_KEY>')
sealed = kb.seal_version(knowledge_base_id=base.id, version_id=version_id,
expected_definition_revision=readiness.definitionrevision,
expected_version_revision=readiness.versionrevision)
print(sealed.id, sealed.versionrevision)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.
latest = kb.get(knowledge_base_id=base.id)
published = kb.publish_version(knowledge_base_id=base.id, version_id=sealed.id,
expected_binding_revision=latest.bindingrevision, expected_version_revision=sealed.versionrevision)
print(published.id)Create a working copy.
client.AddHeader("Idempotency-Key", "<CREATE_KEY>")
op, err := kb.CreateVersion(base.Id, ready.Id, ready.VersionRevision, base.BindingRevision, "draft-v2")
if err != nil { return err }
fmt.Println(op.Id)Query this operation. Only on
succeeded, obtainversionId/version_idfromresult.versionId. Stop onfailedorcancelled; query again later for other states.
st, err := kb.GetWorkingCopyOperation(base.Id, op.Id)
if err != nil { return err }
if st.Status != "succeeded" { return fmt.Errorf("working copy is %s", st.Status) }
result, ok := st.Result.(map[string]interface{})
if !ok { return fmt.Errorf("operation did not return a result") }
versionId, ok := result["versionId"].(string)
if !ok || versionId == "" { return fmt.Errorf("operation did not return a version ID") }
fmt.Println(versionId)Check version readiness and seal only when
sealableis true. For REST, query the version/readinessfirst and replace the example revision numbers with the response.
readiness, err := kb.GetVersionReadiness(base.Id, versionId)
if err != nil { return err }
if !readiness.Sealable { return fmt.Errorf("version is not ready to seal") }
client.AddHeader("Idempotency-Key", "<SEAL_KEY>")
sealed, err := kb.SealVersion(base.Id, versionId, readiness.DefinitionRevision, readiness.VersionRevision)
if err != nil { return err }
fmt.Println(sealed.Id, sealed.VersionRevision)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.
latest, err := kb.Get(base.Id)
if err != nil { return err }
published, err := kb.PublishVersion(base.Id, sealed.Id, latest.BindingRevision, sealed.VersionRevision)
if err != nil { return err }
fmt.Println(published.Id)Create a working copy.
(
set +x
set -o pipefail
: "${APPBASE_API_KEY:?Set APPBASE_API_KEY}"
: "${APPBASE_ENDPOINT:?Set APPBASE_ENDPOINT to the target API endpoint including /v1}"
: "${APPBASE_PROJECT_ID:?Set APPBASE_PROJECT_ID}"
: "${APPBASE_API_KEY:?Set APPBASE_API_KEY}"
: "${KB_ID:?Set KB_ID}"
builtin printf 'X-Appwrite-Key: %s\n' "${APPBASE_API_KEY:?Set APPBASE_API_KEY}" | curl --disable --header @- -fsS -X POST "${APPBASE_ENDPOINT%/}/knowledgebases/${KB_ID}/versions" \
-H "X-Appwrite-Project: $APPBASE_PROJECT_ID" \
-H 'Content-Type: application/json' -H 'Idempotency-Key: <CREATE_KEY>' \
-d '{"sourceVersionId":"<SOURCE_VERSION_ID>","expectedSourceVersionRevision":7,"expectedBindingRevision":3,"label":"draft-v2"}'
)Query this operation. Only on
succeeded, obtainversionId/version_idfromresult.versionId. Stop onfailedorcancelled; query again later for other states.
(
set +x
set -o pipefail
: "${APPBASE_API_KEY:?Set APPBASE_API_KEY}"
: "${APPBASE_ENDPOINT:?Set APPBASE_ENDPOINT to the target API endpoint including /v1}"
: "${APPBASE_PROJECT_ID:?Set APPBASE_PROJECT_ID}"
: "${APPBASE_API_KEY:?Set APPBASE_API_KEY}"
: "${KB_ID:?Set KB_ID}"
: "${OPERATION_ID:?Set OPERATION_ID from the create response}"
builtin printf 'X-Appwrite-Key: %s\n' "${APPBASE_API_KEY:?Set APPBASE_API_KEY}" | curl --disable --header @- -fsS "${APPBASE_ENDPOINT%/}/knowledgebases/${KB_ID}/working-copy-operations/${OPERATION_ID}" \
-H "X-Appwrite-Project: $APPBASE_PROJECT_ID"
)Check version readiness and seal only when
sealableis true. For REST, query the version/readinessfirst and replace the example revision numbers with the response.
(
set +x
set -o pipefail
: "${APPBASE_API_KEY:?Set APPBASE_API_KEY}"
: "${APPBASE_ENDPOINT:?Set APPBASE_ENDPOINT to the target API endpoint including /v1}"
: "${APPBASE_PROJECT_ID:?Set APPBASE_PROJECT_ID}"
: "${APPBASE_API_KEY:?Set APPBASE_API_KEY}"
: "${KB_ID:?Set KB_ID}"
: "${VERSION_ID:?Set VERSION_ID from the succeeded operation}"
builtin printf 'X-Appwrite-Key: %s\n' "${APPBASE_API_KEY:?Set APPBASE_API_KEY}" | curl --disable --header @- -fsS "${APPBASE_ENDPOINT%/}/knowledgebases/${KB_ID}/versions/${VERSION_ID}/readiness" \
-H "X-Appwrite-Project: $APPBASE_PROJECT_ID"
)After checking readiness, seal with the returned revisions:
(
set +x
set -o pipefail
: "${APPBASE_API_KEY:?Set APPBASE_API_KEY}"
: "${APPBASE_ENDPOINT:?Set APPBASE_ENDPOINT to the target API endpoint including /v1}"
: "${APPBASE_PROJECT_ID:?Set APPBASE_PROJECT_ID}"
: "${APPBASE_API_KEY:?Set APPBASE_API_KEY}"
: "${KB_ID:?Set KB_ID}"
: "${VERSION_ID:?Set VERSION_ID from the succeeded operation}"
builtin printf 'X-Appwrite-Key: %s\n' "${APPBASE_API_KEY:?Set APPBASE_API_KEY}" | curl --disable --header @- -fsS -X POST "${APPBASE_ENDPOINT%/}/knowledgebases/${KB_ID}/versions/${VERSION_ID}/seal" \
-H "X-Appwrite-Project: $APPBASE_PROJECT_ID" \
-H 'Content-Type: application/json' -H 'Idempotency-Key: <SEAL_KEY>' \
-d '{"expectedDefinitionRevision":5,"expectedVersionRevision":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.
(
set +x
set -o pipefail
: "${APPBASE_API_KEY:?Set APPBASE_API_KEY}"
: "${APPBASE_ENDPOINT:?Set APPBASE_ENDPOINT to the target API endpoint including /v1}"
: "${APPBASE_PROJECT_ID:?Set APPBASE_PROJECT_ID}"
: "${APPBASE_API_KEY:?Set APPBASE_API_KEY}"
: "${KB_ID:?Set KB_ID}"
: "${VERSION_ID:?Set VERSION_ID from the sealed version}"
builtin printf 'X-Appwrite-Key: %s\n' "${APPBASE_API_KEY:?Set APPBASE_API_KEY}" | curl --disable --header @- -fsS -X POST "${APPBASE_ENDPOINT%/}/knowledgebases/${KB_ID}/versions/${VERSION_ID}/publish" \
-H "X-Appwrite-Project: $APPBASE_PROJECT_ID" \
-H 'Content-Type: application/json' \
-d '{"expectedBindingRevision":3,"expectedVersionRevision":2}'
)