Enhance documentation for folder management and nested folder support across SDK methods. Update parameters to include folder_name and folder_depth for scoping in various document and graph operations. (#21)

Author: Adityav369

python-sdk/add_document_to_folder.mdx

@@ -24,7 +24,7 @@ description: "Add an existing document to a folder"
 
 ## Parameters
 
-- `folder_id_or_name` (str): Folder identifier. Accepts either the folder's UUID or its name.
+- `folder_id_or_name` (str): Folder identifier. Accepts the folder's UUID, name, or canonical path (e.g., `/projects/alpha/specs`; leading slash optional).
 - `document_id` (str): Identifier of the document to move into the folder.
 
 ## Returns
@@ -42,7 +42,7 @@ description: "Add an existing document to a folder"
     folder = db.get_folder("marketing_docs")
 
     db.add_document_to_folder(folder.id, "doc_123")
-    db.add_document_to_folder("marketing_docs", "doc_456")
+    db.add_document_to_folder("/projects/alpha/specs", "doc_456")
     ```
   </Tab>
   <Tab title="Async">
@@ -53,7 +53,7 @@ description: "Add an existing document to a folder"
         folder = await db.get_folder("marketing_docs")
 
         await db.add_document_to_folder(folder.id, "doc_123")
-        await db.add_document_to_folder("marketing_docs", "doc_456")
+        await db.add_document_to_folder("/projects/alpha/specs", "doc_456")
     ```
   </Tab>
 </Tabs>

python-sdk/batch_get_chunks.mdx

@@ -29,7 +29,7 @@ description: "Retrieve specific chunks by their document ID and chunk number"
 ## Parameters
 
 - `sources` (List[Union[ChunkSource, Dict[str, Any]]]): List of ChunkSource objects or dictionaries with document_id and chunk_number
-- `folder_name` (str | List[str], optional): Optional folder scope. Accepts a single folder name or a list of folder names.
+- `folder_name` (str | List[str], optional): Optional folder scope. Accepts canonical paths or a list of paths/names.
 - `use_colpali` (bool, optional): Whether to request multimodal chunks when available. Defaults to True.
 - `output_format` (str, optional): Controls how image chunks are returned. Set to `"url"` to receive presigned URLs; omit or set to `"base64"` (default) to receive base64 content.
 
@@ -100,4 +100,4 @@ Each `FinalChunkResult` object in the returned list has the following properties
 - `metadata` (Dict[str, Any]): Document metadata
 - `content_type` (str): Content type
 - `filename` (Optional[str]): Original filename
-- `download_url` (Optional[str]): URL to download full document 
+- `download_url` (Optional[str]): URL to download full document 

python-sdk/batch_get_documents.mdx

@@ -25,7 +25,7 @@ description: "Retrieve multiple documents by their IDs in a single batch operati
 ## Parameters
 
 - `document_ids` (List[str]): List of document IDs to retrieve
-- `folder_name` (str | List[str], optional): Optional folder scope. Accepts a single folder name or a list of folder names.
+- `folder_name` (str | List[str], optional): Optional folder scope. Accepts canonical paths or a list of paths/names.
 
 ## Returns
 
@@ -67,4 +67,5 @@ Each `Document` object in the returned list has the following properties:
 - `metadata` (Dict[str, Any]): User-defined metadata
 - `storage_info` (Dict[str, str]): Storage-related information
 - `system_metadata` (Dict[str, Any]): System-managed metadata
-- `chunk_ids` (List[str]): IDs of document chunks 
+- `chunk_ids` (List[str]): IDs of document chunks
+- `folder_path` (Optional[str]): Canonical folder path (includes nested parents when scoped)

python-sdk/create_folder.mdx

@@ -9,6 +9,8 @@ description: "Create a new folder for organizing documents"
     def create_folder(
         name: str,
         description: Optional[str] = None,
+        full_path: Optional[str] = None,
+        parent_id: Optional[str] = None,
     ) -> Folder
     ```
   </Tab>
@@ -17,17 +19,19 @@ description: "Create a new folder for organizing documents"
     async def create_folder(
         name: str,
         description: Optional[str] = None,
+        full_path: Optional[str] = None,
+        parent_id: Optional[str] = None,
     ) -> Folder
     ```
   </Tab>
 </Tabs>
 
 ## Parameters
 
-- `name` (str): Folder name. Must be unique per app and cannot contain `/`.
+- `name` (str): Folder name (leaf segment when using nested paths). If `full_path` is omitted, this becomes the canonical path.
 - `description` (str, optional): Optional description of the folder.
-
-> ⚠️ Nested folders are not supported. Use underscores (`_`) to mimic hierarchy (e.g., `team_reports_q1`).
+- `full_path` (str, optional): Canonical folder path (e.g., `"/projects/alpha/specs"`). Leading slash is optional; parents are created automatically.
+- `parent_id` (str, optional): Explicit parent folder ID. Usually not needed—`full_path` handles hierarchy creation.
 
 ## Returns
 
@@ -39,9 +43,17 @@ description: "Create a new folder for organizing documents"
   <Tab title="Sync">
     ```python
     from morphik import Morphik
-
+    
     db = Morphik()
     folder = db.create_folder("marketing_docs", description="All marketing collateral")
+
+    # Create a nested folder (parents auto-created)
+    nested = db.create_folder(
+        name="specs",
+        full_path="/projects/alpha/specs",
+        description="All project specs",
+    )
+    print(nested.full_path)  # "/projects/alpha/specs"
     ```
   </Tab>
   <Tab title="Async">
@@ -50,6 +62,13 @@ description: "Create a new folder for organizing documents"
 
     async with AsyncMorphik() as db:
         folder = await db.create_folder("marketing_docs", description="All marketing collateral")
+
+        nested = await db.create_folder(
+            name="specs",
+            full_path="/projects/alpha/specs",
+            description="All project specs",
+        )
+        print(nested.full_path)  # "/projects/alpha/specs"
     ```
   </Tab>
 </Tabs>

python-sdk/create_graph.mdx

@@ -11,6 +11,8 @@ description: "Create a graph from documents"
         filters: Optional[Dict[str, Any]] = None,
         documents: Optional[List[str]] = None,
         prompt_overrides: Optional[Union[GraphPromptOverrides, Dict[str, Any]]] = None,
+        folder_name: Optional[Union[str, List[str]]] = None,
+        end_user_id: Optional[str] = None,
     ) -> Graph
     ```
   </Tab>
@@ -21,6 +23,8 @@ description: "Create a graph from documents"
         filters: Optional[Dict[str, Any]] = None,
         documents: Optional[List[str]] = None,
         prompt_overrides: Optional[Union[GraphPromptOverrides, Dict[str, Any]]] = None,
+        folder_name: Optional[Union[str, List[str]]] = None,
+        end_user_id: Optional[str] = None,
     ) -> Graph
     ```
   </Tab>
@@ -32,6 +36,8 @@ description: "Create a graph from documents"
 - `filters` (Dict[str, Any], optional): Optional metadata filters to determine which documents to include
 - `documents` (List[str], optional): Optional list of specific document IDs to include
 - `prompt_overrides` (GraphPromptOverrides | Dict[str, Any], optional): Optional customizations for entity extraction and resolution prompts
+- `folder_name` (str | List[str], optional): Optional folder scope (canonical path or list of paths/names)
+- `end_user_id` (str, optional): Optional end-user scope
 
 ## Returns
 
@@ -57,6 +63,7 @@ graph is done, or poll `graph.is_processing` / `graph.is_completed`.
     graph = db.create_graph(
         name="research_graph",
         filters={"category": "research"},
+        folder_name="/projects/alpha",
     )
 
     # Option 1: Block until finished
@@ -127,6 +134,7 @@ graph is done, or poll `graph.is_processing` / `graph.is_completed`.
         graph = await db.create_graph(
             name="research_graph",
             filters={"category": "research"},
+            folder_name="/projects/alpha",
         )
 
         # Wait for completion
@@ -206,3 +214,4 @@ The returned `Graph` object has the following properties:
 - `created_at` (datetime): Creation timestamp
 - `updated_at` (datetime): Last update timestamp
 - `owner` (Dict[str, str]): Graph owner information
+- `folder_path` (Optional[str]): Canonical folder path for the graph (if scoped)

python-sdk/delete_folder.mdx

@@ -22,7 +22,7 @@ description: "Delete a folder and its documents"
 
 ## Parameters
 
-- `folder_id_or_name` (str): Folder identifier. Accepts either the folder's UUID or its name.
+- `folder_id_or_name` (str): Folder identifier. Accepts the folder's UUID, name, or canonical path (e.g., `/projects/alpha/specs`; leading slash optional).
 
 ## Returns
 
@@ -37,6 +37,7 @@ description: "Delete a folder and its documents"
 
     db = Morphik()
     db.delete_folder("marketing_docs")
+    db.delete_folder("/projects/alpha/specs")
     db.delete_folder("bfd74128-8539-4050-8938-542d6ee68be0")
     ```
   </Tab>
