Folders - Knowledge Stack

Folders form the hierarchical namespace for all knowledge content. Every folder has a path_part_id — the underlying tree node — and a parent_path_part_id pointing to its parent folder. The root of each tenant’s shared space is a system-managed folder.

Create folder

POST https://api-staging.knowledgestack.ai/v1/folders Create a new folder as a child of an existing folder.

Request body

name

string

required

Folder name. 1–255 characters.

parent_path_part_id

string (uuid)

required

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

Response `200`

Returns a FolderResponse.

string (uuid)

Folder ID.

path_part_id

string (uuid)

Underlying path part ID used for tree traversal and permissions.

name

string

Folder name.

parent_path_part_id

string (uuid) | null

Parent path part ID. null for the root folder.

materialized_path

string

Full path from root (e.g. /tenant-root/engineering/docs).

system_managed

boolean

Whether this folder is managed by the system and cannot be deleted directly.

tenant_id

string (uuid)

Tenant that owns this folder.

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/folders \
  -H "Authorization: Bearer <your-api-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Engineering Docs",
    "parent_path_part_id": "a1b2c3d4-0000-0000-0000-000000000000"
  }'

List folders

GET https://api-staging.knowledgestack.ai/v1/folders List direct child folders of a parent folder (depth = 1).

Query parameters

parent_path_part_id

string (uuid)

Filter to children of 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 tag data in each folder response. Defaults to false.

limit

integer

Page size.

offset

integer

Pagination offset.

Response `200`

Returns a paginated list of FolderResponse objects.

Example

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

Search items

GET https://api-staging.knowledgestack.ai/v1/folders/search Search for folders and documents by name using a case-insensitive trigram partial match.

Query parameters

name_like

string

Partial name to search for.

part_type

string

Filter by item type. One of FOLDER, DOCUMENT.

parent_path_part_id

string (uuid)

Restrict search to descendants of this folder.

sort_order

string

Sort order. One of NAME, UPDATED_AT, CREATED_AT.

with_tags

boolean

Include tags in results. Defaults to false.

limit

integer

Page size.

offset

integer

Pagination offset.

Response `200`

Returns a paginated discriminated union of FolderResponse and DocumentResponse objects.

Example

curl "https://api-staging.knowledgestack.ai/v1/folders/search?name_like=eng&part_type=FOLDER" \
  -H "Authorization: Bearer <your-api-key>"

Get folder

GET https://api-staging.knowledgestack.ai/v1/folders/{folder_id} Get a single folder by its folder ID.

Path parameters

folder_id

string (uuid)

required

The folder ID (not the path_part_id).

Query parameters

with_tags

boolean

Include tags in the response. Defaults to false.

Response `200`

Returns a FolderResponse. See Create folder for field descriptions.

Example

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

Update folder

PATCH https://api-staging.knowledgestack.ai/v1/folders/{folder_id} Rename a folder, move it to a new parent, or both. All fields are optional — supply only the ones you want to change.

Path parameters

folder_id

string (uuid)

required

The folder ID to update.

Request body

name

string

New folder name. 1–255 characters.

parent_path_part_id

string (uuid)

path_part_id of the new parent folder. Provide this to move the folder.

Response `200`

Returns the updated FolderResponse.

Example

# Rename
curl -X PATCH https://api-staging.knowledgestack.ai/v1/folders/<folder-id> \
  -H "Authorization: Bearer <your-api-key>" \
  -H "Content-Type: application/json" \
  -d '{"name": "Platform Docs"}'

# Move
curl -X PATCH https://api-staging.knowledgestack.ai/v1/folders/<folder-id> \
  -H "Authorization: Bearer <your-api-key>" \
  -H "Content-Type: application/json" \
  -d '{"parent_path_part_id": "<new-parent-path-part-id>"}'

Delete folder

DELETE https://api-staging.knowledgestack.ai/v1/folders/{folder_id} Delete a folder and all of its contents.

This is a cascading delete. All child folders, documents, document versions, sections, and chunks inside this folder will be permanently removed. This action cannot be undone.

Path parameters

folder_id

string (uuid)

required

The folder ID to delete.

Response `200`

Returns an empty {} on success.

Example

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

Folder action

POST https://api-staging.knowledgestack.ai/v1/folders/{folder_id} Perform an action on a folder. Currently the only supported action is reembed, which re-embeds all documents in the folder.

Path parameters

folder_id

string (uuid)

required

The folder to act on.

Query parameters

action

string

required

The action to perform. Currently supported: reembed.

Response `200`

Returns a FolderActionResponse.

folder_id

string (uuid)

The folder ID the action was applied to.

action

string

The action performed (e.g. reembed).

workflow_id

string

ID of the background workflow that was triggered.

Example

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

{
  "folder_id": "a1b2c3d4-0000-0000-0000-000000000000",
  "action": "reembed",
  "workflow_id": "reembed-workflow-abc123"
}

List folder contents

GET https://api-staging.knowledgestack.ai/v1/folders/{folder_id}/contents List all items (folders and documents) under a folder up to a specified depth. Returns a paginated discriminated union — each item includes a part_type field (FOLDER or DOCUMENT) so you can distinguish between them.

Path parameters

folder_id

string (uuid)

required

The folder whose contents to list.

Query parameters

max_depth

integer

Maximum depth to traverse below the specified folder. 1 returns only direct children.

sort_order

string

Sort order. One of NAME, UPDATED_AT, CREATED_AT.

with_tags

boolean

Include tag data in each item. Defaults to false.

limit

integer

Page size.

offset

integer

Pagination offset.

Response `200`

Returns a paginated list. Each item is either a FolderResponse or DocumentResponse, discriminated by the part_type field.

Example

curl "https://api-staging.knowledgestack.ai/v1/folders/<folder-id>/contents?max_depth=2&limit=50" \
  -H "Authorization: Bearer <your-api-key>"

{
  "items": [
    {
      "part_type": "FOLDER",
      "id": "...",
      "name": "Subfolder A",
      ...
    },
    {
      "part_type": "DOCUMENT",
      "id": "...",
      "name": "Architecture Overview.pdf",
      ...
    }
  ],
  "total": 2,
  "limit": 50,
  "offset": 0
}

Authentication

Knowledge

Search & AI

Organization

Workspace

Workflows

​Create folder

​Request body

​Response 200

​Example

​List folders

​Query parameters

​Response 200

​Example

​Search items

​Query parameters

​Response 200

​Example

​Get folder

​Path parameters

​Query parameters

​Response 200

​Example

​Update folder

​Path parameters

​Request body

​Response 200

​Example

​Delete folder

​Path parameters

​Response 200

​Example

​Folder action

​Path parameters

​Query parameters

​Response 200

​Example

​List folder contents

​Path parameters

​Query parameters

​Response 200

​Example

Create folder

Request body

Response `200`

Example

List folders

Query parameters

Response `200`

Example

Search items

Query parameters

Response `200`

Example

Get folder

Path parameters

Query parameters

Response `200`

Example

Update folder

Path parameters

Request body

Response `200`

Example

Delete folder

Path parameters

Response `200`

Example

Folder action

Path parameters

Query parameters

Response `200`

Example

List folder contents

Path parameters

Query parameters

Response `200`

Example