List folders - Omni Docs

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

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

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)

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

userId

string<uuid>

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

records

object[]

Array of folder objects matching the query.

Show child attributes

pageInfo

object

Pagination information for paginated responses.

Show child attributes