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
NameTypeRequiredDescriptionDefault
namestringyesFolder name-
descriptionstringnoFolder descriptionNone
parent_folder_idstringnoParent folder ID for nesting. Omit to create at the root.None

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

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 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
NameTypeRequiredDescriptionDefault
parent_folder_idstringno"root" for root-level only, a folder ID for subfolders, or omit for allNone

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.