Documents

A document is a named container within a folder that holds one or more document versions. Every document has an active version — the version used for search and retrieval unless otherwise specified.

Document types

The DocumentType enum describes the file format:

Value	Description
`PDF`	PDF file
`DOCX`	Microsoft Word document
`PLAINTEXT`	Plain text file
`IMAGE`	Image file
`XLSX`	Microsoft Excel spreadsheet
`CSV`	Comma-separated values
`PPTX`	Microsoft PowerPoint presentation
`UNKNOWN`	Unrecognized or unspecified format

Document origins

The DocumentOrigin enum describes where the document came from:

Value	Description
`SOURCE`	Uploaded directly by a user or integration
`GENERATED`	Produced by the system (e.g. an AI-generated output)

Ingest document

POST https://api-staging.knowledgestack.ai/v1/documents/ingest Upload a file, create a document and its initial version (v0), and trigger the ingestion pipeline. This is the primary way to add content to Knowledge Stack. The request must be multipart/form-data.

Request body (multipart)

file

required

The file to upload.

path_part_id

string (uuid)

required

path_part_id of the parent folder. Must reference a FOLDER type path part.

name

string

Document name. Defaults to the uploaded filename if omitted.

ingestion_mode

string

Ingestion pipeline mode. One of:

high_accuracy — default for PDF; uses high-quality conversion
standard — default for DOCX, XLSX, PPTX, PLAINTEXT
single_chunk — default for IMAGE and CSV; treats the entire file as one chunk

Auto-resolved based on file type when omitted.

chunk_type

string

Force a specific chunk type (TABLE, IMAGE, or HTML). Only valid with single_chunk mode.

secondary_taxonomy

string

Force secondary taxonomy (e.g. picture, flowchart). Only valid with single_chunk mode and chunk_type=IMAGE.

page_dpi

integer

DPI for PDF page screenshots. Range 36–216. Defaults to 72.

Response `201`

Returns an IngestDocumentResponse.

document_id

string (uuid)

ID of the created document.

document_version_id

string (uuid)

ID of the created document version (v0).

workflow_id

string

Workflow ID for tracking ingestion progress.

Example

curl -X POST https://api-staging.knowledgestack.ai/v1/documents/ingest \
  -H "Authorization: Bearer <your-api-key>" \
  -F "file=@/path/to/report.pdf" \
  -F "path_part_id=a1b2c3d4-0000-0000-0000-000000000000" \
  -F "name=Q4 Report"

{
  "document_id": "d1e2f3a4-0000-0000-0000-000000000001",
  "document_version_id": "b2c3d4e5-0000-0000-0000-000000000002",
  "workflow_id": "ingest-abc123"
}

Ingest document version

POST https://api-staging.knowledgestack.ai/v1/documents/{document_id}/ingest Upload a new file for an existing document, creating a new version and triggering ingestion. The new version is automatically assigned the next version number.

Path parameters

document_id

string (uuid)

required

The document to create a new version for.

Request body (multipart)

file

required

The new file to upload.

ingestion_mode

string

Ingestion mode (same options as ingest document).

chunk_type

string

Force chunk type. Only valid with single_chunk mode.

secondary_taxonomy

string

Force secondary taxonomy. Only valid with single_chunk and chunk_type=IMAGE.

page_dpi

integer

DPI for PDF page screenshots. Range 36–216. Defaults to 72.

Response `201`

Returns an IngestDocumentResponse with the new document_version_id.

Example

curl -X POST https://api-staging.knowledgestack.ai/v1/documents/<document-id>/ingest \
  -H "Authorization: Bearer <your-api-key>" \
  -F "file=@/path/to/report-v2.pdf"

Create document

POST https://api-staging.knowledgestack.ai/v1/documents Create a new empty document (with an empty v0 version) without uploading a file. Use this when you intend to populate the document manually via the sections and chunks APIs rather than through file ingestion.

Request body

name

string

required

Document name. 1–255 characters.

parent_path_part_id

string (uuid)

required

path_part_id of the parent folder.

document_type

string

required

The document type. One of the DocumentType enum values.

document_origin

string

required

The document origin. One of SOURCE or GENERATED.

Response `200`

Returns a DocumentResponse.

string (uuid)

Document ID.

path_part_id

string (uuid)

Underlying path part ID.

name

string

Document name.

parent_path_part_id

string (uuid) | null

Parent folder’s path part ID.

document_type

string

Document type enum value.

document_origin

string

Document origin enum value.

active_version_id

string (uuid)

