PageIndex

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 PageIndex Cloud only.

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 via the REST API, optionally filtered by parent.

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" });

For agentic use cases, traverse folders through the MCP tool client.tools.getFolderStructure(), which returns the folder hierarchy as a tree.

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");