📁 Folder (Workspace) Management
Folders let you organize your PageIndex documents into groups. You can create nested folder hierarchies, assign documents to folders during upload, and filter documents by folder.
Folders are available on the Max plan only. See Pricing for details.
Create Folder
Create a new folder, optionally nested under a parent folder.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
| name | string | yes | Folder name |
| description | string | no | Folder description |
| parentFolderId | string | no | Parent folder ID for nesting |
Example
const result = await client.api.createFolder({
name: "Research Papers",
description: "2024 research collection",
});
console.log(result.folder.id); // "folder-abc123"With Parent Folder (nested)
const result = await client.api.createFolder({
name: "Q1 Reports",
parentFolderId: "folder-abc123",
});Response
{
"folder": {
"id": "folder-abc123",
"name": "Research Papers",
"description": "2024 research collection",
"parent_folder_id": null,
"created_at": "2024-06-15T10:30:00.000Z",
"updated_at": "2024-06-15T10:30:00.000Z",
"file_count": 0,
"children_count": 0
}
}List Folders
Retrieve folders, optionally filtered by parent. Available via both the API and as an MCP tool.
Parameters
| Name | Type | Required | Description | Default |
|---|---|---|---|---|
| parentFolderId | string | no | "root" for root-level only, a specific ID for children of that folder, or omit for all folders | all |
Example
// List all folders
const all = await client.api.listFolders();
console.log(`Total folders: ${all.total}`);
// List root-level folders only
const root = await client.api.listFolders({ parentFolderId: "root" });
// List children of a specific folder
const children = await client.api.listFolders({ parentFolderId: "folder-abc123" });listFolders is also available as an MCP tool via client.tools.listFolders() for use in agentic integrations.
Response
{
"folders": [
{
"id": "folder-abc123",
"name": "Research Papers",
"description": "2024 research collection",
"parent_folder_id": null,
"created_at": "2024-06-15T10:30:00.000Z",
"updated_at": "2024-06-15T10:30:00.000Z",
"file_count": 5,
"children_count": 2
}
],
"total": 1
}Using Folders with Documents
Once you have folders, you can assign documents to them during upload and filter documents by folder.
Upload a document to a specific folder
import { readFileSync } from "fs";
const file = readFileSync("./report.pdf");
const result = await client.api.submitDocument(file, "report.pdf", {
folderId: "folder-abc123",
});List documents in a specific folder
// List documents in a specific folder
const docs = await client.api.listDocuments({ folderId: "folder-abc123" });
// List all documents (no folder filter)
const allDocs = await client.api.listDocuments();
// With pagination
const page = await client.api.listDocuments({
folderId: "folder-abc123",
limit: 10,
offset: 20,
});Get document metadata (includes folderId)
const doc = await client.api.getDocument("pi-abc123def456");
console.log(doc.folderId); // "folder-abc123"Folder Scope
You can restrict all SDK operations to a specific folder and its subfolders using folderScope. When set, document uploads, listings, searches, and reads are automatically scoped.
// Set at initialization
const client = new PageIndexClient({
apiKey: "YOUR_API_KEY",
folderScope: "folder-abc123",
});
// Or change dynamically
client.setFolderScope("another-folder-id");