ID of the currently active version.

active_version

DocumentVersionResponse

Full details of the active version. See Document Versions for field descriptions.

materialized_path

string

Full path from root.

system_managed

boolean

Whether this document 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).

Example

curl -X POST https://api-staging.knowledgestack.ai/v1/documents \
  -H "Authorization: Bearer <your-api-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "API Design Notes",
    "parent_path_part_id": "a1b2c3d4-0000-0000-0000-000000000000",
    "document_type": "PLAINTEXT",
    "document_origin": "SOURCE"
  }'

List documents

GET https://api-staging.knowledgestack.ai/v1/documents List direct child documents of a parent folder.

Query parameters

parent_path_part_id

string (uuid)

Filter to documents in this folder. Defaults to the tenant’s shared root.

sort_order

string

Sort order. One of NAME, UPDATED_AT, CREATED_AT.

with_tags

boolean

Include tags in each result. Defaults to false.

limit

integer

Page size.

offset

integer

Pagination offset.

Response `200`

Returns a paginated list of DocumentResponse objects.

Example

curl "https://api-staging.knowledgestack.ai/v1/documents?parent_path_part_id=<folder-path-part-id>&limit=20" \
  -H "Authorization: Bearer <your-api-key>"

Get document

GET https://api-staging.knowledgestack.ai/v1/documents/{document_id} Get a single document by ID, including its active version details.

Path parameters

document_id

string (uuid)

required

The document ID.

Query parameters

with_tags

boolean

Include tags in the response. Defaults to false.

Response `200`

Returns a DocumentResponse. See Create document for field descriptions.

Example

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

Update document

PATCH https://api-staging.knowledgestack.ai/v1/documents/{document_id} Rename a document, move it to a different folder, or change its active version. All fields are optional.

Path parameters

document_id

string (uuid)

required

The document ID to update.

Request body

name

string

New document name. 1–255 characters.

parent_path_part_id

string (uuid)

Move the document to this parent folder (path_part_id of the destination folder).

active_version_id

string (uuid)

Set a different version as the active version.

Response `200`

Returns the updated DocumentResponse.

Example

# Rename
curl -X PATCH https://api-staging.knowledgestack.ai/v1/documents/<document-id> \
  -H "Authorization: Bearer <your-api-key>" \
  -H "Content-Type: application/json" \
  -d '{"name": "Q4 Report Final"}'

# Promote a version to active
curl -X PATCH https://api-staging.knowledgestack.ai/v1/documents/<document-id> \
  -H "Authorization: Bearer <your-api-key>" \
  -H "Content-Type: application/json" \
  -d '{"active_version_id": "<version-id>"}'

Delete document

DELETE https://api-staging.knowledgestack.ai/v1/documents/{document_id} Delete a document and all of its contents.

This is a cascading delete. All versions, sections, and chunks belonging to this document are permanently removed. This action cannot be undone.

Path parameters

document_id

string (uuid)

required

The document ID to delete.

Response `200`

Returns an empty {} on success.

Example

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

Authentication

Knowledge

Search & AI

Organization

Workspace

Workflows

Document types

Document origins

Ingest document

Request body (multipart)

Response `201`

Example

Ingest document version

Path parameters

Request body (multipart)

Response `201`

Example

Create document

Request body

Response `200`

Example

List documents

Query parameters

Response `200`

Example

Get document

Path parameters

Query parameters

Response `200`

Example

Update document

Path parameters

Request body

Response `200`

Example

Delete document

Path parameters

Response `200`

Example

Authentication

Knowledge

Search & AI

Organization

Workspace

Workflows

​Document types

​Document origins

​Ingest document

​Request body (multipart)

​Response 201

​Example

​Ingest document version

​Path parameters

​Request body (multipart)

​Response 201

​Example

​Create document

​Request body

​Response 200

​Example

​List documents

​Query parameters

​Response 200

​Example

​Get document

​Path parameters

​Query parameters

​Response 200

​Example

​Update document

​Path parameters

​Request body

​Response 200

​Example

​Delete document

​Path parameters

​Response 200

​Example

Document types

Document origins

Ingest document

Request body (multipart)

Response `201`

Example

Ingest document version

Path parameters

Request body (multipart)

Response `201`

Example

Create document

Request body

Response `200`

Example

List documents

Query parameters

Response `200`

Example

Get document

Path parameters

Query parameters

Response `200`

Example

Update document

Path parameters

Request body

Response `200`

Example

Delete document

Path parameters

Response `200`

Example