Skip to main content

Folder APIs

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

Create a folder​

Creates a new folder. Folders can be nested up to 7 levels.

Folder paths are automatically generated based on hierarchy. This means that child folder paths will include the paths of their parents.

POST /api/v1/folders
curl -X POST 'https://myorg.omniapp.co/api/v1/folders' \
--H 'Authorization: Bearer <TOKEN>' \
--H 'Content-Type: application/json' \
--d '{
  "name": "Root Folder",
  "scope": "restricted"
}'

Parameters​

Loading parameters...

Response​

201 Created

Successful requests will return a 201 Created status and a response body similar to the following:

{
  "id": "folder123",
  "name": "Root Folder",
  "path": "/root-folder",
  "scope": "restricted",
  "owner": {
    "id": "user123",
    "name": "John Smith"
  }
}
FieldTypeDescription
idstringUnique identifier for the created folder
namestringDisplay name of the folder
pathstringFull path to the folder
scopestringVisibility scope of the folder
ownerobjectInformation about the folder owner containing id and name
400 Bad Request
{
  "detail": "<errorReason>",
  "status": 400
}
IssueError detail
Invalid JSONBad Request: Invalid JSON
Missing required fieldsBad Request: name: Required
Folder nesting limitBad Request: Maximum folder nesting depth reached
Scope mismatchBad Request: Child folder scope must match parent folder scope
404 Not Found
{
  "detail": "<errorReason>",
  "status": 404
}
IssueError detail
Parent folder not foundParent folder with id <parentFolderId> does not exist
User not foundUser with id <userId> 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.

List folders​

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

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

Parameters​

Note: All parameters must be provided as query parameters.

Loading parameters...

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

Parameters​

Loading parameters...

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.