Cloud

Cloud accepts PDF, PPTX, and Word. Uploads process asynchronously — either block with wait=True, or submit many documents and poll afterwards.

# Block until ready
doc_id = client.submit_document("./report.pdf", wait=True)["doc_id"]
 
# Or poll yourself
doc_id = client.submit_document("./report.pdf")["doc_id"]
if client.get_document(doc_id)["status"] == "completed":
    print("Document processing completed")

Local

Local mode accepts PDF only. The call finishes indexing before returning and stores the document under storage_path.

doc_id = client.submit_document("./report.pdf")["doc_id"]

Document info

meta = client.get_document(doc_id)
print(f"{meta['name']}: {meta['status']}, {meta['pageNum']} pages")

from datetime import datetime, timezone
 
datetime.fromisoformat(meta["createdAt"]).replace(tzinfo=timezone.utc).astimezone()

Tree index

get_tree() includes node text by default (include_text=True), with summaries off (node_summary=False). For a compact tree with summaries and no node text, set both options explicitly:

tree_result = client.get_tree(doc_id, node_summary=True, include_text=False)
if tree_result.get("status") == "completed":
    print("PageIndex Tree Structure:", tree_result.get("result"))

{
  "doc_id": "pi-abc123def456",
  "status": "processing"
}

{
  "doc_id": "pi-abc123def456",
  "status": "completed",
  "result": [
    {
      "title": "Financial Stability",
      "node_id": "0006",
      "page_index": 21,
      "prefix_summary": "The Federal Reserve maintains financial stability through comprehensive monitoring...",
      "nodes": [
        {
          "title": "Monitoring Financial Vulnerabilities",
          "node_id": "0007",
          "page_index": 22,
          "summary": "The Federal Reserve's monitoring focuses on identifying and assessing potential risks..."
        },
        {
          "title": "Domestic and International Cooperation and Coordination",
          "node_id": "0008",
          "page_index": 28,
          "summary": "In 2023, the Federal Reserve collaborated internationally with central banks..."
        }
      ]
    }
  ]
}

With node_summary=True, leaf nodes carry summary and nodes with children carry prefix_summary. With include_text=True, each node also carries a text field.

Local documents are always "completed" by the time submit_document returns.

Page content

Read the text of specific pages.

pages = client.get_page_content(doc_id, "5-7")
for page in pages:
    print(page["page_index"], page["markdown"][:200])

The full extraction is also available through get_ocr(doc_id, format=...), which returns page-based ("page"), node-based ("node"), or concatenated ("raw") markdown.

List

Paginated list of indexed documents, newest first.

Returns: an object with documents (array of document metadata), total, limit, and offset. Each document includes id, name, description, status, createdAt, pageNum, folderId, metadata, features, and path (the folder chain as "Parent/Child", or null when the document is unfiled or in local mode).

result = client.list_documents(limit=10)

For the next page, pass offset=10:

result = client.list_documents(limit=10, offset=10)

Delete

Permanently delete a document and all its associated data.

client.delete_document(doc_id)

{ "message": "Document deleted successfully." }

Create

result = client.create_folder("Research Papers", description="2024 research collection")
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")

{
  "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
  }
}

Upload

Assign a document to a folder during upload:

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

List documents

Filter documents by folder. Omit folder_id to list all documents; "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")
 
# 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")

{
  "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
}

Paths

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() works in both modes, returning just the name for a document at the library root or a local one. The two folder calls are cloud-only. Feed a document path straight back to get_document_id().

To ask questions within a folder, pass folder_id to LLM Integration, or use folder_context() with Agent Integration. For chat, "root" means the whole library; for document listing, it means only documents outside folders.