GET
Get all directories (folders)
Request · Guide: Folders
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 limit or use cursor mode.
  • search (optional): Case-insensitive substring match on the directory name. When present, directories is a FLAT list of matches — no subfolders nesting — and each match carries its full breadcrumbs path. 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 limit for 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.

Authorizations

​
x-api-key
string
header
required

API key for authentication

Query Parameters

​
search
string

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.

Example:

"invoices"

​
page
number
default:1

Page number

Example:

1

​
limit
number
default:100

Number of items per page

Example:

100

​
sortBy
string
default:createdAt

Field to sort by

Example:

"createdAt"

​
sortOrder
enum<string>
default:ASC

Sort direction

Available options:
ASC,
DESC
Example:

"ASC"

​
cursor
string

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

​
directories
object[]
required

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

​
count
number
required

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.

​
currentPage
number
required