Document Versions - Knowledge Stack

Every document has one or more versions. Versions are numbered starting from 0 (v0, v1, v2, …). Each version has an independent ingestion pipeline state and its own sections and chunks. Only the document’s active version is used by default for search and retrieval.

Pipeline state

After ingestion is triggered, the pipeline_state field in system_metadata tracks progress:

`PipelineStatus`	Meaning
`pending`	Ingestion workflow has been queued but not started
`processing`	Ingestion is actively running
`completed`	Ingestion finished successfully
`failed`	Ingestion failed; see `pipeline_state.error` for details
`cancelled`	Ingestion was cancelled

Version actions

The DocumentVersionAction enum currently supports one action:

Value	Description
`reembed`	Re-run vector embedding for all chunks in this version

Create version

POST https://api-staging.knowledgestack.ai/v1/documents/{document_id}/versions Create a new empty version for a document. The version number is automatically incremented. Use this when you want to populate content manually rather than through file ingestion.

Path parameters

document_id

string (uuid)

required

The document to create a new version for.

Response `200`

Returns a DocumentVersionResponse.

string (uuid)

Document version ID.

path_part_id

string (uuid)

Underlying path part ID.

version

integer

Version number (0, 1, 2, …).

name

string

Auto-generated name (e.g. v0, v1).

parent_path_id

string (uuid) | null

The parent document’s path part ID.

materialized_path

string

Full path from root.

system_managed

boolean

Whether this version is system-managed.

tenant_id

string (uuid)

Owning tenant.

created_at

string (datetime)

Creation timestamp (ISO 8601).

updated_at

string (datetime)

Last update timestamp (ISO 8601).

source_url

string | null

Time-limited URL to download the source document. null until ingestion completes.

plaintext_url

string | null

Time-limited URL to download a plain-text export of the document. null until ingestion completes.

system_metadata

DocumentVersionMetadata

Pipeline state, artifact URLs, and document statistics.

Example

curl -X POST https://api-staging.knowledgestack.ai/v1/documents/<document-id>/versions \
  -H "Authorization: Bearer <your-api-key>"

List versions

GET https://api-staging.knowledgestack.ai/v1/document_versions List all versions for a document.

Query parameters

document_id

string (uuid)

The document whose versions to list.

limit

integer

Page size.

offset

integer

Pagination offset.

Response `200`

Returns a paginated list of DocumentVersionResponse objects.

Example

curl "https://api-staging.knowledgestack.ai/v1/document_versions?document_id=<document-id>&limit=10" \
  -H "Authorization: Bearer <your-api-key>"

Get version

GET https://api-staging.knowledgestack.ai/v1/document_versions/{version_id} Get a single document version by ID.

Path parameters

version_id

string (uuid)

required

The document version ID.

Response `200`

Returns a DocumentVersionResponse. See Create version for field descriptions.

Example

curl "https://api-staging.knowledgestack.ai/v1/document_versions/<version-id>" \
  -H "Authorization: Bearer <your-api-key>"

Delete version

DELETE https://api-staging.knowledgestack.ai/v1/document_versions/{version_id} Delete a document version and all of its sections and chunks.

You cannot delete the document’s active version. To delete the active version, first promote a different version using PATCH /v1/documents/{document_id}.

Path parameters

version_id

string (uuid)

required

The version ID to delete.

Response `200`

Returns an empty {} on success.

Example

curl -X DELETE https://api-staging.knowledgestack.ai/v1/document_versions/<version-id> \
  -H "Authorization: Bearer <your-api-key>"

Version action

POST https://api-staging.knowledgestack.ai/v1/document_versions/{version_id} Perform an action on a document version.

Path parameters

version_id

string (uuid)

required

The version to act on.

Query parameters

action

string

required

The action to perform. Currently supported: reembed.

Response `200`

Returns a DocumentVersionActionResponse.

version_id

string (uuid)

The version ID the action was applied to.

action

string

The action performed.

workflow_id

string

Workflow ID for tracking the background job.

Example

curl -X POST "https://api-staging.knowledgestack.ai/v1/document_versions/<version-id>?action=reembed" \
  -H "Authorization: Bearer <your-api-key>"

