Skip to main content
GET
/
v1
/
folders
List folders
curl --request GET \
  --url https://{instance}.omniapp.co/api/v1/folders \
  --header 'Authorization: Bearer <token>'
{
  "records": [
    {
      "id": "21db26b3-466c-4791-90e7-b9ce9375426d",
      "name": "Blob Sales",
      "path": "/blob-sales",
      "scope": "organization",
      "url": "https://blobsrus.omni.co/f/blob-sales-reports",
      "owner": {
        "id": "f4df8d6e-7f69-4d54-b23b-7abfe5c4da74",
        "name": "Blob Ross"
      },
      "labels": [
        "important",
        "archived"
      ],
      "_count": {
        "documents": 15,
        "favorites": 3
      }
    }
  ],
  "pageInfo": {
    "hasNextPage": true,
    "nextCursor": "eyJpZCI6ImZvbGRlcjEyMyJ9",
    "pageSize": 20,
    "totalRecords": 45
  }
}

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)

ScopeownerIdBehavior
organizationNot providedAll organization-shared folders user has permission to access
organizationown IDOwn organization folders only
restrictedNot providedInfers owner's ID, returns own restricted folders
restrictedOwn IDOwn restricted folders
restrictedOther's ID403 Forbidden

Organization API key

ScopeownerIdBehavior
organizationNot providedAll organization folders
organizationAny IDThat user's organization folders
restrictedNot provided400 Bad Request (ownerId required)
restrictedAny IDThat 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.

​
pageInfo
object

Pagination information for paginated responses.