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",
      "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
​
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 set to restricted, the ownerId parameter is required.

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.

Required when scope is restricted.

Response

Paginated folder list

​
records
object[]

Array of folder objects matching the query.

​
pageInfo
object

Pagination information for paginated responses.