Docs
Contents

Knowledge Base Version Management API

Before running the examples, replace <APPBASE_ENDPOINT_WITH_V1> with the intended environment API endpoint and verify that the project and credentials belong to that environment.

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

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 + pathPurpose
GET /knowledgebases/{knowledgeBaseId}/versionsList versions (status / role filters, cursor pagination) (see version management)
POST /knowledgebases/{knowledgeBaseId}/versionsCreate 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}/publishPublish READY version as current version (see version management)
POST /knowledgebases/{knowledgeBaseId}/versions/{versionId}/rollbackRoll back to the retained rollback target (see version management)
POST /knowledgebases/{knowledgeBaseId}/versions/{versionId}/sealSeal DRAFT as READY after the ready check passes (see version management)
GET /knowledgebases/{knowledgeBaseId}/versions/{versionId}/readinessReadiness summary (sealable + blocking reasons) (see version management)
GET /knowledgebases/{knowledgeBaseId}/version-adoptionsList adoption operations (see version management)
POST /knowledgebases/{knowledgeBaseId}/version-adoptionsStart 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}/cancelRequest 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-operationsList 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}/cancelRequest cancellation of working copy operation (see version management)

Endpoint details

Only the accepted operations listed above use Idempotency-Key. Publish and rollback use expectedBindingRevision for concurrency control and do not guarantee the same result on replay; if the result is unknown, read the current version and revision before deciding what to do.

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:

ParameterLocationTypeRequiredDefault/enumDescription
knowledgeBaseIdpathstringYesTarget knowledge base ID.
limitqueryintegernodefault 25Maximum number of versions per page.
cursorquerystringnodefault ""Version ID pagination cursor.
statusquerystringnoenum: draft / readyFilter by lifecycle status.
rolequerystringnoenum: current / rollback / noneFilter 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:

ParameterLocationTypeRequiredDefault/enumDescription
knowledgeBaseIdpathstringYesTarget knowledge base ID.
sourceVersionIdbodystringyesSource version ID (READY and not in the deletion flow).
expectedSourceVersionRevisionbodyintegeryesExpected source version revision number.
expectedBindingRevisionbodyintegeryesExpected knowledge base binding revision number.
labelbodystringyesWorking copy label, non-empty and unique.
descriptionbodystringnoWorking copy description.
retryOfbodystringnoID of the failed / cancelled operation being retried; the source version must match and cleanup must be complete.

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:

