# Kiteworks API — files Operations
**65 endpoints** | [Browse interactive reference](https://developer.kiteworks.com/api-reference/files.html) | [Download spec slice](https://developer.kiteworks.com/assets/specs/files.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/files
**Summary:** Delete files
Deletes the specified files. Depending on the system retention policy, the files may be
recoverable until permanently deleted by the system.
**Requires `file_delete` permission
on the parent folder for each file.**
**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 | Files successfully deleted. |
| 403 | Forbidden Possible error codes: ERR_ENTITY_LOCKED |
| 490 | Request blocked by WAF |
**Response Examples:**
**403 (ERR_ENTITY_LOCKED):**
```json
{
"errors": {
"code": "ERR_ENTITY_LOCKED",
"message": "File is locked"
}
}
```
**Code Samples:**
**cURL:**
```shell
curl -X DELETE \
"https://{instance}.kiteworks.com/rest/files?id:in=VALUE" \
-H "Authorization: Bearer YOUR_TOKEN"
```
**Python:**
```python
import requests
url = "https://{instance}.kiteworks.com/rest/files"
headers = {
"Authorization": "Bearer YOUR_TOKEN",
}
params = {
"id:in": "VALUE",
}
response = requests.delete(url, params=params, headers=headers)
print(response.json())
```
---
## POST /rest/files/actions/copy
**Summary:** Copy files
### Description:
Copies the specified files to a folder.
### Precondition:
Must be assigned the `file_copy` permission for the files being copied and `file_add` permission for the destination folder.
### Response:
Copies the files to the folder. If duplicate files exist, appends a number to copied file names.
**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. |
| `id:in` | query | no | Comma-separated list of file UUIDs to copy. Cannot be used together with `ids` in the request body. |
| `partialSuccess` | query | no | If true, successfully copied files are committed even if some files fail to copy. |
**Request Body:**
| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `ids` | string[] | no | List of file UUIDs to copy. Cannot be used together with `id:in` in the query string. |
| `destinationFolderId` | string | yes | UUID of the destination folder to copy the files into. |
| `replace` | boolean | no | If true, overwrites existing files in the destination folder if they share the same name. |
| `newFileName` | string | no | New name for the copied file. Only applicable when copying a single file into the same folder to avoid a name conflict. |
**Responses:**
| Code | Description |
|------|-------------|
| 201 | Files have been copied successfully. |
| 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, ERR_ENTITY_DELETED, ERR_ENTITY_COPIED_FROM_EC, ERR_ENTITY_EC_TO_EC, ERR_ENTITY_NOT_SCANNED, ERR_ENTITY_VIRUS_FOUND, ERR_ENTITY_RESTRICTED_EXTENSION, ERR_ENTITY_RESTRICTED_TYPE, ERR_ENTITY_IS_BASE_DIR, ERR_ENTITY_IS_MY_DIR |
| 413 | Content Too Large Possible error codes: ERR_SYSTEM_NO_STORAGE_AVAILABLE |
| 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"
}
]
}
```
**403 (ERR_ENTITY_DELETED):**
```json
{
"errors": [
{
"code": "ERR_ENTITY_DELETED",
"message": "Entity is deleted"
}
]
}
```
**403 (ERR_ENTITY_COPIED_FROM_EC):**
```json
{
"errors": [
{
"code": "ERR_ENTITY_COPIED_FROM_EC",
"message": "Can not perform action on file copied from Repositories Gateway source"
}
]
}
```
**403 (ERR_ENTITY_EC_TO_EC):**
```json
{
"errors": [
{
"code": "ERR_ENTITY_EC_TO_EC",
"message": "Unable to copy/move Repositories Gateway file to Repositories Gateway"
}
]
}
```
**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_ENTITY_RESTRICTED_EXTENSION):**
```json
{
"errors": [
{
"code": "ERR_ENTITY_RESTRICTED_EXTENSION",
"message": "File extension is in exclusion extensions list"
}
]
}
```
**403 (ERR_ENTITY_RESTRICTED_TYPE):**
```json
{
"errors": [
{
"code": "ERR_ENTITY_RESTRICTED_TYPE",
"message": "The specified entity mime type is not allowed."
}
]
}
```
**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"
}
]
}
```
**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."
}
]
}
```
**Code Samples:**
**cURL:**
```shell
curl -X POST \
"https://{instance}.kiteworks.com/rest/files/actions/copy" \
-H "Authorization: Bearer YOUR_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"ids": [
"a1b2c3d4-e5f6-7890-abcd-ef1234567890"
],
"destinationFolderId": "string",
"replace": true,
"newFileName": "string"
}'
```
**Python:**
```python
import requests
url = "https://{instance}.kiteworks.com/rest/files/actions/copy"
headers = {
"Authorization": "Bearer YOUR_TOKEN",
"Content-Type": "application/json",
}
payload = {
"ids": [
"a1b2c3d4-e5f6-7890-abcd-ef1234567890"
],
"destinationFolderId": "string",
"replace": true,
"newFileName": "string"
}
response = requests.post(url, headers=headers, json=payload)
print(response.json())
```
---
## PATCH /rest/files/actions/lock
**Summary:** Lock files
### Description:
Locks the specified files, preventing others from performing actions such as editing, moving, and deleting the files.
### Precondition:
Must be assigned the `lock` permission for the files.
### Response:
Locks the files.
**Parameters:**
| Name | In | Required | Description |
|------|----|----------|-------------|
| `id:in` | query | no | A comma-separated list of unique identifier (UUID) of the objects to be processed. |
| `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. |
| `partialSuccess` | query | no | If set to `true`, the operation will continue for the valid items even if some items result in failure. |
**Request Body:**
| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `ids` | string[] | no | A list of file object IDs to be locked/unlocked. |
**Responses:**
| Code | Description |
|------|-------------|
| 200 | The files have been successfully locked. |
| 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_ATTACHMENT, ERR_ENTITY_NOT_SCANNED, ERR_ENTITY_VIRUS_FOUND |
| 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_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_ATTACHMENT):**
```json
{
"errors": [
{
"code": "ERR_ENTITY_IS_ATTACHMENT",
"message": "Operation not permitted on attachment"
}
]
}
```
**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"
}
]
}
```
**422 (ERR_INVALID_PARAMETER):**
```json
{
"errors": [
{
"code": "ERR_INVALID_PARAMETER",
"message": "Invalid Parameter Exception"
}
]
}
```
**Code Samples:**
**cURL:**
```shell
curl -X PATCH \
"https://{instance}.kiteworks.com/rest/files/actions/lock" \
-H "Authorization: Bearer YOUR_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"ids": [
"a1b2c3d4-e5f6-7890-abcd-ef1234567890"
]
}'
```
**Python:**
```python
import requests
url = "https://{instance}.kiteworks.com/rest/files/actions/lock"
headers = {
"Authorization": "Bearer YOUR_TOKEN",
"Content-Type": "application/json",
}
payload = {
"ids": [
"a1b2c3d4-e5f6-7890-abcd-ef1234567890"
]
}
response = requests.patch(url, headers=headers, json=payload)
print(response.json())
```
---
## POST /rest/files/actions/move
**Summary:** Move files
### Description:
Moves the specified files to a folder.
### Precondition:
Must be assigned the `file_move` permission for the files being moved and the `file_add` permission for the destination folder.
### Response:
Moves the files to the 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. |
| `id:in` | query | no | Comma-separated list of file UUIDs to move. Cannot be used together with `ids` in the request body. |
| `partialSuccess` | query | no | If true, successfully moved files are committed even if some files fail to move. |
**Request Body:**
| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `ids` | string[] | no | List of file UUIDs to move. Cannot be used together with `id:in` in the query string. |
| `destinationFolderId` | string | yes | UUID of the destination folder to move the files into. |
| `replace` | boolean | no | If true, overwrites existing files in the destination folder if they share the same name. |
**Responses:**
| Code | Description |
|------|-------------|
| 201 | Files have been moved successfully. |
| 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, ERR_ENTITY_DELETED, ERR_ENTITY_COPIED_FROM_EC, ERR_ENTITY_EC_TO_EC, ERR_ENTITY_NOT_SCANNED, ERR_ENTITY_VIRUS_FOUND, ERR_ENTITY_RESTRICTED_EXTENSION, ERR_ENTITY_RESTRICTED_TYPE, ERR_ENTITY_IS_BASE_DIR, ERR_ENTITY_IS_MY_DIR |
| 413 | Content Too Large Possible error codes: ERR_SYSTEM_NO_STORAGE_AVAILABLE |
| 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"
}
]
}
```
**403 (ERR_ENTITY_DELETED):**
```json
{
"errors": [
{
"code": "ERR_ENTITY_DELETED",
"message": "Entity is deleted"
}
]
}
```
**403 (ERR_ENTITY_COPIED_FROM_EC):**
```json
{
"errors": [
{
"code": "ERR_ENTITY_COPIED_FROM_EC",
"message": "Can not perform action on file copied from Repositories Gateway source"
}
]
}
```
**403 (ERR_ENTITY_EC_TO_EC):**
```json
{
"errors": [
{
"code": "ERR_ENTITY_EC_TO_EC",
"message": "Unable to copy/move Repositories Gateway file to Repositories Gateway"
}
]
}
```
**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_ENTITY_RESTRICTED_EXTENSION):**
```json
{
"errors": [
{
"code": "ERR_ENTITY_RESTRICTED_EXTENSION",
"message": "File extension is in exclusion extensions list"
}
]
}
```
**403 (ERR_ENTITY_RESTRICTED_TYPE):**
```json
{
"errors": [
{
"code": "ERR_ENTITY_RESTRICTED_TYPE",
"message": "The specified entity mime type is not allowed."
}
]
}
```
**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"
}
]
}
```
**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."
}
]
}
```
**Code Samples:**
**cURL:**
```shell
curl -X POST \
"https://{instance}.kiteworks.com/rest/files/actions/move" \
-H "Authorization: Bearer YOUR_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"ids": [
"a1b2c3d4-e5f6-7890-abcd-ef1234567890"
],
"destinationFolderId": "string",
"replace": true
}'
```
**Python:**
```python
import requests
url = "https://{instance}.kiteworks.com/rest/files/actions/move"
headers = {
"Authorization": "Bearer YOUR_TOKEN",
"Content-Type": "application/json",
}
payload = {
"ids": [
"a1b2c3d4-e5f6-7890-abcd-ef1234567890"
],
"destinationFolderId": "string",
"replace": true
}
response = requests.post(url, headers=headers, json=payload)
print(response.json())
```
---
## DELETE /rest/files/actions/permanent
**Summary:** Delete files permanently
Permanently deletes the specified files. Files cannot be recovered after this operation.
**Requires `permanent delete` permission on the parent folder for each file.** Each file must
already be in the deleted state and must not be locked.
**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 | All specified files permanently deleted. |
| 403 | Forbidden Possible error codes: ERR_ENTITY_LOCKED |
| 490 | Request blocked by WAF |
**Response Examples:**
**403 (ERR_ENTITY_LOCKED):**
```json
{
"errors": {
"code": "ERR_ENTITY_LOCKED",
"message": "File is locked"
}
}
```
**Code Samples:**
**cURL:**
```shell
curl -X DELETE \
"https://{instance}.kiteworks.com/rest/files/actions/permanent?id:in=VALUE" \
-H "Authorization: Bearer YOUR_TOKEN"
```
**Python:**
```python
import requests
url = "https://{instance}.kiteworks.com/rest/files/actions/permanent"
headers = {
"Authorization": "Bearer YOUR_TOKEN",
}
params = {
"id:in": "VALUE",
}
response = requests.delete(url, params=params, headers=headers)
print(response.json())
```
---
## PATCH /rest/files/actions/recover
**Summary:** Recover deleted files
Recovers the specified deleted files, restoring them to their parent folders.
**Requires
`file_recover` permission on the parent folder for each file.** Each file must be in the
deleted state and must not be permanently deleted.
**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 recovered files with their restored status. |
| 490 | Request blocked by WAF |
**Response Examples:**
**200 (FilesRecovered):**
```json
[
{
"id": "9",
"name": "report.pdf",
"size": 204800,
"mime": "application/pdf",
"deleted": false,
"locked": 0,
"created": "2024-03-01T10:00:00Z",
"modified": "2024-06-15T08:30:00Z"
},
{
"id": "10",
"name": "notes.docx",
"size": 51200,
"mime": "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
"deleted": false,
"locked": 0,
"created": "2024-04-10T11:00:00Z",
"modified": "2024-06-15T08:30:00Z"
}
]
```
**Code Samples:**
**cURL:**
```shell
curl -X PATCH \
"https://{instance}.kiteworks.com/rest/files/actions/recover?id:in=VALUE" \
-H "Authorization: Bearer YOUR_TOKEN"
```
**Python:**
```python
import requests
url = "https://{instance}.kiteworks.com/rest/files/actions/recover"
headers = {
"Authorization": "Bearer YOUR_TOKEN",
}
params = {
"id:in": "VALUE",
}
response = requests.patch(url, params=params, headers=headers)
print(response.json())
```
---
## POST /rest/files/actions/scan
**Summary:** Scan files for security
Queues security scans for the specified files. Depending on system scan policies, files are
scanned for anti-virus threats, data loss prevention (DLP) violations, and advanced threat
protection. Scans run asynchronously.
**Requires `view` permission on each file.** Files
must not be deleted.
**Parameters:**
| Name | In | Required | Description |
|------|----|----------|-------------|
| `returnEntity` | query | no | If set to `true`, returns information about the newly created entity. |
| `id:in` | query | no | 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 files for which security scans were queued. |
| 490 | Request blocked by WAF |
**Response Examples:**
**200 (ScansQueued):**
```json
[
{
"id": "9",
"name": "report.pdf",
"size": 204800,
"mime": "application/pdf",
"deleted": false,
"locked": 0,
"created": "2024-03-01T10:00:00Z",
"modified": "2024-06-15T08:30:00Z"
},
{
"id": "10",
"name": "notes.docx",
"size": 51200,
"mime": "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
"deleted": false,
"locked": 0,
"created": "2024-04-10T11:00:00Z",
"modified": "2024-06-15T08:30:00Z"
}
]
```
**Code Samples:**
**cURL:**
```shell
curl -X POST \
"https://{instance}.kiteworks.com/rest/files/actions/scan" \
-H "Authorization: Bearer YOUR_TOKEN"
```
**Python:**
```python
import requests
url = "https://{instance}.kiteworks.com/rest/files/actions/scan"
headers = {
"Authorization": "Bearer YOUR_TOKEN",
}
response = requests.post(url, headers=headers)
print(response.json())
```
---
## PATCH /rest/files/actions/unlock
**Summary:** Unlock files
### Description:
Unlocks the specified files, enabling others to perform actions such as edit, move, and delete the files.
### Precondition:
Must be assigned the `unlock` permission for the files.
### Response:
Unlocks the files.
**Parameters:**
| Name | In | Required | Description |
|------|----|----------|-------------|
| `id:in` | query | no | A comma-separated list of unique identifier (UUID) of the objects to be processed. |
| `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. |
| `partialSuccess` | query | no | If set to `true`, the operation will continue for the valid items even if some items result in failure. |
**Request Body:**
| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `ids` | string[] | no | A list of file object IDs to be locked/unlocked. |
**Responses:**
| Code | Description |
|------|-------------|
| 200 | The files have been successfully unlocked. |
| 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_ATTACHMENT, ERR_ENTITY_NOT_SCANNED, ERR_ENTITY_VIRUS_FOUND |
| 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_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_ATTACHMENT):**
```json
{
"errors": [
{
"code": "ERR_ENTITY_IS_ATTACHMENT",
"message": "Operation not permitted on attachment"
}
]
}
```
**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"
}
]
}
```
**422 (ERR_INVALID_PARAMETER):**
```json
{
"errors": [
{
"code": "ERR_INVALID_PARAMETER",
"message": "Invalid Parameter Exception"
}
]
}
```
**Code Samples:**
**cURL:**
```shell
curl -X PATCH \
"https://{instance}.kiteworks.com/rest/files/actions/unlock" \
-H "Authorization: Bearer YOUR_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"ids": [
"a1b2c3d4-e5f6-7890-abcd-ef1234567890"
]
}'
```
**Python:**
```python
import requests
url = "https://{instance}.kiteworks.com/rest/files/actions/unlock"
headers = {
"Authorization": "Bearer YOUR_TOKEN",
"Content-Type": "application/json",
}
payload = {
"ids": [
"a1b2c3d4-e5f6-7890-abcd-ef1234567890"
]
}
response = requests.patch(url, headers=headers, json=payload)
print(response.json())
```
---
## GET /rest/files/actions/zip
**Summary:** Download files and folders in ZIP format
Downloads the specified files and folders as a ZIP archive. Folder contents are included
recursively. Optionally filtered by file extension.
**Requires `download` permission on
each file and folder.** Files must not be deleted, infected, or DLP-locked.
**Parameters:**
| Name | In | Required | Description |
|------|----|----------|-------------|
| `name` | query | no | The name for the generated ZIP archive. |
| `fileId:in` | query | no | A comma-separated list of file IDs to include in the ZIP archive.. Search for results that match any of the specified values for this parameter. |
| `folderId:in` | query | no | A comma-separated list of folder IDs to include in the ZIP archive.. Search for results that match any of the specified values for this parameter. |
| `username` | query | no | The email address of the user requesting the ZIP archive. |
| `extensions` | query | no | Filter files by the specified comma-separated list of extensions. |
| `utcOffset` | query | no | The user's timezone offset in seconds (e.g., UTC+08:00 = 28800). |
| `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 |
|------|-------------|
| 200 | Returns a binary ZIP archive containing the requested files and folders. |
| 403 | Forbidden Possible error codes: ERR_ACCESS_USER |
| 490 | Request blocked by WAF |
**Response Examples:**
**403 (ERR_ACCESS_USER):**
```json
{
"errors": {
"code": "ERR_ACCESS_USER",
"message": "Insufficient access permissions"
}
}
```
**Code Samples:**
**cURL:**
```shell
curl -X GET \
"https://{instance}.kiteworks.com/rest/files/actions/zip" \
-H "Authorization: Bearer YOUR_TOKEN"
```
**Python:**
```python
import requests
url = "https://{instance}.kiteworks.com/rest/files/actions/zip"
headers = {
"Authorization": "Bearer YOUR_TOKEN",
}
response = requests.get(url, headers=headers)
print(response.json())
```
---
## GET /rest/files/actions/zipStatus
**Summary:** Get file and folder security status
### Description:
Gets the security scan results of specified files and folders in preparation for downloading them in ZIP format.
### Precondition:
Must be assigned the `download` permission for the files and folders.
### Response:
Returns an empty response if all files are safe for download.
**Parameters:**
| Name | In | Required | Description |
|------|----|----------|-------------|
| `fileId:in` | query | no | A comma-separated list of file IDs (UUID) to check. (Recommended request size <= 100) |
| `folderId:in` | query | no | A comma-separated list of folder IDs (UUID) to check. (Recommended request size <= 100) |
| `partialSuccess` | query | no | Indicates whether the operation should proceed if some files/folders fail the check. |
| `extensions` | query | no | Filter results to include only files with the specified comma-separated list of extensions. |
**Responses:**
| Code | Description |
|------|-------------|
| 200 | All files and folders are verified as safe for zipping and download. |
| 400 | Bad Request Possible error codes: ERR_REQUEST_INVALID_FILTER |
| 401 | Unauthorized Possible error codes: ERR_AUTH_UNAUTHORIZED |
| 403 | Forbidden Possible error codes: ERR_SYSTEM_TENANT_SUSPENDED, ERR_ACCESS_USER, ERR_ENTITY_VIRUS_FOUND, ERR_ENTITY_NOT_SCANNED, ERR_ENTITY_DLP_LOCKED, ERR_ENTITY_DLP_SCANNING, ERR_ENTITY_IS_SECURE_FOLDER, ERR_ENTITY_DELETED |
| 422 | Unprocessable Content Possible error codes: ERR_LICENSE_EXPIRED |
| 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_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_ENTITY_VIRUS_FOUND):**
```json
{
"errors": [
{
"code": "ERR_ENTITY_VIRUS_FOUND",
"message": "File is infected"
}
]
}
```
**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_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_DLP_SCANNING):**
```json
{
"errors": [
{
"code": "ERR_ENTITY_DLP_SCANNING",
"message": "One or more files are undergoing security and privacy scans. Please try again later."
}
]
}
```
**403 (ERR_ENTITY_IS_SECURE_FOLDER):**
```json
{
"errors": [
{
"code": "ERR_ENTITY_IS_SECURE_FOLDER",
"message": "Operation not permitted on restricted Folder."
}
]
}
```
**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/files/actions/zipStatus" \
-H "Authorization: Bearer YOUR_TOKEN"
```
**Python:**
```python
import requests
url = "https://{instance}.kiteworks.com/rest/files/actions/zipStatus"
headers = {
"Authorization": "Bearer YOUR_TOKEN",
}
response = requests.get(url, headers=headers)
print(response.json())
```
---
## GET /rest/files/{id}
**Summary:** Get file metadata
### Description:
Gets metadata for specified files, such as file owner, creation date, digital fingerprint, and security scan status.
### Precondition:
Must be assigned the `properties_view` permission for the file.
### Response:
Returns the file metadata.
**Parameters:**
| Name | In | Required | Description |
|------|----|----------|-------------|
| `id` | path | yes | The unique identifier (UUID) of the entity. |
| `requirementId` | query | no | UUID of the approval requirement. Required together with `accessVerificationId` to access a file under an approval workflow. |
| `accessVerificationId` | query | no | UUID of the access verification event. Required together with `requirementId` to validate approver access. |
**Responses:**
| Code | Description |
|------|-------------|
| 200 | The file has been successfully returned. |
| 400 | Bad Request Possible error codes: ERR_REQUEST_INVALID_FILTER |
| 401 | Unauthorized Possible error codes: ERR_AUTH_UNAUTHORIZED |
| 403 | Forbidden Possible error codes: ERR_ACCESS_USER, ERR_AUTH_INVALID_CSRF, 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_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_AUTH_INVALID_CSRF):**
```json
{
"errors": [
{
"code": "ERR_AUTH_INVALID_CSRF",
"message": "Invalid CSRF Authentication"
}
]
}
```
**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/files/: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/files/{id}"
headers = {
"Authorization": "Bearer YOUR_TOKEN",
}
response = requests.get(url, headers=headers)
print(response.json())
```
---
## POST /rest/files/{id}
**Summary:** Upload a file version
Uploads a new version of the specified file. The uploaded content becomes the new current version (version 0), and the previous current version is incremented. **Requires `version_create` permission on the file.**
**Parameters:**
| Name | In | Required | Description |
|------|----|----------|-------------|
| `id` | path | yes | The unique identifier (UUID) of the file |
| `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. |
**Request Body:**
| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `body` | string | yes | Binary content of the file |
| `clientCreated` | string | no | The date and time when the file was created on the client side. |
| `clientModified` | string | no | The date and time when the file was last modified on the client side. |
**Responses:**
| Code | Description |
|------|-------------|
| 200 | Returns the updated file record reflecting the newly uploaded version. |
| 403 | Forbidden Possible error codes: ERR_ENTITY_LOCKED, ERR_ENTITY_RESTRICTED_EXTENSION, ERR_ENTITY_RESTRICTED_EXTENSION_CUSTOM, ERR_ENTITY_RESTRICTED_TYPE, ERR_ENTITY_RESTRICTED_TYPE_CUSTOM, ERR_ENTITY_RESTRICTED_TYPE_GROUP |
| 422 | Unprocessable Content Possible error codes: ERR_INPUT_INVALID_DATE |
| 490 | Request blocked by WAF |
**Response Examples:**
**200 (New version uploaded):**
```json
{
"id": 7,
"name": "quarterly-report-v2.pdf",
"parent_id": 3,
"size": 215040,
"mime": "application/pdf",
"created": "2024-01-05T09:00:00+00:00",
"modified": "2024-03-15T10:23:45+00:00",
"deleted": false,
"locked": 0
}
```
**403 (ERR_ENTITY_LOCKED):**
```json
{
"errors": {
"code": "ERR_ENTITY_LOCKED",
"message": "File is locked"
}
}
```
**403 (ERR_ENTITY_RESTRICTED_EXTENSION):**
```json
{
"errors": {
"code": "ERR_ENTITY_RESTRICTED_EXTENSION",
"message": "File extension is in exclusion extensions list"
}
}
```
**403 (ERR_ENTITY_RESTRICTED_EXTENSION_CUSTOM):**
```json
{
"errors": {
"code": "ERR_ENTITY_RESTRICTED_EXTENSION_CUSTOM",
"message": "File extension is in custom exclusion extensions list"
}
}
```
**403 (ERR_ENTITY_RESTRICTED_TYPE):**
```json
{
"errors": {
"code": "ERR_ENTITY_RESTRICTED_TYPE",
"message": "The specified entity mime type is not allowed."
}
}
```
**403 (ERR_ENTITY_RESTRICTED_TYPE_CUSTOM):**
```json
{
"errors": {
"code": "ERR_ENTITY_RESTRICTED_TYPE_CUSTOM",
"message": "The specified file type is in custom excluded file types list."
}
}
```
**403 (ERR_ENTITY_RESTRICTED_TYPE_GROUP):**
```json
{
"errors": {
"code": "ERR_ENTITY_RESTRICTED_TYPE_GROUP",
"message": "File mime type is in exclusion groups list."
}
}
```
**Code Samples:**
**cURL:**
```shell
curl -X POST \
"https://{instance}.kiteworks.com/rest/files/:id" \
-H "Authorization: Bearer YOUR_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"body": "string",
"clientCreated": "string",
"clientModified": "string"
}'
```
**Python:**
```python
import requests
id = "VALUE" # The unique identifier (UUID) of the file
url = f"https://{{instance}}.kiteworks.com/rest/files/{id}"
headers = {
"Authorization": "Bearer YOUR_TOKEN",
"Content-Type": "application/json",
}
payload = {
"body": "string",
"clientCreated": "string",
"clientModified": "string"
}
response = requests.post(url, headers=headers, json=payload)
print(response.json())
```
---
## PUT /rest/files/{id}
**Summary:** Update a file
### Description:
Updates a file's properties such as name and expiration date.
### Precondition:
User must have `properties_edit` permission for the file.
### Response:
The file 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 | The new name for the file. |
| `expire` | string | no | The updated expiration date for the file. |
| `replace` | boolean | no | Indicates whether to replace the existing file if one with the same name already exists. |
**Responses:**
| Code | Description |
|------|-------------|
| 200 | The file has been updated successfully. |
| 401 | Unauthorized Possible error codes: ERR_AUTH_INVALID_CSRF, ERR_AUTH_UNAUTHORIZED |
| 403 | Forbidden Possible error codes: ERR_ACCESS_USER, ERR_ACCESS_DENIED, ERR_ENTITY_DELETED |
| 422 | Unprocessable Content Possible error codes: ERR_ENTITY_LOCKED, ERR_INVALID_PARAMETER, ERR_ENTITY_RESTRICTED_EXTENSION, ERR_ENTITY_RESTRICTED_EXTENSION_CUSTOM, ERR_ENTITY_RESTRICTED_TYPE, ERR_ENTITY_RESTRICTED_TYPE_CUSTOM, ERR_ENTITY_RESTRICTED_TYPE_GROUP, 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_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_ENTITY_LOCKED):**
```json
{
"errors": [
{
"code": "ERR_ENTITY_LOCKED",
"message": "File is locked"
}
]
}
```
**422 (ERR_INVALID_PARAMETER):**
```json
{
"errors": [
{
"code": "ERR_INVALID_PARAMETER",
"message": "Invalid Parameter Exception"
}
]
}
```
**422 (ERR_ENTITY_RESTRICTED_EXTENSION):**
```json
{
"errors": [
{
"code": "ERR_ENTITY_RESTRICTED_EXTENSION",
"message": "File extension is in exclusion extensions list"
}
]
}
```
**422 (ERR_ENTITY_RESTRICTED_EXTENSION_CUSTOM):**
```json
{
"errors": [
{
"code": "ERR_ENTITY_RESTRICTED_EXTENSION_CUSTOM",
"message": "File extension is in custom exclusion extensions list"
}
]
}
```
**422 (ERR_ENTITY_RESTRICTED_TYPE):**
```json
{
"errors": [
{
"code": "ERR_ENTITY_RESTRICTED_TYPE",
"message": "The specified entity mime type is not allowed."
}
]
}
```
**422 (ERR_ENTITY_RESTRICTED_TYPE_CUSTOM):**
```json
{
"errors": [
{
"code": "ERR_ENTITY_RESTRICTED_TYPE_CUSTOM",
"message": "The specified file type is in custom excluded file types list."
}
]
}
```
**422 (ERR_ENTITY_RESTRICTED_TYPE_GROUP):**
```json
{
"errors": [
{
"code": "ERR_ENTITY_RESTRICTED_TYPE_GROUP",
"message": "File mime type is in exclusion groups list."
}
]
}
```
**422 (ERR_ENTITY_EXISTS):**
```json
{
"errors": [
{
"code": "ERR_ENTITY_EXISTS",
"message": "Entity exists"
}
]
}
```
**Code Samples:**
**cURL:**
```shell
curl -X PUT \
"https://{instance}.kiteworks.com/rest/files/:id" \
-H "Authorization: Bearer YOUR_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"name": "string",
"expire": "2024-01-15",
"replace": true
}'
```
**Python:**
```python
import requests
id = "VALUE" # The unique identifier (UUID) of the entity.
url = f"https://{{instance}}.kiteworks.com/rest/files/{id}"
headers = {
"Authorization": "Bearer YOUR_TOKEN",
"Content-Type": "application/json",
}
payload = {
"name": "string",
"expire": "2024-01-15",
"replace": true
}
response = requests.put(url, headers=headers, json=payload)
print(response.json())
```
---
## DELETE /rest/files/{id}
**Summary:** Delete a file
Deletes the specified file. Depending on the system retention policy, the file may be
recoverable until permanently deleted by the system.
**Requires `delete` permission on
the parent folder.** The file must not be locked.
**Parameters:**
| Name | In | Required | Description |
|------|----|----------|-------------|
| `id` | path | yes | The unique identifier (UUID) of the file. |
**Responses:**
| Code | Description |
|------|-------------|
| 204 | File successfully deleted. |
| 403 | Forbidden Possible error codes: ERR_ENTITY_LOCKED |
| 490 | Request blocked by WAF |
**Response Examples:**
**403 (ERR_ENTITY_LOCKED):**
```json
{
"errors": {
"code": "ERR_ENTITY_LOCKED",
"message": "File is locked"
}
}
```
**Code Samples:**
**cURL:**
```shell
curl -X DELETE \
"https://{instance}.kiteworks.com/rest/files/:id" \
-H "Authorization: Bearer YOUR_TOKEN"
```
**Python:**
```python
import requests
id = "VALUE" # The unique identifier (UUID) of the file.
url = f"https://{{instance}}.kiteworks.com/rest/files/{id}"
headers = {
"Authorization": "Bearer YOUR_TOKEN",
}
response = requests.delete(url, headers=headers)
print(response.json())
```
---
## PATCH /rest/files/{id}/actions/lock
**Summary:** Lock a file
Locks the specified file, preventing other users from editing, moving, or deleting it until
the lock is released.
**Requires `lock` permission on the file.** The file must not already
be locked or deleted.
**Parameters:**
| Name | In | Required | Description |
|------|----|----------|-------------|
| `id` | path | yes | The unique identifier (UUID) of the file |
| `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 file with its updated lock status. |
| 403 | Forbidden Possible error codes: ERR_ENTITY_LOCKED |
| 490 | Request blocked by WAF |
**Response Examples:**
**200 (FileLocked):**
```json
{
"id": "9",
"name": "report.pdf",
"size": 204800,
"mime": "application/pdf",
"deleted": false,
"locked": 101,
"expire": null,
"created": "2024-03-01T10:00:00Z",
"modified": "2024-06-20T09:00:00Z"
}
```
**403 (ERR_ENTITY_LOCKED):**
```json
{
"errors": {
"code": "ERR_ENTITY_LOCKED",
"message": "File is locked"
}
}
```
**Code Samples:**
**cURL:**
```shell
curl -X PATCH \
"https://{instance}.kiteworks.com/rest/files/:id/actions/lock" \
-H "Authorization: Bearer YOUR_TOKEN"
```
**Python:**
```python
import requests
id = "VALUE" # The unique identifier (UUID) of the file
url = f"https://{{instance}}.kiteworks.com/rest/files/{id}/actions/lock"
headers = {
"Authorization": "Bearer YOUR_TOKEN",
}
response = requests.patch(url, headers=headers)
print(response.json())
```
---
## DELETE /rest/files/{id}/actions/permanent
**Summary:** Permanently delete a file
### Description:
Permanently deletes the specified file. The file must have been soft-deleted first.
### Precondition:
The user must be the owner, manager, or collaborator of the file.
The file must not be locked or safe-edit locked, unless the user is an admin.
The file must have been soft-deleted via `DELETE /rest/files/{id}`.
### Response:
The file is permanently deleted and its content cannot be retrieved.
**Parameters:**
| Name | In | Required | Description |
|------|----|----------|-------------|
| `id` | path | yes | The unique identifier (UUID) of the entity. |
**Responses:**
| Code | Description |
|------|-------------|
| 204 | The file has been permanently deleted. |
| 401 | Unauthorized Possible error codes: ERR_AUTH_UNAUTHORIZED, ERR_AUTH_INVALID_CSRF |
| 403 | Forbidden Possible error codes: ERR_ACCESS_USER, ERR_ENTITY_LOCKED, ERR_ENTITY_SAFE_EDIT_LOCKED |
| 490 | Request blocked by WAF |
**Response Examples:**
**401 (ERR_AUTH_UNAUTHORIZED):**
```json
{
"errors": [
{
"code": "ERR_AUTH_UNAUTHORIZED",
"message": "Unauthorized"
}
]
}
```
**401 (ERR_AUTH_INVALID_CSRF):**
```json
{
"errors": [
{
"code": "ERR_AUTH_INVALID_CSRF",
"message": "Invalid CSRF Authentication"
}
]
}
```
**403 (ERR_ACCESS_USER):**
```json
{
"errors": [
{
"code": "ERR_ACCESS_USER",
"message": "Insufficient access permissions"
}
]
}
```
**403 (ERR_ENTITY_LOCKED):**
```json
{
"errors": [
{
"code": "ERR_ENTITY_LOCKED",
"message": "File is locked"
}
]
}
```
**403 (ERR_ENTITY_SAFE_EDIT_LOCKED):**
```json
{
"errors": [
{
"code": "ERR_ENTITY_SAFE_EDIT_LOCKED",
"message": "File is under SafeEDIT by another user"
}
]
}
```
**Code Samples:**
**cURL:**
```shell
curl -X DELETE \
"https://{instance}.kiteworks.com/rest/files/:id/actions/permanent" \
-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/files/{id}/actions/permanent"
headers = {
"Authorization": "Bearer YOUR_TOKEN",
}
response = requests.delete(url, headers=headers)
print(response.json())
```
---
## PATCH /rest/files/{id}/actions/recover
**Summary:** Recover a file.
Recovers the specified deleted file, restoring it to its parent folder.
**Requires
`recover` permission on the parent folder.** The file must be in the deleted state and must
not be permanently deleted.
**Parameters:**
| Name | In | Required | Description |
|------|----|----------|-------------|
| `id` | path | yes | The unique identifier (UUID) of the file |
| `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 file with its restored status. |
| 490 | Request blocked by WAF |
**Response Examples:**
**200 (FileRecovered):**
```json
{
"id": "9",
"name": "report.pdf",
"size": 204800,
"mime": "application/pdf",
"deleted": false,
"locked": 0,
"expire": null,
"created": "2024-03-01T10:00:00Z",
"modified": "2024-06-15T08:30:00Z"
}
```
**Code Samples:**
**cURL:**
```shell
curl -X PATCH \
"https://{instance}.kiteworks.com/rest/files/:id/actions/recover" \
-H "Authorization: Bearer YOUR_TOKEN"
```
**Python:**
```python
import requests
id = "VALUE" # The unique identifier (UUID) of the file
url = f"https://{{instance}}.kiteworks.com/rest/files/{id}/actions/recover"
headers = {
"Authorization": "Bearer YOUR_TOKEN",
}
response = requests.patch(url, headers=headers)
print(response.json())
```
---
## PATCH /rest/files/{id}/actions/return
**Summary:** Check file into Repositories Gateway source
Checks the specified file back into its Repositories Gateway source. The local copy of
the file is permanently deleted after a successful check-in. If the file is locked in
the Repositories Gateway source and the caller has `unlock` permission, the lock is
released automatically.
**Requires `view` permission on the parent folder.** The file
must be eligible to return to source (i.e., it was originally checked out) and must not
be infected.
**Parameters:**
| Name | In | Required | Description |
|------|----|----------|-------------|
| `id` | path | yes | The unique identifier (UUID) of the file |
| `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 updated file metadata from the Repositories Gateway source after check-in. |
| 490 | Request blocked by WAF |
**Response Examples:**
**200 (FileCheckedIn):**
```json
{
"id": "kp-42",
"name": "report.pdf",
"parent_id": "kp-folder-7",
"type": "f",
"size": 204800,
"mime": "application/pdf",
"locked": false,
"status": "active",
"deleted": false,
"av_status": "allowed",
"dlp_status": "allowed",
"created": "2024-03-01T10:00:00Z",
"modified": "2024-06-20T14:00:00Z"
}
```
**Code Samples:**
**cURL:**
```shell
curl -X PATCH \
"https://{instance}.kiteworks.com/rest/files/:id/actions/return" \
-H "Authorization: Bearer YOUR_TOKEN"
```
**Python:**
```python
import requests
id = "VALUE" # The unique identifier (UUID) of the file
url = f"https://{{instance}}.kiteworks.com/rest/files/{id}/actions/return"
headers = {
"Authorization": "Bearer YOUR_TOKEN",
}
response = requests.patch(url, headers=headers)
print(response.json())
```
---
## POST /rest/files/{id}/actions/scan
**Summary:** Scan a file for security
Queues a security scan for the specified file. Depending on system scan policies, the file
is scanned for anti-virus threats, data loss prevention (DLP) violations, and advanced threat
protection. The scan runs asynchronously.
**Requires `view` permission on the file.**
The file must not be deleted.
**Parameters:**
| Name | In | Required | Description |
|------|----|----------|-------------|
| `id` | path | yes | The unique identifier (UUID) of the file |
| `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 file for which the security scan was queued. |
| 490 | Request blocked by WAF |
**Response Examples:**
**200 (ScanQueued):**
```json
{
"id": "9",
"name": "report.pdf",
"size": 204800,
"mime": "application/pdf",
"deleted": false,
"locked": 0,
"created": "2024-03-01T10:00:00Z",
"modified": "2024-06-15T08:30:00Z"
}
```
**Code Samples:**
**cURL:**
```shell
curl -X POST \
"https://{instance}.kiteworks.com/rest/files/:id/actions/scan" \
-H "Authorization: Bearer YOUR_TOKEN"
```
**Python:**
```python
import requests
id = "VALUE" # The unique identifier (UUID) of the file
url = f"https://{{instance}}.kiteworks.com/rest/files/{id}/actions/scan"
headers = {
"Authorization": "Bearer YOUR_TOKEN",
}
response = requests.post(url, headers=headers)
print(response.json())
```
---
## PATCH /rest/files/{id}/actions/unlock
**Summary:** Unlock a file
Unlocks the specified file, allowing other users to edit, move, and delete it.
**Requires `unlock` permission on the file.** The file must currently be locked.
**Parameters:**
| Name | In | Required | Description |
|------|----|----------|-------------|
| `id` | path | yes | The unique identifier (UUID) of the file |
| `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 file with its updated lock status. |
| 403 | Forbidden Possible error codes: ERR_ENTITY_LOCKED_BY_ANOTHER_USER, ERR_ENTITY_UNLOCKED |
| 490 | Request blocked by WAF |
**Response Examples:**
**200 (FileUnlocked):**
```json
{
"id": "9",
"name": "report.pdf",
"size": 204800,
"mime": "application/pdf",
"deleted": false,
"locked": 0,
"expire": null,
"created": "2024-03-01T10:00:00Z",
"modified": "2024-06-20T09:15:00Z"
}
```
**403 (ERR_ENTITY_LOCKED_BY_ANOTHER_USER):**
```json
{
"errors": {
"code": "ERR_ENTITY_LOCKED_BY_ANOTHER_USER",
"message": "File is locked by another user"
}
}
```
**403 (ERR_ENTITY_UNLOCKED):**
```json
{
"errors": {
"code": "ERR_ENTITY_UNLOCKED",
"message": "File is already unlocked"
}
}
```
**Code Samples:**
**cURL:**
```shell
curl -X PATCH \
"https://{instance}.kiteworks.com/rest/files/:id/actions/unlock" \
-H "Authorization: Bearer YOUR_TOKEN"
```
**Python:**
```python
import requests
id = "VALUE" # The unique identifier (UUID) of the file
url = f"https://{{instance}}.kiteworks.com/rest/files/{id}/actions/unlock"
headers = {
"Authorization": "Bearer YOUR_TOKEN",
}
response = requests.patch(url, headers=headers)
print(response.json())
```
---
## GET /rest/files/{id}/content
**Summary:** Download a file
### Description:
Downloads the specified file.
### Precondition:
Must be assigned the `download` permission for the file.
### Response:
Downloads the file to the specified location.
**Parameters:**
| Name | In | Required | Description |
|------|----|----------|-------------|
| `id` | path | yes | The unique identifier (UUID) of the entity. |
| `Range` | header | no | Range of bytes to download. e.g. `bytes=0-1024` |
**Responses:**
| Code | Description |
|------|-------------|
| 200 | The file download request was successful. |
| 206 | The file was partially downloaded. |
| 401 | Unauthorized Possible error codes: ERR_AUTH_UNAUTHORIZED |
| 403 | Forbidden Possible error codes: ERR_ACCESS_USER, ERR_ENTITY_DELETED, ERR_ENTITY_DLP_LOCKED, ERR_ENTITY_IS_SECURE_FOLDER, ERR_ENTITY_NOT_SCANNED, ERR_ENTITY_VIRUS_FOUND |
| 490 | Request blocked by WAF |
**Response Examples:**
**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_SECURE_FOLDER):**
```json
{
"errors": [
{
"code": "ERR_ENTITY_IS_SECURE_FOLDER",
"message": "Operation not permitted on restricted 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"
}
]
}
```
**Code Samples:**
**cURL:**
```shell
curl -X GET \
"https://{instance}.kiteworks.com/rest/files/:id/content" \
-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/files/{id}/content"
headers = {
"Authorization": "Bearer YOUR_TOKEN",
}
response = requests.get(url, headers=headers)
print(response.json())
```
---
## GET /rest/files/{id}/externalEdit
**Summary:** Get access token for external file edit.
Retrieves a short-lived refresh token scoped to the specified file, authorizing an external
editor to download the current version and upload a new version.
**Requires `file_add`
permission on the parent folder.** The file must not be permanently deleted. Users with
Collaborator, Downloader, or Viewer roles cannot edit files in restricted folders.
**Parameters:**
| Name | In | Required | Description |
|------|----|----------|-------------|
| `id` | path | yes | The unique identifier of the file |
| `with` | query | no | With parameters |
| `mode` | query | no | Determines the detail level of the response body. |
**Responses:**
| Code | Description |
|------|-------------|
| 200 | Returns a short-lived refresh token with the scope and expiration required for external file editing. |
| 490 | Request blocked by WAF |
**Response Examples:**
**200 (ExternalEditToken):**
```json
{
"data": [
{
"user_id": 101,
"expire": "2024-06-20T10:05:00Z",
"scope": "GET/files/abc-123/content POST/files/abc-123",
"refresh_token": "rt_xK9mLpQ2nWvZ7rYsT4uA"
}
]
}
```
**Code Samples:**
**cURL:**
```shell
curl -X GET \
"https://{instance}.kiteworks.com/rest/files/:id/externalEdit" \
-H "Authorization: Bearer YOUR_TOKEN"
```
**Python:**
```python
import requests
id = "VALUE" # The unique identifier of the file
url = f"https://{{instance}}.kiteworks.com/rest/files/{id}/externalEdit"
headers = {
"Authorization": "Bearer YOUR_TOKEN",
}
response = requests.get(url, headers=headers)
print(response.json())
```
---
## GET /rest/files/{id}/members
**Summary:** Get users with access to a shared file
### Description:
Gets a list of users with access to the specified shared file. Also gets the file metadata, providing context and information about the shared file such as each user's role for accessing the file and the user who shared the file.
### Precondition:
File sharing must be activated on the system. Must be assigned the `user_view` permission for the shared file.
### Response:
Returns the list of users with access to the shared file, along with metadata about the shared file.
### 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 |
**Parameters:**
| Name | In | Required | Description |
|------|----|----------|-------------|
| `id` | path | yes | The unique identifier (UUID) of the entity. |
| `userId` | query | no | Filter results by user ID (UUID). |
| `groupId` | query | no | Filter results by LDAP group ID. |
| `roleId` | query | no | Filter results by role ID. |
| `userId:in` | query | no | Filter by a comma-separated list of user IDs (UUID). (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. `f` – File membership. `d` – Directory (folder) 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 file 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_ENTITY_DELETED, ERR_USER_TYPE_NO_ACCESS |
| 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_ENTITY_DELETED):**
```json
{
"errors": [
{
"code": "ERR_ENTITY_DELETED",
"message": "Entity is deleted"
}
]
}
```
**403 (ERR_USER_TYPE_NO_ACCESS):**
```json
{
"errors": [
{
"code": "ERR_USER_TYPE_NO_ACCESS",
"message": "Permission denied"
}
]
}
```
**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/files/: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/files/{id}/members"
headers = {
"Authorization": "Bearer YOUR_TOKEN",
}
response = requests.get(url, headers=headers)
print(response.json())
```
---
## DELETE /rest/files/{id}/members
**Summary:** Remove all access to a shared file
### Description:
Removes user access to the specified shared file.
### Precondition:
Must be assigned the `user_add` permission for the folder containing the shared file.
### Response:
Removes user access to the shared file.
**Parameters:**
| Name | In | Required | Description |
|------|----|----------|-------------|
| `id` | path | yes | The unique identifier (UUID) of the entity. |
**Responses:**
| Code | Description |
|------|-------------|
| 200 | All file members have been successfully removed. |
| 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 DELETE \
"https://{instance}.kiteworks.com/rest/files/: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/files/{id}/members"
headers = {
"Authorization": "Bearer YOUR_TOKEN",
}
response = requests.delete(url, headers=headers)
print(response.json())
```
---
## GET /rest/files/{id}/members/ldapGroup
**Summary:** List LDAP groups with access to a shared file
Returns a list of LDAP groups and their assigned roles for the folder containing the specified file. Requires the `user_view` permission on the shared file.
**Parameters:**
| Name | In | Required | Description |
|------|----|----------|-------------|
| `id` | path | yes | ID of the file |
| `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 folder containing the specified file, including each group's assigned role. |
| 490 | Request blocked by WAF |
**Response Examples:**
**200 (FileGroupList):**
```json
[
{
"objectId": "abc12345def67890ab",
"groupId": 42,
"roleId": 3
}
]
```
**Code Samples:**
**cURL:**
```shell
curl -X GET \
"https://{instance}.kiteworks.com/rest/files/:id/members/ldapGroup" \
-H "Authorization: Bearer YOUR_TOKEN"
```
**Python:**
```python
import requests
id = "VALUE" # ID of the file
url = f"https://{{instance}}.kiteworks.com/rest/files/{id}/members/ldapGroup"
headers = {
"Authorization": "Bearer YOUR_TOKEN",
}
response = requests.get(url, headers=headers)
print(response.json())
```
---
## GET /rest/files/{id}/members/ldapGroup/{ldap_group_id}
**Summary:** Get a specific LDAP group's access to a shared file
Returns the access grant record for the specified LDAP group on the folder containing the file, including the group's assigned role. Requires the `user_view` permission on the shared file.
**Parameters:**
| Name | In | Required | Description |
|------|----|----------|-------------|
| `id` | path | yes | ID of the file |
| `ldap_group_id` | path | yes | The unique identifier of the LDAP group. |
| `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 for the file's folder. |
| 490 | Request blocked by WAF |
**Response Examples:**
**200 (FileGroupMember):**
```json
{
"objectId": "abc12345def67890ab",
"groupId": 42,
"roleId": 4
}
```
**Code Samples:**
**cURL:**
```shell
curl -X GET \
"https://{instance}.kiteworks.com/rest/files/:id/members/ldapGroup/:ldap_group_id" \
-H "Authorization: Bearer YOUR_TOKEN"
```
**Python:**
```python
import requests
id = "VALUE" # ID of the file
ldap_group_id = "VALUE" # The unique identifier of the LDAP group.
url = f"https://{{instance}}.kiteworks.com/rest/files/{id}/members/ldapGroup/{ldap_group_id}"
headers = {
"Authorization": "Bearer YOUR_TOKEN",
}
response = requests.get(url, headers=headers)
print(response.json())
```
---
## GET /rest/files/{id}/members/{member_user_id}
**Summary:** Returns the specified user member associated with the file.
Returns the name of the specified user with access to the specified shared file. Also gets metadata, providing context and information about the user such as their ID, email address, and role for accessing the file. Must be assigned the `user_view` permission for the shared file.
**Parameters:**
| Name | In | Required | Description |
|------|----|----------|-------------|
| `id` | path | yes | The unique identifier (UUID) of the file. |
| `member_user_id` | path | yes | The unique identifier 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 for the file. |
| 490 | Request blocked by WAF |
**Response Examples:**
**200 (FileMember):**
```json
{
"objectId": "abc12345def67890ab",
"userId": "usr98765cba43210fe",
"roleId": 4
}
```
**Code Samples:**
**cURL:**
```shell
curl -X GET \
"https://{instance}.kiteworks.com/rest/files/:id/members/:member_user_id" \
-H "Authorization: Bearer YOUR_TOKEN"
```
**Python:**
```python
import requests
id = "VALUE" # The unique identifier (UUID) of the file.
member_user_id = "VALUE" # The unique identifier of the user member.
url = f"https://{{instance}}.kiteworks.com/rest/files/{id}/members/{member_user_id}"
headers = {
"Authorization": "Bearer YOUR_TOKEN",
}
response = requests.get(url, headers=headers)
print(response.json())
```
---
## PUT /rest/files/{id}/members/{member_user_id}
**Summary:** Update file member
### Description:
Changes the role assigned to the specified user for accessing the specified shared file.
### Precondition:
Must be assigned the `user_add` permission for the folder containing the file.
### Response:
Changes the user's role to the specified role.
**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. |
**Responses:**
| Code | Description |
|------|-------------|
| 200 | The file member's role has been successfully updated. |
| 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_ENTITY_IS_SECURE_FOLDER, ERR_ACCESS_USER, ERR_ENTITY_DELETED |
| 409 | Conflict Possible error codes: ERR_ENTITY_EXISTS, ERR_ENTITY_ROLE_IS_ASSIGNED, ERR_ENTITY_USER_HAS_INSUFFICIENT_PERMISSIONS |
| 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_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_IS_SECURE_FOLDER):**
```json
{
"errors": [
{
"code": "ERR_ENTITY_IS_SECURE_FOLDER",
"message": "Operation not permitted on restricted Folder."
}
]
}
```
**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"
}
]
}
```
**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_USER_HAS_INSUFFICIENT_PERMISSIONS):**
```json
{
"errors": [
{
"code": "ERR_ENTITY_USER_HAS_INSUFFICIENT_PERMISSIONS",
"message": "Target user has insufficient access permissions"
}
]
}
```
**422 (ERR_INVALID_PARAMETER):**
```json
{
"errors": [
{
"code": "ERR_INVALID_PARAMETER",
"message": "Invalid Parameter Exception"
}
]
}
```
**Code Samples:**
**cURL:**
```shell
curl -X PUT \
"https://{instance}.kiteworks.com/rest/files/: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/files/{id}/members/{member_user_id}"
headers = {
"Authorization": "Bearer YOUR_TOKEN",
}
response = requests.put(url, headers=headers)
print(response.json())
```
---
## DELETE /rest/files/{id}/members/{member_user_id}
**Summary:** Remove a user's access to a shared file
### Description:
Removes the specified user's access to the specified shared file.
### Precondition:
Must be assigned the `user_add` permission for the folder containing the shared file.
### Response:
Removes the user's access to the shared file.
**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. |
**Responses:**
| Code | Description |
|------|-------------|
| 200 | The member has been successfully removed from the file. |
| 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 DELETE \
"https://{instance}.kiteworks.com/rest/files/: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/files/{id}/members/{member_user_id}"
headers = {
"Authorization": "Bearer YOUR_TOKEN",
}
response = requests.delete(url, headers=headers)
print(response.json())
```
---
## GET /rest/files/{id}/path
**Summary:** Get file path
Returns the full ancestor path of the specified file, from the workspace root down to the
file's parent folder. Each element in the path represents a folder node with its ID and
name.
**Requires `properties_view` permission on the file.**
**Parameters:**
| Name | In | Required | Description |
|------|----|----------|-------------|
| `id` | path | yes | The unique identifier of the file |
| `mode` | query | no | Determines the detail level of the response body. |
**Responses:**
| Code | Description |
|------|-------------|
| 200 | Returns the full ancestor path of the file as an ordered list of folder nodes. |
| 490 | Request blocked by WAF |
**Response Examples:**
**200 (FilePathSuccess):**
```json
{
"data": [
{
"id": "1",
"name": "My Workspace"
},
{
"id": "3",
"name": "Documents"
}
],
"links": [
{
"rel": "self",
"href": "https:///rest/1.0/files/9/path"
}
]
}
```
**Code Samples:**
**cURL:**
```shell
curl -X GET \
"https://{instance}.kiteworks.com/rest/files/:id/path" \
-H "Authorization: Bearer YOUR_TOKEN"
```
**Python:**
```python
import requests
id = "VALUE" # The unique identifier of the file
url = f"https://{{instance}}.kiteworks.com/rest/files/{id}/path"
headers = {
"Authorization": "Bearer YOUR_TOKEN",
}
response = requests.get(url, headers=headers)
print(response.json())
```
---
## GET /rest/files/{id}/preview
**Summary:** Get file preview metadata
### Description:
Gets file preview metadata about the specified file, such as the permalink for previewing the file and if the file contains a watermark.
### Precondition:
Must be assigned the `view` permission for the file.
### Response:
Returns the file preview metadata.
**Parameters:**
| Name | In | Required | Description |
|------|----|----------|-------------|
| `id` | path | yes | The unique identifier (UUID) of the entity. |
**Responses:**
| Code | Description |
|------|-------------|
| 200 | The file preview information 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, ERR_ENTITY_DELETED |
| 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"
}
]
}
```
**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/files/:id/preview" \
-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/files/{id}/preview"
headers = {
"Authorization": "Bearer YOUR_TOKEN",
}
response = requests.get(url, headers=headers)
print(response.json())
```
---
## GET /rest/files/{id}/tasks
**Summary:** Get file tasks
Gets a list of tasks assigned to the specified file. **Requires `task_view` permission on the file's parent folder.**
**Parameters:**
| Name | In | Required | Description |
|------|----|----------|-------------|
| `id` | path | yes | The unique identifier (UUID) of the file. |
| `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 associated with the specified file. |
| 490 | Request blocked by WAF |
**Response Examples:**
**200 (File 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
}
],
"total": 1,
"page": 1,
"pageSize": 20
}
```
**Code Samples:**
**cURL:**
```shell
curl -X GET \
"https://{instance}.kiteworks.com/rest/files/:id/tasks" \
-H "Authorization: Bearer YOUR_TOKEN"
```
**Python:**
```python
import requests
id = "VALUE" # The unique identifier (UUID) of the file.
url = f"https://{{instance}}.kiteworks.com/rest/files/{id}/tasks"
headers = {
"Authorization": "Bearer YOUR_TOKEN",
}
response = requests.get(url, headers=headers)
print(response.json())
```
---
## POST /rest/files/{id}/tasks
**Summary:** Create file task
Creates a task for the specified file and assigns it to a user. The assignee must have at least `properties_view` permission on the file's parent folder. **Requires `task_add` permission on the file's parent folder.**
**Parameters:**
| Name | In | Required | Description |
|------|----|----------|-------------|
| `id` | path | yes | Object ID of the file task is created on |
| `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. |
**Request Body:**
| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `assigneeId` | integer | yes | Assignee user unique identifier |
| `due` | string | yes | Date and time by which the task must be completed |
| `parentId` | integer | no | Parent Comment identifier |
| `contents` | string | yes | Body text of the task |
| `addLinks` | boolean | no | Indicates whether HATEOAS links should be included in the response |
**Responses:**
| Code | Description |
|------|-------------|
| 200 | Returns the newly created task record. |
| 403 | Forbidden Possible error codes: ERR_ACCESS_USER |
| 422 | Unprocessable Content Possible error codes: ERR_INPUT_REQUIRED, ERR_INPUT_DATE_NOT_AFTER, ERR_INPUT_HTML_TAGS_INVALID |
| 490 | Request blocked by WAF |
**Response Examples:**
**200 (Task created):**
```json
{
"id": 15,
"object_id": 7,
"parent_id": 0,
"user_id": 3,
"assignee_id": 5,
"contents": "Review the quarterly report for accuracy.",
"status": "D",
"due": "2024-04-01T00:00:00+00:00",
"created": "2024-03-15T10:00:00+00:00",
"modified": "2024-03-15T10:00:00+00:00",
"deleted": false,
"folder_id": 3
}
```
**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_HTML_TAGS_INVALID):**
```json
{
"errors": {
"code": "ERR_INPUT_HTML_TAGS_INVALID",
"message": "Cannot contain HTML tags other than B, I, or U"
}
}
```
**Code Samples:**
**cURL:**
```shell
curl -X POST \
"https://{instance}.kiteworks.com/rest/files/:id/tasks" \
-H "Authorization: Bearer YOUR_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"assigneeId": 1,
"due": "2024-01-15",
"parentId": 1,
"contents": "string",
"addLinks": true
}'
```
**Python:**
```python
import requests
id = "VALUE" # Object ID of the file task is created on
url = f"https://{{instance}}.kiteworks.com/rest/files/{id}/tasks"
headers = {
"Authorization": "Bearer YOUR_TOKEN",
"Content-Type": "application/json",
}
payload = {
"assigneeId": 1,
"due": "2024-01-15",
"parentId": 1,
"contents": "string",
"addLinks": true
}
response = requests.post(url, headers=headers, json=payload)
print(response.json())
```
---
## GET /rest/files/{id}/versions
**Summary:** Get file versions
Gets a list of file versions for the specified file. Also gets the file metadata, such as its owner, creation date, digital fingerprint, and security scan status. **Requires `version_view` permission on the file.**
**Parameters:**
| Name | In | Required | Description |
|------|----|----------|-------------|
| `id` | path | yes | The unique identifier (UUID) of the file. |
| `created` | query | no | File Version creation date |
| `created:gt` | query | no | File Version creation date. Search for results where this parameter value is greater than the specified value. |
| `created:gte` | query | no | File Version creation date. Search for results where this parameter value is greater than or equal to the specified value. |
| `created:lt` | query | no | File Version creation date. Search for results where this parameter value is less than the specified value. |
| `created:lte` | query | no | File Version creation date. Search for results where this parameter value is less than or equal to the specified value. |
| `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 version records for the specified file. |
| 490 | Request blocked by WAF |
**Response Examples:**
**200 (Version list):**
```json
{
"data": [
{
"id": 42,
"object_id": 7,
"version": 0,
"created": "2024-03-15T10:23:45+00:00",
"user_id": 5,
"size": 204800,
"fingerprint": "d41d8cd98f00b204e9800998ecf8427e",
"fingerprint_algo": "md5",
"mime": "application/pdf",
"name": "quarterly-report.pdf",
"flag": 0,
"backend": "local",
"deleted": false,
"status": "clean"
},
{
"id": 41,
"object_id": 7,
"version": 1,
"created": "2024-01-10T08:00:00+00:00",
"user_id": 5,
"size": 198400,
"fingerprint": "9e107d9d372bb6826bd81d3542a419d6",
"fingerprint_algo": "md5",
"mime": "application/pdf",
"name": "quarterly-report.pdf",
"flag": 0,
"backend": "local",
"deleted": false,
"status": "clean"
}
],
"total": 2,
"page": 1,
"pageSize": 20
}
```
**Code Samples:**
**cURL:**
```shell
curl -X GET \
"https://{instance}.kiteworks.com/rest/files/:id/versions" \
-H "Authorization: Bearer YOUR_TOKEN"
```
**Python:**
```python
import requests
id = "VALUE" # The unique identifier (UUID) of the file.
url = f"https://{{instance}}.kiteworks.com/rest/files/{id}/versions"
headers = {
"Authorization": "Bearer YOUR_TOKEN",
}
response = requests.get(url, headers=headers)
print(response.json())
```
---
## POST /rest/files/{id}/versions
**Summary:** Upload a file version
Uploads a new version of the specified file using streaming upload, where the file content is sent in the request body. Requires the `version_create` permission on the target file. Returns the updated file entity.
**Parameters:**
| Name | In | Required | Description |
|------|----|----------|-------------|
| `id` | path | yes | The unique identifier of the file (UUID) to which the version is being uploaded. |
| `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. |
**Request Body:**
| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `body` | string | yes | The binary content of the file. |
**Responses:**
| Code | Description |
|------|-------------|
| 200 | New file version uploaded successfully. |
| 403 | Forbidden Possible error codes: ERR_ENTITY_LOCKED, ERR_ENTITY_RESTRICTED_EXTENSION, ERR_ENTITY_RESTRICTED_EXTENSION_CUSTOM, ERR_ENTITY_RESTRICTED_TYPE, ERR_ENTITY_RESTRICTED_TYPE_CUSTOM, ERR_ENTITY_RESTRICTED_TYPE_GROUP |
| 409 | Conflict Possible error codes: ERR_ENTITY_EXISTS |
| 490 | Request blocked by WAF |
**Response Examples:**
**200 (FileVersionCreated):**
```json
{
"id": "a1b2c3d4-e5f6-4789-abcd-ef1234567890",
"name": "document.pdf",
"type": "file",
"size": 307200,
"modified": "2024-03-02T09:30:00+00:00"
}
```
**403 (ERR_ENTITY_LOCKED):**
```json
{
"errors": {
"code": "ERR_ENTITY_LOCKED",
"message": "File is locked"
}
}
```
**403 (ERR_ENTITY_RESTRICTED_EXTENSION):**
```json
{
"errors": {
"code": "ERR_ENTITY_RESTRICTED_EXTENSION",
"message": "File extension is in exclusion extensions list"
}
}
```
**403 (ERR_ENTITY_RESTRICTED_EXTENSION_CUSTOM):**
```json
{
"errors": {
"code": "ERR_ENTITY_RESTRICTED_EXTENSION_CUSTOM",
"message": "File extension is in custom exclusion extensions list"
}
}
```
**403 (ERR_ENTITY_RESTRICTED_TYPE):**
```json
{
"errors": {
"code": "ERR_ENTITY_RESTRICTED_TYPE",
"message": "The specified entity mime type is not allowed."
}
}
```
**403 (ERR_ENTITY_RESTRICTED_TYPE_CUSTOM):**
```json
{
"errors": {
"code": "ERR_ENTITY_RESTRICTED_TYPE_CUSTOM",
"message": "The specified file type is in custom excluded file types list."
}
}
```
**403 (ERR_ENTITY_RESTRICTED_TYPE_GROUP):**
```json
{
"errors": {
"code": "ERR_ENTITY_RESTRICTED_TYPE_GROUP",
"message": "File mime type is in exclusion groups list."
}
}
```
**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/files/:id/versions" \
-H "Authorization: Bearer YOUR_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"body": "string"
}'
```
**Python:**
```python
import requests
id = "VALUE" # The unique identifier of the file (UUID) to which the version is being uploaded.
url = f"https://{{instance}}.kiteworks.com/rest/files/{id}/versions"
headers = {
"Authorization": "Bearer YOUR_TOKEN",
"Content-Type": "application/json",
}
payload = {
"body": "string"
}
response = requests.post(url, headers=headers, json=payload)
print(response.json())
```
---
## GET /rest/files/{id}/versions/{version_id}
**Summary:** Get a file version
Gets file metadata for the specified file version, such as the date it was added, its expiration date, and any tags applied to the file. **Requires `version_view` permission on the file.**
**Parameters:**
| Name | In | Required | Description |
|------|----|----------|-------------|
| `id` | path | yes | The unique identifier (UUID) of the file. |
| `version_id` | path | yes | The unique identifier (UUID) of the file version. |
**Responses:**
| Code | Description |
|------|-------------|
| 200 | Returns the metadata for the specified file version. |
| 490 | Request blocked by WAF |
**Response Examples:**
**200 (Version metadata):**
```json
{
"id": 42,
"object_id": 7,
"version": 0,
"created": "2024-03-15T10:23:45+00:00",
"user_id": 5,
"size": 204800,
"fingerprint": "d41d8cd98f00b204e9800998ecf8427e",
"fingerprint_algo": "md5",
"mime": "application/pdf",
"name": "quarterly-report.pdf",
"flag": 0,
"backend": "local",
"deleted": false,
"status": "clean",
"avStatus": {
"available": true,
"scanned": true,
"infected": false
},
"dlpStatus": {
"available": true,
"scanned": true,
"infected": false
},
"fingerprints": [
{
"algo": "md5",
"hash": "d41d8cd98f00b204e9800998ecf8427e"
}
],
"tags": []
}
```
**Code Samples:**
**cURL:**
```shell
curl -X GET \
"https://{instance}.kiteworks.com/rest/files/:id/versions/:version_id" \
-H "Authorization: Bearer YOUR_TOKEN"
```
**Python:**
```python
import requests
id = "VALUE" # The unique identifier (UUID) of the file.
version_id = "VALUE" # The unique identifier (UUID) of the file version.
url = f"https://{{instance}}.kiteworks.com/rest/files/{id}/versions/{version_id}"
headers = {
"Authorization": "Bearer YOUR_TOKEN",
}
response = requests.get(url, headers=headers)
print(response.json())
```
---
## DELETE /rest/files/{id}/versions/{version_id}
**Summary:** Delete a file version
Deletes the specified version of the file. Cannot delete the last remaining version of a file. **Requires `version_delete` permission on the file.**
**Parameters:**
| Name | In | Required | Description |
|------|----|----------|-------------|
| `id` | path | yes | The unique identifier of the file. |
| `version_id` | path | yes | The unique identifier (UUID) of the file version. |
**Responses:**
| Code | Description |
|------|-------------|
| 204 | The version was successfully deleted. Returns no content. |
| 403 | Forbidden Possible error codes: ERR_ACCESS_USER, ERR_ENTITY_LOCKED |
| 490 | Request blocked by WAF |
**Response Examples:**
**403 (ERR_ACCESS_USER):**
```json
{
"errors": {
"code": "ERR_ACCESS_USER",
"message": "Insufficient access permissions"
}
}
```
**403 (ERR_ENTITY_LOCKED):**
```json
{
"errors": {
"code": "ERR_ENTITY_LOCKED",
"message": "File is locked"
}
}
```
**Code Samples:**
**cURL:**
```shell
curl -X DELETE \
"https://{instance}.kiteworks.com/rest/files/:id/versions/:version_id" \
-H "Authorization: Bearer YOUR_TOKEN"
```
**Python:**
```python
import requests
id = "VALUE" # The unique identifier of the file.
version_id = "VALUE" # The unique identifier (UUID) of the file version.
url = f"https://{{instance}}.kiteworks.com/rest/files/{id}/versions/{version_id}"
headers = {
"Authorization": "Bearer YOUR_TOKEN",
}
response = requests.delete(url, headers=headers)
print(response.json())
```
---
## POST /rest/files/{id}/versions/{version_id}/actions/promote
**Summary:** Promote a file version
Makes the specified version of the file the current version of the file. The promoted version is assigned version number 0 (current), and all lower-numbered versions are incremented. Also updates the file name to match the promoted version. **Requires `version_promote` permission on the file.**
**Parameters:**
| Name | In | Required | Description |
|------|----|----------|-------------|
| `id` | path | yes | The unique identifier (UUID) of file |
| `version_id` | path | yes | The unique identifier (UUID) of the file version. |
| `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 promoted version record after it has been set as the current version. |
| 403 | Forbidden Possible error codes: ERR_ACCESS_USER, ERR_ENTITY_LOCKED |
| 490 | Request blocked by WAF |
**Response Examples:**
**200 (Version promoted):**
```json
{
"id": 41,
"object_id": 7,
"version": 0,
"created": "2024-01-10T08:00:00+00:00",
"user_id": 5,
"size": 198400,
"fingerprint": "9e107d9d372bb6826bd81d3542a419d6",
"fingerprint_algo": "md5",
"mime": "application/pdf",
"name": "quarterly-report.pdf",
"flag": 0,
"backend": "local",
"deleted": false,
"status": "clean"
}
```
**403 (ERR_ACCESS_USER):**
```json
{
"errors": {
"code": "ERR_ACCESS_USER",
"message": "Insufficient access permissions"
}
}
```
**403 (ERR_ENTITY_LOCKED):**
```json
{
"errors": {
"code": "ERR_ENTITY_LOCKED",
"message": "File is locked"
}
}
```
**Code Samples:**
**cURL:**
```shell
curl -X POST \
"https://{instance}.kiteworks.com/rest/files/:id/versions/:version_id/actions/promote" \
-H "Authorization: Bearer YOUR_TOKEN"
```
**Python:**
```python
import requests
id = "VALUE" # The unique identifier (UUID) of file
version_id = "VALUE" # The unique identifier (UUID) of the file version.
url = f"https://{{instance}}.kiteworks.com/rest/files/{id}/versions/{version_id}/actions/promote"
headers = {
"Authorization": "Bearer YOUR_TOKEN",
}
response = requests.post(url, headers=headers)
print(response.json())
```
---
## POST /rest/files/{id}/versions/{version_id}/actions/scan
**Summary:** Scan a file version for security
Triggers a security scan on the specified file version. Depending on system scan policies, the scan may include anti-virus, data loss prevention, and advanced threat protection checks. **Requires `version_view` permission on the file.**
**Parameters:**
| Name | In | Required | Description |
|------|----|----------|-------------|
| `id` | path | yes | The unique identifier (UUID) of file |
| `version_id` | path | yes | The unique identifier (UUID) of the file version. |
| `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 version record after the scan has been triggered. The scan result is reflected in the `avStatus` and `dlpStatus` fields once the scan completes. |
| 403 | Forbidden Possible error codes: ERR_ACCESS_USER |
| 490 | Request blocked by WAF |
**Response Examples:**
**200 (Scan triggered):**
```json
{
"id": 42,
"object_id": 7,
"version": 0,
"created": "2024-03-15T10:23:45+00:00",
"user_id": 5,
"size": 204800,
"fingerprint": "d41d8cd98f00b204e9800998ecf8427e",
"fingerprint_algo": "md5",
"mime": "application/pdf",
"name": "quarterly-report.pdf",
"flag": 0,
"backend": "local",
"deleted": false,
"status": "scanning",
"avStatus": {
"available": false,
"scanned": false,
"infected": false
},
"dlpStatus": {
"available": false,
"scanned": false,
"infected": false
}
}
```
**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/files/:id/versions/:version_id/actions/scan" \
-H "Authorization: Bearer YOUR_TOKEN"
```
**Python:**
```python
import requests
id = "VALUE" # The unique identifier (UUID) of file
version_id = "VALUE" # The unique identifier (UUID) of the file version.
url = f"https://{{instance}}.kiteworks.com/rest/files/{id}/versions/{version_id}/actions/scan"
headers = {
"Authorization": "Bearer YOUR_TOKEN",
}
response = requests.post(url, headers=headers)
print(response.json())
```
---
## GET /rest/files/{id}/versions/{version_id}/content
**Summary:** Download a file version
Downloads the binary content of the specified file version. **Requires `download` permission on the file.** Users assigned the Downloader or Viewer role can only download the current version (version 0); attempting to download an older version returns a 403.
**Parameters:**
| Name | In | Required | Description |
|------|----|----------|-------------|
| `id` | path | yes | The unique identifier (UUID) of file |
| `version_id` | path | yes | The unique identifier (UUID) of the file version. |
| `Range` | header | no | Range of bytes to download. e.g. `bytes=0-1024` |
**Responses:**
| Code | Description |
|------|-------------|
| 200 | Returns the binary content of the file version as an octet-stream. Supports range requests via the `Range` header; a partial-content request returns HTTP 206. |
| 403 | Forbidden Possible error codes: ERR_ACCESS_USER |
| 490 | Request blocked by WAF |
**Response Examples:**
**403 (ERR_ACCESS_USER):**
```json
{
"errors": {
"code": "ERR_ACCESS_USER",
"message": "Insufficient access permissions"
}
}
```
**Code Samples:**
**cURL:**
```shell
curl -X GET \
"https://{instance}.kiteworks.com/rest/files/:id/versions/:version_id/content" \
-H "Authorization: Bearer YOUR_TOKEN"
```
**Python:**
```python
import requests
id = "VALUE" # The unique identifier (UUID) of file
version_id = "VALUE" # The unique identifier (UUID) of the file version.
url = f"https://{{instance}}.kiteworks.com/rest/files/{id}/versions/{version_id}/content"
headers = {
"Authorization": "Bearer YOUR_TOKEN",
}
response = requests.get(url, headers=headers)
print(response.json())
```
---
## GET /rest/files/{id}/versions/{version_id}/preview
**Summary:** Get file preview metadata for a file version
Gets file preview metadata for the specified file version, such as the permalink for previewing the file and if the file contains a watermark. **Requires `view` permission on the file.**
**Parameters:**
| Name | In | Required | Description |
|------|----|----------|-------------|
| `id` | path | yes | The unique identifier of the file. |
| `version_id` | path | yes | The unique identifier (UUID) of the file version. |
**Responses:**
| Code | Description |
|------|-------------|
| 200 | Returns the preview metadata for the specified file version. |
| 403 | Forbidden Possible error codes: ERR_ACCESS_USER |
| 490 | Request blocked by WAF |
**Response Examples:**
**200 (Preview ready):**
```json
{
"link": "/preview/files/7/versions/42/preview.html",
"pdf": null,
"view_url": "https://viewer.example.com/view?token=abc123",
"status": "Preview",
"mime": "application/pdf",
"native": true,
"watermark": null,
"tdfOriginalExtension": null
}
```
**200 (Preview processing):**
```json
{
"link": null,
"pdf": null,
"view_url": null,
"status": "Processing",
"mime": null,
"native": false,
"watermark": null,
"tdfOriginalExtension": null
}
```
**403 (ERR_ACCESS_USER):**
```json
{
"errors": {
"code": "ERR_ACCESS_USER",
"message": "Insufficient access permissions"
}
}
```
**Code Samples:**
**cURL:**
```shell
curl -X GET \
"https://{instance}.kiteworks.com/rest/files/:id/versions/:version_id/preview" \
-H "Authorization: Bearer YOUR_TOKEN"
```
**Python:**
```python
import requests
id = "VALUE" # The unique identifier of the file.
version_id = "VALUE" # The unique identifier (UUID) of the file version.
url = f"https://{{instance}}.kiteworks.com/rest/files/{id}/versions/{version_id}/preview"
headers = {
"Authorization": "Bearer YOUR_TOKEN",
}
response = requests.get(url, headers=headers)
print(response.json())
```
---
## POST /rest/folders/{id}/actions/file
**Summary:** Upload a file using multipart form data
Uploads a file to the specified folder using multipart form data. If a file with the same
name already exists, a new version is created unless `disableAutoVersion` is set.
**Requires `file_add` permission on the target folder** (or `version_create` if a file with
the same name already exists). The folder must not be deleted. Sufficient storage must be
available. The file extension and MIME type must not be excluded by the system policy.
**Parameters:**
| Name | In | Required | Description |
|------|----|----------|-------------|
| `id` | path | yes | The unique identifier (UUID) of the target 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. |
**Request Body:**
| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `body` | string | yes | The binary content of the file. |
| `clientCreated` | string | no | The date and time when the file was created on the client side. |
| `clientModified` | string | no | The date and time when the file was last modified on the client side. |
| `disableAutoVersion` | boolean | no | Indicates if the file should be prevented from being saved as a new version. |
| `note` | boolean | no | Indicates if the file should be uploaded as a note. |
**Responses:**
| Code | Description |
|------|-------------|
| 200 | Returns the uploaded file metadata. |
| 403 | Forbidden Possible error codes: ERR_ENTITY_LOCKED, ERR_ENTITY_RESTRICTED_EXTENSION, ERR_ENTITY_RESTRICTED_EXTENSION_CUSTOM, ERR_ENTITY_RESTRICTED_TYPE, ERR_ENTITY_RESTRICTED_TYPE_CUSTOM, ERR_ENTITY_RESTRICTED_TYPE_GROUP |
| 409 | Conflict Possible error codes: ERR_ENTITY_EXISTS |
| 422 | Unprocessable Content Possible error codes: ERR_INPUT_INVALID_DATE |
| 490 | Request blocked by WAF |
**Response Examples:**
**200 (FileUploaded):**
```json
{
"id": "9",
"name": "report.pdf",
"size": 204800,
"mime": "application/pdf",
"deleted": false,
"locked": 0,
"created": "2024-06-20T10:00:00Z",
"modified": "2024-06-20T10:00:00Z",
"parent": {
"id": "3",
"name": "Documents"
}
}
```
**403 (ERR_ENTITY_LOCKED):**
```json
{
"errors": {
"code": "ERR_ENTITY_LOCKED",
"message": "File is locked"
}
}
```
**403 (ERR_ENTITY_RESTRICTED_EXTENSION):**
```json
{
"errors": {
"code": "ERR_ENTITY_RESTRICTED_EXTENSION",
"message": "File extension is in exclusion extensions list"
}
}
```
**403 (ERR_ENTITY_RESTRICTED_EXTENSION_CUSTOM):**
```json
{
"errors": {
"code": "ERR_ENTITY_RESTRICTED_EXTENSION_CUSTOM",
"message": "File extension is in custom exclusion extensions list"
}
}
```
**403 (ERR_ENTITY_RESTRICTED_TYPE):**
```json
{
"errors": {
"code": "ERR_ENTITY_RESTRICTED_TYPE",
"message": "The specified entity mime type is not allowed."
}
}
```
**403 (ERR_ENTITY_RESTRICTED_TYPE_CUSTOM):**
```json
{
"errors": {
"code": "ERR_ENTITY_RESTRICTED_TYPE_CUSTOM",
"message": "The specified file type is in custom excluded file types list."
}
}
```
**403 (ERR_ENTITY_RESTRICTED_TYPE_GROUP):**
```json
{
"errors": {
"code": "ERR_ENTITY_RESTRICTED_TYPE_GROUP",
"message": "File mime type is in exclusion groups list."
}
}
```
**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/actions/file" \
-H "Authorization: Bearer YOUR_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"body": "string",
"clientCreated": "string",
"clientModified": "string",
"disableAutoVersion": true,
"note": true
}'
```
**Python:**
```python
import requests
id = "VALUE" # The unique identifier (UUID) of the target folder.
url = f"https://{{instance}}.kiteworks.com/rest/folders/{id}/actions/file"
headers = {
"Authorization": "Bearer YOUR_TOKEN",
"Content-Type": "application/json",
}
payload = {
"body": "string",
"clientCreated": "string",
"clientModified": "string",
"disableAutoVersion": true,
"note": true
}
response = requests.post(url, headers=headers, json=payload)
print(response.json())
```
---
## POST /rest/folders/{id}/actions/fileBase64Encoded
**Summary:** Upload a base64-encoded file
Uploads a base64-encoded file to the specified folder. If a file with the same name already
exists, a new version is created unless `disableAutoVersion` is set.
**Requires
`file_add` permission on the target folder** (or `version_create` if a file with the same
name already exists). The file content must be valid base64. The file size must not exceed
the system-configured upload size limit. The file extension must not be excluded by the
system policy.
**Parameters:**
| Name | In | Required | Description |
|------|----|----------|-------------|
| `id` | path | yes | The unique identifier (UUID) of the target 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. |
**Request Body:**
| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `addLinks` | boolean | no | Indicates whether HATEOAS links should be included in the response |
| `name` | string | yes | Display name of the file |
| `content` | string | yes | Raw content body of the file being created |
| `clientCreated` | integer | no | Date and time when the file was created on the client side |
| `clientModified` | integer | no | Date and time when the file was last modified on the client side |
| `note` | integer | no | Indicates whether the file should be uploaded as a note |
| `disableAutoVersion` | boolean | no | Indicates whether the file should be prevented from being saved as a new version |
**Responses:**
| Code | Description |
|------|-------------|
| 200 | Returns the uploaded file metadata. |
| 403 | Forbidden Possible error codes: ERR_ENTITY_LOCKED, ERR_ENTITY_RESTRICTED_EXTENSION, ERR_ENTITY_RESTRICTED_EXTENSION_CUSTOM, ERR_ENTITY_RESTRICTED_TYPE, ERR_ENTITY_RESTRICTED_TYPE_CUSTOM, ERR_ENTITY_RESTRICTED_TYPE_GROUP |
| 409 | Conflict Possible error codes: ERR_ENTITY_EXISTS |
| 490 | Request blocked by WAF |
**Response Examples:**
**200 (FileUploaded):**
```json
{
"id": "12",
"name": "notes.txt",
"size": 1024,
"mime": "text/plain",
"deleted": false,
"locked": 0,
"created": "2024-06-20T11:00:00Z",
"modified": "2024-06-20T11:00:00Z",
"parent": {
"id": "3",
"name": "Documents"
}
}
```
**403 (ERR_ENTITY_LOCKED):**
```json
{
"errors": {
"code": "ERR_ENTITY_LOCKED",
"message": "File is locked"
}
}
```
**403 (ERR_ENTITY_RESTRICTED_EXTENSION):**
```json
{
"errors": {
"code": "ERR_ENTITY_RESTRICTED_EXTENSION",
"message": "File extension is in exclusion extensions list"
}
}
```
**403 (ERR_ENTITY_RESTRICTED_EXTENSION_CUSTOM):**
```json
{
"errors": {
"code": "ERR_ENTITY_RESTRICTED_EXTENSION_CUSTOM",
"message": "File extension is in custom exclusion extensions list"
}
}
```
**403 (ERR_ENTITY_RESTRICTED_TYPE):**
```json
{
"errors": {
"code": "ERR_ENTITY_RESTRICTED_TYPE",
"message": "The specified entity mime type is not allowed."
}
}
```
**403 (ERR_ENTITY_RESTRICTED_TYPE_CUSTOM):**
```json
{
"errors": {
"code": "ERR_ENTITY_RESTRICTED_TYPE_CUSTOM",
"message": "The specified file type is in custom excluded file types list."
}
}
```
**403 (ERR_ENTITY_RESTRICTED_TYPE_GROUP):**
```json
{
"errors": {
"code": "ERR_ENTITY_RESTRICTED_TYPE_GROUP",
"message": "File mime type is in exclusion groups list."
}
}
```
**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/actions/fileBase64Encoded" \
-H "Authorization: Bearer YOUR_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"addLinks": true,
"name": "string",
"content": "string",
"clientCreated": 1,
"clientModified": 1,
"note": 1
}'
```
**Python:**
```python
import requests
id = "VALUE" # The unique identifier (UUID) of the target folder.
url = f"https://{{instance}}.kiteworks.com/rest/folders/{id}/actions/fileBase64Encoded"
headers = {
"Authorization": "Bearer YOUR_TOKEN",
"Content-Type": "application/json",
}
payload = {
"addLinks": true,
"name": "string",
"content": "string",
"clientCreated": 1,
"clientModified": 1,
"note": 1
}
response = requests.post(url, headers=headers, json=payload)
print(response.json())
```
---
## POST /rest/folders/{parent_id}/actions/fileFromTemplate
**Summary:** Create Microsoft Office document from template
Creates a new, blank Microsoft Office document from a template in the specified folder.
**Requires `file_add` permission on the target folder.** The folder must not be deleted.
The file name must not contain invalid characters.
**Parameters:**
| Name | In | Required | Description |
|------|----|----------|-------------|
| `parent_id` | path | yes | ID of the parent folder |
**Request Body:**
| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `fileType` | string | no | The file type |
| `fileName` | string | no | The file name |
**Responses:**
| Code | Description |
|------|-------------|
| 200 | Returns the newly created file. |
| 403 | Forbidden Possible error codes: ERR_ACCESS_USER, ERR_ENTITY_LOCKED, ERR_ENTITY_RESTRICTED_EXTENSION, ERR_ENTITY_RESTRICTED_EXTENSION_CUSTOM, ERR_ENTITY_RESTRICTED_TYPE, ERR_ENTITY_RESTRICTED_TYPE_CUSTOM, ERR_ENTITY_RESTRICTED_TYPE_GROUP |
| 422 | Unprocessable Content Possible error codes: ERR_INPUT_INVALID_DATE |
| 490 | Request blocked by WAF |
**Response Examples:**
**200 (FileCreatedFromTemplate):**
```json
{
"id": "20",
"name": "Report.docx",
"size": 0,
"mime": "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
"deleted": false,
"locked": 0,
"created": "2024-06-20T12:00:00Z",
"modified": "2024-06-20T12:00:00Z",
"parent": {
"id": "3",
"name": "Documents"
}
}
```
**403 (ERR_ACCESS_USER):**
```json
{
"errors": {
"code": "ERR_ACCESS_USER",
"message": "Insufficient access permissions"
}
}
```
**403 (ERR_ENTITY_LOCKED):**
```json
{
"errors": {
"code": "ERR_ENTITY_LOCKED",
"message": "File is locked"
}
}
```
**403 (ERR_ENTITY_RESTRICTED_EXTENSION):**
```json
{
"errors": {
"code": "ERR_ENTITY_RESTRICTED_EXTENSION",
"message": "File extension is in exclusion extensions list"
}
}
```
**403 (ERR_ENTITY_RESTRICTED_EXTENSION_CUSTOM):**
```json
{
"errors": {
"code": "ERR_ENTITY_RESTRICTED_EXTENSION_CUSTOM",
"message": "File extension is in custom exclusion extensions list"
}
}
```
**403 (ERR_ENTITY_RESTRICTED_TYPE):**
```json
{
"errors": {
"code": "ERR_ENTITY_RESTRICTED_TYPE",
"message": "The specified entity mime type is not allowed."
}
}
```
**403 (ERR_ENTITY_RESTRICTED_TYPE_CUSTOM):**
```json
{
"errors": {
"code": "ERR_ENTITY_RESTRICTED_TYPE_CUSTOM",
"message": "The specified file type is in custom excluded file types list."
}
}
```
**403 (ERR_ENTITY_RESTRICTED_TYPE_GROUP):**
```json
{
"errors": {
"code": "ERR_ENTITY_RESTRICTED_TYPE_GROUP",
"message": "File mime type is in exclusion groups list."
}
}
```
**Code Samples:**
**cURL:**
```shell
curl -X POST \
"https://{instance}.kiteworks.com/rest/folders/:parent_id/actions/fileFromTemplate" \
-H "Authorization: Bearer YOUR_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"fileType": "string",
"fileName": "string"
}'
```
**Python:**
```python
import requests
parent_id = "VALUE" # ID of the parent folder
url = f"https://{{instance}}.kiteworks.com/rest/folders/{parent_id}/actions/fileFromTemplate"
headers = {
"Authorization": "Bearer YOUR_TOKEN",
"Content-Type": "application/json",
}
payload = {
"fileType": "string",
"fileName": "string"
}
response = requests.post(url, headers=headers, json=payload)
print(response.json())
```
---
## POST /rest/folders/{parent}/files
**Summary:** Upload a file
Uploads a file to the specified folder using streaming upload, where the file content is sent in the request body and metadata is provided via request headers. Requires the `file_add` permission on the target folder. Returns the created file entity.
**Parameters:**
| Name | In | Required | Description |
|------|----|----------|-------------|
| `parent` | path | yes | The unique identifier (UUID) of the target folder. |
| `X-KW-Note` | header | no | Indicates if the file should be uploaded as a note. |
| `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. |
**Request Body:**
| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `body` | string | yes | The binary content of the file. |
**Responses:**
| Code | Description |
|------|-------------|
| 200 | File uploaded successfully. |
| 403 | Forbidden Possible error codes: ERR_ENTITY_LOCKED, ERR_ENTITY_RESTRICTED_EXTENSION, ERR_ENTITY_RESTRICTED_EXTENSION_CUSTOM, ERR_ENTITY_RESTRICTED_TYPE, ERR_ENTITY_RESTRICTED_TYPE_CUSTOM, ERR_ENTITY_RESTRICTED_TYPE_GROUP |
| 409 | Conflict Possible error codes: ERR_ENTITY_EXISTS |
| 490 | Request blocked by WAF |
**Response Examples:**
**200 (FileCreated):**
```json
{
"id": "a1b2c3d4-e5f6-4789-abcd-ef1234567890",
"name": "document.pdf",
"type": "file",
"size": 204800,
"modified": "2024-03-01T12:00:00+00:00"
}
```
**403 (ERR_ENTITY_LOCKED):**
```json
{
"errors": {
"code": "ERR_ENTITY_LOCKED",
"message": "File is locked"
}
}
```
**403 (ERR_ENTITY_RESTRICTED_EXTENSION):**
```json
{
"errors": {
"code": "ERR_ENTITY_RESTRICTED_EXTENSION",
"message": "File extension is in exclusion extensions list"
}
}
```
**403 (ERR_ENTITY_RESTRICTED_EXTENSION_CUSTOM):**
```json
{
"errors": {
"code": "ERR_ENTITY_RESTRICTED_EXTENSION_CUSTOM",
"message": "File extension is in custom exclusion extensions list"
}
}
```
**403 (ERR_ENTITY_RESTRICTED_TYPE):**
```json
{
"errors": {
"code": "ERR_ENTITY_RESTRICTED_TYPE",
"message": "The specified entity mime type is not allowed."
}
}
```
**403 (ERR_ENTITY_RESTRICTED_TYPE_CUSTOM):**
```json
{
"errors": {
"code": "ERR_ENTITY_RESTRICTED_TYPE_CUSTOM",
"message": "The specified file type is in custom excluded file types list."
}
}
```
**403 (ERR_ENTITY_RESTRICTED_TYPE_GROUP):**
```json
{
"errors": {
"code": "ERR_ENTITY_RESTRICTED_TYPE_GROUP",
"message": "File mime type is in exclusion groups list."
}
}
```
**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/:parent/files" \
-H "Authorization: Bearer YOUR_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"body": "string"
}'
```
**Python:**
```python
import requests
parent = "VALUE" # The unique identifier (UUID) of the target folder.
url = f"https://{{instance}}.kiteworks.com/rest/folders/{parent}/files"
headers = {
"Authorization": "Bearer YOUR_TOKEN",
"Content-Type": "application/json",
}
payload = {
"body": "string"
}
response = requests.post(url, headers=headers, json=payload)
print(response.json())
```
---
## GET /rest/permissions/file/{file_id}
**Summary:** Get file permissions
Returns the list of actions the current user is allowed to perform on the specified file, such as downloading, editing, or commenting.
**Parameters:**
| Name | In | Required | Description |
|------|----|----------|-------------|
| `file_id` | path | yes | ID of the file |
| `id` | query | no | Unique action identifier |
| `id:in` | query | no | Unique action identifier. Search for results that match any of the specified values for this parameter. |
| `name` | query | no | Action name |
| `name:contains` | query | no | Action name. Search for results that contain the specified characters in this parameter. |
| `allowed` | query | no | Determines if one has permissions to perform action |
| `enabled` | query | no | Determines if the given action is available considering the current object state (locked, deleted, etc.). |
| `with` | query | no | With parameters |
| `mode` | query | no | Determines the detail level of the response body. |
**Responses:**
| Code | Description |
|------|-------------|
| 200 | File permissions retrieved successfully. |
| 490 | Request blocked by WAF |
**Response Examples:**
**200 (FilePermissions):**
```json
{
"data": [
{
"id": "DOWNLOAD",
"name": "Download",
"allowed": true
}
]
}
```
**Code Samples:**
**cURL:**
```shell
curl -X GET \
"https://{instance}.kiteworks.com/rest/permissions/file/:file_id" \
-H "Authorization: Bearer YOUR_TOKEN"
```
**Python:**
```python
import requests
file_id = "VALUE" # ID of the file
url = f"https://{{instance}}.kiteworks.com/rest/permissions/file/{file_id}"
headers = {
"Authorization": "Bearer YOUR_TOKEN",
}
response = requests.get(url, headers=headers)
print(response.json())
```
---
## GET /rest/permissions/files
**Summary:** Get file permissions for a set of files
Returns the current user's allowed actions for each of the specified files. File IDs are passed as request parameters. Returns 400 if no file IDs are provided.
**Parameters:**
| Name | In | Required | Description |
|------|----|----------|-------------|
| `id:in` | query | yes | Unique identifier of the file.. Search for results that match any of the specified values for this parameter. |
| `name` | query | no | Action name |
| `name:contains` | query | no | Action name. Search for results that contain the specified characters in this parameter. |
| `allowed` | query | no | Determines if one has permissions to perform action |
| `enabled` | query | no | Determines if the given action is available considering the current object state (locked, deleted, etc.). |
| `action_id` | query | no | Unique action identifier |
| `action_id:in` | query | no | Unique action identifier. 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 | File permissions retrieved successfully. |
| 490 | Request blocked by WAF |
**Response Examples:**
**200 (BulkFilePermissions):**
```json
{
"data": [
{
"fileId": "f1a2b3c4-d5e6-7890-abcd-ef1234567890",
"permissions": [
{
"id": "DOWNLOAD",
"name": "Download",
"allowed": true
}
]
}
]
}
```
**Code Samples:**
**cURL:**
```shell
curl -X GET \
"https://{instance}.kiteworks.com/rest/permissions/files?id:in=VALUE" \
-H "Authorization: Bearer YOUR_TOKEN"
```
**Python:**
```python
import requests
url = "https://{instance}.kiteworks.com/rest/permissions/files"
headers = {
"Authorization": "Bearer YOUR_TOKEN",
}
params = {
"id:in": "VALUE",
}
response = requests.get(url, params=params, headers=headers)
print(response.json())
```
---
## POST /rest/requestFile/{ref}/actions/file
**Summary:** Upload a file requested by user
Uploads a file to a folder or inbox in response to a file request from another user.
Access is granted via the request file reference link (`ref`). If the request requires
authentication (`require_auth`), the caller must be logged in. The uploaded file is
renamed to include the uploader's email address.
The request link must not be expired
or have reached its upload limit. Sufficient storage must be available in the target
folder. The file extension and MIME type must not be excluded by the requestor's system
policy.
**Parameters:**
| Name | In | Required | Description |
|------|----|----------|-------------|
| `ref` | path | yes | The unique reference of the Request File upload link. |
| `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. |
**Request Body:**
| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `body` | string | yes | The binary content of the file. |
| `clientCreated` | string | no | The date and time when the file was created on the client side. |
| `clientModified` | string | no | The date and time when the file was last modified on the client side. |
**Responses:**
| Code | Description |
|------|-------------|
| 200 | Returns the uploaded file metadata. |
| 403 | Forbidden Possible error codes: ERR_ACCESS_USER, ERR_ENTITY_RESTRICTED_EXTENSION, ERR_ENTITY_RESTRICTED_EXTENSION_CUSTOM, ERR_ENTITY_RESTRICTED_TYPE, ERR_ENTITY_RESTRICTED_TYPE_CUSTOM, ERR_ENTITY_RESTRICTED_TYPE_GROUP |
| 422 | Unprocessable Content Possible error codes: ERR_INPUT_INVALID_DATE |
| 490 | Request blocked by WAF |
**Response Examples:**
**200 (FileUploaded):**
```json
{
"id": "30",
"name": "contract (alice@example.com).pdf",
"size": 512000,
"mime": "application/pdf",
"deleted": false,
"locked": 0,
"created": "2024-06-20T15:00:00Z",
"modified": "2024-06-20T15:00:00Z",
"parent": {
"id": "3",
"name": "Incoming Requests"
}
}
```
**403 (ERR_ACCESS_USER):**
```json
{
"errors": {
"code": "ERR_ACCESS_USER",
"message": "Insufficient access permissions"
}
}
```
**403 (ERR_ENTITY_RESTRICTED_EXTENSION):**
```json
{
"errors": {
"code": "ERR_ENTITY_RESTRICTED_EXTENSION",
"message": "File extension is in exclusion extensions list"
}
}
```
**403 (ERR_ENTITY_RESTRICTED_EXTENSION_CUSTOM):**
```json
{
"errors": {
"code": "ERR_ENTITY_RESTRICTED_EXTENSION_CUSTOM",
"message": "File extension is in custom exclusion extensions list"
}
}
```
**403 (ERR_ENTITY_RESTRICTED_TYPE):**
```json
{
"errors": {
"code": "ERR_ENTITY_RESTRICTED_TYPE",
"message": "The specified entity mime type is not allowed."
}
}
```
**403 (ERR_ENTITY_RESTRICTED_TYPE_CUSTOM):**
```json
{
"errors": {
"code": "ERR_ENTITY_RESTRICTED_TYPE_CUSTOM",
"message": "The specified file type is in custom excluded file types list."
}
}
```
**403 (ERR_ENTITY_RESTRICTED_TYPE_GROUP):**
```json
{
"errors": {
"code": "ERR_ENTITY_RESTRICTED_TYPE_GROUP",
"message": "File mime type is in exclusion groups list."
}
}
```
**Code Samples:**
**cURL:**
```shell
curl -X POST \
"https://{instance}.kiteworks.com/rest/requestFile/:ref/actions/file" \
-H "Authorization: Bearer YOUR_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"body": "string",
"clientCreated": "string",
"clientModified": "string"
}'
```
**Python:**
```python
import requests
ref = "VALUE" # The unique reference of the Request File upload link.
url = f"https://{{instance}}.kiteworks.com/rest/requestFile/{ref}/actions/file"
headers = {
"Authorization": "Bearer YOUR_TOKEN",
"Content-Type": "application/json",
}
payload = {
"body": "string",
"clientCreated": "string",
"clientModified": "string"
}
response = requests.post(url, headers=headers, json=payload)
print(response.json())
```
---
## POST /rest/requestFile/{ref}/comment/{object_id}
**Summary:** Add a comment to an uploaded file
Adds a comment to a file that was uploaded through the request file link. Only accessible when the link requires authentication (`require_auth=true`) and has not expired.
**Parameters:**
| Name | In | Required | Description |
|------|----|----------|-------------|
| `ref` | path | yes | The unique reference of the Request File upload link. |
| `object_id` | path | yes | Object ID of the file being commented on. |
| `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. |
**Request Body:**
| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `parentId` | integer | no | Unique identifier of the parent comment. Set this value when replying to an existing comment |
| `contents` | string | yes | Text content of the comment |
| `addLinks` | boolean | no | Indicates whether HATEOAS links should be included in the response |
**Responses:**
| Code | Description |
|------|-------------|
| 200 | Returns the newly created comment record. |
| 403 | Forbidden Possible error codes: ERR_ACCESS_USER |
| 422 | Unprocessable Content Possible error codes: ERR_INPUT_MAX_VALUE, ERR_INPUT_HTML_TAGS_INVALID, ERR_INPUT_REQUIRED |
| 490 | Request blocked by WAF |
**Response Examples:**
**200 (Comment created):**
```json
{
"id": 88,
"parent_id": 0,
"object_id": 55,
"user_id": 5,
"contents": "Please review the highlighted sections on page 3.",
"created": "2024-03-20T12:00:00+00:00",
"modified": "2024-03-20T12:00:00+00:00",
"deleted": false,
"folder_id": 3,
"is_comment": true
}
```
**403 (ERR_ACCESS_USER):**
```json
{
"errors": {
"code": "ERR_ACCESS_USER",
"message": "Insufficient access permissions"
}
}
```
**422 (ERR_INPUT_HTML_TAGS_INVALID):**
```json
{
"errors": {
"code": "ERR_INPUT_HTML_TAGS_INVALID",
"message": "Cannot contain HTML tags other than B, I, or U"
}
}
```
**422 (ERR_INPUT_REQUIRED):**
```json
{
"errors": {
"code": "ERR_INPUT_REQUIRED",
"message": "Field is required"
}
}
```
**Code Samples:**
**cURL:**
```shell
curl -X POST \
"https://{instance}.kiteworks.com/rest/requestFile/:ref/comment/:object_id" \
-H "Authorization: Bearer YOUR_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"parentId": 1,
"contents": "string",
"addLinks": true
}'
```
**Python:**
```python
import requests
ref = "VALUE" # The unique reference of the Request File upload link.
object_id = "VALUE" # Object ID of the file being commented on.
url = f"https://{{instance}}.kiteworks.com/rest/requestFile/{ref}/comment/{object_id}"
headers = {
"Authorization": "Bearer YOUR_TOKEN",
"Content-Type": "application/json",
}
payload = {
"parentId": 1,
"contents": "string",
"addLinks": true
}
response = requests.post(url, headers=headers, json=payload)
print(response.json())
```
---
## GET /rest/requestFile/{ref}/sources/{object_id}/content
**Summary:** Download files from folder in request files to folder message
Downloads a file that was made available to recipients as a source attachment in a
request files to folder message. Access is granted via the request file reference link
(`ref`).
The request link must be valid and not expired. If the request requires
authentication, the caller must be logged in. The file must not be deleted, infected,
or DLP-locked.
**Parameters:**
| Name | In | Required | Description |
|------|----|----------|-------------|
| `ref` | path | yes | The unique reference of the Request File upload link. |
| `object_id` | path | yes | The unique identifier of the file |
| `Range` | header | no | Range of bytes to download. e.g. `bytes=0-1024` |
**Responses:**
| Code | Description |
|------|-------------|
| 200 | Returns the binary file content as a downloadable stream. |
| 403 | Forbidden Possible error codes: ERR_ACCESS_USER |
| 490 | Request blocked by WAF |
**Response Examples:**
**403 (ERR_ACCESS_USER):**
```json
{
"errors": {
"code": "ERR_ACCESS_USER",
"message": "Insufficient access permissions"
}
}
```
**Code Samples:**
**cURL:**
```shell
curl -X GET \
"https://{instance}.kiteworks.com/rest/requestFile/:ref/sources/:object_id/content" \
-H "Authorization: Bearer YOUR_TOKEN"
```
**Python:**
```python
import requests
ref = "VALUE" # The unique reference of the Request File upload link.
object_id = "VALUE" # The unique identifier of the file
url = f"https://{{instance}}.kiteworks.com/rest/requestFile/{ref}/sources/{object_id}/content"
headers = {
"Authorization": "Bearer YOUR_TOKEN",
}
response = requests.get(url, headers=headers)
print(response.json())
```
---
## GET /rest/requestFile/{ref}/uploads/{object_id}/content
**Summary:** Download files uploaded to request files to folder or inbox message
Downloads a file that was uploaded to a request files to folder or inbox message. Access
is granted via the request file reference link (`ref`).
**Authentication is required**
— guest access is not permitted for this endpoint. The file must be associated with the
specified request link, must not be deleted, and must not be infected or DLP-locked.
**Parameters:**
| Name | In | Required | Description |
|------|----|----------|-------------|
| `ref` | path | yes | The unique reference of the Request File upload link. |
| `object_id` | path | yes | The unique identifier of the file |
| `Range` | header | no | Range of bytes to download. e.g. `bytes=0-1024` |
**Responses:**
| Code | Description |
|------|-------------|
| 200 | Returns the binary file content as a downloadable stream. |
| 403 | Forbidden Possible error codes: ERR_ACCESS_USER |
| 490 | Request blocked by WAF |
**Response Examples:**
**403 (ERR_ACCESS_USER):**
```json
{
"errors": {
"code": "ERR_ACCESS_USER",
"message": "Insufficient access permissions"
}
}
```
**Code Samples:**
**cURL:**
```shell
curl -X GET \
"https://{instance}.kiteworks.com/rest/requestFile/:ref/uploads/:object_id/content" \
-H "Authorization: Bearer YOUR_TOKEN"
```
**Python:**
```python
import requests
ref = "VALUE" # The unique reference of the Request File upload link.
object_id = "VALUE" # The unique identifier of the file
url = f"https://{{instance}}.kiteworks.com/rest/requestFile/{ref}/uploads/{object_id}/content"
headers = {
"Authorization": "Bearer YOUR_TOKEN",
}
response = requests.get(url, headers=headers)
print(response.json())
```
---
## GET /rest/sources/actions/downloadByTransaction
**Summary:** Download a file from Repositories Gateway source by transaction ID
Downloads a file from its Repositories Gateway source using the transaction ID obtained
from `POST /sources/{id}/actions/initiateDownload`. The transfer must have completed
successfully before calling this endpoint.
**Requires `download` permission on the
file.**
**Parameters:**
| Name | In | Required | Description |
|------|----|----------|-------------|
| `transactionId` | query | no | Transaction ID of download |
| `mode` | query | no | Determines the detail level of the response body. |
**Responses:**
| Code | Description |
|------|-------------|
| 200 | Returns the binary file content as a downloadable stream. |
| 490 | Request blocked by WAF |
**Code Samples:**
**cURL:**
```shell
curl -X GET \
"https://{instance}.kiteworks.com/rest/sources/actions/downloadByTransaction" \
-H "Authorization: Bearer YOUR_TOKEN"
```
**Python:**
```python
import requests
url = "https://{instance}.kiteworks.com/rest/sources/actions/downloadByTransaction"
headers = {
"Authorization": "Bearer YOUR_TOKEN",
}
response = requests.get(url, headers=headers)
print(response.json())
```
---
## POST /rest/sources/actions/files/{id}
**Summary:** Upload a file version to Repositories Gateway source
Uploads a new version of the specified file to its Repositories Gateway source. Returns a
transfer status record reflecting the result of the upload operation.
**Requires
`file_add` permission on the Repositories Gateway parent folder of the file.** The file
extension and MIME type must not be excluded by the system policy.
**Parameters:**
| Name | In | Required | Description |
|------|----|----------|-------------|
| `id` | path | yes | The unique identifier of the Repositories Gateway file to add a new version to. |
| `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. |
**Request Body:**
| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `body` | string | yes | The binary content of the file. |
**Responses:**
| Code | Description |
|------|-------------|
| 200 | Returns the transfer status record for the upload operation. |
| 403 | Forbidden Possible error codes: ERR_ENTITY_RESTRICTED_EXTENSION, ERR_ENTITY_RESTRICTED_EXTENSION_CUSTOM, ERR_ENTITY_RESTRICTED_TYPE, ERR_ENTITY_RESTRICTED_TYPE_CUSTOM, ERR_ENTITY_RESTRICTED_TYPE_GROUP |
| 490 | Request blocked by WAF |
**Response Examples:**
**200 (VersionUploaded):**
```json
{
"id": 57,
"transaction_id": "txn-ghi789",
"kp_object_id": "kp-42",
"file_handle": "tmp_ghi789",
"user_id": 101,
"err_code": null,
"status": "2",
"av_status": "allowed",
"dlp_status": "allowed"
}
```
**403 (ERR_ENTITY_RESTRICTED_EXTENSION):**
```json
{
"errors": {
"code": "ERR_ENTITY_RESTRICTED_EXTENSION",
"message": "File extension is in exclusion extensions list"
}
}
```
**403 (ERR_ENTITY_RESTRICTED_EXTENSION_CUSTOM):**
```json
{
"errors": {
"code": "ERR_ENTITY_RESTRICTED_EXTENSION_CUSTOM",
"message": "File extension is in custom exclusion extensions list"
}
}
```
**403 (ERR_ENTITY_RESTRICTED_TYPE):**
```json
{
"errors": {
"code": "ERR_ENTITY_RESTRICTED_TYPE",
"message": "The specified entity mime type is not allowed."
}
}
```
**403 (ERR_ENTITY_RESTRICTED_TYPE_CUSTOM):**
```json
{
"errors": {
"code": "ERR_ENTITY_RESTRICTED_TYPE_CUSTOM",
"message": "The specified file type is in custom excluded file types list."
}
}
```
**403 (ERR_ENTITY_RESTRICTED_TYPE_GROUP):**
```json
{
"errors": {
"code": "ERR_ENTITY_RESTRICTED_TYPE_GROUP",
"message": "File mime type is in exclusion groups list."
}
}
```
**Code Samples:**
**cURL:**
```shell
curl -X POST \
"https://{instance}.kiteworks.com/rest/sources/actions/files/:id" \
-H "Authorization: Bearer YOUR_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"body": "string"
}'
```
**Python:**
```python
import requests
id = "VALUE" # The unique identifier of the Repositories Gateway file to add a new version to.
url = f"https://{{instance}}.kiteworks.com/rest/sources/actions/files/{id}"
headers = {
"Authorization": "Bearer YOUR_TOKEN",
"Content-Type": "application/json",
}
payload = {
"body": "string"
}
response = requests.post(url, headers=headers, json=payload)
print(response.json())
```
---
## POST /rest/sources/{id}/actions/file
**Summary:** Upload a file to Repositories Gateway source
Uploads a file to the specified Repositories Gateway source folder. Returns a transfer
status record that reflects the result of the upload operation.
**Requires `file_add`
permission on the target Repositories Gateway folder.** The file extension and MIME type
must not be excluded by the system policy.
**Parameters:**
| Name | In | Required | Description |
|------|----|----------|-------------|
| `id` | path | yes | The unique identifier of the Repositories Gateway target 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. |
**Request Body:**
| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `body` | string | yes | The binary content of the file. |
**Responses:**
| Code | Description |
|------|-------------|
| 200 | Returns the transfer status record for the upload operation. |
| 403 | Forbidden Possible error codes: ERR_ENTITY_RESTRICTED_EXTENSION, ERR_ENTITY_RESTRICTED_EXTENSION_CUSTOM, ERR_ENTITY_RESTRICTED_TYPE, ERR_ENTITY_RESTRICTED_TYPE_CUSTOM, ERR_ENTITY_RESTRICTED_TYPE_GROUP |
| 490 | Request blocked by WAF |
**Response Examples:**
**200 (FileUploaded):**
```json
{
"id": 56,
"transaction_id": "txn-def456",
"kp_object_id": "kp-99",
"file_handle": "tmp_def456",
"user_id": 101,
"err_code": null,
"status": "2",
"av_status": "allowed",
"dlp_status": "allowed"
}
```
**403 (ERR_ENTITY_RESTRICTED_EXTENSION):**
```json
{
"errors": {
"code": "ERR_ENTITY_RESTRICTED_EXTENSION",
"message": "File extension is in exclusion extensions list"
}
}
```
**403 (ERR_ENTITY_RESTRICTED_EXTENSION_CUSTOM):**
```json
{
"errors": {
"code": "ERR_ENTITY_RESTRICTED_EXTENSION_CUSTOM",
"message": "File extension is in custom exclusion extensions list"
}
}
```
**403 (ERR_ENTITY_RESTRICTED_TYPE):**
```json
{
"errors": {
"code": "ERR_ENTITY_RESTRICTED_TYPE",
"message": "The specified entity mime type is not allowed."
}
}
```
**403 (ERR_ENTITY_RESTRICTED_TYPE_CUSTOM):**
```json
{
"errors": {
"code": "ERR_ENTITY_RESTRICTED_TYPE_CUSTOM",
"message": "The specified file type is in custom excluded file types list."
}
}
```
**403 (ERR_ENTITY_RESTRICTED_TYPE_GROUP):**
```json
{
"errors": {
"code": "ERR_ENTITY_RESTRICTED_TYPE_GROUP",
"message": "File mime type is in exclusion groups list."
}
}
```
**Code Samples:**
**cURL:**
```shell
curl -X POST \
"https://{instance}.kiteworks.com/rest/sources/:id/actions/file" \
-H "Authorization: Bearer YOUR_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"body": "string"
}'
```
**Python:**
```python
import requests
id = "VALUE" # The unique identifier of the Repositories Gateway target folder.
url = f"https://{{instance}}.kiteworks.com/rest/sources/{id}/actions/file"
headers = {
"Authorization": "Bearer YOUR_TOKEN",
"Content-Type": "application/json",
}
payload = {
"body": "string"
}
response = requests.post(url, headers=headers, json=payload)
print(response.json())
```
---
## POST /rest/sources/{id}/actions/initiateDownload
**Summary:** Download a file asynchronously from Repositories Gateway source
Initiates an asynchronous download of the specified file from its Repositories Gateway
source. Returns a transfer status record that can be polled via
`GET /sources/actions/downloadByTransaction` until the transfer completes.
**Requires `download` permission on the file.**
**Parameters:**
| Name | In | Required | Description |
|------|----|----------|-------------|
| `id` | path | yes | The unique identifier of the file from Repositories Gateway Source. |
**Responses:**
| Code | Description |
|------|-------------|
| 200 | Returns the transfer status record for the initiated download, including the transaction ID used to poll for completion. |
| 403 | Forbidden Possible error codes: ERR_ACCESS_USER |
| 490 | Request blocked by WAF |
**Response Examples:**
**200 (DownloadInitiated):**
```json
{
"id": 55,
"transaction_id": "txn-abc123",
"kp_object_id": "kp-42",
"file_handle": "tmp_abc123",
"user_id": 101,
"err_code": null,
"status": "1",
"av_status": "allowed",
"dlp_status": "allowed"
}
```
**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/sources/:id/actions/initiateDownload" \
-H "Authorization: Bearer YOUR_TOKEN"
```
**Python:**
```python
import requests
id = "VALUE" # The unique identifier of the file from Repositories Gateway Source.
url = f"https://{{instance}}.kiteworks.com/rest/sources/{id}/actions/initiateDownload"
headers = {
"Authorization": "Bearer YOUR_TOKEN",
}
response = requests.post(url, headers=headers)
print(response.json())
```
---
## GET /rest/sources/{id}/content
**Summary:** Download a file from repositories gateway source
Downloads the binary content of the specified file from its Repositories Gateway source.
**Requires `download` permission on the file.**
**Parameters:**
| Name | In | Required | Description |
|------|----|----------|-------------|
| `id` | path | yes | Repositories Gateway file id |
**Responses:**
| Code | Description |
|------|-------------|
| 200 | Returns the binary file content as a downloadable stream. |
| 490 | Request blocked by WAF |
**Code Samples:**
**cURL:**
```shell
curl -X GET \
"https://{instance}.kiteworks.com/rest/sources/:id/content" \
-H "Authorization: Bearer YOUR_TOKEN"
```
**Python:**
```python
import requests
id = "VALUE" # Repositories Gateway file id
url = f"https://{{instance}}.kiteworks.com/rest/sources/{id}/content"
headers = {
"Authorization": "Bearer YOUR_TOKEN",
}
response = requests.get(url, headers=headers)
print(response.json())
```
---
## GET /rest/files/actions/content/link/{ref}
**Summary:** Download a file via a reference link
### Description:
Downloads the file identified by the provided reference link.
### Precondition:
Must be assigned the `download` permission for the file.
### Response:
The file content is streamed to the user.
**Parameters:**
| Name | In | Required | Description |
|------|----|----------|-------------|
| `ref` | path | yes | The unique reference for the download link. |
**Responses:**
| Code | Description |
|------|-------------|
| 200 | The file download request by reference link was successful. |
| 401 | Unauthorized Possible error codes: ERR_AUTH_UNAUTHORIZED |
| 403 | Forbidden Possible error codes: ERR_ACCESS_USER, ERR_ENTITY_DELETED, ERR_ENTITY_DLP_LOCKED, ERR_ENTITY_IS_SECURE_FOLDER, ERR_ENTITY_NOT_SCANNED, ERR_ENTITY_VIRUS_FOUND |
| 490 | Request blocked by WAF |
**Response Examples:**
**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_SECURE_FOLDER):**
```json
{
"errors": [
{
"code": "ERR_ENTITY_IS_SECURE_FOLDER",
"message": "Operation not permitted on restricted 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"
}
]
}
```
**Code Samples:**
**cURL:**
```shell
curl -X GET \
"https://{instance}.kiteworks.com/rest/files/actions/content/link/:ref" \
-H "Authorization: Bearer YOUR_TOKEN"
```
**Python:**
```python
import requests
ref = "VALUE" # The unique reference for the download link.
url = f"https://{{instance}}.kiteworks.com/rest/files/actions/content/link/{ref}"
headers = {
"Authorization": "Bearer YOUR_TOKEN",
}
response = requests.get(url, headers=headers)
print(response.json())
```
---
## GET /preview/file/{id}
**Summary:** Preview a file
### Description:
Returns the preview content for the specified file via the Repositories Gateway.
### Precondition:
User must have the `view` permission for the file.
### Response:
The preview content is returned.
**Parameters:**
| Name | In | Required | Description |
|------|----|----------|-------------|
| `id` | path | yes | The unique identifier of the entity. |
**Responses:**
| Code | Description |
|------|-------------|
| 200 | The preview content has been successfully returned. |
| 401 | Unauthorized Possible error codes: ERR_AUTH_UNAUTHORIZED |
| 403 | Forbidden Possible error codes: ERR_ENTITY_USER_HAS_INSUFFICIENT_PERMISSIONS |
| 490 | Request blocked by WAF |
**Response Examples:**
**401 (ERR_AUTH_UNAUTHORIZED):**
```json
{
"errors": [
{
"code": "ERR_AUTH_UNAUTHORIZED",
"message": "Unauthorized"
}
]
}
```
**403 (ERR_ENTITY_USER_HAS_INSUFFICIENT_PERMISSIONS):**
```json
{
"errors": [
{
"code": "ERR_ENTITY_USER_HAS_INSUFFICIENT_PERMISSIONS",
"message": "Target user has insufficient access permissions"
}
]
}
```
**Code Samples:**
**cURL:**
```shell
curl -X GET \
"https://{instance}.kiteworks.com/preview/file/:id" \
-H "Authorization: Bearer YOUR_TOKEN"
```
**Python:**
```python
import requests
id = "VALUE" # The unique identifier of the entity.
url = f"https://{{instance}}.kiteworks.com/preview/file/{id}"
headers = {
"Authorization": "Bearer YOUR_TOKEN",
}
response = requests.get(url, headers=headers)
print(response.json())
```
---
## POST /rest/files/members
**Summary:** Share files
### Description:
Shares specified files with multiple users.
### Precondition:
Must be assigned the `user_add` permission for the folder.
### Response:
Shares the files with the specified users.
**Parameters:**
| Name | In | Required | Description |
|------|----|----------|-------------|
| `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 file via email. |
| `emails` | string[] | no | List of email addresses for new members. |
| `userIds` | string[] | no | List of user IDs (UUID) for new members. (Recommended request size <= 100) |
| `ids` | string[] | no | List of file UUIDs to share with the specified users. |
| `roleId` | integer | yes | The role to assign to the new members. `8` – Collaborator (can upload, edit, and download). `9` – Viewer (read-only access). |
| `message` | string | no | Optional message to include with the file sharing. |
**Responses:**
| Code | Description |
|------|-------------|
| 201 | All files were successfully shared with the specified users. |
| 207 | Files were partially shared — some users 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_ENTITY_IS_SECURE_FOLDER, 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 |
| 409 | Conflict Possible error codes: ERR_ENTITY_EXISTS, ERR_ENTITY_ROLE_IS_ASSIGNED |
| 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_ENTITY_IS_SECURE_FOLDER):**
```json
{
"errors": [
{
"code": "ERR_ENTITY_IS_SECURE_FOLDER",
"message": "Operation not permitted on restricted 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"
}
]
}
```
**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"
}
]
}
```
**Code Samples:**
**cURL:**
```shell
curl -X POST \
"https://{instance}.kiteworks.com/rest/files/members" \
-H "Authorization: Bearer YOUR_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"notify": true,
"emails": [
"string"
],
"userIds": [
"string"
],
"ids": [
"string"
],
"roleId": 1,
"message": "string"
}'
```
**Python:**
```python
import requests
url = "https://{instance}.kiteworks.com/rest/files/members"
headers = {
"Authorization": "Bearer YOUR_TOKEN",
"Content-Type": "application/json",
}
payload = {
"notify": true,
"emails": [
"string"
],
"userIds": [
"string"
],
"ids": [
"string"
],
"roleId": 1,
"message": "string"
}
response = requests.post(url, headers=headers, json=payload)
print(response.json())
```
---
## GET /rest/files/shared
**Summary:** Get shared files
### Description:
Gets a list of files that have been shared with the user. For each file, the file name, size, and date the file was shared is returned.
### Precondition:
If the user is assigned the Restricted profile, the "Collaboration Allowed" setting must be turned on to get results.
### Response:
Returns the list of files that have been shared with the user.
### Sorting:
Sorting can be applied using two query parameters: `orderBy` for the field name,
and `orderType` for the sort order, which can be either `asc` or `desc`.
### Sorting field options:
| FIELD_NAME | Description |
|------------|-------------|
| name | The name of the file |
| size | The size of the file |
| shared | The datetime when the file was shared |
**Parameters:**
| Name | In | Required | Description |
|------|----|----------|-------------|
| `orderBy` | query | no | Field to sort by. Default is `shared`. Allowed values: `name`, `size`, `shared`, `sharedBy`, `modified`. |
| `orderType` | query | no | Sort direction. `asc` for ascending, `desc` for descending. Default is `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 | Successfully returned the list of files shared with the user. |
| 401 | Unauthorized Possible error codes: 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_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/files/shared" \
-H "Authorization: Bearer YOUR_TOKEN"
```
**Python:**
```python
import requests
url = "https://{instance}.kiteworks.com/rest/files/shared"
headers = {
"Authorization": "Bearer YOUR_TOKEN",
}
response = requests.get(url, headers=headers)
print(response.json())
```
---
## DELETE /rest/files/{id}/members/me
**Summary:** Remove access to shared file
### Description:
Removes the current user's access to the specified file that was shared with them.
### Precondition:
The file must have been shared with the user.
### Response:
Removes the user's access to the shared file.
**Parameters:**
| Name | In | Required | Description |
|------|----|----------|-------------|
| `id` | path | yes | The unique identifier (UUID) of the entity. |
**Responses:**
| Code | Description |
|------|-------------|
| 200 | The user has been successfully removed from the file. |
| 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 DELETE \
"https://{instance}.kiteworks.com/rest/files/: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/files/{id}/members/me"
headers = {
"Authorization": "Bearer YOUR_TOKEN",
}
response = requests.delete(url, headers=headers)
print(response.json())
```
---
## GET /rest/files/previewSupport
**Summary:** Get file preview status
### Description:
Gets the status of the specified file to determine if the file type is supported for preview.
### Precondition:
Must be assigned the `view` permission for the folder.
### Response:
Returns confirmation as to whether the file type is supported for preview.
**Parameters:**
| Name | In | Required | Description |
|------|----|----------|-------------|
| `id:in` | query | yes | Comma-separated list of file UUIDs to check for preview support. |
**Responses:**
| Code | Description |
|------|-------------|
| 200 | Returns a list of unique identifiers (UUIDs) of the files supported for preview. |
| 400 | Bad Request Possible error codes: ERR_REQUEST_INVALID_FILTER |
| 401 | Unauthorized Possible error codes: ERR_AUTH_INVALID_CSRF, ERR_AUTH_UNAUTHORIZED |
| 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"
}
]
}
```
**Code Samples:**
**cURL:**
```shell
curl -X GET \
"https://{instance}.kiteworks.com/rest/files/previewSupport?id:in=VALUE" \
-H "Authorization: Bearer YOUR_TOKEN"
```
**Python:**
```python
import requests
url = "https://{instance}.kiteworks.com/rest/files/previewSupport"
headers = {
"Authorization": "Bearer YOUR_TOKEN",
}
params = {
"id:in": "VALUE",
}
response = requests.get(url, params=params, headers=headers)
print(response.json())
```
---
## POST /rest/files/actions/downloadLink
**Summary:** Get link for downloading files and folders
### Description:
Generates a link for downloading specified folders and files.
### Precondition:
Must be assigned the download permission for the specified files and folders.
### Response:
A download link is generated and returned.
Returns the link for downloading the files and folders, once files complete security scans. Depending on system scan policies, files will be scanned for anti-virus, data loss prevention, and advanced threat protection.
**Parameters:**
| Name | In | Required | Description |
|------|----|----------|-------------|
| `partialSuccess` | query | no | Indicates whether the operation should proceed if some files/folders fail the check. |
| `extensions` | query | no | Filter results to include only files with the specified comma-separated list of extensions. |
**Request Body:**
| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `fileIds` | string[] | no | List of file UUIDs to include in the bulk download. Maximum 1000 entries. |
| `folderIds` | string[] | no | List of folder UUIDs to include in the bulk download. Maximum 100 entries. |
| `fileId` | string | no | UUID of a single file to download. Use this for single-file downloads instead of `fileIds`. |
| `versionId` | string | no | The version ID of the specified file. |
**Responses:**
| Code | Description |
|------|-------------|
| 200 | The download link has been successfully generated. |
| 400 | Bad Request Possible error codes: ERR_REQUEST_INVALID_FILTER |
| 401 | Unauthorized Possible error codes: ERR_AUTH_UNAUTHORIZED |
| 422 | Unprocessable Content Possible error codes: ERR_INVALID_PARAMETER |
| 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_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 POST \
"https://{instance}.kiteworks.com/rest/files/actions/downloadLink" \
-H "Authorization: Bearer YOUR_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"fileIds": [
"string"
],
"folderIds": [
"string"
],
"fileId": "string",
"versionId": "string"
}'
```
**Python:**
```python
import requests
url = "https://{instance}.kiteworks.com/rest/files/actions/downloadLink"
headers = {
"Authorization": "Bearer YOUR_TOKEN",
"Content-Type": "application/json",
}
payload = {
"fileIds": [
"string"
],
"folderIds": [
"string"
],
"fileId": "string",
"versionId": "string"
}
response = requests.post(url, headers=headers, json=payload)
print(response.json())
```
---
## PUT /rest/admin/files
**Summary:** Update files
### Description:
Updates the metadata of multiple files at the same time.
### Precondition:
Must be an administrator with access to the Files and Folders page in the Kiteworks PDN Admin.
### Response:
Updates the selected files.
**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 file object IDs (UUID) to be updated. |
| `expire` | string | no | New expiration date for the selected files. |
**Responses:**
| Code | Description |
|------|-------------|
| 200 | The files have been successfully updated. |
| 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_ATTACHMENT, ERR_ENTITY_NOT_SCANNED, ERR_ENTITY_VIRUS_FOUND |
| 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_ATTACHMENT):**
```json
{
"errors": [
{
"code": "ERR_ENTITY_IS_ATTACHMENT",
"message": "Operation not permitted on attachment"
}
]
}
```
**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"
}
]
}
```
**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/files" \
-H "Authorization: Bearer YOUR_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"ids": [
"string"
],
"expire": "2024-01-15"
}'
```
**Python:**
```python
import requests
url = "https://{instance}.kiteworks.com/rest/admin/files"
headers = {
"Authorization": "Bearer YOUR_TOKEN",
"Content-Type": "application/json",
}
payload = {
"ids": [
"string"
],
"expire": "2024-01-15"
}
response = requests.put(url, headers=headers, json=payload)
print(response.json())
```
---
## POST /rest/admin/files/{id}/actions/rescan
**Summary:** Scan a file for security
### Description:
Runs a security scan on the specified file.
### Precondition:
Must authenticate as an administrator with a role allowing for manually scanning files for security.
### Response:
Scans the selected file for security. Depending on system scan policies, the file is scanned for anti-virus, data loss prevention, and advanced threat protection.
**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 |
|------|-------------|
| 201 | The file has been successfully submitted for rescan. |
| 401 | Unauthorized Possible error codes: ERR_AUTH_INVALID_CSRF, ERR_AUTH_UNAUTHORIZED |
| 403 | Forbidden Possible error codes: ERR_ACCESS_ADMIN |
| 404 | Not Found Possible error codes: ERR_ENTITY_FILE_IS_NOT_FOUND, ERR_ENABLED_SCANNING_SERVICE_IS_NOT_FOUND |
| 409 | Conflict Possible error codes: ERR_SCANNING_IN_PROGRESS |
| 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_ADMIN):**
```json
{
"errors": [
{
"code": "ERR_ACCESS_ADMIN",
"message": "Insufficient admin access permissions"
}
]
}
```
**404 (ERR_ENTITY_FILE_IS_NOT_FOUND):**
```json
{
"errors": [
{
"code": "ERR_ENTITY_FILE_IS_NOT_FOUND",
"message": "The file is not found"
}
]
}
```
**404 (ERR_ENABLED_SCANNING_SERVICE_IS_NOT_FOUND):**
```json
{
"errors": [
{
"code": "ERR_ENABLED_SCANNING_SERVICE_IS_NOT_FOUND",
"message": "No enabled scanning service is found"
}
]
}
```
**409 (ERR_SCANNING_IN_PROGRESS):**
```json
{
"errors": [
{
"code": "ERR_SCANNING_IN_PROGRESS",
"message": "Scanning in progress. Please rescan later."
}
]
}
```
**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/admin/files/:id/actions/rescan" \
-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/admin/files/{id}/actions/rescan"
headers = {
"Authorization": "Bearer YOUR_TOKEN",
}
response = requests.post(url, headers=headers)
print(response.json())
```
---