Get all directories (folders)
Retrieve all directories (folders) in the workspace with hierarchical structure.
This endpoint returns a paginated list of directories including their nested subfolders. Each directory includes breadcrumb navigation for easy hierarchy tracking.
Pagination is over TOP-LEVEL directories: one page row is one root folder, returned with its complete subtree. A subfolder is therefore never a page row of its own — reach it through its root’s subfolders, or use cursor mode for a flat walk of every directory. Because a page carries whole subtrees, page size in bytes is driven by how deep those trees are; prefer cursor mode for large workspaces.
Query Parameters:
-
page (optional): Page number for pagination (default: 1)
-
limit (optional): Number of TOP-LEVEL directories per page (default: 100). Subfolders nested under a returned root do not count against it, so this bounds rows, NOT total directories returned — a page whose subtrees expand past 5000 directories is rejected with 400; lower
limitor use cursor mode. -
search (optional): Case-insensitive substring match on the directory name. When present,
directoriesis a FLAT list of matches — nosubfoldersnesting — and each match carries its fullbreadcrumbspath. Omit it to get the nested tree.
Response:
The response includes:
-
directories: Array of directory objects with nested subfolders
-
count: Total number of TOP-LEVEL directories, i.e. the number of page rows across all pages. Divide by
limitfor the page count. -
currentPage: Current page number
Each directory object contains:
-
Basic information: id, name, description, status
-
Hierarchy information: parentId, depth, breadcrumbs, subfolders
-
Metadata: userId, organizationId, workspaceId
-
Timestamps: createdAt, updatedAt
-
isFromAutomatedRule: Indicates if directory was created by automation
Notes:
-
Directories are returned with their complete subfolder hierarchy
-
Breadcrumbs provide the full path from root to current directory
-
Subfolders array contains nested directories recursively
Cursor pagination: pass the cursor query parameter (empty for the first page) and the response becomes { data, pagination: { limit, nextCursor, hasMore } } where data is a FLAT list of directories — no subfolders nesting; each row carries its breadcrumbs ancestor path instead. Follow nextCursor until hasMore is false. Cursors are bound to the search value they were minted with; keep it identical for every page of a walk.
Use Cases
Folder Management
File Organization
Navigation Systems
Automation Rules
Query Parameters
cursor parameter
(empty value for the first page) to use cursor pagination; omit it entirely to
keep the legacy page/limit response shape. See
Pagination for the full comparison.How pagination works here
Pagination is over top-level directories: one page row is one root folder, returned with its complete subtree. A subfolder is never a page row of its own — reach it through its root’ssubfolders, or use cursor mode for a flat walk of
every directory.
Cursor mode returns a FLAT list
Cursor mode returns a FLAT list
{ data, pagination } and data is a flat
list of directories with no subfolders nesting. Each row carries its
breadcrumbs ancestor path instead. Follow nextCursor until hasMore is
false. Cursors are bound to the search value they were minted with — keep
it identical for every page of a walk. Prefer this mode for large workspaces.Searching flattens the tree too
Searching flattens the tree too
search is present, directories is a flat list of matches with no
subfolders nesting, and each match carries its full breadcrumbs path.
Omit search to get the nested tree.What count means
What count means
count is the total number of top-level directories —
that is, the number of page rows across all pages. Divide by limit for the
page count, not by the total number of directories in the workspace.Response Structure
Directory Object
Each directory object contains:Understanding the Hierarchy
Depth Levels
Depth Levels
depth field indicates how deep a folder is in the hierarchy:depth: 0- Root level foldersdepth: 1- First level subfoldersdepth: 2- Second level subfolders, and so on
Recursive Subfolders
Recursive Subfolders
subfolders array contains nested directories recursively. Each subfolder has the same structure as the parent directory, allowing you to traverse the entire hierarchy.Automated Folders
Automated Folders
isFromAutomatedRule: true. This helps distinguish manually created folders from those generated by workflow automation.Authorizations
API key for authentication
Query Parameters
Case-insensitive substring match on the directory name. When present, directories is a FLAT list of matches (subfolders empty); each match carries its full breadcrumbs path. In cursor mode the cursor is bound to the search value.
"invoices"
Page number
1
Number of items per page
100
Field to sort by
"createdAt"
Sort direction
ASC, DESC "ASC"
Opaque pagination cursor. Provide the parameter (empty value for the first page) to switch to cursor pagination: the response becomes { data, pagination: { limit, nextCursor, hasMore } } with default limit 50 (max 100). Omit it entirely for legacy page/limit pagination. In cursor mode sortBy must be one of createdAt, updatedAt, _id, and cursors are bound to the sortBy/sortOrder they were minted with.
Response
The directories are retrieved. Offset mode (default) returns {directories, count, currentPage} as a nested tree; cursor mode (when the cursor query parameter is present) returns {data, pagination} where data is a FLAT list (no subfolders).
- Option 1
- Option 2
Directory tree: one row per TOP-LEVEL directory, carrying its nested subfolders recursively, and each row includes breadcrumbs. Pagination applies to these root rows, so a subfolder never appears as a row of its own. With the search query param the list is FLAT matches instead (empty subfolders).
Total number of top-level directories — the number of rows across all pages, so count / limit is the page count. Not the total row count of the workspace; use cursor mode to enumerate every directory.