(
  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_ENDPOINT="${APPBASE_ENDPOINT%/}"
: "${APPBASE_PROJECT_ID:?Set APPBASE_PROJECT_ID for the target environment}"
builtin printf 'X-Appwrite-Key: %s\n' "$APPBASE_API_KEY" | curl --disable -X POST "${APPBASE_ENDPOINT}/knowledgebases/kb_enterprise_support/versions" \
  -H "X-Appwrite-Project: ${APPBASE_PROJECT_ID}" \
  --header @- \
  -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:

ParameterLocationTypeRequiredDefault/enumDescription
knowledgeBaseIdpathstringYesTarget knowledge base ID.
versionIdpathstringyesVersion ID.

Output: 200, return model KnowledgeBaseVersion.

FieldTypeDescription
$id*stringVersion ID.
$createdAt* / $updatedAt*stringCreation/update time (ISO 8601).
parentVersionIdstringDirect logical parent version ID; null for the root version.
label*stringVersion label.
descriptionstringVersion description.
status*stringLifecycle status: DRAFT / READY.
deletionState*stringDeletion status: NONE / REQUESTED / RUNNING / RETRYABLE_FAILED / COMPLETED; data access is only allowed for NONE.
role*stringRouting role: CURRENT / ROLLBACK / NONE.
versionRevision*integerVersion metadata and lifecycle revision number.
definitionRevision*integerVersion content and configuration revision number.
documentProcessingRevision*integerDocument processing configuration revision number.
readinessobjectRead-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:

ParameterLocationTypeRequiredDefault/enumDescription
knowledgeBaseIdpathstringYesTarget knowledge base ID.
versionIdpathstringYesTarget version ID.
expectedVersionRevisionbodyintegerYesExpected 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:

ParameterLocationTypeRequiredDefault/enumDescription
knowledgeBaseIdpathstringYesTarget knowledge base ID.
versionIdpathstringYesTarget READY version ID.
expectedBindingRevisionbodyintegeryesExpected knowledge base binding revision number.
expectedVersionRevisionbodyintegerYesExpected version lifecycle revision number.

Output: 200, returning model KnowledgeBaseVersion (the published version).

Call example:

(
  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_ENDPOINT="${APPBASE_ENDPOINT%/}"
: "${APPBASE_PROJECT_ID:?Set APPBASE_PROJECT_ID for the target environment}"
builtin printf 'X-Appwrite-Key: %s\n' "$APPBASE_API_KEY" | curl --disable -X POST "${APPBASE_ENDPOINT}/knowledgebases/kb_enterprise_support/versions/ver_draft_20261022/publish" \
  -H "X-Appwrite-Project: ${APPBASE_PROJECT_ID}" \
  --header @- \
  -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:

(
  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_ENDPOINT="${APPBASE_ENDPOINT%/}"
: "${APPBASE_PROJECT_ID:?Set APPBASE_PROJECT_ID for the target environment}"
builtin printf 'X-Appwrite-Key: %s\n' "$APPBASE_API_KEY" | curl --disable -X POST "${APPBASE_ENDPOINT}/knowledgebases/kb_enterprise_support/versions/ver_initial_ready_01/rollback" \
  -H "X-Appwrite-Project: ${APPBASE_PROJECT_ID}" \
  --header @- \
  -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:

ParameterLocationTypeRequiredDefault/enumDescription
knowledgeBaseIdpathstringYesTarget knowledge base ID.
versionIdpathstringYesTarget DRAFT version ID.
expectedDefinitionRevisionbodyintegerYesExpected version content/configuration revision number.
expectedVersionRevisionbodyintegerYesExpected version lifecycle revision number.

Output: 200, returning model KnowledgeBaseVersion (the sealed READY version).

Call example:

(
  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_ENDPOINT="${APPBASE_ENDPOINT%/}"
: "${APPBASE_PROJECT_ID:?Set APPBASE_PROJECT_ID for the target environment}"
builtin printf 'X-Appwrite-Key: %s\n' "$APPBASE_API_KEY" | curl --disable -X POST "${APPBASE_ENDPOINT}/knowledgebases/kb_enterprise_support/versions/ver_draft_20261022/seal" \
  -H "X-Appwrite-Project: ${APPBASE_PROJECT_ID}" \
  --header @- \
  -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:

ParameterLocationTypeRequiredDefault/enumDescription
knowledgeBaseIdpathstringYesTarget knowledge base ID.
versionIdpathstringYesTarget version ID.

Output: 200, return model KnowledgeBaseVersionReadiness.

FieldTypeDescription
versionId*stringVersion ID.
status*stringLifecycle status: DRAFT / READY.
versionRevision*integerCurrent version lifecycle revision number.
definitionRevision*integerCurrent version content/configuration revision number.
documentProcessingRevision*integerCurrent document processing revision number.
sealable*booleanWhether there are no readiness blockers (can be set to READY).
summary*objectReadiness counts (excluding document content and provider references).
blockers*objectStable blocking codes and counts (e.g. active_tasks, documents_not_ready, documents_rebuild_required, capabilities_stale, capabilities_failed, wiki_conflicts).

Call example:

(
  set +x
  set -o pipefail
  : "${APPBASE_API_KEY:?Set APPBASE_API_KEY}"
builtin printf 'X-Appwrite-Key: %s\n' "$APPBASE_API_KEY" | curl --disable -X GET "<APPBASE_ENDPOINT_WITH_V1>/knowledgebases/kb_enterprise_support/versions/ver_draft_20261022/readiness" \
  -H "X-Appwrite-Project: <APPBASE_PROJECT_ID>" \
  --header @-

)

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:

ParameterLocationTypeRequiredDefault/enumDescription
knowledgeBaseIdpathstringYesTarget knowledge base ID.
limitqueryintegerNoDefault 25Maximum number of operations per page.
cursorquerystringNoDefault ""Pagination cursor by operation ID.
statusquerystringNoFilter 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:

ParameterLocationTypeRequiredDefault/enumDescription
knowledgeBaseIdpathstringYesTarget knowledge base ID (must not have versioning enabled).
expectedBindingRevisionbodyintegeryesExpected knowledge base binding revision number.
retryOfbodystringNoID 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:

(
  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_ENDPOINT="${APPBASE_ENDPOINT%/}"
: "${APPBASE_PROJECT_ID:?Set APPBASE_PROJECT_ID for the target environment}"
builtin printf 'X-Appwrite-Key: %s\n' "$APPBASE_API_KEY" | curl --disable -X POST "${APPBASE_ENDPOINT}/knowledgebases/kb_enterprise_support/version-adoptions" \
  -H "X-Appwrite-Project: ${APPBASE_PROJECT_ID}" \
  --header @- \
  -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:

ParameterLocationTypeRequiredDefault/enumDescription
knowledgeBaseIdpathstringYesTarget knowledge base ID.
adoptionIdpathstringYesAdoption 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:

ParameterLocationTypeRequiredDefault/enumDescription
knowledgeBaseIdpathstringYesTarget knowledge base ID.
adoptionIdpathstringYesAdoption operation ID.
expectedOperationRevisionbodyintegerYesExpected 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:

ParameterLocationTypeRequiredDefault/enumDescription
knowledgeBaseIdpathstringYesTarget knowledge base ID (must match the knowledge base the deletion operation belongs to).
operationIdpathstringYesDeletion operation ID.

Output: 200, return model KnowledgeBaseVersionDeleteOperation.

GET /v1/knowledgebases/{knowledgeBaseId}/working-copy-operations

Lists the working-copy operations of this knowledge base.

Input:

ParameterLocationTypeRequiredDefault/enumDescription
knowledgeBaseIdpathstringYesTarget knowledge base ID.
limitqueryintegerNoDefault 25Maximum number of operations per page.
cursorquerystringNoDefault ""Pagination cursor by operation ID.
statusquerystringNoFilter 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:

ParameterLocationTypeRequiredDefault/enumDescription
knowledgeBaseIdpathstringYesTarget knowledge base ID.
operationIdpathstringYesWorking-copy operation ID.

Output: 200, return model KnowledgeBaseWorkingCopyOperation.

POST /v1/knowledgebases/{knowledgeBaseId}/working-copy-operations/{operationId}/cancel

Cancellation can be requested only in queued, preflight, copying, or validating. Acceptance enters cancelling; continue polling the operation and cleanup result. Failed cleanup dispatch may require background reconciliation. Acceptance does not prove cleanup has completed.

Input:

ParameterLocationTypeRequiredDefault/enumDescription
knowledgeBaseIdpathstringYesTarget knowledge base ID.
operationIdpathstringYesWorking-copy operation ID.
expectedOperationRevisionbodyintegerYesExpected working-copy operation revision number.

Output: 200, returning model KnowledgeBaseWorkingCopyOperation (status=cancelling).

Errors and boundaries

Correspondence with the Server SDK

service.methodEndpoint
KnowledgeBases.listVersionsGET /knowledgebases/{id}/versions
KnowledgeBases.createVersionPOST /knowledgebases/{id}/versions
KnowledgeBases.getVersionGET .../versions/{versionId}
KnowledgeBases.deleteVersionDELETE .../versions/{versionId}
KnowledgeBases.publishVersionPOST .../versions/{versionId}/publish
KnowledgeBases.rollbackVersionPOST .../versions/{versionId}/rollback
KnowledgeBases.sealVersionPOST .../versions/{versionId}/seal
KnowledgeBases.getVersionReadinessGET .../versions/{versionId}/readiness
KnowledgeBases.listVersionAdoptions / createVersionAdoptionGET|POST .../version-adoptions
KnowledgeBases.getVersionAdoption / cancelVersionAdoptionGET .../version-adoptions/{adoptionId}、POST .../{adoptionId}/cancel
KnowledgeBases.getVersionDeleteOperationGET .../version-delete-operations/{operationId}
KnowledgeBases.listWorkingCopyOperations / getWorkingCopyOperation / cancelWorkingCopyOperationGET .../working-copy-operations、GET|POST .../working-copy-operations/{operationId}(/cancel)