Folders

Tags: files, organization, storage

File and document folder management

Resources

Request and response models used by the endpoints on this page.

AccessGrantResponse

Field	Type	Required	Description
accessMode	Integer	✓
assignmentId	Integer
bounds	dict[str, Any]
capabilityClass	String
chatId	Integer
consentMethod	String
createdAt	DateTime	✓
dataTypeId	Integer
dataTypeName	String
expiresAt	DateTime
granteeMemberId	Integer	✓
granteeMemberName	String
grantorMemberId	Integer	✓
grantorMemberName	String
id	Integer	✓
memberCredentialId	Integer
resolvedAt	DateTime
resourceId	Integer
resourceLabel	String
resourceType	String	✓
revocationReason	String
revokedAt	DateTime
revokedByMemberId	Integer
revokedByMemberName	String
status	String	✓
trigger	String	✓
uuid	String	✓

Example:

{
  "id": 0  // Integer,
  "uuid": "string"  // String,
  "grantorMemberId": 0  // Integer,
  "grantorMemberName": "string"  // String, optional,
  "granteeMemberId": 0  // Integer,
  "granteeMemberName": "string"  // String, optional,
  "resourceType": "string"  // String,
  "resourceId": 0  // Integer, optional,
  "resourceLabel": "string"  // String, optional,
  "dataTypeId": 0  // Integer, optional,
  "dataTypeName": "string"  // String, optional,
  "capabilityClass": "string"  // String, optional,
  "bounds": {}  // dict[str, Any], optional,
  "accessMode": 0  // Integer,
  "trigger": "string"  // String,
  "memberCredentialId": 0  // Integer, optional,
  "assignmentId": 0  // Integer, optional,
  "chatId": 0  // Integer, optional,
  "status": "string"  // String,
  "consentMethod": "string"  // String, optional,
  "expiresAt": "2024-01-01T00:00:00Z"  // DateTime, optional,
  "revokedAt": "2024-01-01T00:00:00Z"  // DateTime, optional,
  "revokedByMemberId": 0  // Integer, optional,
  "revokedByMemberName": "string"  // String, optional,
  "revocationReason": "string"  // String, optional,
  "createdAt": "2024-01-01T00:00:00Z"  // DateTime,
  "resolvedAt": "2024-01-01T00:00:00Z"  // DateTime, optional
}

FileFolderResponse

Field	Type	Required	Description
access	String		Default: private
ancestors	Array		Default: []
childCount	Integer		Default: 0
createdAt	DateTime	✓
description	String
fileCount	Integer		Default: 0
id	Integer	✓
index	Boolean		Default: False
indexingCompletedAt	DateTime
indexingStartedAt	DateTime
name	String	✓
ownerId	Integer
parentId	Integer
path	String
shareable	Boolean		Default: False
updatedAt	DateTime	✓
uuid	String	✓

Example:

{
  "id": 0  // Integer,
  "name": "string"  // String,
  "uuid": "string"  // String,
  "path": "string"  // String, optional,
  "description": "string"  // String, optional,
  "parentId": 0  // Integer, optional,
  "ownerId": 0  // Integer, optional,
  "childCount": 0  // Integer, optional, default: 0,
  "fileCount": 0  // Integer, optional, default: 0,
  "access": "string"  // String, optional, default: private,
  "shareable": false  // Boolean, optional, default: False,
  "index": false  // Boolean, optional, default: False,
  "indexingStartedAt": "2024-01-01T00:00:00Z"  // DateTime, optional,
  "indexingCompletedAt": "2024-01-01T00:00:00Z"  // DateTime, optional,
  "createdAt": "2024-01-01T00:00:00Z"  // DateTime,
  "updatedAt": "2024-01-01T00:00:00Z"  // DateTime,
  "ancestors": []  // Array<FolderPathSegment>, optional, default: []
}

FileRoleAssociationResponse

Field	Type	Required	Description
accessMode	Integer	✓
memberRoleId	Integer	✓
memberRoleName	String	✓

Example:

{
  "memberRoleId": 0  // Integer,
  "memberRoleName": "string"  // String,
  "accessMode": 0  // Integer
}

FolderPathSegment

Field	Type	Required	Description
id	Integer	✓
name	String	✓

Example:

{
  "id": 0  // Integer,
  "name": "string"  // String
}

FolderSearchResultResponse

Field	Type	Required	Description
content	String	✓
fileId	Integer	✓
fileUuid	String	✓
filename	String	✓
metadata	Object	✓
mimeType	String	✓
score	Number	✓
title	String	✓

Example:

{
  "content": "string"  // String,
  "fileId": 0  // Integer,
  "fileUuid": "string"  // String,
  "filename": "string"  // String,
  "title": "string"  // String,
  "mimeType": "string"  // String,
  "score": 0.0  // Number,
  "metadata": {}  // Object
}

FolderSharingResponse

Field	Type	Required	Description
access	String	✓
grants	Array	✓
ownerId	Integer	✓
ownerName	String	✓
roleAssociations	Array	✓
shareable	Boolean	✓

Example:

{
  "ownerId": 0  // Integer,
  "ownerName": "string"  // String,
  "access": "string"  // String,
  "shareable": false  // Boolean,
  "grants": []  // Array<AccessGrantResponse>,
  "roleAssociations": []  // Array<FileRoleAssociationResponse>
}

Endpoints

• GET /api/v2/w/{workspace_uuid}/folders - List
• POST /api/v2/w/{workspace_uuid}/folders - Create
• DELETE /api/v2/w/{workspace_uuid}/folders/{folder_id} - Delete Folder Id
• GET /api/v2/w/{workspace_uuid}/folders/{folder_id} - Get Folder Id
• PUT /api/v2/w/{workspace_uuid}/folders/{folder_id} - Update Folder Id
• POST /api/v2/w/{workspace_uuid}/folders/{folder_id}/reindex - Reindex
• GET /api/v2/w/{workspace_uuid}/folders/{folder_id}/search - Search
• GET /api/v2/w/{workspace_uuid}/folders/{folder_id}/sharing - Sharing
• PUT /api/v2/w/{workspace_uuid}/folders/{folder_id}/sharing - Update Sharing
• PUT /api/v2/w/{workspace_uuid}/folders/{folder_id}/sharing/roles - Update Roles
• DELETE /api/v2/w/{workspace_uuid}/folders/{folder_id}/sharing/roles/{member_role_id} - Delete Roles

List

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

Description:

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:

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:

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:

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:

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:

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)

---

Search

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

Description:

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:

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:

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

Authorization: Requires files:write scope

Parameters:

• folder_id (Integer)
• request - See UpdateFileSharingRequest

Response: See FolderSharingResponse

---

Update Roles

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

Description:

Set role associations for a folder (replaces all).

Authorization: Requires files:write scope

Parameters:

• folder_id (Integer)
• request - See UpdateFileRoleAssociationsRequest

Response: List of FileRoleAssociationResponse

---

Delete Roles

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

Description:

Remove a single role's access to a folder.

Authorization: Requires files:write scope

Parameters:

• folder_id (Integer)
• member_role_id (Integer)

---