Skip to main content

Folders

Tags: files, organization, storage

Endpoints​

List​

GET /api/v2/w/{workspace_uuid}/folders

Description:

File and document folder management

List child folders of the given parent folder.

Authorization: Requires files:read scope

Parameters:

  • parent_id (Integer)

Response: List of FileFolderResponse

Create​

POST /api/v2/w/{workspace_uuid}/folders

Description:

File and document folder management

Create a new folder.

Authorization: Requires files:write scope

Parameters:

  • folder (CreateFileFolderRequest)

Response: See FileFolderResponse

Delete Folder Id​

DELETE /api/v2/w/{workspace_uuid}/folders/{folder_id}

Description:

File and document folder management

Delete a folder.

Root folders (workspace root, member homes, site assets) cannot be deleted — only emptied. We check early to give a clear error and avoid cascade-deleting children.

Authorization: Requires files:admin scope

Parameters:

  • folder_id (Integer)

Get Folder Id​

GET /api/v2/w/{workspace_uuid}/folders/{folder_id}

Description:

File and document folder management

Get a specific folder by ID, including its children and files.

Authorization: Requires files:read scope

Parameters:

  • folder_id (Integer)

Response: See FileFolderResponse

Update Folder Id​

PUT /api/v2/w/{workspace_uuid}/folders/{folder_id}

Description:

File and document folder management

Update an existing folder.

Authorization: Requires files:write scope

Parameters:

  • folder_id (Integer)
  • folder (UpdateFileFolderRequest)

Response: See FileFolderResponse

Reindex​

POST /api/v2/w/{workspace_uuid}/folders/{folder_id}/reindex

Description:

File and document folder management

Trigger background reindexing of a folder with vector embeddings.

This endpoint triggers background reindexing to:

  1. Process all files in the folder
  2. Generate vector embeddings for semantic search

The indexing happens asynchronously. Check the folder's indexing timestamps to monitor progress.

Authorization: Requires files:write scope

Parameters:

  • folder_id (Integer)

GET /api/v2/w/{workspace_uuid}/folders/{folder_id}/search

Description:

File and document folder management

Search for documents in a folder using vector similarity.

Args: id: The folder ID to search in query: The search query text top_k: Number of results to return (default 5) ctx: The execution context

Returns: List of search results with content snippets and metadata

Authorization: Requires files:read scope

Parameters:

  • folder_id (Integer)
  • query (String)
  • top_k (Integer)

Response: List of FolderSearchResultResponse

Sharing​

GET /api/v2/w/{workspace_uuid}/folders/{folder_id}/sharing

Description:

File and document folder management

Get complete sharing state for a folder.

Authorization: Requires files:read scope

Parameters:

  • folder_id (Integer)

Response: See FolderSharingResponse

Update Sharing​

PUT /api/v2/w/{workspace_uuid}/folders/{folder_id}/sharing

Description:

File and document folder management

Batch-update the complete sharing state for a folder in a single transaction.

Authorization: Requires files:write scope

Parameters:

Response: See FolderSharingResponse

Update Roles​

PUT /api/v2/w/{workspace_uuid}/folders/{folder_id}/sharing/roles

Description:

File and document folder management

Set role associations for a folder (replaces all).

Authorization: Requires files:write scope

Parameters:

Response: List of FileRoleAssociationResponse

Delete Roles​

DELETE /api/v2/w/{workspace_uuid}/folders/{folder_id}/sharing/roles/{member_role_id}

Description:

File and document folder management

Remove a single role's access to a folder.

Authorization: Requires files:write scope

Parameters:

  • folder_id (Integer)
  • member_role_id (Integer)