Get Folder Get a folder with its children (subfolders and resources).
Path Parameters The unique identifier of the datasource
The unique identifier of the folder
Response ID of the datasource this folder belongs to
ID of the parent folder (null for root folders)
Additional metadata for the folder
When the folder was created (ISO 8601 format)
When the folder was last updated (ISO 8601 format)
Array of child folders (recursive structure)
curl --location --request GET 'https://api.plaisolutions.com/datasources/ds_123/folders/folder_456' \ --header 'Authorization: Bearer YOUR_TOKEN'
Update Folder Update folder properties.
Path Parameters The unique identifier of the datasource
The unique identifier of the folder
Request Body Updated parent folder ID (use null to move to root level)
Updated additional metadata
Response Returns the updated folder object.
curl --location --request PATCH 'https://api.plaisolutions.com/datasources/ds_123/folders/folder_456' \ --header 'Authorization: Bearer YOUR_TOKEN' \ --header 'Content-Type: application/json' \ --data-raw '{ "name": "Updated Folder Name", "extra_info": { "description": "Updated folder description", "color": "blue" } }'
Delete Folder Delete a folder and all its contents.
Path Parameters The unique identifier of the datasource
The unique identifier of the folder to delete
Response Returns a 200 status code on successful deletion.
Deleting a folder will permanently remove:
The folder itself
All subfolders within it
All resources contained in the folder and its subfolders
All associated vector embeddings and search indexes
This action cannot be undone. curl --location --request DELETE 'https://api.plaisolutions.com/datasources/ds_123/folders/folder_456' \ --header 'Authorization: Bearer YOUR_TOKEN'
Create Folder Create a new folder within a datasource.
Path Parameters The unique identifier of the datasource
Request Body ID of the parent folder (omit or use null to create in root)
Additional metadata for the folder
Response Returns the created folder object.
curl --location --request POST 'https://api.plaisolutions.com/datasources/ds_123/folders' \ --header 'Authorization: Bearer YOUR_TOKEN' \ --header 'Content-Type: application/json' \ --data-raw '{ "name": "Documentation", "parent_id": null, "extra_info": { "description": "Product documentation and guides", "color": "green" } }'
List Datasource Folders List all folders in a datasource with their hierarchical structure.
Path Parameters The unique identifier of the datasource
Response Array of root-level folders with nested children ID of the datasource this folder belongs to
ID of the parent folder (null for root folders)
Additional metadata for the folder
When the folder was created
When the folder was last updated
Array of child folders (recursive structure)
curl --location --request GET 'https://api.plaisolutions.com/datasources/ds_123/folders' \ --header 'Authorization: Bearer YOUR_TOKEN'
Move Resource to Folder Move a resource into a specific folder.
Path Parameters The unique identifier of the datasource
The unique identifier of the destination folder
The unique identifier of the resource to move
Response Returns a success confirmation.
curl --location --request POST 'https://api.plaisolutions.com/datasources/ds_123/folders/folder_456/resources/resource_789' \ --header 'Authorization: Bearer YOUR_TOKEN'
Folder Organization Best Practices
Plan Your Structure
Design a logical folder hierarchy before adding resources
Use Descriptive Names
Choose clear, descriptive names that indicate the folder’s purpose
Keep It Shallow
Avoid deeply nested structures (3-4 levels maximum)
Group by Function
Organize folders by topic, type, or workflow rather than arbitrary categorization
Common Organization Patterns By Content Type
By Product Area
By Audience
📁 Documentation 📁 User Guides 📁 API Reference 📁 Tutorials 📁 Marketing Materials 📁 Brochures 📁 Case Studies 📁 Press Releases
📁 Product A 📁 Documentation 📁 Support Articles 📁 Product B 📁 Documentation 📁 Support Articles
📁 Customer-Facing 📁 Support 📁 Tutorials 📁 Internal 📁 Policies 📁 Procedures
The extra_info field allows you to store additional metadata about folders:
Store display preferences like colors, icons, or sorting orders { "color" : "blue" , "icon" : "folder-document" , "sort_order" : "alphabetical" }
Store visibility or access information for your application logic { "visibility" : "public" , "access_level" : "read-write" , "owner" : "team-docs" }
Track folder status or workflow information { "status" : "active" , "last_reviewed" : "2024-01-15" , "review_required" : false }
Folders provide organizational structure but do not affect how agents search or access resources. Use metadata filtering on resources for access control and content filtering.
Consider using folder names and structures that align with your users’ mental models. This makes content easier to find and manage over time.
