v1
latestOpenAPI 3.1.02026-07-2618690613.4 KBList folders
Retrieve a paginated list of folders within an organization. Supports filtering, sorting, and cursor-based pagination.
The folders endpoint behaves differently based on the type of API key used to authenticate the request:
- Organization-scoped API keys: Full access to all folders. Can view any user's restricted folders with ownerId. Must provide ownerId for scope=restricted.
- Personal Access Tokens (PAT): Permission-filtered access matching the UI.
- For scope=organization - Returns all organization-shared folders the user can access
- For scope=restricted - Returns only the user's own restricted folders. An ownerId is optional; if not provided, it will be auto-inferred and the API will return only the folders belonging to PAT owner.
Query parameters
Comma-separated list of additional fields to include:
-
_count - Include document and favorite counts
-
labels - Include folder labels
-
onlySharedWithMe - Returns only folders explicitly shared with the specified user via folder permissions. Excludes folders owned by the user. Cannot be combined with 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
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/**)
Comma-separated list of labels to filter by.
Scope of folders to retrieve.
- When include=onlySharedWithMe is specified without a scope parameter, returns shared folders 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
Field to sort by:
- favorites - Sort by number of favorites
- name - Sort by folder name
- path - Sort by folder path
Sort direction.
Cursor for pagination positioning.
Number of items per page.
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)
| Scope | ownerId | Behavior |
|---|---|---|
| organization | Not provided | All organization-shared folders user has permission to access |
| organization | own ID | Own organization folders only |
| restricted | Not provided | Infers owner's ID, returns own restricted folders |
| restricted | Own ID | Own restricted folders |
| restricted | Other's ID | 403 Forbidden |
Organization API key
| Scope | ownerId | Behavior |
|---|---|---|
| organization | Not provided | All organization folders |
| organization | Any ID | That user's organization folders |
| restricted | Not provided | 400 Bad Request (ownerId required) |
| restricted | Any ID | That user's restricted folders |
The ID of a standard or embed user to filter results, returning only folders the specified user can view based on their permissions.
If include=onlyFavorites is specified:
- And using an Organization API key, this parameter is required
- And using a Personal Access Token, the userId will be automatically inferred from the token
Response
Paginated folder list
Example response
{
"records": [
{
"url": "https://blobsrus.omni.co/f/blob-sales-reports"
}
]
}