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

Response

Paginated folder list

​
records
object[]

Array of folder objects matching the query.

​
pageInfo
object

Pagination information for paginated responses.