Folder (Workspace) Management

📁 Folder (Workspace) Management

Folders (workspaces) 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.

This feature is currently available for Max plan users.

Create Folder

Create a new folder for the authenticated user.

Parameters:

Name	Type	Required	Description	Default
name	string	yes	Folder name	-
description	string	no	Folder description	None
parent_folder_id	string	no	Parent folder ID for nesting	None

Example


result = pi_client.create_folder("Research Papers", description="2024 research collection")
print(result["folder"]["id"])

With Parent Folder (nested)


result = pi_client.create_folder("Q1 Reports", parent_folder_id="my-folder-id")

Example Response


{
  "folder": {
    "id": "my-folder-id",
    "name": "Research Papers",
    "description": "2024 research collection",
    "parent_folder_id": null,
    "created_at": "2024-06-15 10:30:00",
    "file_count": 0,
    "children_count": 0
  }
}

List Folders

List folders for the authenticated user, optionally filtered by parent.

Parameters:

Name	Type	Required	Description	Default
parent_folder_id	string	no	`"root"` for root-level only, a folder ID for subfolders, or omit for all	None

Example


# List all folders
result = pi_client.list_folders()
 
# List only root-level folders
result = pi_client.list_folders(parent_folder_id="root")
 
# List subfolders of a specific folder
result = pi_client.list_folders(parent_folder_id="my-folder-id")

Example Response


{
  "folders": [
    {
      "id": "my-folder-id",
      "name": "Research Papers",
      "description": "2024 research collection",
      "parent_folder_id": null,
      "created_at": "2024-06-15T10:30:00",
      "updated_at": "2024-06-15T10:30:00",
      "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


result = pi_client.submit_document("./report.pdf", folder_id="my-folder-id")

List documents in a specific folder


# List documents in a specific folder
docs = pi_client.list_documents(folder_id="my-folder-id")
 
# List all documents (no folder filter)
docs = pi_client.list_documents()
 
# List documents not assigned to any folder
docs = pi_client.list_documents(folder_id="root")
 
# With pagination
docs = pi_client.list_documents(folder_id="my-folder-id", limit=10, offset=20)

Get document metadata (includes folderId)


meta = pi_client.get_document("pi-abc123def456")
print(meta["folderId"])