# Kiteworks API — folders Operations
**36 endpoints** | [Browse interactive reference](https://developer.kiteworks.com/api-reference/folders.html) | [Download spec slice](https://developer.kiteworks.com/assets/specs/folders.json)
> **Authentication required.** All requests must include a Bearer access token in the
> `Authorization` header. See [Authentication](https://developer.kiteworks.com/authentication.md) for how to
> obtain a token using OAuth 2.0 Authorization Code (PKCE) or JWT Bearer flow.
---
## DELETE /rest/folders
**Summary:** Delete a list of folders
Deletes multiple folders specified in the request.
**Parameters:**
| Name | In | Required | Description |
|------|----|----------|-------------|
| `id:in` | query | yes | A comma-separated list of unique identifiers for the entities to be processed.. A comma-separated list of unique identifiers for the entities to be processed. |
| `partialSuccess` | query | no | If set to `true`, the operation will continue for the valid items even if some items result in failure. |
| `mode` | query | no | Determines the detail level of the response body. |
**Responses:**
| Code | Description |
|------|-------------|
| 204 | The specified folders were deleted. No content is returned. |
| 490 | Request blocked by WAF |
**Code Samples:**
**cURL:**
```shell
curl -X DELETE \
"https://{instance}.kiteworks.com/rest/folders?id:in=VALUE" \
-H "Authorization: Bearer YOUR_TOKEN"
```
**Python:**
```python
import requests
url = "https://{instance}.kiteworks.com/rest/folders"
headers = {
"Authorization": "Bearer YOUR_TOKEN",
}
params = {
"id:in": "VALUE",
}
response = requests.delete(url, params=params, headers=headers)
print(response.json())
```
---
## DELETE /rest/folders/actions/permanent
**Summary:** Permanently delete the specified folders
Permanently delete the specified folders.
These folders will no longer be accessible by any means.
**Parameters:**
| Name | In | Required | Description |
|------|----|----------|-------------|
| `id:in` | query | yes | A comma-separated list of unique identifiers for the entities to be processed.. A comma-separated list of unique identifiers for the entities to be processed. |
| `partialSuccess` | query | no | If set to `true`, the operation will continue for the valid items even if some items result in failure. |
| `mode` | query | no | Determines the detail level of the response body. |
**Responses:**
| Code | Description |
|------|-------------|
| 204 | The specified folders were permanently deleted. No content is returned. |
| 490 | Request blocked by WAF |
**Code Samples:**
**cURL:**
```shell
curl -X DELETE \
"https://{instance}.kiteworks.com/rest/folders/actions/permanent?id:in=VALUE" \
-H "Authorization: Bearer YOUR_TOKEN"
```
**Python:**
```python
import requests
url = "https://{instance}.kiteworks.com/rest/folders/actions/permanent"
headers = {
"Authorization": "Bearer YOUR_TOKEN",
}
params = {
"id:in": "VALUE",
}
response = requests.delete(url, params=params, headers=headers)
print(response.json())
```
---
## PATCH /rest/folders/actions/recover
**Summary:** Recover deleted folders
Recover deleted folders and their children files and folders.
**Parameters:**
| Name | In | Required | Description |
|------|----|----------|-------------|
| `id:in` | query | yes | A comma-separated list of unique identifiers for the entities to be processed.. A comma-separated list of unique identifiers for the entities to be processed. |
| `partialSuccess` | query | no | If set to `true`, the operation will continue for the valid items even if some items result in failure. |
| `returnEntity` | query | no | If set to `true`, returns information about the newly created entity. |
| `mode` | query | no | Determines the detail level of the response body. |
**Responses:**
| Code | Description |
|------|-------------|
| 200 | Returns the list of recovered folders with their updated metadata. |
| 490 | Request blocked by WAF |
**Response Examples:**
**200 (RecoveredFolders):**
```json
[
{
"id": "abc12345def67890ab",
"name": "Reports",
"type": "d",
"parent_id": "xyz98765cba43210fe",
"deleted": false,
"modified": "2024-07-01T10:00:00+0000",
"avStatus": "clean",
"dlpStatus": "clean"
}
]
```
**Code Samples:**
**cURL:**
```shell
curl -X PATCH \
"https://{instance}.kiteworks.com/rest/folders/actions/recover?id:in=VALUE" \
-H "Authorization: Bearer YOUR_TOKEN"
```
**Python:**
```python
import requests
url = "https://{instance}.kiteworks.com/rest/folders/actions/recover"
headers = {
"Authorization": "Bearer YOUR_TOKEN",
}
params = {
"id:in": "VALUE",
}
response = requests.patch(url, params=params, headers=headers)
print(response.json())
```
---
## POST /rest/folders/actions/scan
**Summary:** Triggers on demand AV/DLP scan on multiple folders
Attempts to trigger an AV/DLP scan on requested folders.
**Parameters:**
| Name | In | Required | Description |
|------|----|----------|-------------|
| `returnEntity` | query | no | If set to `true`, returns information about the newly created entity. |
| `id:in` | query | yes | List of IDs of entities to scan. Search for results that match any of the specified values for this parameter. |
| `with` | query | no | With parameters |
| `mode` | query | no | Determines the detail level of the response body. |
**Responses:**
| Code | Description |
|------|-------------|
| 200 | Returns the list of folders with their scan status updated to reflect that scans have been triggered. |
| 490 | Request blocked by WAF |
**Response Examples:**
**200 (BulkScanTriggered):**
```json
[
{
"id": "abc12345def67890ab",
"name": "Reports",
"type": "d",
"parent_id": "xyz98765cba43210fe",
"deleted": false,
"avStatus": "pending",
"dlpStatus": "pending"
},
{
"id": "def67890abc12345fe",
"name": "Archives",
"type": "d",
"parent_id": "xyz98765cba43210fe",
"deleted": false,
"avStatus": "pending",
"dlpStatus": "pending"
}
]
```
**Code Samples:**
**cURL:**
```shell
curl -X POST \
"https://{instance}.kiteworks.com/rest/folders/actions/scan?id:in=VALUE" \
-H "Authorization: Bearer YOUR_TOKEN"
```
**Python:**
```python
import requests
url = "https://{instance}.kiteworks.com/rest/folders/actions/scan"
headers = {
"Authorization": "Bearer YOUR_TOKEN",
}
params = {
"id:in": "VALUE",
}
response = requests.post(url, params=params, headers=headers)
print(response.json())
```
---
## GET /rest/folders/shared
**Summary:** List top level shared folders
Return the list of top level shared folders.
**Parameters:**
| Name | In | Required | Description |
|------|----|----------|-------------|
| `name` | query | no | Folder name |
| `name:contains` | query | no | Folder name. Search for results that contain the specified characters in this parameter. |
| `userId` | query | no | Unique identifier of Object creator |
| `userId:in` | query | no | Unique identifier of Object creator. Search for results that match any of the specified values for this parameter. |
| `created` | query | no | Object creation date |
| `created:gt` | query | no | Object creation date. Search for results where this parameter value is greater than the specified value. |
| `created:gte` | query | no | Object creation date. Search for results where this parameter value is greater than or equal to the specified value. |
| `created:lt` | query | no | Object creation date. Search for results where this parameter value is less than the specified value. |
| `created:lte` | query | no | Object creation date. Search for results where this parameter value is less than or equal to the specified value. |
| `modified` | query | no | Object modification date |
| `modified:gt` | query | no | Object modification date. Search for results where this parameter value is greater than the specified value. |
| `modified:gte` | query | no | Object modification date. Search for results where this parameter value is greater than or equal to the specified value. |
| `modified:lt` | query | no | Object modification date. Search for results where this parameter value is less than the specified value. |
| `modified:lte` | query | no | Object modification date. Search for results where this parameter value is less than or equal to the specified value. |
| `deleted` | query | no | Indicates whether the object is deleted. |
| `expire` | query | no | Expiration date |
| `expire:gt` | query | no | Expiration date. Search for results where this parameter value is greater than the specified value. |
| `expire:gte` | query | no | Expiration date. Search for results where this parameter value is greater than or equal to the specified value. |
| `expire:lt` | query | no | Expiration date. Search for results where this parameter value is less than the specified value. |
| `expire:lte` | query | no | Expiration date. Search for results where this parameter value is less than or equal to the specified value. |
| `fileLifetime` | query | no | Folder lifetime |
| `fileLifetime:gt` | query | no | Folder lifetime. Search for results where this parameter value is greater than the specified value. |
| `fileLifetime:gte` | query | no | Folder lifetime. Search for results where this parameter value is greater than or equal to the specified value. |
| `fileLifetime:lt` | query | no | Folder lifetime. Search for results where this parameter value is less than the specified value. |
| `fileLifetime:lte` | query | no | Folder lifetime. Search for results where this parameter value is less than or equal to the specified value. |
| `secure` | query | no | Folder secure flag |
| `description:contains` | query | no | Folder description. Search for results that contain the specified characters in this parameter. |
| `sharedByMe` | query | no | Filter shared folders by direction. Use `true` to return only folders shared by me, `false` for folders shared with me, or omit to return both. |
| `orderBy` | query | no | Sorting options |
| `offset` | query | no | Offset |
| `limit` | query | no | Limit |
| `with` | query | no | With parameters |
| `mode` | query | no | Determines the detail level of the response body. |
**Responses:**
| Code | Description |
|------|-------------|
| 200 | Returns a paginated list of top-level folders shared with the current user. |
| 490 | Request blocked by WAF |
**Response Examples:**
**200 (SharedFolderList):**
```json
[
{
"id": "abc12345def67890ab",
"name": "Team Workspace",
"description": "Shared team files",
"type": "d",
"parent_id": "xyz98765cba43210fe",
"deleted": false,
"created": "2024-01-10T09:00:00+0000",
"modified": "2024-06-20T11:30:00+0000",
"syncable": false,
"secure": false,
"isFavorite": true,
"isShared": true,
"totalFilesCount": 25,
"totalFoldersCount": 5,
"totalMembersCount": 8,
"avStatus": "clean",
"dlpStatus": "clean"
}
]
```
**Code Samples:**
**cURL:**
```shell
curl -X GET \
"https://{instance}.kiteworks.com/rest/folders/shared" \
-H "Authorization: Bearer YOUR_TOKEN"
```
**Python:**
```python
import requests
url = "https://{instance}.kiteworks.com/rest/folders/shared"
headers = {
"Authorization": "Bearer YOUR_TOKEN",
}
response = requests.get(url, headers=headers)
print(response.json())
```
---
## POST /rest/folders/{id}/actions/move
**Summary:** Move a folder
### Description:
Moves the specified folder to a new destination folder.
### Precondition:
User must have `folder_move` permission for the folder being moved.
User must have `folder_add` permission for the destination folder.
### Response:
The folder is moved to the destination folder.
**Parameters:**
| Name | In | Required | Description |
|------|----|----------|-------------|
| `id` | path | yes | The unique identifier (UUID) of the entity. |
| `returnEntity` | query | no | If true, includes the entity in the response body. |
| `with` | query | no | Specifies additional fields to include in the response. |
| `mode` | query | no | Determines the detail level of the response body. |
**Request Body:**
| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `destinationFolderId` | string | yes | The ID of the destination folder where the item will be copied/moved. |
| `addVersion` | boolean | no | If a file with the same name exists, create a new version instead of overwriting it. Default is True. |
**Responses:**
| Code | Description |
|------|-------------|
| 201 | Folder successfully moved |
| 401 | Unauthorized Possible error codes: ERR_AUTH_INVALID_CSRF, ERR_AUTH_UNAUTHORIZED |
| 403 | Forbidden Possible error codes: ERR_ACCESS_USER, ERR_ENTITY_CONTAINS_LOCKED_FILES, ERR_ENTITY_IS_BASE_DIR, ERR_ENTITY_IS_MY_DIR, ERR_ENTITY_IS_SECURE_FOLDER, ERR_ENTITY_IS_SYNC_DIR |
| 409 | Conflict Possible error codes: ERR_ENTITY_EXISTS |
| 413 | Content Too Large Possible error codes: ERR_SYSTEM_NO_STORAGE_AVAILABLE |
| 422 | Unprocessable Content Possible error codes: ERR_CANNOT_MOVE_FOLDER_TO_SELF, ERR_CANNOT_MOVE_TO_CHILD, ERR_INVALID_PARAMETER |
| 490 | Request blocked by WAF |
**Response Examples:**
**401 (ERR_AUTH_INVALID_CSRF):**
```json
{
"errors": [
{
"code": "ERR_AUTH_INVALID_CSRF",
"message": "Invalid CSRF Authentication"
}
]
}
```
**401 (ERR_AUTH_UNAUTHORIZED):**
```json
{
"errors": [
{
"code": "ERR_AUTH_UNAUTHORIZED",
"message": "Unauthorized"
}
]
}
```
**403 (ERR_ACCESS_USER):**
```json
{
"errors": [
{
"code": "ERR_ACCESS_USER",
"message": "Insufficient access permissions"
}
]
}
```
**403 (ERR_ENTITY_CONTAINS_LOCKED_FILES):**
```json
{
"errors": [
{
"code": "ERR_ENTITY_CONTAINS_LOCKED_FILES",
"message": "Folder contains locked files"
}
]
}
```
**403 (ERR_ENTITY_IS_BASE_DIR):**
```json
{
"errors": [
{
"code": "ERR_ENTITY_IS_BASE_DIR",
"message": "Operation not permitted on Base Folder"
}
]
}
```
**403 (ERR_ENTITY_IS_MY_DIR):**
```json
{
"errors": [
{
"code": "ERR_ENTITY_IS_MY_DIR",
"message": "Operation not permitted on Tray Folder"
}
]
}
```
**403 (ERR_ENTITY_IS_SECURE_FOLDER):**
```json
{
"errors": [
{
"code": "ERR_ENTITY_IS_SECURE_FOLDER",
"message": "Operation not permitted on restricted Folder."
}
]
}
```
**403 (ERR_ENTITY_IS_SYNC_DIR):**
```json
{
"errors": [
{
"code": "ERR_ENTITY_IS_SYNC_DIR",
"message": "Operation not permitted on My Folder"
}
]
}
```
**409 (ERR_ENTITY_EXISTS):**
```json
{
"errors": [
{
"code": "ERR_ENTITY_EXISTS",
"message": "Entity exists"
}
]
}
```
**413 (ERR_SYSTEM_NO_STORAGE_AVAILABLE):**
```json
{
"errors": [
{
"code": "ERR_SYSTEM_NO_STORAGE_AVAILABLE",
"message": "Folder owner's remaining storage quota does not permit for a file upload of this size."
}
]
}
```
**422 (ERR_CANNOT_MOVE_FOLDER_TO_SELF):**
```json
{
"errors": [
{
"code": "ERR_CANNOT_MOVE_FOLDER_TO_SELF",
"message": "Cannot move folder to itself"
}
]
}
```
**422 (ERR_CANNOT_MOVE_TO_CHILD):**
```json
{
"errors": [
{
"code": "ERR_CANNOT_MOVE_TO_CHILD",
"message": "Cannot move folder to its child"
}
]
}
```
**422 (ERR_INVALID_PARAMETER):**
```json
{
"errors": [
{
"code": "ERR_INVALID_PARAMETER",
"message": "Invalid Parameter Exception"
}
]
}
```
**Code Samples:**
**cURL:**
```shell
curl -X POST \
"https://{instance}.kiteworks.com/rest/folders/:id/actions/move" \
-H "Authorization: Bearer YOUR_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"destinationFolderId": "string",
"addVersion": true
}'
```
**Python:**
```python
import requests
id = "VALUE" # The unique identifier (UUID) of the entity.
url = f"https://{{instance}}.kiteworks.com/rest/folders/{id}/actions/move"
headers = {
"Authorization": "Bearer YOUR_TOKEN",
"Content-Type": "application/json",
}
payload = {
"destinationFolderId": "string",
"addVersion": true
}
response = requests.post(url, headers=headers, json=payload)
print(response.json())
```
---
## DELETE /rest/folders/{id}/actions/permanent
**Summary:** Permanently delete the specified folder
Permanently delete the specified folder.
This folder will no longer be accessible by any means.
**Parameters:**
| Name | In | Required | Description |
|------|----|----------|-------------|
| `id` | path | yes | The unique identifier (UUID) of the folder. |
**Responses:**
| Code | Description |
|------|-------------|
| 204 | The folder was permanently deleted. No content is returned. |
| 490 | Request blocked by WAF |
**Code Samples:**
**cURL:**
```shell
curl -X DELETE \
"https://{instance}.kiteworks.com/rest/folders/:id/actions/permanent" \
-H "Authorization: Bearer YOUR_TOKEN"
```
**Python:**
```python
import requests
id = "VALUE" # The unique identifier (UUID) of the folder.
url = f"https://{{instance}}.kiteworks.com/rest/folders/{id}/actions/permanent"
headers = {
"Authorization": "Bearer YOUR_TOKEN",
}
response = requests.delete(url, headers=headers)
print(response.json())
```
---
## PATCH /rest/folders/{id}/actions/recover
**Summary:** Recover deleted folder
Recover the specified folder. This un-marks the folder for deletion.
**Parameters:**
| Name | In | Required | Description |
|------|----|----------|-------------|
| `id` | path | yes | The unique identifier (UUID) of the folder. |
| `returnEntity` | query | no | If set to `true`, returns information about the newly created entity. |
| `mode` | query | no | Determines the detail level of the response body. |
**Responses:**
| Code | Description |
|------|-------------|
| 200 | Returns the recovered folder with its updated metadata. |
| 490 | Request blocked by WAF |
**Response Examples:**
**200 (RecoveredFolder):**
```json
{
"id": "abc12345def67890ab",
"name": "Reports",
"description": "Quarterly reports",
"type": "d",
"parent_id": "xyz98765cba43210fe",
"deleted": false,
"created": "2024-03-01T08:00:00+0000",
"modified": "2024-07-01T10:00:00+0000",
"syncable": false,
"secure": false,
"isFavorite": false,
"isShared": false,
"totalFilesCount": 5,
"totalFoldersCount": 1,
"totalMembersCount": 0,
"avStatus": "clean",
"dlpStatus": "clean"
}
```
**Code Samples:**
**cURL:**
```shell
curl -X PATCH \
"https://{instance}.kiteworks.com/rest/folders/:id/actions/recover" \
-H "Authorization: Bearer YOUR_TOKEN"
```
**Python:**
```python
import requests
id = "VALUE" # The unique identifier (UUID) of the folder.
url = f"https://{{instance}}.kiteworks.com/rest/folders/{id}/actions/recover"
headers = {
"Authorization": "Bearer YOUR_TOKEN",
}
response = requests.patch(url, headers=headers)
print(response.json())
```
---
## POST /rest/folders/{id}/actions/scan
**Summary:** Triggers on demand AV/DLP folder scan
Attempts to trigger an AV/DLP scan on requested folder.
**Parameters:**
| Name | In | Required | Description |
|------|----|----------|-------------|
| `id` | path | yes | The unique identifier (UUID) of the folder. |
| `returnEntity` | query | no | If set to `true`, returns information about the newly created entity. |
| `folderId:in` | query | no | List of folder IDs of entities to scan. Search for results that match any of the specified values for this parameter. |
| `fileId:in` | query | no | List of file IDs of entities to scan. Search for results that match any of the specified values for this parameter. |
| `with` | query | no | With parameters |
| `mode` | query | no | Determines the detail level of the response body. |
**Responses:**
| Code | Description |
|------|-------------|
| 200 | Returns the folder with its scan status updated to reflect that a scan has been triggered. |
| 403 | Forbidden Possible error codes: ERR_ACCESS_USER |
| 490 | Request blocked by WAF |
**Response Examples:**
**200 (ScanTriggered):**
```json
{
"id": "abc12345def67890ab",
"name": "Reports",
"type": "d",
"parent_id": "xyz98765cba43210fe",
"deleted": false,
"avStatus": "pending",
"dlpStatus": "pending"
}
```
**403 (ERR_ACCESS_USER):**
```json
{
"errors": {
"code": "ERR_ACCESS_USER",
"message": "Insufficient access permissions"
}
}
```
**Code Samples:**
**cURL:**
```shell
curl -X POST \
"https://{instance}.kiteworks.com/rest/folders/:id/actions/scan" \
-H "Authorization: Bearer YOUR_TOKEN"
```
**Python:**
```python
import requests
id = "VALUE" # The unique identifier (UUID) of the folder.
url = f"https://{{instance}}.kiteworks.com/rest/folders/{id}/actions/scan"
headers = {
"Authorization": "Bearer YOUR_TOKEN",
}
response = requests.post(url, headers=headers)
print(response.json())
```
---
## POST /rest/folders/{id}/actions/sendMessage
**Summary:** Send message from a folder
### Description:
Sends a message from the specified folder to members of the folder.
### Precondition:
The user must be a member of the folder.
### Response:
The message has been successfully sent to members.
**Parameters:**
| Name | In | Required | Description |
|------|----|----------|-------------|
| `id` | path | yes | The unique identifier (UUID) of the entity. |
**Request Body:**
| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `to` | string[] | no | List of recipient user UUIDs (To field). |
| `cc` | string[] | no | List of recipient user UUIDs (CC field). |
| `bcc` | string[] | no | List of recipient user UUIDs (BCC field). |
| `secureBody` | boolean | no | If true, the message body is hidden from the notification email and is only visible to recipients when they open the secure link. |
| `body` | string | no | The body content of the email. |
| `subject` | string | yes | The subject of the email (maximum length: 998 characters). |
**Responses:**
| Code | Description |
|------|-------------|
| 201 | The message has been successfully sent to members. |
| 401 | Unauthorized Possible error codes: ERR_AUTH_INVALID_CSRF, ERR_AUTH_UNAUTHORIZED |
| 403 | Forbidden Possible error codes: ERR_ACCESS_USER, ERR_ENTITY_DELETED |
| 422 | Unprocessable Content Possible error codes: ERR_INVALID_PARAMETER |
| 490 | Request blocked by WAF |
**Response Examples:**
**401 (ERR_AUTH_INVALID_CSRF):**
```json
{
"errors": [
{
"code": "ERR_AUTH_INVALID_CSRF",
"message": "Invalid CSRF Authentication"
}
]
}
```
**401 (ERR_AUTH_UNAUTHORIZED):**
```json
{
"errors": [
{
"code": "ERR_AUTH_UNAUTHORIZED",
"message": "Unauthorized"
}
]
}
```
**403 (ERR_ACCESS_USER):**
```json
{
"errors": [
{
"code": "ERR_ACCESS_USER",
"message": "Insufficient access permissions"
}
]
}
```
**403 (ERR_ENTITY_DELETED):**
```json
{
"errors": [
{
"code": "ERR_ENTITY_DELETED",
"message": "Entity is deleted"
}
]
}
```
**422 (ERR_INVALID_PARAMETER):**
```json
{
"errors": [
{
"code": "ERR_INVALID_PARAMETER",
"message": "Invalid Parameter Exception"
}
]
}
```
**Code Samples:**
**cURL:**
```shell
curl -X POST \
"https://{instance}.kiteworks.com/rest/folders/:id/actions/sendMessage" \
-H "Authorization: Bearer YOUR_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"to": [
"string"
],
"cc": [
"string"
],
"bcc": [
"string"
],
"secureBody": true,
"body": "string",
"subject": "string"
}'
```
**Python:**
```python
import requests
id = "VALUE" # The unique identifier (UUID) of the entity.
url = f"https://{{instance}}.kiteworks.com/rest/folders/{id}/actions/sendMessage"
headers = {
"Authorization": "Bearer YOUR_TOKEN",
"Content-Type": "application/json",
}
payload = {
"to": [
"string"
],
"cc": [
"string"
],
"bcc": [
"string"
],
"secureBody": true,
"body": "string",
"subject": "string"
}
response = requests.post(url, headers=headers, json=payload)
print(response.json())
```
---
## GET /rest/folders/{id}/folders
**Summary:** List children folders of specified parent
Return the list of folders in the specified folder including its metadata.
**Parameters:**
| Name | In | Required | Description |
|------|----|----------|-------------|
| `id` | path | yes | ID of the parent folder |
| `name` | query | no | Folder name |
| `name:contains` | query | no | Folder name. Search for results that contain the specified characters in this parameter. |
| `userId` | query | no | Unique identifier of Object creator |
| `userId:in` | query | no | Unique identifier of Object creator. Search for results that match any of the specified values for this parameter. |
| `created` | query | no | Object creation date |
| `created:gt` | query | no | Object creation date. Search for results where this parameter value is greater than the specified value. |
| `created:gte` | query | no | Object creation date. Search for results where this parameter value is greater than or equal to the specified value. |
| `created:lt` | query | no | Object creation date. Search for results where this parameter value is less than the specified value. |
| `created:lte` | query | no | Object creation date. Search for results where this parameter value is less than or equal to the specified value. |
| `modified` | query | no | Object modification date |
| `modified:gt` | query | no | Object modification date. Search for results where this parameter value is greater than the specified value. |
| `modified:gte` | query | no | Object modification date. Search for results where this parameter value is greater than or equal to the specified value. |
| `modified:lt` | query | no | Object modification date. Search for results where this parameter value is less than the specified value. |
| `modified:lte` | query | no | Object modification date. Search for results where this parameter value is less than or equal to the specified value. |
| `deleted` | query | no | Indicates whether the object is deleted. |
| `expire` | query | no | Expiration date |
| `expire:gt` | query | no | Expiration date. Search for results where this parameter value is greater than the specified value. |
| `expire:gte` | query | no | Expiration date. Search for results where this parameter value is greater than or equal to the specified value. |
| `expire:lt` | query | no | Expiration date. Search for results where this parameter value is less than the specified value. |
| `expire:lte` | query | no | Expiration date. Search for results where this parameter value is less than or equal to the specified value. |
| `fileLifetime` | query | no | Folder lifetime |
| `fileLifetime:gt` | query | no | Folder lifetime. Search for results where this parameter value is greater than the specified value. |
| `fileLifetime:gte` | query | no | Folder lifetime. Search for results where this parameter value is greater than or equal to the specified value. |
| `fileLifetime:lt` | query | no | Folder lifetime. Search for results where this parameter value is less than the specified value. |
| `fileLifetime:lte` | query | no | Folder lifetime. Search for results where this parameter value is less than or equal to the specified value. |
| `secure` | query | no | Folder secure flag |
| `description:contains` | query | no | Folder description. Search for results that contain the specified characters in this parameter. |
| `orderBy` | query | no | Sorting options |
| `offset` | query | no | Offset |
| `limit` | query | no | Limit |
| `locate_id` | query | no | If specified, "offset" parameter will be ignored and the page containing entity with this Id will be returned. |
| `with` | query | no | With parameters |
| `mode` | query | no | Determines the detail level of the response body. |
**Responses:**
| Code | Description |
|------|-------------|
| 200 | Returns a paginated list of child folders within the specified parent folder, including each folder's metadata. |
| 403 | Forbidden Possible error codes: ERR_ACCESS_DLI_ADMIN |
| 490 | Request blocked by WAF |
**Response Examples:**
**200 (FolderList):**
```json
[
{
"id": "abc12345def67890ab",
"name": "Reports",
"description": "Quarterly reports",
"type": "d",
"parent_id": "xyz98765cba43210fe",
"deleted": false,
"created": "2024-03-01T08:00:00+0000",
"modified": "2024-06-15T14:22:00+0000",
"syncable": false,
"secure": false,
"isFavorite": false,
"isShared": true,
"totalFilesCount": 12,
"totalFoldersCount": 3,
"totalMembersCount": 4,
"avStatus": "clean",
"dlpStatus": "clean"
}
]
```
**403 (ERR_ACCESS_DLI_ADMIN):**
```json
{
"errors": {
"code": "ERR_ACCESS_DLI_ADMIN",
"message": "Authenticated user is not a DLI Admin"
}
}
```
**Code Samples:**
**cURL:**
```shell
curl -X GET \
"https://{instance}.kiteworks.com/rest/folders/:id/folders" \
-H "Authorization: Bearer YOUR_TOKEN"
```
**Python:**
```python
import requests
id = "VALUE" # ID of the parent folder
url = f"https://{{instance}}.kiteworks.com/rest/folders/{id}/folders"
headers = {
"Authorization": "Bearer YOUR_TOKEN",
}
response = requests.get(url, headers=headers)
print(response.json())
```
---
## POST /rest/folders/{id}/folders
**Summary:** Create a folder
### Description:
Creates a new folder under the specified parent folder.
### Precondition:
User must have `folder_add` permission for the parent folder.
### Response:
The new folder is created and its details are returned.
**Parameters:**
| Name | In | Required | Description |
|------|----|----------|-------------|
| `id` | path | yes | The unique identifier (UUID) of the entity. |
| `returnEntity` | query | no | If true, includes the entity in the response body. |
| `with` | query | no | Specifies additional fields to include in the response. |
| `mode` | query | no | Determines the detail level of the response body. |
**Request Body:**
| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `name` | string | yes | The name of the new folder (maximum 255 characters). |
| `secure` | boolean | no | Marks the folder as secure, restricting access to authorised recipients only. Can only be set on top-level folders under the user's root folder. |
| `syncable` | boolean | no | Indicates whether the folder can be synced by the Desktop Sync Client. Can only be set on top-level folders. |
| `expire` | string | no | The folder expiration date. Applicable to top-level folders only. |
| `fileLifetime` | integer | no | Number of days files are retained in this folder before expiring. Set to 0 for no expiration. Applicable to top-level folders. |
| `rename` | boolean | no | If true, automatically renames the folder if a folder with the same name already exists in the destination. |
| `description` | string | no | Optional description for the folder. |
| `clientId` | string | no | Client application identifier used to associate the folder with a specific plugin or integration. |
| `vendorDocId` | string | no | External vendor document ID to link this folder to a document in a third-party system. |
| `vendorDocName` | string | no | Display name of the linked vendor document. |
| `isFolderUpload` | boolean | no | Indicates whether this folder is being created as part of a folder upload operation. For internal use only. |
| `useFolderQuota` | boolean | no | Indicates whether this is a system folder with its own dedicated storage quota. |
| `quota` | integer | no | Storage quota for the folder in bytes. Must be one of the permitted sizes: 1 GB (1,073,741,824), 2 GB (2,147,483,648), 5 GB (5,368,709,120), 10 GB (10,737,418,240), 50 GB (53,687,091,200), or -1 for unlimited. |
| `inheritanceEnabled` | boolean | no | Indicates whether the folder inherits member permissions from its parent folder. |
**Responses:**
| Code | Description |
|------|-------------|
| 201 | Folder created successfully. |
| 401 | Unauthorized Possible error codes: ERR_AUTH_INVALID_CSRF, ERR_AUTH_UNAUTHORIZED |
| 403 | Forbidden Possible error codes: ERR_ACCESS_DENIED, ERR_ACCESS_USER |
| 409 | Conflict Possible error codes: ERR_ENTITY_EXISTS |
| 490 | Request blocked by WAF |
**Response Examples:**
**401 (ERR_AUTH_INVALID_CSRF):**
```json
{
"errors": [
{
"code": "ERR_AUTH_INVALID_CSRF",
"message": "Invalid CSRF Authentication"
}
]
}
```
**401 (ERR_AUTH_UNAUTHORIZED):**
```json
{
"errors": [
{
"code": "ERR_AUTH_UNAUTHORIZED",
"message": "Unauthorized"
}
]
}
```
**403 (ERR_ACCESS_DENIED):**
```json
{
"errors": [
{
"code": "ERR_ACCESS_DENIED",
"message": "Your access is denied.",
"redirectUrl": "/login?code=3317"
}
]
}
```
**403 (ERR_ACCESS_USER):**
```json
{
"errors": [
{
"code": "ERR_ACCESS_USER",
"message": "Insufficient access permissions"
}
]
}
```
**409 (ERR_ENTITY_EXISTS):**
```json
{
"errors": [
{
"code": "ERR_ENTITY_EXISTS",
"message": "Entity exists"
}
]
}
```
**Code Samples:**
**cURL:**
```shell
curl -X POST \
"https://{instance}.kiteworks.com/rest/folders/:id/folders" \
-H "Authorization: Bearer YOUR_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"name": "string",
"secure": true,
"syncable": true,
"expire": "2024-01-15",
"fileLifetime": 1,
"rename": true
}'
```
**Python:**
```python
import requests
id = "VALUE" # The unique identifier (UUID) of the entity.
url = f"https://{{instance}}.kiteworks.com/rest/folders/{id}/folders"
headers = {
"Authorization": "Bearer YOUR_TOKEN",
"Content-Type": "application/json",
}
payload = {
"name": "string",
"secure": true,
"syncable": true,
"expire": "2024-01-15",
"fileLifetime": 1,
"rename": true
}
response = requests.post(url, headers=headers, json=payload)
print(response.json())
```
---
## GET /rest/folders/{id}/members
**Summary:** List folder members.
### Description:
Returns a paginated list of members who have access to the specified folder.
### Precondition:
User must have `user_view` permission for the folder.
### Response:
A list of folder members is returned.
### Sorting:
Sort string syntax `FIELD_NAME:ORDER`.
ORDER can be `asc` or `desc`.
### Sorting options:
| FIELD_NAME | Description |
|------------|-------------|
| id | The member ID |
| userId | The user ID |
| groupId | The group ID |
| roleId | The role ID |
| rank | The rank of the role |
| email | The member's email |
**Parameters:**
| Name | In | Required | Description |
|------|----|----------|-------------|
| `id` | path | yes | The unique identifier (UUID) of the entity. |
| `email` | query | no | Filter results by email address. |
| `userId` | query | no | Filter results by user ID. |
| `groupId` | query | no | Filter results by group ID. |
| `roleId` | query | no | Filter results by role ID. |
| `userId:in` | query | no | Filter by a comma-separated list of user IDs. (Recommended request size <= 100) |
| `groupId:in` | query | no | Filter by a comma-separated list of LDAP Group IDs. (Recommended request size <= 100) |
| `roleId:in` | query | no | Filter by a comma-separated list of role IDs. |
| `type` | query | no | Filter members by the object type they have access to. `d` – Directory (folder) membership. `f` – File membership. |
| `orderBy` | query | no | Sort order for the results. Default is `id:asc`. Allowed values: `id:asc`, `id:desc`, `userId:asc`, `userId:desc`, `groupId:asc`, `groupId:desc`, `roleId:asc`, `roleId:desc`, `rank:asc`, `rank:desc`, `email:asc`, `email:desc`. |
| `limit` | query | no | Range limit. |
| `offset` | query | no | Range offset. |
| `with` | query | no | Specifies additional fields to include in the response. |
| `mode` | query | no | Determines the detail level of the response body. |
**Responses:**
| Code | Description |
|------|-------------|
| 200 | The folder members have been successfully returned. |
| 400 | Bad Request Possible error codes: ERR_REQUEST_INVALID_JSON |
| 401 | Unauthorized Possible error codes: ERR_AUTH_INVALID_CSRF, ERR_AUTH_UNAUTHORIZED |
| 403 | Forbidden Possible error codes: ERR_SYSTEM_TENANT_SUSPENDED, ERR_ACCESS_USER, ERR_ACCESS_DENIED, ERR_ENTITY_DELETED |
| 422 | Unprocessable Content Possible error codes: ERR_LICENSE_EXPIRED |
| 490 | Request blocked by WAF |
**Response Examples:**
**400 (ERR_REQUEST_INVALID_JSON):**
```json
{
"errors": [
{
"code": "ERR_REQUEST_INVALID_JSON",
"message": "Invalid json provided"
}
]
}
```
**401 (ERR_AUTH_INVALID_CSRF):**
```json
{
"errors": [
{
"code": "ERR_AUTH_INVALID_CSRF",
"message": "Invalid CSRF Authentication"
}
]
}
```
**401 (ERR_AUTH_UNAUTHORIZED):**
```json
{
"errors": [
{
"code": "ERR_AUTH_UNAUTHORIZED",
"message": "Unauthorized"
}
]
}
```
**403 (ERR_SYSTEM_TENANT_SUSPENDED):**
```json
{
"errors": [
{
"code": "ERR_SYSTEM_TENANT_SUSPENDED",
"message": "Access to the service is restricted by the service provider. Contact your administrator for updates on restoring normal access."
}
]
}
```
**403 (ERR_ACCESS_USER):**
```json
{
"errors": [
{
"code": "ERR_ACCESS_USER",
"message": "Insufficient access permissions"
}
]
}
```
**403 (ERR_ACCESS_DENIED):**
```json
{
"errors": [
{
"code": "ERR_ACCESS_DENIED",
"message": "Your access is denied.",
"redirectUrl": "/login?code=3317"
}
]
}
```
**403 (ERR_ENTITY_DELETED):**
```json
{
"errors": [
{
"code": "ERR_ENTITY_DELETED",
"message": "Entity is deleted"
}
]
}
```
**422 (ERR_LICENSE_EXPIRED):**
```json
{
"errors": [
{
"code": "ERR_LICENSE_EXPIRED",
"message": "License has expired"
}
]
}
```
**Code Samples:**
**cURL:**
```shell
curl -X GET \
"https://{instance}.kiteworks.com/rest/folders/:id/members" \
-H "Authorization: Bearer YOUR_TOKEN"
```
**Python:**
```python
import requests
id = "VALUE" # The unique identifier (UUID) of the entity.
url = f"https://{{instance}}.kiteworks.com/rest/folders/{id}/members"
headers = {
"Authorization": "Bearer YOUR_TOKEN",
}
response = requests.get(url, headers=headers)
print(response.json())
```
---
## POST /rest/folders/{id}/members
**Summary:** Add members to a folder
### Description:
Adds one or more users or LDAP groups as members of the specified folder.
### Precondition:
User must have `user_add` permission for the folder.
### Response:
The new members are added to the folder.
**Parameters:**
| Name | In | Required | Description |
|------|----|----------|-------------|
| `id` | path | yes | The unique identifier (UUID) of the entity. |
| `updateIfExists` | query | no | If set to `true`, updates the member if they already exist and have a different folder role. |
| `partialSuccess` | query | no | If set to `true`, the operation will continue for the valid items even if some items result in failure. |
| `downgradeNested` | query | no | If set to `true`, demote the user member role in all applicable nested folders. |
| `returnEntity` | query | no | If true, includes the entity in the response body. |
| `with` | query | no | Specifies additional fields to include in the response. |
| `mode` | query | no | Determines the detail level of the response body. |
**Request Body:**
| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `notify` | boolean | no | If set to `true`, notifies the user being invited to the folder via email. |
| `emails` | string[] | no | List of email addresses for new members. |
| `userIds` | string[] | no | List of user IDs for new members. |
| `ldapGroupIds` | integer[] | no | List of LDAP group IDs for new members. |
| `roleId` | integer | yes | The role ID to assign to the new members. |
| `notifyFileAdded` | boolean | no | If set to `true`, subscribes the user to notifications for file additions. |
**Responses:**
| Code | Description |
|------|-------------|
| 201 | Members were added successfully. |
| 207 | Some members were added successfully, while others failed. |
| 401 | Unauthorized Possible error codes: ERR_AUTH_INVALID_CSRF, ERR_AUTH_UNAUTHORIZED |
| 403 | Forbidden Possible error codes: ERR_ENTITY_IS_BASE_DIR, ERR_ENTITY_IS_MY_DIR, ERR_ENTITY_IS_SYNC_DIR, ERR_ACCESS_USER, ERR_LICENSE_MAX_USERS_COUNT_REACHED, ERR_USER_HAS_NO_USER_TYPE, ERR_USER_TYPE_NO_ACCESS, ERR_INPUT_EMAIL_IS_DISTRIBUTION_LIST, ERR_ENTITY_USER_HAS_INSUFFICIENT_PERMISSIONS, ERR_PROFILE_COLLABORATION_DISABLED, ERR_ENTITY_IS_OWNER, ERR_ENTITY_DELETED, ERR_CLIENT_OBJECT, ERR_PROFILE_SALESFORCE_OBJECT_DISABLED, ERR_PROFILE_SALESFORCE_OBJECT_ROLE_DISALLOWED |
| 409 | Conflict Possible error codes: ERR_ENTITY_EXISTS, ERR_ENTITY_ROLE_IS_ASSIGNED, ERR_ENTITY_PARENT_FOLDER_MEMBER_EXISTS |
| 490 | Request blocked by WAF |
**Response Examples:**
**401 (ERR_AUTH_INVALID_CSRF):**
```json
{
"errors": [
{
"code": "ERR_AUTH_INVALID_CSRF",
"message": "Invalid CSRF Authentication"
}
]
}
```
**401 (ERR_AUTH_UNAUTHORIZED):**
```json
{
"errors": [
{
"code": "ERR_AUTH_UNAUTHORIZED",
"message": "Unauthorized"
}
]
}
```
**403 (ERR_ENTITY_IS_BASE_DIR):**
```json
{
"errors": [
{
"code": "ERR_ENTITY_IS_BASE_DIR",
"message": "Operation not permitted on Base Folder"
}
]
}
```
**403 (ERR_ENTITY_IS_MY_DIR):**
```json
{
"errors": [
{
"code": "ERR_ENTITY_IS_MY_DIR",
"message": "Operation not permitted on Tray Folder"
}
]
}
```
**403 (ERR_ENTITY_IS_SYNC_DIR):**
```json
{
"errors": [
{
"code": "ERR_ENTITY_IS_SYNC_DIR",
"message": "Operation not permitted on My Folder"
}
]
}
```
**403 (ERR_ACCESS_USER):**
```json
{
"errors": [
{
"code": "ERR_ACCESS_USER",
"message": "Insufficient access permissions"
}
]
}
```
**403 (ERR_LICENSE_MAX_USERS_COUNT_REACHED):**
```json
{
"errors": [
{
"code": "ERR_LICENSE_MAX_USERS_COUNT_REACHED",
"message": "License count has been reached"
}
]
}
```
**403 (ERR_USER_HAS_NO_USER_TYPE):**
```json
{
"errors": [
{
"code": "ERR_USER_HAS_NO_USER_TYPE",
"message": "User has no profile"
}
]
}
```
**403 (ERR_USER_TYPE_NO_ACCESS):**
```json
{
"errors": [
{
"code": "ERR_USER_TYPE_NO_ACCESS",
"message": "Permission denied"
}
]
}
```
**403 (ERR_INPUT_EMAIL_IS_DISTRIBUTION_LIST):**
```json
{
"errors": [
{
"code": "ERR_INPUT_EMAIL_IS_DISTRIBUTION_LIST",
"message": "Distribution list user is not allowed to register"
}
]
}
```
**403 (ERR_ENTITY_USER_HAS_INSUFFICIENT_PERMISSIONS):**
```json
{
"errors": [
{
"code": "ERR_ENTITY_USER_HAS_INSUFFICIENT_PERMISSIONS",
"message": "Target user has insufficient access permissions"
}
]
}
```
**403 (ERR_PROFILE_COLLABORATION_DISABLED):**
```json
{
"errors": [
{
"code": "ERR_PROFILE_COLLABORATION_DISABLED",
"message": "User's profile has no collaboration access"
}
]
}
```
**403 (ERR_ENTITY_IS_OWNER):**
```json
{
"errors": [
{
"code": "ERR_ENTITY_IS_OWNER",
"message": "Operation not permitted on owner member"
}
]
}
```
**403 (ERR_ENTITY_DELETED):**
```json
{
"errors": [
{
"code": "ERR_ENTITY_DELETED",
"message": "Entity is deleted"
}
]
}
```
**403 (ERR_CLIENT_OBJECT):**
```json
{
"errors": [
{
"code": "ERR_CLIENT_OBJECT",
"message": "Operation is not allowed on this client object"
}
]
}
```
**403 (ERR_PROFILE_SALESFORCE_OBJECT_DISABLED):**
```json
{
"errors": [
{
"code": "ERR_PROFILE_SALESFORCE_OBJECT_DISABLED",
"message": "This Salesforce object is not enabled for this profile"
}
]
}
```
**403 (ERR_PROFILE_SALESFORCE_OBJECT_ROLE_DISALLOWED):**
```json
{
"errors": [
{
"code": "ERR_PROFILE_SALESFORCE_OBJECT_ROLE_DISALLOWED",
"message": "This role is disallowed for this Salesforce object"
}
]
}
```
**409 (ERR_ENTITY_EXISTS):**
```json
{
"errors": [
{
"code": "ERR_ENTITY_EXISTS",
"message": "Entity exists"
}
]
}
```
**409 (ERR_ENTITY_ROLE_IS_ASSIGNED):**
```json
{
"errors": [
{
"code": "ERR_ENTITY_ROLE_IS_ASSIGNED",
"message": "Cannot assign already assigned role"
}
]
}
```
**409 (ERR_ENTITY_PARENT_FOLDER_MEMBER_EXISTS):**
```json
{
"errors": [
{
"code": "ERR_ENTITY_PARENT_FOLDER_MEMBER_EXISTS",
"message": "Parent folder member exists"
}
]
}
```
**Code Samples:**
**cURL:**
```shell
curl -X POST \
"https://{instance}.kiteworks.com/rest/folders/:id/members" \
-H "Authorization: Bearer YOUR_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"notify": true,
"emails": [
"string"
],
"userIds": [
"string"
],
"ldapGroupIds": [
1
],
"roleId": 1,
"notifyFileAdded": true
}'
```
**Python:**
```python
import requests
id = "VALUE" # The unique identifier (UUID) of the entity.
url = f"https://{{instance}}.kiteworks.com/rest/folders/{id}/members"
headers = {
"Authorization": "Bearer YOUR_TOKEN",
"Content-Type": "application/json",
}
payload = {
"notify": true,
"emails": [
"string"
],
"userIds": [
"string"
],
"ldapGroupIds": [
1
],
"roleId": 1,
"notifyFileAdded": true
}
response = requests.post(url, headers=headers, json=payload)
print(response.json())
```
---
## GET /rest/folders/{id}/members/ldapGroup
**Summary:** List LDAP groups with access to a folder
Returns a list of LDAP groups and their assigned roles for the specified folder.
**Parameters:**
| Name | In | Required | Description |
|------|----|----------|-------------|
| `id` | path | yes | The unique identifier (UUID) of the folder. |
| `groupId` | query | no | The unique identifier of the group. |
| `groupId:in` | query | no | The unique identifier of the group.. Search for results that match any of the specified values for this parameter. |
| `roleId` | query | no | The unique identifier of the role. |
| `roleId:in` | query | no | The unique identifier of the role.. Search for results that match any of the specified values for this parameter. |
| `orderBy` | query | no | Sorting options |
| `offset` | query | no | Offset |
| `limit` | query | no | Limit |
| `with` | query | no | With parameters |
| `mode` | query | no | Determines the detail level of the response body. |
**Responses:**
| Code | Description |
|------|-------------|
| 200 | Returns a paginated list of LDAP groups that have been granted access to the specified folder, including each group's assigned role. |
| 490 | Request blocked by WAF |
**Response Examples:**
**200 (FolderGroupList):**
```json
[
{
"objectId": "abc12345def67890ab",
"groupId": 42,
"roleId": 3
}
]
```
**Code Samples:**
**cURL:**
```shell
curl -X GET \
"https://{instance}.kiteworks.com/rest/folders/:id/members/ldapGroup" \
-H "Authorization: Bearer YOUR_TOKEN"
```
**Python:**
```python
import requests
id = "VALUE" # The unique identifier (UUID) of the folder.
url = f"https://{{instance}}.kiteworks.com/rest/folders/{id}/members/ldapGroup"
headers = {
"Authorization": "Bearer YOUR_TOKEN",
}
response = requests.get(url, headers=headers)
print(response.json())
```
---
## GET /rest/folders/{id}/members/ldapGroup/{ldap_group_id}
**Summary:** Return a specific LDAP group's access to a folder
Returns the access grant record for the specified LDAP group in the folder, including the group's assigned role.
**Parameters:**
| Name | In | Required | Description |
|------|----|----------|-------------|
| `id` | path | yes | The unique identifier (UUID) of the folder. |
| `ldap_group_id` | path | yes | The unique identifier of the LDAP group member |
| `with` | query | no | With parameters |
| `mode` | query | no | Determines the detail level of the response body. |
**Responses:**
| Code | Description |
|------|-------------|
| 200 | Returns the access grant record for the specified LDAP group, including its assigned role in the folder. |
| 490 | Request blocked by WAF |
**Response Examples:**
**200 (FolderGroupMember):**
```json
{
"objectId": "abc12345def67890ab",
"groupId": 42,
"roleId": 3
}
```
**Code Samples:**
**cURL:**
```shell
curl -X GET \
"https://{instance}.kiteworks.com/rest/folders/:id/members/ldapGroup/:ldap_group_id" \
-H "Authorization: Bearer YOUR_TOKEN"
```
**Python:**
```python
import requests
id = "VALUE" # The unique identifier (UUID) of the folder.
ldap_group_id = "VALUE" # The unique identifier of the LDAP group member
url = f"https://{{instance}}.kiteworks.com/rest/folders/{id}/members/ldapGroup/{ldap_group_id}"
headers = {
"Authorization": "Bearer YOUR_TOKEN",
}
response = requests.get(url, headers=headers)
print(response.json())
```
---
## PUT /rest/folders/{id}/members/ldapGroup/{ldap_group_id}
**Summary:** Update folder LDAP group members
Updates LDAP group members within the folder
**Parameters:**
| Name | In | Required | Description |
|------|----|----------|-------------|
| `id` | path | yes | The unique identifier (UUID) of the folder. |
| `ldap_group_id` | path | yes | The unique identifier (UUID) of the LDAP group member. |
| `returnEntity` | query | no | If set to `true`, returns information about the newly created entity. |
| `downgradeNested` | query | no | Also downgrade the member role for nested folders. |
| `mode` | query | no | Determines the detail level of the response body. |
**Request Body:**
| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `roleId` | integer | yes | Unique identifier of the role to assign to this member |
| `notifyFileAdded` | boolean | no | Indicates whether the member should be notified when a file is added |
| `addLinks` | boolean | no | Indicates whether HATEOAS links should be included in the response |
**Responses:**
| Code | Description |
|------|-------------|
| 200 | Returns the updated LDAP group access records reflecting the new role assignment. |
| 403 | Forbidden Possible error codes: ERR_ACCESS_USER |
| 422 | Unprocessable Content Possible error codes: ERR_INPUT_REQUIRED |
| 490 | Request blocked by WAF |
**Response Examples:**
**200 (UpdatedGroupMember):**
```json
[
{
"objectId": "abc12345def67890ab",
"groupId": 42,
"roleId": 4
}
]
```
**403 (ERR_ACCESS_USER):**
```json
{
"errors": {
"code": "ERR_ACCESS_USER",
"message": "Insufficient access permissions"
}
}
```
**422 (ERR_INPUT_REQUIRED):**
```json
{
"errors": {
"code": "ERR_INPUT_REQUIRED",
"message": "Field is required"
}
}
```
**Code Samples:**
**cURL:**
```shell
curl -X PUT \
"https://{instance}.kiteworks.com/rest/folders/:id/members/ldapGroup/:ldap_group_id" \
-H "Authorization: Bearer YOUR_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"roleId": 1,
"notifyFileAdded": true,
"addLinks": true
}'
```
**Python:**
```python
import requests
id = "VALUE" # The unique identifier (UUID) of the folder.
ldap_group_id = "VALUE" # The unique identifier (UUID) of the LDAP group member.
url = f"https://{{instance}}.kiteworks.com/rest/folders/{id}/members/ldapGroup/{ldap_group_id}"
headers = {
"Authorization": "Bearer YOUR_TOKEN",
"Content-Type": "application/json",
}
payload = {
"roleId": 1,
"notifyFileAdded": true,
"addLinks": true
}
response = requests.put(url, headers=headers, json=payload)
print(response.json())
```
---
## DELETE /rest/folders/{id}/members/ldapGroup/{ldap_group_id}
**Summary:** Delete a folder LDAP group member
### Description:
Removes an LDAP member from the specified folder.
### Precondition:
The user must have the `user_remove` permission for the folder.
### Response:
The specified folder LDAP group member is successfully removed.
**Parameters:**
| Name | In | Required | Description |
|------|----|----------|-------------|
| `id` | path | yes | The unique identifier (UUID) of the entity. |
| `ldap_group_id` | path | yes | The unique identifier of the LDAP group. |
| `downgradeNested` | query | no | If set to `true`, the user's role will be removed from all nested folders. |
**Responses:**
| Code | Description |
|------|-------------|
| 204 | The folder LDAP group member was successfully removed from the folder. |
| 401 | Unauthorized Possible error codes: ERR_AUTH_INVALID_CSRF, ERR_AUTH_UNAUTHORIZED |
| 403 | Forbidden Possible error codes: ERR_ACCESS_USER, ERR_ENTITY_DELETED, ERR_INPUT_IS_OWNER, ERR_ENTITY_PARENT_FOLDER_MEMBER_EXISTS |
| 422 | Unprocessable Content Possible error codes: ERR_INVALID_PARAMETER |
| 490 | Request blocked by WAF |
**Response Examples:**
**401 (ERR_AUTH_INVALID_CSRF):**
```json
{
"errors": [
{
"code": "ERR_AUTH_INVALID_CSRF",
"message": "Invalid CSRF Authentication"
}
]
}
```
**401 (ERR_AUTH_UNAUTHORIZED):**
```json
{
"errors": [
{
"code": "ERR_AUTH_UNAUTHORIZED",
"message": "Unauthorized"
}
]
}
```
**403 (ERR_ACCESS_USER):**
```json
{
"errors": [
{
"code": "ERR_ACCESS_USER",
"message": "Insufficient access permissions"
}
]
}
```
**403 (ERR_ENTITY_DELETED):**
```json
{
"errors": [
{
"code": "ERR_ENTITY_DELETED",
"message": "Entity is deleted"
}
]
}
```
**403 (ERR_INPUT_IS_OWNER):**
```json
{
"errors": [
{
"code": "ERR_INPUT_IS_OWNER",
"message": "Can not set owner role"
}
]
}
```
**403 (ERR_ENTITY_PARENT_FOLDER_MEMBER_EXISTS):**
```json
{
"errors": [
{
"code": "ERR_ENTITY_PARENT_FOLDER_MEMBER_EXISTS",
"message": "Parent folder member exists"
}
]
}
```
**422 (ERR_INVALID_PARAMETER):**
```json
{
"errors": [
{
"code": "ERR_INVALID_PARAMETER",
"message": "Invalid Parameter Exception"
}
]
}
```
**Code Samples:**
**cURL:**
```shell
curl -X DELETE \
"https://{instance}.kiteworks.com/rest/folders/:id/members/ldapGroup/:ldap_group_id" \
-H "Authorization: Bearer YOUR_TOKEN"
```
**Python:**
```python
import requests
id = "VALUE" # The unique identifier (UUID) of the entity.
ldap_group_id = "VALUE" # The unique identifier of the LDAP group.
url = f"https://{{instance}}.kiteworks.com/rest/folders/{id}/members/ldapGroup/{ldap_group_id}"
headers = {
"Authorization": "Bearer YOUR_TOKEN",
}
response = requests.delete(url, headers=headers)
print(response.json())
```
---
## GET /rest/folders/{id}/members/{member_user_id}
**Summary:** Return folder user member
Returns the specified user member within the folder.
**Parameters:**
| Name | In | Required | Description |
|------|----|----------|-------------|
| `id` | path | yes | The unique identifier (UUID) of the folder. |
| `member_user_id` | path | yes | The unique identifier (UUID) of the user member. |
| `with` | query | no | With parameters |
| `mode` | query | no | Determines the detail level of the response body. |
**Responses:**
| Code | Description |
|------|-------------|
| 200 | Returns the specified user member and their role within the folder. |
| 490 | Request blocked by WAF |
**Response Examples:**
**200 (FolderMember):**
```json
{
"objectId": "abc12345def67890ab",
"userId": "usr98765cba43210fe",
"roleId": 3
}
```
**Code Samples:**
**cURL:**
```shell
curl -X GET \
"https://{instance}.kiteworks.com/rest/folders/:id/members/:member_user_id" \
-H "Authorization: Bearer YOUR_TOKEN"
```
**Python:**
```python
import requests
id = "VALUE" # The unique identifier (UUID) of the folder.
member_user_id = "VALUE" # The unique identifier (UUID) of the user member.
url = f"https://{{instance}}.kiteworks.com/rest/folders/{id}/members/{member_user_id}"
headers = {
"Authorization": "Bearer YOUR_TOKEN",
}
response = requests.get(url, headers=headers)
print(response.json())
```
---
## PUT /rest/folders/{id}/members/{member_user_id}
**Summary:** Update folder user members
Updates the user members within the folder.
**Parameters:**
| Name | In | Required | Description |
|------|----|----------|-------------|
| `id` | path | yes | The unique identifier (UUID) of the folder. |
| `member_user_id` | path | yes | The unique identifier of the user member. |
| `returnEntity` | query | no | If set to `true`, returns information about the newly created entity. |
| `downgradeNested` | query | no | Also downgrade the member role for nested folders. |
| `mode` | query | no | Determines the detail level of the response body. |
**Request Body:**
| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `roleId` | integer | yes | Unique identifier of the role to assign to this member |
| `notifyFileAdded` | boolean | no | Indicates whether the member should be notified when a file is added |
| `addLinks` | boolean | no | Indicates whether HATEOAS links should be included in the response |
| `notify` | boolean | no | Indicates whether user would like to receive emails when new member is added into folder |
**Responses:**
| Code | Description |
|------|-------------|
| 200 | Returns the updated member records reflecting the new role assignment. |
| 403 | Forbidden Possible error codes: ERR_ACCESS_USER |
| 422 | Unprocessable Content Possible error codes: ERR_INPUT_REQUIRED, ERR_INPUT_INVALID_EMAIL |
| 490 | Request blocked by WAF |
**Response Examples:**
**200 (UpdatedMember):**
```json
[
{
"objectId": "abc12345def67890ab",
"userId": "usr98765cba43210fe",
"roleId": 4
}
]
```
**403 (ERR_ACCESS_USER):**
```json
{
"errors": {
"code": "ERR_ACCESS_USER",
"message": "Insufficient access permissions"
}
}
```
**422 (ERR_INPUT_REQUIRED):**
```json
{
"errors": {
"code": "ERR_INPUT_REQUIRED",
"message": "Field is required"
}
}
```
**422 (ERR_INPUT_INVALID_EMAIL):**
```json
{
"errors": {
"code": "ERR_INPUT_INVALID_EMAIL",
"message": "Input is not a valid email"
}
}
```
**Code Samples:**
**cURL:**
```shell
curl -X PUT \
"https://{instance}.kiteworks.com/rest/folders/:id/members/:member_user_id" \
-H "Authorization: Bearer YOUR_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"roleId": 1,
"notifyFileAdded": true,
"addLinks": true,
"notify": true
}'
```
**Python:**
```python
import requests
id = "VALUE" # The unique identifier (UUID) of the folder.
member_user_id = "VALUE" # The unique identifier of the user member.
url = f"https://{{instance}}.kiteworks.com/rest/folders/{id}/members/{member_user_id}"
headers = {
"Authorization": "Bearer YOUR_TOKEN",
"Content-Type": "application/json",
}
payload = {
"roleId": 1,
"notifyFileAdded": true,
"addLinks": true,
"notify": true
}
response = requests.put(url, headers=headers, json=payload)
print(response.json())
```
---
## DELETE /rest/folders/{id}/members/{member_user_id}
**Summary:** Delete a folder member
### Description:
Removes a member from the specified folder.
### Precondition:
The user must have the `user_remove` permission for the folder.
### Response:
The specified folder member is successfully removed.
**Parameters:**
| Name | In | Required | Description |
|------|----|----------|-------------|
| `id` | path | yes | The unique identifier (UUID) of the entity. |
| `member_user_id` | path | yes | The unique identifier (UUID) of the user. |
| `downgradeNested` | query | no | If set to `true`, the user's role will be removed from all nested folders. |
**Responses:**
| Code | Description |
|------|-------------|
| 204 | The folder member was successfully removed from the folder. |
| 401 | Unauthorized Possible error codes: ERR_AUTH_INVALID_CSRF, ERR_AUTH_UNAUTHORIZED |
| 403 | Forbidden Possible error codes: ERR_ACCESS_USER, ERR_ENTITY_DELETED, ERR_INPUT_IS_OWNER, ERR_ENTITY_PARENT_FOLDER_MEMBER_EXISTS, ERR_ENTITY_INHERITED_MEMBER_NOT_MODIFIABLE |
| 422 | Unprocessable Content Possible error codes: ERR_INVALID_PARAMETER |
| 490 | Request blocked by WAF |
**Response Examples:**
**401 (ERR_AUTH_INVALID_CSRF):**
```json
{
"errors": [
{
"code": "ERR_AUTH_INVALID_CSRF",
"message": "Invalid CSRF Authentication"
}
]
}
```
**401 (ERR_AUTH_UNAUTHORIZED):**
```json
{
"errors": [
{
"code": "ERR_AUTH_UNAUTHORIZED",
"message": "Unauthorized"
}
]
}
```
**403 (ERR_ACCESS_USER):**
```json
{
"errors": [
{
"code": "ERR_ACCESS_USER",
"message": "Insufficient access permissions"
}
]
}
```
**403 (ERR_ENTITY_DELETED):**
```json
{
"errors": [
{
"code": "ERR_ENTITY_DELETED",
"message": "Entity is deleted"
}
]
}
```
**403 (ERR_INPUT_IS_OWNER):**
```json
{
"errors": [
{
"code": "ERR_INPUT_IS_OWNER",
"message": "Can not set owner role"
}
]
}
```
**403 (ERR_ENTITY_PARENT_FOLDER_MEMBER_EXISTS):**
```json
{
"errors": [
{
"code": "ERR_ENTITY_PARENT_FOLDER_MEMBER_EXISTS",
"message": "Parent folder member exists"
}
]
}
```
**403 (ERR_ENTITY_INHERITED_MEMBER_NOT_MODIFIABLE):**
```json
{
"errors": [
{
"code": "ERR_ENTITY_INHERITED_MEMBER_NOT_MODIFIABLE",
"message": "Cannot modify an inherited member at this folder. Make the change at the origin folder."
}
]
}
```
**422 (ERR_INVALID_PARAMETER):**
```json
{
"errors": [
{
"code": "ERR_INVALID_PARAMETER",
"message": "Invalid Parameter Exception"
}
]
}
```
**Code Samples:**
**cURL:**
```shell
curl -X DELETE \
"https://{instance}.kiteworks.com/rest/folders/:id/members/:member_user_id" \
-H "Authorization: Bearer YOUR_TOKEN"
```
**Python:**
```python
import requests
id = "VALUE" # The unique identifier (UUID) of the entity.
member_user_id = "VALUE" # The unique identifier (UUID) of the user.
url = f"https://{{instance}}.kiteworks.com/rest/folders/{id}/members/{member_user_id}"
headers = {
"Authorization": "Bearer YOUR_TOKEN",
}
response = requests.delete(url, headers=headers)
print(response.json())
```
---
## GET /rest/folders/{id}/tasks
**Summary:** Get tasks for a folder
Gets a list of tasks associated with all files in the specified folder. **Requires `task_view` permission on the folder.**
**Parameters:**
| Name | In | Required | Description |
|------|----|----------|-------------|
| `id` | path | yes | The unique identifier (UUID) of the folder. |
| `assigneeId` | query | no | Assigned User unique identifier |
| `assigneeId:in` | query | no | Assigned User unique identifier. Search for results that match any of the specified values for this parameter. |
| `due` | query | no | Task due date |
| `due:gt` | query | no | Task due date. Search for results where this parameter value is greater than the specified value. |
| `due:gte` | query | no | Task due date. Search for results where this parameter value is greater than or equal to the specified value. |
| `due:lt` | query | no | Task due date. Search for results where this parameter value is less than the specified value. |
| `due:lte` | query | no | Task due date. Search for results where this parameter value is less than or equal to the specified value. |
| `parentId` | query | no | Parent Comment identifier |
| `parentId:in` | query | no | Parent Comment identifier. Search for results that match any of the specified values for this parameter. |
| `userId` | query | no | Identifier of User who created a Task |
| `userId:in` | query | no | Identifier of User who created a Task. Search for results that match any of the specified values for this parameter. |
| `created` | query | no | Task creation date |
| `created:gt` | query | no | Task creation date. Search for results where this parameter value is greater than the specified value. |
| `created:gte` | query | no | Task creation date. Search for results where this parameter value is greater than or equal to the specified value. |
| `created:lt` | query | no | Task creation date. Search for results where this parameter value is less than the specified value. |
| `created:lte` | query | no | Task creation date. Search for results where this parameter value is less than or equal to the specified value. |
| `modified` | query | no | Task modification date |
| `modified:gt` | query | no | Task modification date. Search for results where this parameter value is greater than the specified value. |
| `modified:gte` | query | no | Task modification date. Search for results where this parameter value is greater than or equal to the specified value. |
| `modified:lt` | query | no | Task modification date. Search for results where this parameter value is less than the specified value. |
| `modified:lte` | query | no | Task modification date. Search for results where this parameter value is less than or equal to the specified value. |
| `contents:contains` | query | no | Task content. Search for results that contain the specified characters in this parameter. |
| `status` | query | no | Filter tasks by status. Accepted values: `D`, `P`, `C`. |
| `deleted` | query | no | Whether the task has been deleted |
| `orderBy` | query | no | Sorting options |
| `offset` | query | no | Offset |
| `limit` | query | no | Limit |
| `with` | query | no | With parameters |
| `mode` | query | no | Determines the detail level of the response body. |
**Responses:**
| Code | Description |
|------|-------------|
| 200 | Returns a paginated list of tasks for all files within the specified folder. |
| 490 | Request blocked by WAF |
**Response Examples:**
**200 (Folder task list):**
```json
{
"data": [
{
"id": 15,
"object_id": 7,
"parent_id": 0,
"user_id": 3,
"assignee_id": 5,
"contents": "Review the quarterly report for accuracy.",
"status": "P",
"due": "2024-04-01T00:00:00+00:00",
"created": "2024-03-15T10:00:00+00:00",
"modified": "2024-03-16T08:30:00+00:00",
"deleted": false,
"folder_id": 3
},
{
"id": 16,
"object_id": 8,
"parent_id": 0,
"user_id": 3,
"assignee_id": 3,
"contents": "Update the budget spreadsheet with Q1 actuals.",
"status": "D",
"due": "2024-04-15T00:00:00+00:00",
"created": "2024-03-16T09:00:00+00:00",
"modified": "2024-03-16T09:00:00+00:00",
"deleted": false,
"folder_id": 3
}
],
"total": 2,
"page": 1,
"pageSize": 20
}
```
**Code Samples:**
**cURL:**
```shell
curl -X GET \
"https://{instance}.kiteworks.com/rest/folders/:id/tasks" \
-H "Authorization: Bearer YOUR_TOKEN"
```
**Python:**
```python
import requests
id = "VALUE" # The unique identifier (UUID) of the folder.
url = f"https://{{instance}}.kiteworks.com/rest/folders/{id}/tasks"
headers = {
"Authorization": "Bearer YOUR_TOKEN",
}
response = requests.get(url, headers=headers)
print(response.json())
```
---
## GET /rest/folders/{id}/tree
**Summary:** Get the ancestor path of a folder
Returns the ancestor path of the specified folder as an ordered list of folder nodes, from the root down to the target folder.
**Parameters:**
| Name | In | Required | Description |
|------|----|----------|-------------|
| `id` | path | yes | The unique identifier (UUID) of the folder. |
| `includeOwner` | query | no | Include owner root folder in the tree |
| `mode` | query | no | Determines the detail level of the response body. |
**Responses:**
| Code | Description |
|------|-------------|
| 200 | Returns an ordered list of ancestor folder nodes from root to the specified folder, representing its full tree path. |
| 403 | Forbidden Possible error codes: ERR_ACCESS_DLI_ADMIN |
| 490 | Request blocked by WAF |
**Response Examples:**
**200 (FolderTree):**
```json
[
{
"id": "root1234567890abcd",
"name": "My Files"
},
{
"id": "xyz98765cba43210fe",
"name": "Projects"
},
{
"id": "abc12345def67890ab",
"name": "Reports"
}
]
```
**403 (ERR_ACCESS_DLI_ADMIN):**
```json
{
"errors": {
"code": "ERR_ACCESS_DLI_ADMIN",
"message": "Authenticated user is not a DLI Admin"
}
}
```
**Code Samples:**
**cURL:**
```shell
curl -X GET \
"https://{instance}.kiteworks.com/rest/folders/:id/tree" \
-H "Authorization: Bearer YOUR_TOKEN"
```
**Python:**
```python
import requests
id = "VALUE" # The unique identifier (UUID) of the folder.
url = f"https://{{instance}}.kiteworks.com/rest/folders/{id}/tree"
headers = {
"Authorization": "Bearer YOUR_TOKEN",
}
response = requests.get(url, headers=headers)
print(response.json())
```
---
## GET /rest/folders/{parent}/files
**Summary:** Return the list of files in a folder
### Description:
Returns the list of files within the specified folder.
### Precondition:
User must have `properties_view` permission for the folder.
### Response:
Returns a list of files within the specified folder.
### Sorting:
Sort string syntax `FIELD_NAME:ORDER`.
ORDER can be `asc` or `desc`.
### Sorting options:
| FIELD_NAME | Description |
|------------|-------------|
| name | The name of the file |
| created | The creation datetime of file |
| modified | The last modified datetime of file |
| size | The file size (for files) |
**Parameters:**
| Name | In | Required | Description |
|------|----|----------|-------------|
| `parent` | path | yes | The unique identifier (UUID) of the parent folder. |
| `deleted` | query | no | Filter by deletion status. If true, show only deleted items; if false, show non-deleted items; if not specified, show both deleted and non-deleted items. |
| `name` | query | no | Filter by the name of file within the folder. |
| `name:contains` | query | no | Search for files whose names contain the specified characters. |
| `userId` | query | no | The unique identifier of the file creator. |
| `userId:in` | query | no | Search for files created by the specified user IDs. (Recommended request size <= 100) |
| `created` | query | no | Search for files created on the specified date. |
| `created:gt` | query | no | Search for files created after the specified date. |
| `created:gte` | query | no | Search for files created on or after the specified date. |
| `created:lt` | query | no | Search for files created before the specified date. |
| `created:lte` | query | no | Search for files created on or before the specified date. |
| `modified` | query | no | Search for files modified on the specified date. |
| `modified:gt` | query | no | Search for files modified after the specified date. |
| `modified:gte` | query | no | Search for files modified on or after the specified date. |
| `modified:lt` | query | no | Search for files modified before the specified date. |
| `modified:lte` | query | no | Search for files modified on or before the specified date. |
| `expire` | query | no | Search for files that expire on the specified date. |
| `expire:gt` | query | no | Search for files that expire after the specified date. |
| `expire:gte` | query | no | Search for files that expire on or after the specified date. |
| `expire:lt` | query | no | Search for files that expire before the specified date. |
| `expire:lte` | query | no | Search for files that expire on or before the specified date. |
| `isPushed` | query | no | If true, returns only files that have been pushed to a mobile device via the mobile sync feature. |
| `orderBy` | query | no | Sort order for the results. Default is `name:asc`. Allowed values: `name:asc`, `name:desc`, `created:asc`, `created:desc`, `modified:asc`, `modified:desc`, `size:asc`, `size:desc`. |
| `limit` | query | no | Range limit. |
| `offset` | query | no | Range offset. |
| `with` | query | no | Specifies additional fields to include in the response. |
| `mode` | query | no | Determines the detail level of the response body. |
**Responses:**
| Code | Description |
|------|-------------|
| 200 | A list of files in the folder is returned successfully. |
| 400 | Bad Request Possible error codes: ERR_REQUEST_INVALID_JSON |
| 401 | Unauthorized Possible error codes: ERR_ACCESS_USER, ERR_AUTH_INVALID_CSRF, ERR_AUTH_UNAUTHORIZED |
| 422 | Unprocessable Content Possible error codes: ERR_INVALID_PARAMETER |
| 490 | Request blocked by WAF |
**Response Examples:**
**400 (ERR_REQUEST_INVALID_JSON):**
```json
{
"errors": [
{
"code": "ERR_REQUEST_INVALID_JSON",
"message": "Invalid json provided"
}
]
}
```
**401 (ERR_ACCESS_USER):**
```json
{
"errors": [
{
"code": "ERR_ACCESS_USER",
"message": "Insufficient access permissions"
}
]
}
```
**401 (ERR_AUTH_INVALID_CSRF):**
```json
{
"errors": [
{
"code": "ERR_AUTH_INVALID_CSRF",
"message": "Invalid CSRF Authentication"
}
]
}
```
**401 (ERR_AUTH_UNAUTHORIZED):**
```json
{
"errors": [
{
"code": "ERR_AUTH_UNAUTHORIZED",
"message": "Unauthorized"
}
]
}
```
**422 (ERR_INVALID_PARAMETER):**
```json
{
"errors": [
{
"code": "ERR_INVALID_PARAMETER",
"message": "Invalid Parameter Exception"
}
]
}
```
**Code Samples:**
**cURL:**
```shell
curl -X GET \
"https://{instance}.kiteworks.com/rest/folders/:parent/files" \
-H "Authorization: Bearer YOUR_TOKEN"
```
**Python:**
```python
import requests
parent = "VALUE" # The unique identifier (UUID) of the parent folder.
url = f"https://{{instance}}.kiteworks.com/rest/folders/{parent}/files"
headers = {
"Authorization": "Bearer YOUR_TOKEN",
}
response = requests.get(url, headers=headers)
print(response.json())
```
---
## GET /rest/permissions/folder/{id}
**Summary:** List folder permissions
### Description:
Return the list of permissions associated with the specified folder.
### Precondition:
The user must be a member of the folder.
### Response:
Returns a list of available permissions for the specified folder.
**Parameters:**
| Name | In | Required | Description |
|------|----|----------|-------------|
| `id` | path | yes | The unique identifier (UUID) of the entity. |
| `actionId` | query | no | The unique identifier for the action. |
| `id:in` | query | no | List of unique action identifiers. Search for results that match any of the specified values. |
| `name` | query | no | Filter by the permission action name. Allowed values: `view`, `download`, `comment_view`, `comment_add`, `comment_edit`, `comment_reply`, `comment_delete`, `task_view`, `task_update_status`, `notification_subscribe`, `notification_unsubscribe`, `properties_view`, `file_send`, `tray_add`, `favorite_add`. |
| `name:contains` | query | no | Action name filter. Search for actions whose names contain the specified characters. |
| `with` | query | no | Specifies additional fields to include in the response. |
| `mode` | query | no | Determines the detail level of the response body. |
**Responses:**
| Code | Description |
|------|-------------|
| 200 | Successfully returned the list of permissions for the specified folder. |
| 400 | Bad Request Possible error codes: ERR_REQUEST_INVALID_JSON |
| 401 | Unauthorized Possible error codes: ERR_ACCESS_USER, ERR_AUTH_INVALID_CSRF, ERR_AUTH_UNAUTHORIZED |
| 422 | Unprocessable Content Possible error codes: ERR_INVALID_PARAMETER |
| 490 | Request blocked by WAF |
**Response Examples:**
**400 (ERR_REQUEST_INVALID_JSON):**
```json
{
"errors": [
{
"code": "ERR_REQUEST_INVALID_JSON",
"message": "Invalid json provided"
}
]
}
```
**401 (ERR_ACCESS_USER):**
```json
{
"errors": [
{
"code": "ERR_ACCESS_USER",
"message": "Insufficient access permissions"
}
]
}
```
**401 (ERR_AUTH_INVALID_CSRF):**
```json
{
"errors": [
{
"code": "ERR_AUTH_INVALID_CSRF",
"message": "Invalid CSRF Authentication"
}
]
}
```
**401 (ERR_AUTH_UNAUTHORIZED):**
```json
{
"errors": [
{
"code": "ERR_AUTH_UNAUTHORIZED",
"message": "Unauthorized"
}
]
}
```
**422 (ERR_INVALID_PARAMETER):**
```json
{
"errors": [
{
"code": "ERR_INVALID_PARAMETER",
"message": "Invalid Parameter Exception"
}
]
}
```
**Code Samples:**
**cURL:**
```shell
curl -X GET \
"https://{instance}.kiteworks.com/rest/permissions/folder/:id" \
-H "Authorization: Bearer YOUR_TOKEN"
```
**Python:**
```python
import requests
id = "VALUE" # The unique identifier (UUID) of the entity.
url = f"https://{{instance}}.kiteworks.com/rest/permissions/folder/{id}"
headers = {
"Authorization": "Bearer YOUR_TOKEN",
}
response = requests.get(url, headers=headers)
print(response.json())
```
---
## POST /rest/folders/actions/move
**Summary:** Move multiple folders
### Description:
Moves multiple folders to a new destination folder.
### Precondition:
User must have `folder_move` permission for the folders being moved.
User must have `folder_add` permission for the destination folder.
### Response:
The folders are moved to the destination folder.
**Parameters:**
| Name | In | Required | Description |
|------|----|----------|-------------|
| `returnEntity` | query | no | If true, includes the entity in the response body. |
| `with` | query | no | Specifies additional fields to include in the response. |
| `mode` | query | no | Determines the detail level of the response body. |
**Request Body:**
| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `folderIds` | string[] | yes | A list of folder IDs to be processed. |
| `destinationFolderId` | string | yes | The destination folder |
**Responses:**
| Code | Description |
|------|-------------|
| 201 | Folders successfully moved. |
| 207 | Partially successful operation |
| 403 | Forbidden Possible error codes: ERR_SYSTEM_FOLDER_QUOTA_EXCEEDED |
| 490 | Request blocked by WAF |
**Response Examples:**
**403 (ERR_SYSTEM_FOLDER_QUOTA_EXCEEDED):**
```json
{
"errors": [
{
"code": "ERR_SYSTEM_FOLDER_QUOTA_EXCEEDED",
"message": "Folder's remaining storage quota does not permit for a file upload or operation of this size."
}
]
}
```
**Code Samples:**
**cURL:**
```shell
curl -X POST \
"https://{instance}.kiteworks.com/rest/folders/actions/move" \
-H "Authorization: Bearer YOUR_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"folderIds": [
"string"
],
"destinationFolderId": "string"
}'
```
**Python:**
```python
import requests
url = "https://{instance}.kiteworks.com/rest/folders/actions/move"
headers = {
"Authorization": "Bearer YOUR_TOKEN",
"Content-Type": "application/json",
}
payload = {
"folderIds": [
"string"
],
"destinationFolderId": "string"
}
response = requests.post(url, headers=headers, json=payload)
print(response.json())
```
---
## GET /rest/folders/{id}/quota
**Summary:** Return the folder quota
### Description:
Returns the quota information for a specific folder.
### Precondition:
User must have `file_add` permission for the folder.
### Response:
The folder quota is returned.
**Parameters:**
| Name | In | Required | Description |
|------|----|----------|-------------|
| `id` | path | yes | The unique identifier (UUID) of the entity. |
| `fileId` | query | no | The unique identifier (UUID) of the file. |
**Responses:**
| Code | Description |
|------|-------------|
| 200 | The folder quota has been successfully returned. |
| 401 | Unauthorized Possible error codes: ERR_ACCESS_USER, ERR_AUTH_INVALID_CSRF, ERR_AUTH_UNAUTHORIZED, ERR_ENTITY_NOT_FOUND |
| 403 | Forbidden Possible error codes: ERR_ENTITY_DELETED |
| 490 | Request blocked by WAF |
**Response Examples:**
**401 (ERR_ACCESS_USER):**
```json
{
"errors": [
{
"code": "ERR_ACCESS_USER",
"message": "Insufficient access permissions"
}
]
}
```
**401 (ERR_AUTH_INVALID_CSRF):**
```json
{
"errors": [
{
"code": "ERR_AUTH_INVALID_CSRF",
"message": "Invalid CSRF Authentication"
}
]
}
```
**401 (ERR_AUTH_UNAUTHORIZED):**
```json
{
"errors": [
{
"code": "ERR_AUTH_UNAUTHORIZED",
"message": "Unauthorized"
}
]
}
```
**401 (ERR_ENTITY_NOT_FOUND):**
```json
{
"errors": [
{
"code": "ERR_ENTITY_NOT_FOUND",
"message": "Entity does not exist"
}
]
}
```
**403 (ERR_ENTITY_DELETED):**
```json
{
"errors": [
{
"code": "ERR_ENTITY_DELETED",
"message": "Entity is deleted"
}
]
}
```
**Code Samples:**
**cURL:**
```shell
curl -X GET \
"https://{instance}.kiteworks.com/rest/folders/:id/quota" \
-H "Authorization: Bearer YOUR_TOKEN"
```
**Python:**
```python
import requests
id = "VALUE" # The unique identifier (UUID) of the entity.
url = f"https://{{instance}}.kiteworks.com/rest/folders/{id}/quota"
headers = {
"Authorization": "Bearer YOUR_TOKEN",
}
response = requests.get(url, headers=headers)
print(response.json())
```
---
## GET /rest/folders/{id}/children
**Summary:** List folder children
### Description:
Returns the list of folder children, where folders are fetched first, followed by files.
### Precondition:
User must have `properties_view` permission for the folder.
### Response:
Returns a list of folders and files within the specified folder.
### Sorting:
Sort string syntax `FIELD_NAME:ORDER`.
ORDER can be `asc` or `desc`.
### Sorting options:
| FIELD_NAME | Description |
|------------|-------------|
| name | The name of the folder or file |
| created | The creation datetime of the folder or file |
| modified | The last modified datetime of the folder or file |
| size | The number of items in the folder (for folders) or the file size (for files) |
**Parameters:**
| Name | In | Required | Description |
|------|----|----------|-------------|
| `id` | path | yes | The unique identifier (UUID) of the entity. |
| `deleted` | query | no | Filter by deletion status. If true, show only deleted items; if false, show non-deleted items; if not specified, show both deleted and non-deleted items. |
| `orderBy` | query | no | Sort order for the results. Default is `name:asc`. Allowed values: `name:asc`, `name:desc`, `created:asc`, `created:desc`, `modified:asc`, `modified:desc`, `size:asc`, `size:desc`. |
| `type` | query | no | Filter results by object type. `f` – Files only. `d` – Directories (folders) only. |
| `extensions` | query | no | A comma-delimited list of file extensions to include in the filter. |
| `regex` | query | no | A regular expression pattern used to filter files by their names or other attributes. |
| `name` | query | no | Filter by the name of the folder or file within the folder. |
| `fileId` | query | no | Filter by a specific file ID. |
| `limit` | query | no | Range limit. |
| `offset` | query | no | Range offset. |
| `with` | query | no | Specifies additional fields to include in the response. |
| `mode` | query | no | Determines the detail level of the response body. |
**Responses:**
| Code | Description |
|------|-------------|
| 200 | Returns the list of folder children. |
| 400 | Bad Request Possible error codes: ERR_REQUEST_INVALID_JSON |
| 401 | Unauthorized Possible error codes: ERR_ACCESS_USER, ERR_AUTH_INVALID_CSRF, ERR_AUTH_UNAUTHORIZED |
| 422 | Unprocessable Content Possible error codes: ERR_INVALID_PARAMETER |
| 490 | Request blocked by WAF |
**Response Examples:**
**400 (ERR_REQUEST_INVALID_JSON):**
```json
{
"errors": [
{
"code": "ERR_REQUEST_INVALID_JSON",
"message": "Invalid json provided"
}
]
}
```
**401 (ERR_ACCESS_USER):**
```json
{
"errors": [
{
"code": "ERR_ACCESS_USER",
"message": "Insufficient access permissions"
}
]
}
```
**401 (ERR_AUTH_INVALID_CSRF):**
```json
{
"errors": [
{
"code": "ERR_AUTH_INVALID_CSRF",
"message": "Invalid CSRF Authentication"
}
]
}
```
**401 (ERR_AUTH_UNAUTHORIZED):**
```json
{
"errors": [
{
"code": "ERR_AUTH_UNAUTHORIZED",
"message": "Unauthorized"
}
]
}
```
**422 (ERR_INVALID_PARAMETER):**
```json
{
"errors": [
{
"code": "ERR_INVALID_PARAMETER",
"message": "Invalid Parameter Exception"
}
]
}
```
**Code Samples:**
**cURL:**
```shell
curl -X GET \
"https://{instance}.kiteworks.com/rest/folders/:id/children" \
-H "Authorization: Bearer YOUR_TOKEN"
```
**Python:**
```python
import requests
id = "VALUE" # The unique identifier (UUID) of the entity.
url = f"https://{{instance}}.kiteworks.com/rest/folders/{id}/children"
headers = {
"Authorization": "Bearer YOUR_TOKEN",
}
response = requests.get(url, headers=headers)
print(response.json())
```
---
## GET /rest/folders/top
**Summary:** List top level folders
### Description:
Returns the list of top level folders.
### Precondition:
The user profile must have "Collaboration Allowed" enabled.
### Response:
Lists of top level folders are returned.
### Sorting:
Sort string syntax `FIELD_NAME:ORDER`.
ORDER can be `asc` or `desc`.
### Sorting options:
| FIELD_NAME | Description |
|------------|-------------|
| name | The name of the folder |
| created | The creation datetime of the folder |
| modified | The last modified datetime of the folder |
| size | The number of items in the folder |
**Parameters:**
| Name | In | Required | Description |
|------|----|----------|-------------|
| `deleted` | query | no | Filter by deletion status. If true, show only deleted items; if false, show non-deleted items; if not specified, show both deleted and non-deleted items. |
| `orderBy` | query | no | Sort order for the results. Default is `name:asc`. Allowed values: `name:asc`, `name:desc`, `created:asc`, `created:desc`, `modified:asc`, `modified:desc`, `size:asc`, `size:desc`. |
| `limit` | query | no | Range limit. |
| `offset` | query | no | Range offset. |
| `with` | query | no | Specifies additional fields to include in the response. |
| `mode` | query | no | Determines the detail level of the response body. |
**Responses:**
| Code | Description |
|------|-------------|
| 200 | The top level folders have been successfully returned. |
| 400 | Bad Request Possible error codes: ERR_REQUEST_INVALID_JSON |
| 401 | Unauthorized Possible error codes: ERR_ACCESS_USER, ERR_AUTH_INVALID_CSRF, ERR_AUTH_UNAUTHORIZED |
| 422 | Unprocessable Content Possible error codes: ERR_INVALID_PARAMETER |
| 490 | Request blocked by WAF |
**Response Examples:**
**400 (ERR_REQUEST_INVALID_JSON):**
```json
{
"errors": [
{
"code": "ERR_REQUEST_INVALID_JSON",
"message": "Invalid json provided"
}
]
}
```
**401 (ERR_ACCESS_USER):**
```json
{
"errors": [
{
"code": "ERR_ACCESS_USER",
"message": "Insufficient access permissions"
}
]
}
```
**401 (ERR_AUTH_INVALID_CSRF):**
```json
{
"errors": [
{
"code": "ERR_AUTH_INVALID_CSRF",
"message": "Invalid CSRF Authentication"
}
]
}
```
**401 (ERR_AUTH_UNAUTHORIZED):**
```json
{
"errors": [
{
"code": "ERR_AUTH_UNAUTHORIZED",
"message": "Unauthorized"
}
]
}
```
**422 (ERR_INVALID_PARAMETER):**
```json
{
"errors": [
{
"code": "ERR_INVALID_PARAMETER",
"message": "Invalid Parameter Exception"
}
]
}
```
**Code Samples:**
**cURL:**
```shell
curl -X GET \
"https://{instance}.kiteworks.com/rest/folders/top" \
-H "Authorization: Bearer YOUR_TOKEN"
```
**Python:**
```python
import requests
url = "https://{instance}.kiteworks.com/rest/folders/top"
headers = {
"Authorization": "Bearer YOUR_TOKEN",
}
response = requests.get(url, headers=headers)
print(response.json())
```
---
## GET /rest/folders/{id}
**Summary:** Return the folder
### Description:
Returns the folder corresponding to the provided ID.
### Precondition:
User must have `properties_view` permission for the folder.
### Response:
The folder is returned.
**Parameters:**
| Name | In | Required | Description |
|------|----|----------|-------------|
| `id` | path | yes | The unique identifier (UUID) of the entity. |
| `returnEntity` | query | no | If true, includes the entity in the response body. |
| `with` | query | no | Specifies additional fields to include in the response. |
| `mode` | query | no | Determines the detail level of the response body. |
**Responses:**
| Code | Description |
|------|-------------|
| 200 | The folder has been successfully returned. |
| 400 | Bad Request Possible error codes: ERR_REQUEST_INVALID_FILTER |
| 401 | Unauthorized Possible error codes: ERR_AUTH_INVALID_CSRF, ERR_AUTH_UNAUTHORIZED |
| 403 | Forbidden Possible error codes: ERR_ACCESS_USER, ERR_ACCESS_DENIED |
| 490 | Request blocked by WAF |
**Response Examples:**
**400 (ERR_REQUEST_INVALID_FILTER):**
```json
{
"errors": [
{
"code": "ERR_REQUEST_INVALID_FILTER",
"message": "Filter validation failed"
}
]
}
```
**401 (ERR_AUTH_INVALID_CSRF):**
```json
{
"errors": [
{
"code": "ERR_AUTH_INVALID_CSRF",
"message": "Invalid CSRF Authentication"
}
]
}
```
**401 (ERR_AUTH_UNAUTHORIZED):**
```json
{
"errors": [
{
"code": "ERR_AUTH_UNAUTHORIZED",
"message": "Unauthorized"
}
]
}
```
**403 (ERR_ACCESS_USER):**
```json
{
"errors": [
{
"code": "ERR_ACCESS_USER",
"message": "Insufficient access permissions"
}
]
}
```
**403 (ERR_ACCESS_DENIED):**
```json
{
"errors": [
{
"code": "ERR_ACCESS_DENIED",
"message": "Your access is denied.",
"redirectUrl": "/login?code=3317"
}
]
}
```
**Code Samples:**
**cURL:**
```shell
curl -X GET \
"https://{instance}.kiteworks.com/rest/folders/:id" \
-H "Authorization: Bearer YOUR_TOKEN"
```
**Python:**
```python
import requests
id = "VALUE" # The unique identifier (UUID) of the entity.
url = f"https://{{instance}}.kiteworks.com/rest/folders/{id}"
headers = {
"Authorization": "Bearer YOUR_TOKEN",
}
response = requests.get(url, headers=headers)
print(response.json())
```
---
## PUT /rest/folders/{id}
**Summary:** Update a folder
### Description:
Updates the properties of the specified folder.
### Precondition:
User must have `properties_edit` permission for the folder.
### Response:
The folder is updated.
**Parameters:**
| Name | In | Required | Description |
|------|----|----------|-------------|
| `id` | path | yes | The unique identifier (UUID) of the entity. |
| `returnEntity` | query | no | If true, includes the entity in the response body. |
| `with` | query | no | Specifies additional fields to include in the response. |
| `mode` | query | no | Determines the detail level of the response body. |
**Request Body:**
| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `name` | string | no | New name for the folder (maximum 255 characters). |
| `description` | string | no | Updated description for the folder. |
| `syncable` | boolean | no | Indicates whether the folder can be synced by the Desktop Sync Client. Can only be set on top-level folders. |
| `expire` | string | no | The folder expiration date. Applicable to top-level folders only. |
| `fileLifetime` | integer | no | Number of days files are retained in this folder before expiring. Set to 0 for no expiration. |
| `applyFileLifetimeToFiles` | boolean | no | If true, applies the updated `fileLifetime` setting to all existing files in this folder. |
| `applyFileLifetimeToNested` | boolean | no | If true, applies the updated `fileLifetime` setting to all nested subfolders. |
| `secure` | boolean | no | Marks the folder as secure, restricting access to authorised recipients only. Can only be set on top-level folders under the user's root folder. |
| `clientId` | string | no | Client application identifier used to associate the folder with a specific plugin or integration. |
| `vendorDocId` | string | no | External vendor document ID to link this folder to a document in a third-party system. |
| `vendorDocName` | string | no | Display name of the linked vendor document. |
| `useFolderQuota` | boolean | no | Indicates whether this is a system folder with its own dedicated storage quota. |
| `quota` | integer | no | Storage quota for the folder in bytes. Must be one of the permitted sizes: 1 GB (1,073,741,824), 2 GB (2,147,483,648), 5 GB (5,368,709,120), 10 GB (10,737,418,240), 50 GB (53,687,091,200), or -1 for unlimited. |
| `breakInheritance` | boolean | no | If true, breaks permission inheritance from the parent folder, making this folder's members independent. Only `true` is accepted; passing `false` is invalid. |
**Responses:**
| Code | Description |
|------|-------------|
| 200 | The folder has been updated successfully. |
| 401 | Unauthorized Possible error codes: ERR_AUTH_INVALID_CSRF, ERR_AUTH_UNAUTHORIZED |
| 403 | Forbidden Possible error codes: ERR_ACCESS_DENIED, ERR_ACCESS_USER |
| 409 | Conflict Possible error codes: ERR_ENTITY_EXISTS |
| 490 | Request blocked by WAF |
**Response Examples:**
**401 (ERR_AUTH_INVALID_CSRF):**
```json
{
"errors": [
{
"code": "ERR_AUTH_INVALID_CSRF",
"message": "Invalid CSRF Authentication"
}
]
}
```
**401 (ERR_AUTH_UNAUTHORIZED):**
```json
{
"errors": [
{
"code": "ERR_AUTH_UNAUTHORIZED",
"message": "Unauthorized"
}
]
}
```
**403 (ERR_ACCESS_DENIED):**
```json
{
"errors": [
{
"code": "ERR_ACCESS_DENIED",
"message": "Your access is denied.",
"redirectUrl": "/login?code=3317"
}
]
}
```
**403 (ERR_ACCESS_USER):**
```json
{
"errors": [
{
"code": "ERR_ACCESS_USER",
"message": "Insufficient access permissions"
}
]
}
```
**409 (ERR_ENTITY_EXISTS):**
```json
{
"errors": [
{
"code": "ERR_ENTITY_EXISTS",
"message": "Entity exists"
}
]
}
```
**Code Samples:**
**cURL:**
```shell
curl -X PUT \
"https://{instance}.kiteworks.com/rest/folders/:id" \
-H "Authorization: Bearer YOUR_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"name": "string",
"description": "string",
"syncable": true,
"expire": "2024-01-15",
"fileLifetime": 1,
"applyFileLifetimeToFiles": true
}'
```
**Python:**
```python
import requests
id = "VALUE" # The unique identifier (UUID) of the entity.
url = f"https://{{instance}}.kiteworks.com/rest/folders/{id}"
headers = {
"Authorization": "Bearer YOUR_TOKEN",
"Content-Type": "application/json",
}
payload = {
"name": "string",
"description": "string",
"syncable": true,
"expire": "2024-01-15",
"fileLifetime": 1,
"applyFileLifetimeToFiles": true
}
response = requests.put(url, headers=headers, json=payload)
print(response.json())
```
---
## DELETE /rest/folders/{id}
**Summary:** Delete a folder
### Description:
Deletes a specified folder.
### Precondition:
User must have `folder_delete` permission for the folder.
### Response:
The folder is deleted
## Additional Information:
The folder will be automatically deleted after a set number of days as configured by the administrator.
**Parameters:**
| Name | In | Required | Description |
|------|----|----------|-------------|
| `id` | path | yes | The unique identifier (UUID) of the entity. |
**Responses:**
| Code | Description |
|------|-------------|
| 204 | The folder has been successfully deleted. |
| 401 | Unauthorized Possible error codes: ERR_AUTH_INVALID_CSRF, ERR_AUTH_UNAUTHORIZED |
| 403 | Forbidden Possible error codes: ERR_SYSTEM_TENANT_SUSPENDED, ERR_ACCESS_DENIED, ERR_ENTITY_IS_SYNC_DIR, ERR_ENTITY_IS_MY_DIR, ERR_ENTITY_IS_BASE_DIR, ERR_ENTITY_IS_NOT_UPDATABLE, ERR_ENTITY_IS_SECURE_FOLDER, ERR_ENTITY_CONTAINS_LOCKED_FILES, ERR_ACCESS_USER, ERR_PROFILE_COLLABORATION_DISABLED, ERR_ENTITY_DELETED |
| 490 | Request blocked by WAF |
**Response Examples:**
**401 (ERR_AUTH_INVALID_CSRF):**
```json
{
"errors": [
{
"code": "ERR_AUTH_INVALID_CSRF",
"message": "Invalid CSRF Authentication"
}
]
}
```
**401 (ERR_AUTH_UNAUTHORIZED):**
```json
{
"errors": [
{
"code": "ERR_AUTH_UNAUTHORIZED",
"message": "Unauthorized"
}
]
}
```
**403 (ERR_SYSTEM_TENANT_SUSPENDED):**
```json
{
"errors": [
{
"code": "ERR_SYSTEM_TENANT_SUSPENDED",
"message": "Access to the service is restricted by the service provider. Contact your administrator for updates on restoring normal access."
}
]
}
```
**403 (ERR_ACCESS_DENIED):**
```json
{
"errors": [
{
"code": "ERR_ACCESS_DENIED",
"message": "Your access is denied.",
"redirectUrl": "/login?code=3317"
}
]
}
```
**403 (ERR_ENTITY_IS_SYNC_DIR):**
```json
{
"errors": [
{
"code": "ERR_ENTITY_IS_SYNC_DIR",
"message": "Operation not permitted on My Folder"
}
]
}
```
**403 (ERR_ENTITY_IS_MY_DIR):**
```json
{
"errors": [
{
"code": "ERR_ENTITY_IS_MY_DIR",
"message": "Operation not permitted on Tray Folder"
}
]
}
```
**403 (ERR_ENTITY_IS_BASE_DIR):**
```json
{
"errors": [
{
"code": "ERR_ENTITY_IS_BASE_DIR",
"message": "Operation not permitted on Base Folder"
}
]
}
```
**403 (ERR_ENTITY_IS_NOT_UPDATABLE):**
```json
{
"errors": [
{
"code": "ERR_ENTITY_IS_NOT_UPDATABLE",
"message": "Can not update folder"
}
]
}
```
**403 (ERR_ENTITY_IS_SECURE_FOLDER):**
```json
{
"errors": [
{
"code": "ERR_ENTITY_IS_SECURE_FOLDER",
"message": "Operation not permitted on restricted Folder."
}
]
}
```
**403 (ERR_ENTITY_CONTAINS_LOCKED_FILES):**
```json
{
"errors": [
{
"code": "ERR_ENTITY_CONTAINS_LOCKED_FILES",
"message": "Folder contains locked files"
}
]
}
```
**403 (ERR_ACCESS_USER):**
```json
{
"errors": [
{
"code": "ERR_ACCESS_USER",
"message": "Insufficient access permissions"
}
]
}
```
**403 (ERR_PROFILE_COLLABORATION_DISABLED):**
```json
{
"errors": [
{
"code": "ERR_PROFILE_COLLABORATION_DISABLED",
"message": "User's profile has no collaboration access"
}
]
}
```
**403 (ERR_ENTITY_DELETED):**
```json
{
"errors": [
{
"code": "ERR_ENTITY_DELETED",
"message": "Entity is deleted"
}
]
}
```
**Code Samples:**
**cURL:**
```shell
curl -X DELETE \
"https://{instance}.kiteworks.com/rest/folders/:id" \
-H "Authorization: Bearer YOUR_TOKEN"
```
**Python:**
```python
import requests
id = "VALUE" # The unique identifier (UUID) of the entity.
url = f"https://{{instance}}.kiteworks.com/rest/folders/{id}"
headers = {
"Authorization": "Bearer YOUR_TOKEN",
}
response = requests.delete(url, headers=headers)
print(response.json())
```
---
## GET /rest/folders/{id}/activities
**Summary:** Return folder activities
### Description:
Return the activities of a specified folder.
### Precondition:
The user must have the `user_view` permission for the folder.
### Response:
Returns the folder activities.
**Parameters:**
| Name | In | Required | Description |
|------|----|----------|-------------|
| `id` | path | yes | The unique identifier (UUID) of the entity. |
| `noDayBack` | query | no | Number of days to look back when searching for activities. |
| `startTime` | query | no | Start time of the search range, represented as a Unix timestamp. |
| `endTime` | query | no | End time of the search range, represented as a Unix timestamp. |
| `startDate` | query | no | Start date of the search range. |
| `endDate` | query | no | End date of the search range. |
| `filter` | query | no | Filter activities by ownership. `all` – Show all activities in the folder. `my` – Show only activities performed by the current user. |
| `search` | query | no | Search activities by email body, subject, sender, or recipients. |
| `type` | query | no | Filter activities by type. `all` – All activity types. `content_changes` – File content uploads or replacements. `file_changes` – File metadata changes (rename, move, delete, etc.). `folder_changes` – Folder-level changes. `kitepoint` – KitePoint reward activities. `mail` – Email send/receive activities. `tasks` – Task-related activities. `comments` – Comment activities. `folder_activities` – General folder activities. |
| `transactionId` | query | no | Filter activities by transaction ID. |
| `orderBy` | query | no | Sort order for the results. Default is `created:desc`. Allowed values: `id:asc`, `id:desc`, `created:asc`, `created:desc`, `event_name:asc`, `event_name:desc`, `name:asc`, `name:desc`. |
| `nested` | query | no | If set to `true`, includes activities from nested folders. |
| `fileId` | query | no | Specifies a file ID within the folder to filter activities related to that file. |
| `limit` | query | no | Range limit. |
| `offset` | query | no | Range offset. |
| `with` | query | no | Specifies additional fields to include in the response. |
| `mode` | query | no | Determines the detail level of the response body. |
**Responses:**
| Code | Description |
|------|-------------|
| 200 | Successfully return folder activities. |
| 401 | Unauthorized Possible error codes: ERR_ACCESS_USER, ERR_AUTH_INVALID_CSRF, ERR_AUTH_UNAUTHORIZED |
| 422 | Unprocessable Content Possible error codes: ERR_INVALID_PARAMETER |
| 490 | Request blocked by WAF |
**Response Examples:**
**401 (ERR_ACCESS_USER):**
```json
{
"errors": [
{
"code": "ERR_ACCESS_USER",
"message": "Insufficient access permissions"
}
]
}
```
**401 (ERR_AUTH_INVALID_CSRF):**
```json
{
"errors": [
{
"code": "ERR_AUTH_INVALID_CSRF",
"message": "Invalid CSRF Authentication"
}
]
}
```
**401 (ERR_AUTH_UNAUTHORIZED):**
```json
{
"errors": [
{
"code": "ERR_AUTH_UNAUTHORIZED",
"message": "Unauthorized"
}
]
}
```
**422 (ERR_INVALID_PARAMETER):**
```json
{
"errors": [
{
"code": "ERR_INVALID_PARAMETER",
"message": "Invalid Parameter Exception"
}
]
}
```
**Code Samples:**
**cURL:**
```shell
curl -X GET \
"https://{instance}.kiteworks.com/rest/folders/:id/activities" \
-H "Authorization: Bearer YOUR_TOKEN"
```
**Python:**
```python
import requests
id = "VALUE" # The unique identifier (UUID) of the entity.
url = f"https://{{instance}}.kiteworks.com/rest/folders/{id}/activities"
headers = {
"Authorization": "Bearer YOUR_TOKEN",
}
response = requests.get(url, headers=headers)
print(response.json())
```
---
## GET /rest/folders/{id}/activities/actions/exportCSV
**Summary:** Export folder activities
### Description:
Exports the activities of a folder in CSV format.
### Precondition:
The user must have the `user_view` permission for the folder.
### Response:
The folder activities are returned in CSV format.
**Parameters:**
| Name | In | Required | Description |
|------|----|----------|-------------|
| `id` | path | yes | The unique identifier (UUID) of the entity. |
| `noDayBack` | query | no | Number of days to look back when searching for activities. |
| `startTime` | query | no | Start time of the search range, represented as a Unix timestamp. |
| `endTime` | query | no | End time of the search range, represented as a Unix timestamp. |
| `startDate` | query | no | Start date of the search range. |
| `endDate` | query | no | End date of the search range. |
| `filter` | query | no | Filter activities by ownership. `all` – Show all activities in the folder. `my` – Show only activities performed by the current user. |
| `search` | query | no | Search activities by email body, subject, sender, or recipients. |
| `type` | query | no | Filter activities by type. `all` – All activity types. `content_changes` – File content uploads or replacements. `file_changes` – File metadata changes (rename, move, delete, etc.). `folder_changes` – Folder-level changes. `kitepoint` – KitePoint reward activities. `mail` – Email send/receive activities. `tasks` – Task-related activities. `comments` – Comment activities. `folder_activities` – General folder activities. |
| `transactionId` | query | no | Filter activities by transaction ID. |
| `orderBy` | query | no | Sort order for the results. Default is `created:desc`. Allowed values: `id:asc`, `id:desc`, `created:asc`, `created:desc`, `event_name:asc`, `event_name:desc`, `name:asc`, `name:desc`. |
| `nested` | query | no | If set to `true`, includes activities from nested folders. |
| `fileId` | query | no | Specifies a file ID within the folder to filter activities related to that file. |
| `limit` | query | no | Range limit. |
| `offset` | query | no | Range offset. |
| `with` | query | no | Specifies additional fields to include in the response. |
| `mode` | query | no | Determines the detail level of the response body. |
**Responses:**
| Code | Description |
|------|-------------|
| 200 | Successfully initiated the folder activities export. |
| 401 | Unauthorized Possible error codes: ERR_ACCESS_USER, ERR_AUTH_INVALID_CSRF, ERR_AUTH_UNAUTHORIZED |
| 422 | Unprocessable Content Possible error codes: ERR_INVALID_PARAMETER |
| 490 | Request blocked by WAF |
**Response Examples:**
**401 (ERR_ACCESS_USER):**
```json
{
"errors": [
{
"code": "ERR_ACCESS_USER",
"message": "Insufficient access permissions"
}
]
}
```
**401 (ERR_AUTH_INVALID_CSRF):**
```json
{
"errors": [
{
"code": "ERR_AUTH_INVALID_CSRF",
"message": "Invalid CSRF Authentication"
}
]
}
```
**401 (ERR_AUTH_UNAUTHORIZED):**
```json
{
"errors": [
{
"code": "ERR_AUTH_UNAUTHORIZED",
"message": "Unauthorized"
}
]
}
```
**422 (ERR_INVALID_PARAMETER):**
```json
{
"errors": [
{
"code": "ERR_INVALID_PARAMETER",
"message": "Invalid Parameter Exception"
}
]
}
```
**Code Samples:**
**cURL:**
```shell
curl -X GET \
"https://{instance}.kiteworks.com/rest/folders/:id/activities/actions/exportCSV" \
-H "Authorization: Bearer YOUR_TOKEN"
```
**Python:**
```python
import requests
id = "VALUE" # The unique identifier (UUID) of the entity.
url = f"https://{{instance}}.kiteworks.com/rest/folders/{id}/activities/actions/exportCSV"
headers = {
"Authorization": "Bearer YOUR_TOKEN",
}
response = requests.get(url, headers=headers)
print(response.json())
```
---
## DELETE /rest/folders/{id}/members/me
**Summary:** Remove oneself as a folder member
### Description:
Removes the current user from the specified folder.
### Precondition:
The user must be a member of the folder.
### Response:
The current user is removed from the folder.
**Parameters:**
| Name | In | Required | Description |
|------|----|----------|-------------|
| `id` | path | yes | The unique identifier (UUID) of the entity. |
| `downgradeNested` | query | no | If set to `true`, the user's role will be removed from all nested folders. |
**Responses:**
| Code | Description |
|------|-------------|
| 204 | The user was successfully removed from the folder. |
| 401 | Unauthorized Possible error codes: ERR_AUTH_INVALID_CSRF, ERR_AUTH_UNAUTHORIZED |
| 403 | Forbidden Possible error codes: ERR_ACCESS_USER, ERR_ENTITY_DELETED, ERR_INPUT_IS_OWNER, ERR_ENTITY_PARENT_FOLDER_MEMBER_EXISTS |
| 422 | Unprocessable Content Possible error codes: ERR_INVALID_PARAMETER |
| 490 | Request blocked by WAF |
**Response Examples:**
**401 (ERR_AUTH_INVALID_CSRF):**
```json
{
"errors": [
{
"code": "ERR_AUTH_INVALID_CSRF",
"message": "Invalid CSRF Authentication"
}
]
}
```
**401 (ERR_AUTH_UNAUTHORIZED):**
```json
{
"errors": [
{
"code": "ERR_AUTH_UNAUTHORIZED",
"message": "Unauthorized"
}
]
}
```
**403 (ERR_ACCESS_USER):**
```json
{
"errors": [
{
"code": "ERR_ACCESS_USER",
"message": "Insufficient access permissions"
}
]
}
```
**403 (ERR_ENTITY_DELETED):**
```json
{
"errors": [
{
"code": "ERR_ENTITY_DELETED",
"message": "Entity is deleted"
}
]
}
```
**403 (ERR_INPUT_IS_OWNER):**
```json
{
"errors": [
{
"code": "ERR_INPUT_IS_OWNER",
"message": "Can not set owner role"
}
]
}
```
**403 (ERR_ENTITY_PARENT_FOLDER_MEMBER_EXISTS):**
```json
{
"errors": [
{
"code": "ERR_ENTITY_PARENT_FOLDER_MEMBER_EXISTS",
"message": "Parent folder member exists"
}
]
}
```
**422 (ERR_INVALID_PARAMETER):**
```json
{
"errors": [
{
"code": "ERR_INVALID_PARAMETER",
"message": "Invalid Parameter Exception"
}
]
}
```
**Code Samples:**
**cURL:**
```shell
curl -X DELETE \
"https://{instance}.kiteworks.com/rest/folders/:id/members/me" \
-H "Authorization: Bearer YOUR_TOKEN"
```
**Python:**
```python
import requests
id = "VALUE" # The unique identifier (UUID) of the entity.
url = f"https://{{instance}}.kiteworks.com/rest/folders/{id}/members/me"
headers = {
"Authorization": "Bearer YOUR_TOKEN",
}
response = requests.delete(url, headers=headers)
print(response.json())
```
---
## PUT /rest/admin/folders
**Summary:** Bulk update folders
### Description:
Updates multiple folders in a single request.
### Precondition:
The user must be an administrator with access to the Files and Folders page in the Kiteworks PDN Admin.
### Response:
The specified folders are updated.
**Parameters:**
| Name | In | Required | Description |
|------|----|----------|-------------|
| `returnEntity` | query | no | If true, includes the entity in the response body. |
| `with` | query | no | Specifies additional fields to include in the response. |
| `mode` | query | no | Determines the detail level of the response body. |
**Request Body:**
| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `ids` | string[] | yes | List of folder object IDs to be updated. |
| `expire` | string | no | Expiration date for the folder. |
| `applyTo` | string | no | Defines the scope of the expiration update. `folders` – Apply expiration to folders only. `files` – Apply expiration to files only. `folders_and_files` – Apply expiration to both folders and files. |
| `quota` | integer | no | Storage quota for the folder in bytes. Must be one of the permitted sizes: 1 GB (1,073,741,824), 2 GB (2,147,483,648), 5 GB (5,368,709,120), 10 GB (10,737,418,240), 50 GB (53,687,091,200), or -1 for unlimited. |
| `applyToNestedFiles` | boolean | no | If set to `true`, expiration will also apply to files in child folders. |
**Responses:**
| Code | Description |
|------|-------------|
| 200 | Folders were updated successfully. |
| 401 | Unauthorized Possible error codes: ERR_AUTH_INVALID_CSRF, ERR_AUTH_UNAUTHORIZED |
| 403 | Forbidden Possible error codes: ERR_ACCESS_USER, ERR_ENTITY_DELETED, ERR_ENTITY_DLP_LOCKED, ERR_ENTITY_IS_BASE_DIR, ERR_ENTITY_IS_MY_DIR, ERR_ENTITY_IS_SYNC_DIR, ERR_ENTITY_NOT_SCANNED, ERR_ENTITY_VIRUS_FOUND, ERR_PROFILE_COLLABORATION_DISABLED |
| 422 | Unprocessable Content Possible error codes: ERR_INPUT_EXCEEDS_MAX_VALUE, ERR_INPUT_PAST_DATE, ERR_INVALID_PARAMETER, ERR_SYSTEM_EXTEND_FILE_EXPIRATION_DISABLED |
| 490 | Request blocked by WAF |
**Response Examples:**
**401 (ERR_AUTH_INVALID_CSRF):**
```json
{
"errors": [
{
"code": "ERR_AUTH_INVALID_CSRF",
"message": "Invalid CSRF Authentication"
}
]
}
```
**401 (ERR_AUTH_UNAUTHORIZED):**
```json
{
"errors": [
{
"code": "ERR_AUTH_UNAUTHORIZED",
"message": "Unauthorized"
}
]
}
```
**403 (ERR_ACCESS_USER):**
```json
{
"errors": [
{
"code": "ERR_ACCESS_USER",
"message": "Insufficient access permissions"
}
]
}
```
**403 (ERR_ENTITY_DELETED):**
```json
{
"errors": [
{
"code": "ERR_ENTITY_DELETED",
"message": "Entity is deleted"
}
]
}
```
**403 (ERR_ENTITY_DLP_LOCKED):**
```json
{
"errors": [
{
"code": "ERR_ENTITY_DLP_LOCKED",
"message": "One or more files have been quarantined and are not available to download. Please contact your administrator for assistance."
}
]
}
```
**403 (ERR_ENTITY_IS_BASE_DIR):**
```json
{
"errors": [
{
"code": "ERR_ENTITY_IS_BASE_DIR",
"message": "Operation not permitted on Base Folder"
}
]
}
```
**403 (ERR_ENTITY_IS_MY_DIR):**
```json
{
"errors": [
{
"code": "ERR_ENTITY_IS_MY_DIR",
"message": "Operation not permitted on Tray Folder"
}
]
}
```
**403 (ERR_ENTITY_IS_SYNC_DIR):**
```json
{
"errors": [
{
"code": "ERR_ENTITY_IS_SYNC_DIR",
"message": "Operation not permitted on My Folder"
}
]
}
```
**403 (ERR_ENTITY_NOT_SCANNED):**
```json
{
"errors": [
{
"code": "ERR_ENTITY_NOT_SCANNED",
"message": "One or more files are undergoing security and privacy scans. Please try again later."
}
]
}
```
**403 (ERR_ENTITY_VIRUS_FOUND):**
```json
{
"errors": [
{
"code": "ERR_ENTITY_VIRUS_FOUND",
"message": "File is infected"
}
]
}
```
**403 (ERR_PROFILE_COLLABORATION_DISABLED):**
```json
{
"errors": [
{
"code": "ERR_PROFILE_COLLABORATION_DISABLED",
"message": "User's profile has no collaboration access"
}
]
}
```
**422 (ERR_INPUT_EXCEEDS_MAX_VALUE):**
```json
{
"errors": [
{
"code": "ERR_INPUT_EXCEEDS_MAX_VALUE",
"message": "Field value exceeds maximum allowed value"
}
]
}
```
**422 (ERR_INPUT_PAST_DATE):**
```json
{
"errors": [
{
"code": "ERR_INPUT_PAST_DATE",
"message": "Field value should be future date"
}
]
}
```
**422 (ERR_INVALID_PARAMETER):**
```json
{
"errors": [
{
"code": "ERR_INVALID_PARAMETER",
"message": "Invalid Parameter Exception"
}
]
}
```
**422 (ERR_SYSTEM_EXTEND_FILE_EXPIRATION_DISABLED):**
```json
{
"errors": [
{
"code": "ERR_SYSTEM_EXTEND_FILE_EXPIRATION_DISABLED",
"message": "Extending file expiration is not allowed"
}
]
}
```
**Code Samples:**
**cURL:**
```shell
curl -X PUT \
"https://{instance}.kiteworks.com/rest/admin/folders" \
-H "Authorization: Bearer YOUR_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"ids": [
"string"
],
"expire": "2024-01-15",
"applyTo": "folders_only",
"quota": 1,
"applyToNestedFiles": true
}'
```
**Python:**
```python
import requests
url = "https://{instance}.kiteworks.com/rest/admin/folders"
headers = {
"Authorization": "Bearer YOUR_TOKEN",
"Content-Type": "application/json",
}
payload = {
"ids": [
"string"
],
"expire": "2024-01-15",
"applyTo": "folders_only",
"quota": 1,
"applyToNestedFiles": true
}
response = requests.put(url, headers=headers, json=payload)
print(response.json())
```
---