Folders - PLai Framework Documentation

Get Folder

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

Path Parameters

datasource_id

string

required

The unique identifier of the datasource

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)

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'

const datasourceId = 'ds_123';
const folderId = 'folder_456';
const response = await fetch(`https://api.plaisolutions.com/datasources/${datasourceId}/folders/${folderId}`, {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
    'Content-Type': 'application/json'
  }
});

const folder = await response.json();
console.log(folder);

import requests

datasource_id = "ds_123"
folder_id = "folder_456"
url = f"https://api.plaisolutions.com/datasources/{datasource_id}/folders/{folder_id}"
headers = {
    "Authorization": "Bearer YOUR_TOKEN",
    "Content-Type": "application/json"
}

response = requests.get(url, headers=headers)
folder = response.json()
print(folder)

Update Folder

Update folder properties.

Path Parameters

datasource_id

string

required

The unique identifier of the datasource

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"
  }
}'

const datasourceId = 'ds_123';
const folderId = 'folder_456';
const response = await fetch(`https://api.plaisolutions.com/datasources/${datasourceId}/folders/${folderId}`, {
  method: 'PATCH',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    name: "Updated Folder Name",
    extra_info: {
      description: "Updated folder description",
      color: "blue"
    }
  })
});

const folder = await response.json();
console.log(folder);

import requests

datasource_id = "ds_123"
folder_id = "folder_456"
url = f"https://api.plaisolutions.com/datasources/{datasource_id}/folders/{folder_id}"
headers = {
    "Authorization": "Bearer YOUR_TOKEN",
    "Content-Type": "application/json"
}
data = {
    "name": "Updated Folder Name",
    "extra_info": {
        "description": "Updated folder description",
        "color": "blue"
    }
}

response = requests.patch(url, headers=headers, json=data)
folder = response.json()
print(folder)

Delete Folder

Delete a folder and all its contents.

Path Parameters

datasource_id

string

required

The unique identifier of the datasource

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'

const datasourceId = 'ds_123';
const folderId = 'folder_456';
const response = await fetch(`https://api.plaisolutions.com/datasources/${datasourceId}/folders/${folderId}`, {
  method: 'DELETE',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
    'Content-Type': 'application/json'
  }
});

console.log('Folder deleted:', response.status === 200);

import requests

datasource_id = "ds_123"
folder_id = "folder_456"
url = f"https://api.plaisolutions.com/datasources/{datasource_id}/folders/{folder_id}"
headers = {
    "Authorization": "Bearer YOUR_TOKEN",
    "Content-Type": "application/json"
}

response = requests.delete(url, headers=headers)
print(f"Folder deleted: {response.status_code == 200}")

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"
  }
}'

const datasourceId = 'ds_123';
const response = await fetch(`https://api.plaisolutions.com/datasources/${datasourceId}/folders`, {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    name: "Documentation",
    parent_id: null,
    extra_info: {
      description: "Product documentation and guides",
      color: "green"
    }
  })
});

const folder = await response.json();
console.log(folder);

import requests

datasource_id = "ds_123"
url = f"https://api.plaisolutions.com/datasources/{datasource_id}/folders"
headers = {
    "Authorization": "Bearer YOUR_TOKEN",
    "Content-Type": "application/json"
}
data = {
    "name": "Documentation",
    "parent_id": None,
    "extra_info": {
        "description": "Product documentation and guides",
        "color": "green"
    }
}

response = requests.post(url, headers=headers, json=data)
folder = response.json()
print(folder)

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

Show Folder Object

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)

string

Folder unique identifier

extra_info

object

Additional metadata for the folder

created_at

string

When the folder was created

updated_at

string

When the folder was last updated

children

array

Array of child folders (recursive structure)

curl --location --request GET 'https://api.plaisolutions.com/datasources/ds_123/folders' \
--header 'Authorization: Bearer YOUR_TOKEN'

const datasourceId = 'ds_123';
const response = await fetch(`https://api.plaisolutions.com/datasources/${datasourceId}/folders`, {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
    'Content-Type': 'application/json'
  }
});

const folders = await response.json();
console.log(folders);

import requests

datasource_id = "ds_123"
url = f"https://api.plaisolutions.com/datasources/{datasource_id}/folders"
headers = {
    "Authorization": "Bearer YOUR_TOKEN",
    "Content-Type": "application/json"
}

response = requests.get(url, headers=headers)
folders = response.json()
print(folders)

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'

const datasourceId = 'ds_123';
const folderId = 'folder_456';
const resourceId = 'resource_789';
const response = await fetch(`https://api.plaisolutions.com/datasources/${datasourceId}/folders/${folderId}/resources/${resourceId}`, {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
    'Content-Type': 'application/json'
  }
});

const result = await response.json();
console.log(result);

import requests

datasource_id = "ds_123"
folder_id = "folder_456"
resource_id = "resource_789"
url = f"https://api.plaisolutions.com/datasources/{datasource_id}/folders/{folder_id}/resources/{resource_id}"
headers = {
    "Authorization": "Bearer YOUR_TOKEN",
    "Content-Type": "application/json"
}

response = requests.post(url, headers=headers)
result = response.json()
print(result)

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

Extra Info Usage

The extra_info field allows you to store additional metadata about folders:

UI Customization

Store display preferences like colors, icons, or sorting orders

{
  "color": "blue",
  "icon": "folder-document",
  "sort_order": "alphabetical"
}

Access Control

Store visibility or access information for your application logic

{
  "visibility": "public",
  "access_level": "read-write",
  "owner": "team-docs"
}

Workflow State

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.

​Get Folder

​Path Parameters

​Response

​Update Folder

​Path Parameters

​Request Body

​Response

​Delete Folder

​Path Parameters

​Response

​Create Folder

​Path Parameters

​Request Body

​Response

​List Datasource Folders

​Path Parameters

​Response

​Move Resource to Folder

​Path Parameters

​Response

​Folder Organization Best Practices

​Common Organization Patterns

​Extra Info Usage

Get Folder

Path Parameters

Response

Update Folder

Path Parameters

Request Body

Response

Delete Folder

Path Parameters

Response

Create Folder

Path Parameters

Request Body

Response

List Datasource Folders

Path Parameters

Response

Move Resource to Folder

Path Parameters

Response

Folder Organization Best Practices

Common Organization Patterns

Extra Info Usage