Skip to main content
GET
List folders

Authorizations

Authorization
string
header
required

Can be either an Organization API Key or Personal Access Token (PAT).

Include in the Authorization header as: Bearer YOUR_TOKEN

Query Parameters

include
string

Comma-separated list of additional fields to include:

  • _count - Include document and favorite counts

  • labels - Include folder labels

  • onlyFavorites - Returns only folders the user has favorited and can still access. Cannot be combined with onlySharedWithMe, ownerId, or path.

  • onlySharedWithMe - Returns only folders explicitly shared with the specified user via folder permissions. Excludes folders owned by the user. Cannot be combined with onlyFavorites, ownerId, or path.

    Additionally, depending on the type of API key being used:

    • Organization API keys require the userId parameter
    • Personal Access Tokens automatically infer the userId from the token
Pattern: ^\s*((_count|labels|onlyFavorites|onlySharedWithMe)\s*)?(,\s*((_count|labels|onlyFavorites|onlySharedWithMe)\s*)?)*$
path
string

Filter folders by path. Wildcards are supported and must appear at the end of the path:

  • * - Include direct children only (e.g., blob-sales/*)
  • ** - Include all descendants recursively (e.g., blob-sales/**)
labels
string[]

Comma-separated list of labels to filter by.

scope
enum<string>
default:organization

Scope of folders to retrieve.

  • When include=onlySharedWithMe or include=onlyFavorites is specified without a scope parameter, returns results of all scopes with each folder's actual scope preserved
  • Otherwise, defaults to organization

When set to restricted, the ownerId parameter behavior depends on the API key type:

  • Organization-scoped API keys: ownerId is required
  • Personal Access Tokens (PAT): ownerId is optional and auto-inferred to the token owner
Available options:
organization,
restricted
sortField
enum<string>
default:name

Field to sort by:

  • favorites - Sort by number of favorites
  • name - Sort by folder name
  • path - Sort by folder path
Available options:
favorites,
name,
path
sortDirection
enum<string>
default:desc

Sort direction.

Available options:
asc,
desc
cursor
string

Cursor for pagination positioning.

pageSize
integer
default:20

Number of items per page.

Required range: x >= 1
ownerId
string<uuid>

UUID of organization membership.

How the API behaves depends on the type of API key used to authenticate the request and the current scope value.

Personal Access Tokens (PAT)

Organization API key

userId
string<uuid>

Membership ID of the user whose folders to return. Only used with include=onlyFavorites or include=onlySharedWithMe.

Required when using an Organization API key with either flag. Automatically inferred from the token when using a Personal Access Token.

Response

Paginated folder list

records
object[]

Array of folder objects matching the query.

pageInfo
object

Pagination information for paginated responses.