File system with folders
Keep documents in a familiar folder structure: create folders, upload into them, and browse or search by folder. Folders come with the PageIndex Agent SDK (Python and JavaScript); set up the client as in the Quick start. PageIndex Agent can also use collections; Page Search and Page Extract use only collections.
Organize documents into folders and nested subfolders. Folders created without a parent and documents uploaded without a folder are placed at the root.
Create a folder
result = client.create_folder("Research Papers", description="2024 research papers")
folder_id = result["folder"]["id"]
With no parent_folder_id, the folder is created at the root — that is why the
response below has "parent_folder_id": null.
With Parent Folder (nested)
result = client.create_folder("Q1 Reports", parent_folder_id="my-folder-id")
Example Response
{
"folder": {
"id": "my-folder-id",
"name": "Research Papers",
"description": "2024 research papers",
"parent_folder_id": null,
"created_at": "2024-06-15 10:30:00",
"file_count": 0,
"children_count": 0
}
}
create_folder() 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. Omit to create at the root. | None |
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",
});
Example 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
}
}
createFolder() parameters
| Name | Type | Required | Description |
|---|---|---|---|
| name | string | yes | Folder name |
| description | string | no | Folder description |
| parentFolderId | string | no | Parent folder ID for nesting |
Upload into a folder
Assign a document to a folder during upload. Its folder is then returned as folderId in the document's info.
result = client.submit_document("./report.pdf", folder_id="my-folder-id")
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 folder
Filter documents by folder. Omit the folder ID to list all documents.
folder_id="root" returns documents not assigned to a folder.
# List documents in a specific folder
docs = client.list_documents(folder_id="my-folder-id")
# List all documents (no folder filter)
docs = client.list_documents()
# List documents not assigned to any folder
docs = client.list_documents(folder_id="root")
# Include its subfolders' documents too
docs = client.list_documents(folder_id="my-folder-id", recursive=True)
# Only documents whose metadata matches
docs = client.list_documents(filter={"year": {"$gte": 2024}})
# With pagination
docs = client.list_documents(folder_id="my-folder-id", limit=10, offset=20)
// 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,
});
List folders
List your folders, optionally filtered by parent.
# List all folders
result = client.list_folders()
# List only root-level folders
result = client.list_folders(parent_folder_id="root")
# List subfolders of a specific folder
result = client.list_folders(parent_folder_id="my-folder-id")
Example Response
{
"folders": [
{
"id": "my-folder-id",
"name": "Research Papers",
"description": "2024 research papers",
"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
}
list_folders() 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 |
// 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" });
Example 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
}
listFolders() 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 |
Paths
Python SDK only. In JavaScript, the agent tools return each folder's and document's path and take it back to address them.
A document or folder's place in the library, as a readable path — and the reverse lookup:
client.get_document_path(doc_id) # "Research/Papers/attention.pdf"
client.get_folder_path(folder_id) # "Research/Papers"
client.get_folder_id("Research/Papers") # the folder's ID
get_document_path() returns just the name for a document at the library root. Feed a document path straight back to get_document_id().
Folder scope
JavaScript SDK only.
Keep a client to one folder and its subfolders with folderScope. The agent tools (client.tools) see only that folder, and client.api uploads into it and lists it by default.
// Set at initialization
const client = new PageIndexClient({
apiKey: "YOUR_API_KEY",
folderScope: "folder-abc123",
});
// Or change it later (agent tools only)
await client.setFolderScope("another-folder-id");
Ask questions within a folder
To ask questions within a folder, pass folder_id to Use with your LLM, or use folder_context() with Use with your agent. For chat, "root" means the whole library; for document listing, it means only documents outside folders.