@@ -46,6 +47,7 @@ description: "Delete a folder and its documents"
 
     async with AsyncMorphik() as db:
         await db.delete_folder("marketing_docs")
+        await db.delete_folder("/projects/alpha/specs")
         await db.delete_folder("bfd74128-8539-4050-8938-542d6ee68be0")
     ```
   </Tab>

python-sdk/folders.mdx

@@ -7,7 +7,7 @@ description: "Organize and isolate data into logical folder groups in Morphik"
 
 Folders in Morphik provide a way to organize documents into logical groups. This is particularly useful for multi-project environments where you want to maintain separation between different contexts. Documents within a folder are isolated from those in other folders, allowing for clean organization and data separation.  
 
-> ℹ️ All folder APIs accept **either the folder’s UUID or its name**. Use whichever identifier you already have—Morphik resolves it automatically.
+> ℹ️ All folder APIs accept **folder UUIDs, names, or canonical paths** (e.g., `"/projects/alpha/specs"`). Folder objects expose `full_path`, `parent_id`, `depth`, and `child_count`; documents and graphs expose `folder_path` to mirror server responses.
 
 ## Creating and Accessing Folders
 
@@ -20,9 +20,12 @@ Folders in Morphik provide a way to organize documents into logical groups. This
 
     # Create a new folder
     folder = db.create_folder("marketing_docs")
+
+    # Create a nested folder (parents created automatically)
+    nested = db.create_folder(full_path="/projects/alpha/specs")
 
-    # Access an existing folder by name or UUID
-    folder = db.get_folder("marketing_docs")
+    # Access an existing folder by name/path or UUID
+    folder = db.get_folder("/projects/alpha")
     folder_by_id = db.get_folder(folder.id)
     ```
   </Tab>
