Skip to main content

Folder APIs

These APIs are in beta

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.

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

List folders​

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

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

Parameters​

Note: All parameters must be provided as query parameters.

ParameterTypeRequiredDefaultDescription
includestringNo Xnull

Comma-separated list of fields to include:

  • _count - Include document and favorite counts
  • labels - Include folder labels
pathstringNo Xnull

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
cursorstringNo XnullCursor for pagination positioning
pageSizenumberNo X20Number of items per page (minimum: 1)
sortFieldstringNo Xname

Field to sort by:

  • favorites - Sort by number of favorites
  • name - Sort by folder name
  • path - Sort by folder path
sortDirectionstringNo XdescSort direction (asc or desc)
labelsstringNo XnullComma-separated list of labels to filter by
scopestringNo Xorganization

Scope of folders to retrieve (organization or restricted). Note: When restricted, ownerId is required.

ownerIdstringNo* ✓nullRequired 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
  }
}
FieldTypeDescription
recordsarrayArray of folder objects matching the query
pageInfoobjectInformation about the current page of results
pageInfo.hasNextPagebooleanIf true, another page of results exists
pageInfo.nextCursorstringBase64 encoded cursor for the next page
pageInfo.pageSizenumberNumber of items on the current page
pageInfo.totalRecordsnumberTotal number of matching records
400 Bad Request
{
  "detail": "<errorReason>",
  "status": 400
}
IssueError detail
Invalid page sizeBad Request: pageSize: Page size must be at least 1
Missing required ownerIdBad Request: ownerId: ownerId is required when scope is 'restricted'
Invalid sort fieldBad Request: sortField: Invalid enum value. Expected 'name' | 'path', received '&lt;invalidField&gt;'
Invalid include parameterBad Request: include: Invalid value. Expected: _count, labels, received '&lt;invalidValue&gt;'
Invalid path patternBad Request: Invalid path pattern. Only a single wildcard (*) is allowed at the end of the pattern
404 Not Found
{
  "detail": "<errorReason>",
  "status": 404
}
IssueError detail
Parent folder not foundFolder with path <path> does not exist
Owner membership not foundUser 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.

Delete a folder​

Deletes an empty folder. This operation will only succeed if the folder has no documents or subfolders.

DELETE /api/unstable/folders/:folderId
curl -X DELETE 'https://myorg.omniapp.co/api/unstable/folders/ce3b1dcd-c768-4f01-a479-353325c4c5b0' \
--H 'Authorization: Bearer <TOKEN>' \
--H 'Content-Type: application/json'

Parameters​

ParameterTypeRequiredDefaultDescription
folderIdURL parameterYes ✓- The UUID of the folder to delete.

Response​

200 OK

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

{
  "success": true
}
FieldTypeDescription
successbooleanIndicates if the folder was successfully deleted
400 Bad Request
{
  "detail": "<errorReason>",
  "status": 400
}
IssueError detail
Folder has documentsFolders with documents cannot be deleted
Folder has subfoldersOnly empty folders can be deleted
404 Not Found
{
  "detail": "Folder with id ce3b1dcd-c768-4f01-a479-353325c4c5b0 does not exist",
  "status": 404
}
IssueError detail
Folder not foundFolder with id <folderId> does not exist
429 Too Many Requests

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