Skip to main content

​
Get Folder

Get a folder with its children (subfolders and resources).

​
Path Parameters

​
datasource_id
string
required
The unique identifier of the datasource
​
id
string
required
The unique identifier of the folder

​
Response

​
name
string
Folder name
​
datasource_id
string
ID of the datasource this folder belongs to
​
parent_id
string
ID of the parent folder (null for root folders)
​
id
string
Folder unique identifier
​
extra_info
object
Additional metadata for the folder
​
created_at
string
When the folder was created (ISO 8601 format)
​
updated_at
string
When the folder was last updated (ISO 8601 format)
​
children
array
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

​
datasource_id
string
required
The unique identifier of the datasource
​
id
string
required
The unique identifier of the folder

​
Request Body

​
name
string
Updated folder name
​
parent_id
string
Updated parent folder ID (use null to move to root level)
​
extra_info
object
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

​
datasource_id
string
required
The unique identifier of the datasource
​
id
string
required
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

​
datasource_id
string
required
The unique identifier of the datasource

​
Request Body

​
name
string
required
Folder name
​
parent_id
string
ID of the parent folder (omit or use null to create in root)
​
extra_info
object
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

​
datasource_id
string
required
The unique identifier of the datasource

​
Response

​
folders
array
Array of root-level folders with nested children
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

​
datasource_id
string
required
The unique identifier of the datasource
​
folder_id
string
required
The unique identifier of the destination folder
​
resource_id
string
required
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

1

Plan Your Structure

Design a logical folder hierarchy before adding resources
2

Use Descriptive Names

Choose clear, descriptive names that indicate the folder’s purpose
3

Keep It Shallow

Avoid deeply nested structures (3-4 levels maximum)
4

Group by Function

Organize folders by topic, type, or workflow rather than arbitrary categorization

​
Common Organization Patterns

📁 Documentation
  📁 User Guides
  📁 API Reference
  📁 Tutorials
📁 Marketing Materials
  📁 Brochures
  📁 Case Studies
  📁 Press Releases

​
Extra Info Usage

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.