Folder APIs

Heads up!

The folder APIs are in beta and may have future breaking changes.

The folder APIs allow you to manage and organize content hierarchically within your Omni organization.

Folder object

Represents a folder in Omni.

Example

{
  "id": "folder123",
  "name": "Documents",
  "path": "/documents",
  "scope": "organization",
  "type": "folder",
  "owner": {
    "id": "user123",
    "name": "John Smith"
  },
  "labels": ["important", "archived"],
  "_count": {
    "documents": 15,
    "favorites": 3
  }
}

Fields

Field	Type	Description
id	string	Unique identifier for the folder
name	string	Display name of the folder
path	string	Full path to the folder
scope	string	Visibility scope. Must be one of: organization - Organization-wide access restricted - Limited access
owner	object	Information about the folder owner containing id (string) and name (string)
labels	array	List of labels associated with the folder. Only included when requested via include parameter.
_count	object	Contains count information. Only included when requested via include parameter.
_count.documents	number	Number of documents contained in the folder
_count.favorites	number	Number of users who have favorited this folder

List folders

Retrieves a paginated list of folders within an organization. This endpoint supports filtering, sorting, and cursor-based pagination.

Basic request

GET /api/unstable/folders

curl -X GET 'https://myorg.omniapp.co/api/unstable/folders' \
--H 'Authorization: Bearer <TOKEN>' \
--H 'Content-Type: application/json'

With includes

GET /api/unstable/folders?include=_count,labels

curl -X GET 'https://myorg.omniapp.co/api/unstable/folders?include=_count,labels' \
--H 'Authorization: Bearer <TOKEN>' \
--H 'Content-Type: application/json'

Path filtering

GET /api/unstable/folders?path=/documents/*

curl -X GET 'https://myorg.omniapp.co/api/unstable/folders?path=/documents/*' \
--H 'Authorization: Bearer <TOKEN>' \
--H 'Content-Type: application/json'

Filters & sorting

GET /api/unstable/folders?labels=<labels>&scope=<scope>&sortField=<field>&sortDirection=<direction>

curl -X GET 'https://myorg.omniapp.co/api/unstable/folders?labels=important,archived&scope=restricted&sortField=name&sortDirection=desc' \
--H 'Authorization: Bearer <TOKEN>' \
--H 'Content-Type: application/json'

Pagination with cursor

GET /api/unstable/folders?cursor=<cursor>&pageSize=<size>

curl -X GET 'https://myorg.omniapp.co/api/unstable/folders?cursor=eyJpZCI6ImZvbGRlcjEyMyJ9&pageSize=20' \
--H 'Authorization: Bearer <TOKEN>' \
--H 'Content-Type: application/json'

Parameters

Note: All parameters must be provided as query parameters.

Parameter	Type	Required	Default	Description
include	string	No X	null	Comma-separated list of fields to include: _count - Include document and favorite counts labels - Include folder labels
path	string	No X	null	Filter folders by path. Supports: Exact matching (e.g. /documents) Wildcard for children (e.g. /documents/*) Note: Wildcard can only appear at end of path
cursor	string	No X	null	Cursor for pagination positioning
pageSize	number	No X	20	Number of items per page (minimum: 1)
sortField	string	No X	name	Field to sort by: favorites - Sort by number of favorites name - Sort by folder name path - Sort by folder path
sortDirection	string	No X	desc	Sort direction (asc or desc)
labels	string	No X	null	Comma-separated list of labels to filter by
scope	string	No X	organization	Scope of folders to retrieve (organization or restricted). Note: When restricted, ownerId is required.
ownerId	string	No* ✓	null	Required when scope is restricted. UUID of organization membership.

Response

200 OK

Successful requests will return a 200 OK status and a response body similar to the following:

{
  "records": [
    {
      "id": "folder123",
      "name": "Documents",
      "path": "/documents",
      "scope": "organization",
      "owner": {
        "id": "user123",
        "name": "John Smith"
      },
      "labels": ["important", "archived"],
      "_count": {
        "documents": 15,
        "favorites": 3
      }
    }
  ],
  "pageInfo": {
    "hasNextPage": true,
    "nextCursor": "eyJpZCI6ImZvbGRlcjEyMyJ9",
    "pageSize": 20,
    "totalRecords": 45
  }
}

Field	Type	Description
records	array	Array of folder objects matching the query
pageInfo	object	Information about the current page of results
pageInfo.hasNextPage	boolean	If true, another page of results exists
pageInfo.nextCursor	string	Base64 encoded cursor for the next page
pageInfo.pageSize	number	Number of items on the current page
pageInfo.totalRecords	number	Total number of matching records

400 Bad Request

{
  "detail": "<errorReason>",
  "schemas": ["urn:ietf:params:scim:api:messages:2.0:Error"],
  "status": 400
}

Issue	Error detail
Invalid page size	Bad Request: pageSize: Page size must be at least 1
Missing required ownerId	Bad Request: ownerId: ownerId is required when scope is 'restricted'
Invalid sort field	Bad Request: sortField: Invalid enum value. Expected 'name' | 'path', received '<invalidField>'
Invalid include parameter	Bad Request: include: Invalid value. Expected: _count, labels, received '<invalidValue>'
Invalid path pattern	Bad Request: Invalid path pattern. Only a single wildcard (*) is allowed at the end of the pattern

404 Not Found

{
  "detail": "<errorReason>",
  "schemas": ["urn:ietf:params:scim:api:messages:2.0:Error"],
  "status": 404
}

Issue	Error detail
Parent folder not found	Folder with path <path> does not exist
Owner membership not found	User membership not found

429 Too Many Requests

Results from too many requests in a given time frame. Refer to the Rate limiting documentation for more information.