@@ -32,10 +35,12 @@ Folders in Morphik provide a way to organize documents into logical groups. This
 
     async with AsyncMorphik() as db:
         # Create a new folder
-        folder = db.create_folder("marketing_docs")
+        folder = await db.create_folder("marketing_docs")
+
+        nested = await db.create_folder(full_path="/projects/alpha/specs")
 
-        # Access an existing folder by name or UUID
-        folder = await db.get_folder("marketing_docs")
+        # Access an existing folder by name/path or UUID
+        folder = await db.get_folder("/projects/alpha")
         folder_by_id = await db.get_folder(folder.id)
     ```
   </Tab>
@@ -88,6 +93,23 @@ Once you have a folder object, all operations performed on it are scoped to that
   </Tab>
 </Tabs>
 
+## Nested Folders and Scope Depth
+
+Folders can be nested arbitrarily. Use canonical paths (leading slash optional) to address them, and include descendant folders in retrieval/listing by setting `folder_depth`:
+
+```python
+folder = db.create_folder(full_path="/projects/alpha/specs")
+
+# Query across /projects/alpha and all children
+chunks = db.retrieve_chunks(
+    query="design notes",
+    folder_name="/projects/alpha",
+    folder_depth=-1,  # -1: all descendants, 0/None: exact only, n>0: include up to n levels
+)
+```
+
+Folder-scoped helpers inherit the path automatically, so `folder.retrieve_chunks(..., folder_depth=-1)` will include its children.
+
 ## Folder Methods
 
 All the core document operations available on the main Morphik client are also available on folder objects, but they are automatically scoped to the specific folder:
@@ -108,7 +130,7 @@ All the core document operations available on the main Morphik client are also a
 
 ## Managing Existing Documents and Folders
 
-You can move previously ingested documents into a folder, remove them, or delete the entire folder. The SDK methods accept a folder name or UUID.
+You can move previously ingested documents into a folder, remove them, or delete the entire folder. The SDK methods accept a folder UUID, name, or canonical path.
 
 <Tabs>
   <Tab title="Sync">
@@ -120,9 +142,9 @@ You can move previously ingested documents into a folder, remove them, or delete
 
     document_id = "doc_123"
 
-    # Add an existing document to the folder (name or UUID works)
+    # Add an existing document to the folder (name/path or UUID works)
     db.add_document_to_folder(folder.id, document_id)
-    db.add_document_to_folder("marketing_docs", document_id)
+    db.add_document_to_folder("/projects/alpha/specs", document_id)
 
     # Remove the document from the folder
     db.remove_document_from_folder("marketing_docs", document_id)
@@ -140,7 +162,7 @@ You can move previously ingested documents into a folder, remove them, or delete
         document_id = "doc_123"
 
         await db.add_document_to_folder(folder.id, document_id)
-        await db.add_document_to_folder("marketing_docs", document_id)
+        await db.add_document_to_folder("/projects/alpha/specs", document_id)
 
         await db.remove_document_from_folder("marketing_docs", document_id)
 

python-sdk/get_folder.mdx

@@ -1,6 +1,6 @@
 ---
 title: "get_folder"
-description: "Retrieve a folder by name or UUID"
+description: "Retrieve a folder by name, canonical path, or UUID"
 ---
 
 <Tabs>
@@ -22,12 +22,14 @@ description: "Retrieve a folder by name or UUID"
 
 ## Parameters
 
-- `folder_id_or_name` (str): Folder identifier. Accepts either the folder's UUID or its name.
+- `folder_id_or_name` (str): Folder identifier. Accepts the folder's UUID, name, or canonical path (e.g., `/projects/alpha/specs`; leading slash optional).
 
 ## Returns
 
 - `Folder`: Folder object that can be used to scope operations (ingest, query, etc.).
 
+Folder objects include hierarchy metadata such as `full_path`, `parent_id`, `depth`, and `child_count`, mirroring the server response.
+
 ## Examples
 
 <Tabs>

python-sdk/get_folders_details.mdx

@@ -40,7 +40,7 @@ description: "Get detailed information about folders with optional document stat
 
 ## Parameters
 
-- `identifiers` (List[str], optional): List of folder IDs or names. If None, returns all accessible folders.
+- `identifiers` (List[str], optional): List of folder IDs, names, or canonical paths (e.g., `/projects/alpha/specs`). If None, returns all accessible folders.
 - `include_document_count` (bool, optional): Include total document count. Defaults to True.
 - `include_status_counts` (bool, optional): Include document counts grouped by processing status. Defaults to False.
 - `include_documents` (bool, optional): Include paginated document list. Defaults to False.
@@ -79,7 +79,7 @@ Filters follow the same JSON syntax across the API. See the [Metadata Filtering
 
     # Get specific folders with status counts
     response = db.get_folders_details(
-        identifiers=["reports", "invoices"],
+        identifiers=["/projects/reports", "invoices"],
         include_status_counts=True,
     )
     for folder_detail in response.folders:
@@ -176,6 +176,8 @@ Filters follow the same JSON syntax across the API. See the [Metadata Filtering
 - `folder` (FolderInfo): Folder information
 - `document_info` (FolderDocumentInfo | None): Document statistics and list
 
+`FolderInfo` includes hierarchy fields: `full_path`, `parent_id`, `depth`, and `child_count`, plus description/name metadata.
+
 ### FolderDocumentInfo
 
 - `total_count` (int | None): Total document count (when `include_document_count=True`)

python-sdk/get_folders_summary.mdx

@@ -78,6 +78,9 @@ The `FolderSummary` objects have the following properties:
 
 - `id` (str): Unique folder identifier
 - `name` (str): Folder name
+- `full_path` (str | None): Canonical folder path (e.g., `/projects/alpha/specs`)
+- `parent_id` (str | None): Parent folder ID
+- `depth` (int | None): Depth in the hierarchy (root = 1)
 - `description` (str | None): Folder description
 - `doc_count` (int): Number of documents in the folder
 - `updated_at` (str | None): Last update timestamp