{
  "version_id": "b2c3d4e5-0000-0000-0000-000000000002",
  "action": "reembed",
  "workflow_id": "reembed-xyz789"
}

Update version metadata

PATCH https://api-staging.knowledgestack.ai/v1/document_versions/{version_id}/metadata Partially update the system_metadata of a document version. Only the provided fields are merged into the existing metadata — omitted fields are left unchanged.

You typically do not need to call this endpoint directly — the ingestion pipeline updates version metadata automatically. Use it when you need to manually correct document statistics or pipeline state.

Path parameters

version_id

string (uuid)

required

The version ID to update.

Request body (`DocumentVersionMetadataUpdate`)

All fields are optional. Provide only the fields you want to update.

pipeline_state

PipelineState

Updated pipeline execution state object.

total_pages

integer

Total number of pages in the document.

total_sections

integer

Total number of sections created by ingestion.

total_chunks

integer

Total number of chunks created by ingestion.

hash

string

Base64-encoded SHA-256 hash of the source file.

Response `200`

Returns the updated DocumentVersionResponse.

Example

curl -X PATCH https://api-staging.knowledgestack.ai/v1/document_versions/<version-id>/metadata \
  -H "Authorization: Bearer <your-api-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "total_pages": 42,
    "total_chunks": 187
  }'

Get version contents

GET https://api-staging.knowledgestack.ai/v1/document_versions/{version_id}/contents Get the top-level contents of a document version as a paginated list of sections and chunks. Each item is a discriminated union of SectionContentItem or ChunkContentItem, identified by the part_type field.

Path parameters

version_id

string (uuid)

required

The version whose contents to retrieve.

Query parameters

section_id

string (uuid)

Restrict contents to a specific section.

content_type

string

Filter by content type (SECTION or CHUNK).

limit

integer

Page size.

offset

integer

Pagination offset.

Response `200`

Returns a paginated list of SectionContentItem | ChunkContentItem discriminated by part_type.

Example

curl "https://api-staging.knowledgestack.ai/v1/document_versions/<version-id>/contents?limit=50" \
  -H "Authorization: Bearer <your-api-key>"

Clear version contents

DELETE https://api-staging.knowledgestack.ai/v1/document_versions/{version_id}/contents Delete all top-level sections and chunks belonging to a document version. The version record itself is preserved.

This permanently removes all content under the version. It is typically used before re-ingesting a version to start fresh.

Path parameters

version_id

string (uuid)

required

The version whose contents to clear.

Response `200`

Returns a ClearVersionContentsResponse.

deleted

integer

Number of top-level children (sections or chunks) deleted.

Example

curl -X DELETE https://api-staging.knowledgestack.ai/v1/document_versions/<version-id>/contents \
  -H "Authorization: Bearer <your-api-key>"

{
  "deleted": 24
}

Authentication

Knowledge

Search & AI

Organization

Workspace

Workflows

​Pipeline state

​Version actions

​Create version

​Path parameters

​Response 200

​Example

​List versions

​Query parameters

​Response 200

​Example

​Get version

​Path parameters

​Response 200

​Example

​Delete version

​Path parameters

​Response 200

​Example

​Version action

​Path parameters

​Query parameters

​Response 200

​Example

​Update version metadata

​Path parameters

​Request body (DocumentVersionMetadataUpdate)

​Response 200

​Example

​Get version contents

​Path parameters

​Query parameters

​Response 200

​Example

​Clear version contents

​Path parameters

​Response 200

​Example

Pipeline state

Version actions

Create version

Path parameters

Response `200`

Example

List versions

Query parameters

Response `200`

Example

Get version

Path parameters

Response `200`

Example

Delete version

Path parameters

Response `200`

Example

Version action

Path parameters

Query parameters

Response `200`

Example

Update version metadata

Path parameters

Request body (`DocumentVersionMetadataUpdate`)

Response `200`

Example

Get version contents

Path parameters

Query parameters

Response `200`

Example

Clear version contents

Path parameters

Response `200`

Example