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.

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

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

Response

{
  "folders": [
    {
      "id": "folder-abc123",
      "name": "Research Papers",
      "description": "2024 research papers",
      "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");